API overview
Authentication, rate limits and the generated public API reference.
Production API base URL: https://api.sieve.one. The interactive reference sends Try it requests to the sandbox at https://sandbox.api.sthanika.ai or to a gateway on your own machine (for example a self-hosted Vault reached through a port-forward). It never sends a request to production from this page.
| Endpoint | Purpose | Reference |
|---|---|---|
POST /v1/systemone | Typed questions about a state. TypeSafe System One contract. | System One |
GET /v1/models | The models and aliases your key can use. | System One |
POST /v1/decisions | The same decisions, OpenAI-style (ordered question list). | /v1/decisions |
The reference is generated at build time from the backend-owned public OpenAPI contracts: Decisions and TypeSafe-compatible System One. It excludes console and admin contracts. Every operation, response, error schema and model in those contracts renders automatically, with code samples in curl, Python, JavaScript and Go.
Try it
- Open System One or /v1/decisions.
- Under Server, keep Sandbox, or choose Local gateway and set the host (
127.0.0.1,localhostor[::1]) and port. - Under Authentication, paste an API key for that server into Bearer Token.
- Select Test Request on an operation, adjust the example body if you like, and select Send.
The key stays in this tab's memory only: it is not saved, not put in the URL and is gone when you reload. Any other host, including production, is refused before a request is sent. Requests count towards your usage like any other call.
Download the combined OpenAPI JSON, browse the sitemap, or use llms.txt.
Authentication
Authorization: Bearer sieve_app_live_...See Authentication.
Request headers
| Header | Required | Meaning |
|---|---|---|
Authorization: Bearer <key> | Yes | Your API key. Missing or invalid gives 401. X-API-Key: <key> is also accepted. |
Content-Type | Yes | application/json, or multipart/form-data for images. |
Content-Encoding | No | gzip, x-gzip or zstd, one layer. Anything else gives 415. |
Idempotency-Key | No | Makes a retry safe. The same key from the same API key within 60 s of a success returns that response again. |
TypeSafe-Danger-Zone-Images: true | For images | Needed for images and box questions. Not available at launch. |
TypeSafe-Danger-Zone-Long-Context: true | For long context | Raises limits only on models that support it. Check the current model contract and your organisation limits. |
Sieve-Extras: true | No | Adds a top-level sieve object to System One, /v1/decisions and /v1/models responses. |
The TypeSafe SDKs also send User-Agent, X-TypeSafe-SDK, X-TypeSafe-Runtime and X-TypeSafe-Retry-Count. They are accepted and ignored.
Response headers
| Header | Meaning |
|---|---|
x-typesafe-request-id | Request ID on every System One response. /v1/decisions uses x-request-id. /v1/models sends both. |
retry-after | Integer seconds, on 429 and 529 (503 on /v1/decisions) when a retry can help. |
retry-after-ms | Milliseconds. Sent with every retry-after. |
x-ratelimit-* | Limit, remaining and reset for requests and input tokens. See Errors. |
x-should-retry: false | On a deliberate refusal (suspended organisation, model switched off), so SDKs do not retry. |
Sieve-Escalation: unavailable | sieve-auto answered from 4B only. See Auto cascade. |
Sieve-Idempotent-Replayed: true | The response is a replay of an earlier identical request. |
Conventions
- Output tokens are free.
usage.input_tokensis what you are billed. - Numbers in answers are rounded to 2 decimal places.
- Errors: see Errors. Limits: see Limits.
- Sieve-only fields never change a standard field. They sit under a top-level
sieveobject, so strict TypeSafe clients keep working.
Next steps
System One
POST /v1/systemone and GET /v1/models, rendered from the OpenAPI file.
/v1/decisions
POST /v1/decisions, the OpenAI-style route, rendered from the OpenAPI file.
Errors
Every status code the decision API returns, with the exact response bodies, headers and retry guidance.
SDKs
Use the TypeSafe Python and JavaScript SDKs with Sieve.
Last updated