REST API Specification

This document is a complete specification of Sawtooth Lake’s REST API, built from the official OpenAPI formatted YAML specification, which can be found on the Sawtooth Lake Github.

Note

This specification has not been fully implemented, and at this point should be considered a roadmap rather than a reference for usage. Until complete, many of the endpoints may not work, or may behave differently than documented.

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 200 is returned with a data object that include 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:
 
  • callback (string) – Callback url
  • 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) – Field to sort a list by, - reverses order
  • fields (string) – Comma separated list of fields to include in response, defaults to all
  • omit (string) – Comma separated list of fields to omit from response, defaults to none
Status Codes:
GET /batches/{batch_id}

Fetches a particular batch

Parameters:
  • batch_id (string) – Batch id
Query Parameters:
 
  • fields (string) – Comma separated list of fields to include in response, defaults to all
  • omit (string) – Comma separated list of fields to omit from response, defaults to none
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, and the response body will _not_ include the head or paging properties.

Query Parameters:
 
  • id (string) – A comma seperated 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) – Field to sort a list by, - reverses order
  • fields (string) – Comma separated list of fields to include in response, defaults to all
  • omit (string) – Comma separated list of fields to omit from response, defaults to none
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
  • fields (string) – Comma separated list of fields to include in response, defaults to all
  • omit (string) – Comma separated list of fields to omit from response, defaults to none
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) – Field to sort a list by, - reverses order
  • fields (string) – Comma separated list of fields to include in response, defaults to all
  • omit (string) – Comma separated list of fields to omit from response, defaults to none
Status Codes:
GET /blocks/{block_id}

Fetches a particlar block

Parameters:
  • block_id (string) – Block id
Query Parameters:
 
  • fields (string) – Comma separated list of fields to include in response, defaults to all
  • omit (string) – Comma separated list of fields to omit from response, defaults to none
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) – Field to sort a list by, - reverses order
  • fields (string) – Comma separated list of fields to include in response, defaults to all
  • omit (string) – Comma separated list of fields to omit from response, defaults to none
Status Codes:
GET /transactions/{transaction_id}

Fetches a particular transaction

Parameters:
  • transaction_id (string) – Trainsaction id
Query Parameters:
 
  • fields (string) – Comma separated list of fields to include in response, defaults to all
  • omit (string) – Comma separated list of fields to omit from response, defaults to none
Status Codes:
GET /stats/validator

Fetches metrics for the validator processing blocks

Fetches a snapshot of metrics relating to this validator’s processing of blocks. These metrics are raw totals of various validator processes, and any processing of the data will depend on the clients consuming it. These totals are further broken down by types of Transaction Processor.

Query Parameters:
 
  • fields (string) – Comma separated list of fields to include in response, defaults to all
  • omit (string) – Comma separated list of fields to omit from response, defaults to none
Status Codes:
GET /stats/gossip

Fetches metrics for inter-validator communication

Fetches a snapshot of metrics relating to this validator’s communication with peer validators. These metrics represent raw totals, and any processing of the data will depend on the clients consuming it. These totals are further broken down by the ids of peers.

Query Parameters:
 
  • fields (string) – Comma separated list of fields to include in response, defaults to all
  • omit (string) – Comma separated list of fields to omit from response, defaults to none
Status Codes:
GET /status/config

Fetches the current configuration of the validator

Query Parameters:
 
  • fields (string) – Comma separated list of fields to include in response, defaults to all
  • omit (string) – Comma separated list of fields to omit from response, defaults to none
Status Codes:
GET /status/system

Fetches the current status of the system the validator is on

Query Parameters:
 
  • fields (string) – Comma separated list of fields to include in response, defaults to all
  • omit (string) – Comma separated list of fields to omit from response, defaults to none
Status Codes: