Endpoint Specifications

These specifications document the available Sawtooth REST API endpoints. They are generated from the official OpenAPI formatted YAML specification, which can be found on the Sawtooth GitHub.

POST /batches

Sends a BatchList to the validator

Accepts a protobuf formatted BatchList as an octet-stream binary file and submits it to the validator to be committed.

The API will return immediately with a status of 202. There will be no data object, only a link to a /batch_statuses endpoint to be polled to check the status of submitted batches.

Status Codes
GET /batches

Fetches a list of batches

Fetches a paginated list of batches from the validator.

Query Parameters

  • head (string) – Index or id of head block

  • start (string) – Id to start paging (inclusive)

  • limit (integer) – Number of items to return

  • reverse (string) – If the list should be reversed

Status Codes
GET /batches/{batch_id}

Fetches a particular batch

Parameters

  • batch_id (string) – Batch id

Status Codes
GET /batch_statuses

Fetches the committed statuses for a set of batches

Fetches an array of objects with a status and id for each batch requested. There are four possible statuses with string values ‘COMMITTED’, ‘INVALID’, ‘PENDING’, and ‘UNKNOWN’.

The batch(es) you want to check can be specified using the id filter parameter. If a wait time is specified in the URL, the API will wait to respond until all batches are committed, or the time in seconds has elapsed. If the value of wait is not set (i.e., ?wait&id=…), or it is set to any non-integer value other than false, the wait time will be just under the API’s specified timeout (usually 300).

Note that because this route does not return full resources, the response will not be paginated, and there will be no head or paging properties.

Query Parameters

  • id (string) – A comma-separated list of batch ids

  • wait (integer) – A time in seconds to wait for commit

Status Codes
POST /batch_statuses

Fetches the committed statuses for a set of batches

Identical to GET /batch_statuses, but takes ids of batches as a JSON formatted POST body rather than a query parameter. This allows for many more batches to be checked and should be used for more than 15 ids.

Note that because query information is not encoded in the URL, no link will be returned with this query.

Query Parameters

  • wait (integer) – A time in seconds to wait for commit

Status Codes
GET /state

Fetches the data for the current state

Fetches a paginated list of entries for the current state, or relative to a particular head block. Using the address filter parameter will narrow the list to any entries that have an address beginning with the characters specified. Note that the partial address in address parameter should have even number of hecadeximal characters (i.e., complete bytes).

Query Parameters

  • head (string) – Index or id of head block

  • address (string) – A partial address to filter leaves by

  • start (string) – Id to start paging (inclusive)

  • limit (integer) – Number of items to return

  • reverse (string) – If the list should be reversed

Status Codes
GET /state/{address}

Fetches a particular leaf from the current state

Takes full 70-character address and fetches a particular leaf. For partial address (i.e., group of leaves) use /state above.

Parameters

  • address (string) – Radix address of a leaf

Query Parameters

  • head (string) – Index or id of head block

Status Codes
GET /blocks

Fetches a list of blocks

Fetches a paginated list of blocks from the validator.

Query Parameters

  • head (string) – Index or id of head block

  • start (string) – Id to start paging (inclusive)

  • limit (integer) – Number of items to return

  • reverse (string) – If the list should be reversed

Status Codes
GET /blocks/{block_id}

Fetches a particular block

Parameters

  • block_id (string) – Block id

Status Codes
GET /transactions

Fetches a list of transactions

Fetches a paginated list of transactions from the validator.

Query Parameters

  • head (string) – Index or id of head block

  • start (string) – Id to start paging (inclusive)

  • limit (integer) – Number of items to return

  • reverse (string) – If the list should be reversed

Status Codes
GET /transactions/{transaction_id}

Fetches a particular transaction

Parameters

  • transaction_id (string) – Transaction id

Status Codes
GET /receipts

Fetches the receipts for a set of transactions

Fetches an array of objects for each receipt requested.

The receipt(s) you want to retrieve can be specified using the id filter parameter, where id refers to the transaction id of the transaction the receipt is associated with.

Query Parameters

  • id (string) – A comma-separated list of transaction ids

Status Codes
POST /receipts

Fetches the receipts for a set of transactions

Identical to GET /receipts, but takes ids of transactions as a JSON formatted POST body rather than a query parameter. This allows for many more receipts to be fetched and should be used with more than 15 ids.

Note that because query information is not encoded in the URL, no link will be returned with this request.

Query Parameters

  • wait (integer) – A time in seconds to wait for commit

Status Codes
GET /peers

Fetches the endpoints of the authorized peers of the validator

Status Codes
GET /status

Fetches information pertaining to the status of the validator

Status Codes