HTTP-based REST API¶
Users interact with httpstan
using an HTTP-based REST API. This page
describes the API.
An alternative single-page rendering of this documentation is available: httpstan HTTP-based REST API.
This page and the alternative rendering are generated from an OpenAPI spec. This API uses conventions described in the document API Design Guide.
- POST /v1/models¶
Compile a Stan model
- Request JSON Object
program_code (string) – (required)
- Status Codes
201 Created – Identifier for compiled Stan model and compiler output.
400 Bad Request – Error associated with compile request.
- Response JSON Object
compiler_output (string) – (required)
name (string) – (required)
stanc_warnings (string) – (required)
- GET /v1/models¶
List cached models.
- Status Codes
200 OK – Identifier for compiled Stan model and compiler output.
- Response JSON Object
models[].compiler_output (string) – (required)
models[].name (string) – (required)
models[].stanc_warnings (string) – (required)
- DELETE /v1/models/{model_id}¶
Delete a model and any associated fits.
Delete a model which has been saved in the cache.
- Parameters
model_id (string) – ID of Stan model
- Status Codes
200 OK – Model successfully deleted.
404 Not Found – Model not found.
- POST /v1/models/{model_id}/params¶
Get parameter names and dimensions.
Returns the output of Stan C++ model class methods:
constrained_param_names
,get_param_names
andget_dims
.- Parameters
model_id (string) – ID of Stan model to use
- Status Codes
200 OK – Parameters for Stan Model
400 Bad Request – Error associated with request.
404 Not Found – Model not found.
- Response JSON Object
id (string) –
params[].constrained_names[] (string) –
params[].dims[] (integer) –
params[].name (string) – (required)
- POST /v1/models/{model_id}/log_prob¶
Return the log probability of the unconstrained parameters.
Returns the output of Stan C++
log_prob
model class method.- Parameters
model_id (string) – ID of Stan model to use
- Request JSON Object
[] (number) –
- Status Codes
200 OK – Log probability of the unconstrained parameters.
400 Bad Request – Error associated with request.
404 Not Found – Model not found.
- Response JSON Object
log_prob (number) –
- POST /v1/models/{model_id}/log_prob_grad¶
Return the gradient of the log posterior evaluated at the unconstrained parameters.
Returns the output of Stan C++ stan::model::log_prob_grad.
- Parameters
model_id (string) – ID of Stan model to use
- Request JSON Object
[] (number) –
- Status Codes
200 OK – Gradient of the log posterior evaluated at the unconstrained parameters.
400 Bad Request – Error associated with request.
404 Not Found – Model not found.
- Response JSON Object
grad_log_prob[] (number) –
- POST /v1/models/{model_id}/write_array¶
Return a sequence of constrained parameters.
Returns the output of Stan C++
write_array
model class method.- Parameters
model_id (string) – ID of Stan model to use
- Request JSON Object
[] (number) –
- Status Codes
200 OK – Sequence of constrained parameters, optionally including transformed parameters and generated quantities.
400 Bad Request – Error associated with request.
404 Not Found – Model not found.
- Response JSON Object
params_r_constrained[] (number) –
- POST /v1/models/{model_id}/transform_inits¶
Return a sequence of unconstrained parameters.
Returns the output of Stan C++
transform_inits
model class method.- Parameters
model_id (string) – ID of Stan model to use
- Status Codes
200 OK – Sequence of unconstrained parameters.
400 Bad Request – Error associated with request.
404 Not Found – Model not found.
- Response JSON Object
params_r_unconstrained[] (number) –
- POST /v1/models/{model_id}/fits¶
Call function defined in stan::services.
A request to this endpoint starts a long-running operation. Users can retrieve information about the status of the operation by making a GET request to the operations resource endpoint. When the operation is done, the “fit” may be downloaded. (A “fit” collects all logger and writer messages from Stan.)
function
indicates the name of thestan::services function
which should be called given the Stan model associated with the idmodel_id
. For example, if sampling usingstan::services::sample::hmc_nuts_diag_e_adapt
thenfunction
is the full function namestan::services::sample::hmc_nuts_diag_e_adapt
. Sampler parameters which are not supplied will be given default values taken from CmdStan. For example, ifstan::services::sample::hmc_nuts_diag_e_adapt
is the function called and the parameternum_samples
is not specified, the value 1000 will be used. For a full list of default values consult the CmdStan documentation.- Parameters
model_id (string) – ID of Stan model to use
- Request JSON Object
chain (integer) –
data (any) –
delta (number) –
function (string) – (required)
gamma (number) –
init (any) –
init_buffer (integer) –
init_radius (number) –
kappa (number) –
max_depth (integer) –
num_samples (integer) –
num_thin (integer) –
num_warmup (integer) –
random_seed (integer) –
refresh (integer) –
save_warmup (boolean) –
stepsize (number) –
stepsize_jitter (number) –
t0 (number) –
term_buffer (integer) –
window (integer) –
- Status Codes
201 Created – Identifier for completed Stan fit
400 Bad Request – Error associated with request.
404 Not Found – Fit not found.
- Response JSON Object
name (string) – (required)
- GET /v1/models/{model_id}/fits/{fit_id}¶
Get results returned by a function.
Result (draws, logger messages) from calling a function defined in stan::services.
- Parameters
model_id (string) – ID of Stan model associated with the result
fit_id (string) – ID of Stan result (“fit”) desired
- Status Codes
200 OK – Newline-delimited JSON-encoded messages from Stan. Includes draws.
404 Not Found – Fit not found.
- DELETE /v1/models/{model_id}/fits/{fit_id}¶
Delete a fit.
Delete a fit which has been saved in the cache.
- Parameters
model_id (string) – ID of Stan model associated with the fit.
fit_id (string) – ID of fit to be deleted.
- Status Codes
200 OK – Fit successfully deleted.
404 Not Found – Fit not found.
- GET /v1/operations/{operation_id}¶
Get Operation details.
Return Operation details. Details about an Operation include whether or not the operation is done and information about the progress of sampling.
- Parameters
operation_id (string) – ID of Operation
- Status Codes
200 OK – Operation name and metadata.
404 Not Found – Operation not found.
- Response JSON Object
done (boolean) – (required)
metadata (object) –
name (string) – (required)
result (object) –