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.

GET /v1/health

Check if service is running.

Status Codes:
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:
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 and get_dims.

Parameters:

  • model_id (string) – ID of Stan model to use

Status Codes:
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:
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:
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 the stan::services function which should be called given the Stan model associated with the id model_id. For example, if sampling using stan::services::sample::hmc_nuts_diag_e_adapt then function is the full function name stan::services::sample::hmc_nuts_diag_e_adapt. Sampler parameters which are not supplied will be given default values taken from CmdStan. For example, if stan::services::sample::hmc_nuts_diag_e_adapt is the function called and the parameter num_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:
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:
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:
Response JSON Object:

  • done (boolean) – (required)

  • metadata (object)

  • name (string) – (required)

  • result (object)