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
202 Accepted – Batches submitted for validation, but not yet committed
400 Bad Request – Request was malformed
429 Too Many Requests – Too many requests have been made to process batches
500 Internal Server Error – Something went wrong within the validator
503 Service Unavailable – API is unable to reach the validator
-
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
200 OK – Successfully retrieved batches
400 Bad Request – Request was malformed
500 Internal Server Error – Something went wrong within the validator
503 Service Unavailable – API is unable to reach the validator
-
GET
/batches/{batch_id}
¶ Fetches a particular batch
- Parameters
batch_id (string) – Batch id
- Status Codes
200 OK – Successfully retrieved batch
400 Bad Request – Request was malformed
404 Not Found – Address or id did not match any resource
500 Internal Server Error – Something went wrong within the validator
503 Service Unavailable – API is unable to reach the validator
-
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
200 OK – Successfully retrieved statuses
400 Bad Request – Request was malformed
500 Internal Server Error – Something went wrong within the validator
503 Service Unavailable – API is unable to reach the validator
-
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
- Request JSON Object
[] (string) –
- Status Codes
200 OK – Successfully retrieved statuses
400 Bad Request – Request was malformed
500 Internal Server Error – Something went wrong within the validator
503 Service Unavailable – API is unable to reach the validator
-
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 hexadecimal 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
200 OK – Successfully retrieved state data
400 Bad Request – Request was malformed
500 Internal Server Error – Something went wrong within the validator
503 Service Unavailable – API is unable to reach the validator
-
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
200 OK – Successfully fetched leaves
400 Bad Request – Request was malformed
404 Not Found – Address or id did not match any resource
500 Internal Server Error – Something went wrong within the validator
503 Service Unavailable – API is unable to reach the validator
-
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
200 OK – Successfully retrieved blocks
400 Bad Request – Request was malformed
500 Internal Server Error – Something went wrong within the validator
503 Service Unavailable – API is unable to reach the validator
-
GET
/blocks/{block_id}
¶ Fetches a particular block
- Parameters
block_id (string) – Block id
- Status Codes
200 OK – Successfully retrieved block
400 Bad Request – Request was malformed
404 Not Found – Address or id did not match any resource
500 Internal Server Error – Something went wrong within the validator
503 Service Unavailable – API is unable to reach the validator
-
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
200 OK – Successfully retrieved transactions
400 Bad Request – Request was malformed
500 Internal Server Error – Something went wrong within the validator
503 Service Unavailable – API is unable to reach the validator
-
GET
/transactions/{transaction_id}
¶ Fetches a particular transaction
- Parameters
transaction_id (string) – Transaction id
- Status Codes
200 OK – Successfully retrieved transaction
400 Bad Request – Request was malformed
404 Not Found – Address or id did not match any resource
500 Internal Server Error – Something went wrong within the validator
503 Service Unavailable – API is unable to reach the validator
-
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
200 OK – Successfully retrieved transaction receipts
400 Bad Request – Request was malformed
500 Internal Server Error – Something went wrong within the validator
503 Service Unavailable – API is unable to reach the validator
-
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
- Request JSON Object
[] (string) –
- Status Codes
200 OK – Successfully retrieved transaction receipts
400 Bad Request – Request was malformed
500 Internal Server Error – Something went wrong within the validator
503 Service Unavailable – API is unable to reach the validator
-
GET
/peers
¶ Fetches the endpoints of the authorized peers of the validator
- Status Codes
200 OK – Successfully retrieved peers
400 Bad Request – Request was malformed
500 Internal Server Error – Something went wrong within the validator
503 Service Unavailable – API is unable to reach the validator
-
GET
/status
¶ Fetches information pertaining to the status of the validator
- Status Codes
200 OK – Successfully retrieved status
400 Bad Request – Request was malformed
500 Internal Server Error – Something went wrong within the validator
503 Service Unavailable – API is unable to reach the validator