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.

If the wait parameter is set in the url, the API will try to wait to respond until all batches have been committed to the blockchain, returning a 201 response with a link to the committed batches.

If wait is set to a positive integer, the API will timeout and return after that time in seconds has elapsed. If set to any non-integer value other than false (including simply ?wait), the API may still timeout, but will use its own settings (usually 300s). After timing out, a 202 is returned with a data object that includes the statuses of each batch (COMMITTED, INVALID, PENDING, or UNKNOWN), and a link to a /batch_status endpoint for further polling.

If wait is not set, or is set to false, the API will return immediately with a status of 202. There will be no data object, only a link to a /batch_status endpoint to be polled to check the status of submitted batches.

Query Parameters:
 
  • wait (integer) – A time in seconds to wait for commit
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
  • count (integer) – Number of items to return
  • min (string) – Id or index to start paging (inclusive)
  • max (string) – Id or index to end paging (inclusive)
  • sort (string) –
    Comma-separated keys to sort a list by:
    • can reference header keys explicitly or implicitly
    • dot-notation indicates nested keys
    • starting a key with a minus-sign indicates descending order
    • ending a key with .length sorts by the length
    • example: sort=header.signer_pubkey,-transaction_ids.length
Status Codes:
GET /batches/{batch_id}

Fetches a particular batch

Parameters:
  • batch_id (string) – Batch id
Status Codes:
GET /batch_status

Fetches the committed statuses for a set of batches

Fetches an object with a status for each batch requested. The keys of the data object will be the ids of the batch(es), while the values will be a string status with the values ‘COMMITTED’, ‘INVALID’, ‘PENDING’, or ‘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 shy of the api’s specified timeout (usually 300).

Note that as this route does not return a full resource, the response body will _not_ include the 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_status

Fetches the committed statuses for a set of batches

Identical to GET /batch_status, 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 since 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 leaves for the current state, or relative to a particular head block. Using the address filter parameter, will narrow the list to any leaves that have an address beginning with the characters specified.

Query Parameters:
 
  • head (string) – Index or id of head block
  • address (string) – A partial address to filter leaves by
  • count (integer) – Number of items to return
  • min (string) – Id or index to start paging (inclusive)
  • max (string) – Id or index to end paging (inclusive)
  • sort (string) –
    Comma-separated keys to sort a list by:
    • can reference header keys explicitly or implicitly
    • dot-notation indicates nested keys
    • starting a key with a minus-sign indicates descending order
    • ending a key with .length sorts by the length
    • example: sort=header.signer_pubkey,-transaction_ids.length
Status Codes:
GET /state/{address}

Fetches a particular leaf from the current state

Parameters:
  • address (string) – Radix address of a leaf, or prefix for leaves
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
  • count (integer) – Number of items to return
  • min (string) – Id or index to start paging (inclusive)
  • max (string) – Id or index to end paging (inclusive)
  • sort (string) –
    Comma-separated keys to sort a list by:
    • can reference header keys explicitly or implicitly
    • dot-notation indicates nested keys
    • starting a key with a minus-sign indicates descending order
    • ending a key with .length sorts by the length
    • example: sort=header.signer_pubkey,-transaction_ids.length
Status Codes:
GET /blocks/{block_id}

Fetches a particlar 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
  • count (integer) – Number of items to return
  • min (string) – Id or index to start paging (inclusive)
  • max (string) – Id or index to end paging (inclusive)
  • sort (string) –
    Comma-separated keys to sort a list by:
    • can reference header keys explicitly or implicitly
    • dot-notation indicates nested keys
    • starting a key with a minus-sign indicates descending order
    • ending a key with .length sorts by the length
    • example: sort=header.signer_pubkey,-transaction_ids.length
Status Codes:
GET /transactions/{transaction_id}

Fetches a particular transaction

Parameters:
  • transaction_id (string) – Trainsaction id
Status Codes: