API overview · Sextant docs

The REST API is the interface every other part of Sextant uses: the CLI, the SDKs and the dashboard call the same endpoints. Resources below this page are listed in the sidebar: Jobs, Schedules, Queues, Workers, Webhooks and Tokens.

Base URL and format

Text

https://api.sextant.example/v2

Requests and responses are JSON. Send Content-Type: application/json on requests with a body. Times are ISO 8601 in UTC, durations are strings such as 15m, and ids are opaque strings with a prefix that tells you the type (job_, sch_, wrk_, whk_, tok_).

Authentication

Send a token in the Authorization header:

cURLShell

curl https://api.sextant.example/v2/queues \
  -H "Authorization: Bearer $SEXTANT_TOKEN"

NodeTypeScript

const queues = await sextant.queues.list(); // token from SEXTANT_TOKEN

PythonPython

queues = client.queues.list()  # token from SEXTANT_TOKEN

GoGo

queues, err := client.Queues.List(ctx)

Each endpoint lists the scope it needs. A missing or revoked token returns 401; a token without the scope returns 403. See Tokens and scopes.

Errors

Errors use the status code for the class of problem and a JSON body for the details:

JSON

{
  "error": {
    "code": "validation_failed",
    "message": "queue 'emial' does not exist",
    "param": "queue",
    "request_id": "req_c1f0a2"
  }
}

Status	`code`	Meaning
400	`bad_request`	The body is not valid JSON
401	`unauthenticated`	Missing, malformed or revoked token
403	`forbidden`	The token lacks the required scope
404	`not_found`	No such resource
409	`invalid_state`	The resource is in a state that does not allow this action
422	`validation_failed`	A field is invalid; `param` names it
429	`rate_limited`	Too many requests; see `Retry-After`
5xx	`internal`	A server error. Safe to retry with an idempotency key

Quote request_id when you contact support: it finds the request in the server logs.

Pagination

List endpoints return newest first with cursor pagination:

JSON

{ "data": [ ], "next_cursor": "cur_Xk92" }

Pass next_cursor back as cursor to get the next page. next_cursor is null on the last page. limit is 50 by default and 200 at most.

Idempotency

POST /v2/jobs accepts an idempotency_key. Within 24 hours, a second request with the same key returns the original job with status 200 instead of 201. Other POST endpoints are not deduplicated.

Rate limits

ReadsGET

1,000 requests per minute per token.

WritesPOST, PATCH, DELETE

300 requests per minute per token.

Every response carries RateLimit-Remaining and RateLimit-Reset (seconds). A 429 includes Retry-After. The SDKs wait and retry on their own; if you call the API directly, back off with jitter.

Versioning

The major version is in the path. Within v2, changes are additive: new fields and new endpoints may appear, so clients must ignore fields they do not know. Breaking changes ship in a new major version and are announced in the changelog.