Guides
- Quickstart
- Authentication and keys
- Key protection
- Models, aliases and fallbacks
- Automatic model choice (silicon/auto)
- Chat completions
- Streaming
- Structured outputs and tools
- Logprobs
- Vision
- Responses, Claude and Ollama
- Embeddings, rerank, audio, images
- Files and batches
- Documents and search
- LoRA adapters
- Project tags and costs
- Prefix caching
- Headers, rate limits and spend caps
- Errors
- Versioning and the sandbox
- Privacy and retention
- Verifiable receipts
- Data residency
- Pricing
- Billing
- Pay per request (x402)
- On-chain oracle
- Agent credit (backed compute lines)
- Status
- SDKs
- Swift SDK
- Integrations
- Run a node
- Linux agent
- Compute API
- Architecture
- Changelog
- Glossary
API reference
Guide
Versioning and the sandbox
What we promise about change, how you hear about it before it reaches you, and a key you can test against without spending anything.
The policy
The API has one major version, /v1, in the path. Within it, changes are additive: new routes, new optional request fields, new response fields and new headers. Your code should ignore fields it does not know. We do not rename or remove a field, change its type, or make an optional field required within /v1.
Every answer from the API host and the control plane carries Silicon-Version: the date of the last change to the contract, for example 2026-10-29. Log it with your request ids; it tells you which revision answered. You cannot pin a revision: there is only the current one.
Changes are announced in the changelog, which is also an RSS and JSON feed.
Deprecation and sunset
Something that has to go is deprecated first. From the day it is deprecated, every answer on that route carries these headers, so a log search or a client check finds it long before it stops working:
| Header | Meaning |
|---|---|
| Deprecation: @1793491200 | RFC 9745: when it was deprecated, as seconds since 1970. |
| Sunset: Thu, 01 Apr 2027 00:00:00 GMT | RFC 8594: when it stops working. Set once the date is decided. |
| Link: <...>; rel="deprecation" | Where the change and its replacement are described. rel="sunset" as well once there is a sunset. |
The sunset is at least 90 days after the deprecation. After it, the route answers 410 Gone with the replacement in the error message. Nothing is deprecated today.
Safe retries
The routes that start or stop compute or move money take an Idempotency-Key header. Send a unique value, and the same value when you retry the same request: the first answer comes back with Idempotent-Replayed: true and nothing happens twice.
| Case | Answer |
|---|---|
| Same request, first one finished | The first answer again, with Idempotent-Replayed: true. |
| Same request, first one still running | 409 with Retry-After: 1. |
| A different request | 422: the key was used for a different request. |
| First answer was a 5xx, 408, 409, 425 or 429 | Not kept: the retry runs the request again. |
Keys are kept for 24 hours and are scoped to the credential that sent them. The routes: compute launch and stop, top-up claims, the spend cap, project budgets, invoices, referral codes, operator bonds and refunds, SIL withdrawals, and agent credit lines and repayments. Compute launch also takes an idempotency_key in the body, which keeps working.
Sandbox keys
A sandbox key is an sn_test_ key made with the sandbox option on the API Keys page. It reaches only the sandbox: the API host answers it with deterministic test output and never sends it to a node or a compute provider, and it is never billed. Every answer to it carries Silicon-Sandbox: 1. Sandbox keys are not switched on yet; the option appears once they are.
What it answers
| Route | Answer |
|---|---|
| POST /v1/chat/completions | A reply quoting your last message, streamed or not. max_tokens, stop and stream_options.include_usage are honored. With tools, a user message gets a call of the named (or first) function with placeholder arguments from its schema; a tool result gets text again. |
| POST /v1/embeddings | Unit vectors derived from a hash of each input, the same every time. dimensions (default 64) and encoding_format are honored. |
| GET /v1/models | sandbox-chat and sandbox-embed. |
| /v1/compute/* | One sandbox offer per workload at a price of zero. Instances start, run, log and stop like real ones, in memory: a restart of the API host forgets them. |
| Everything else | 403, naming the sandbox. |
Validation is the real one: a missing model, empty messages, an out of range temperature or n above 1 get the same 400 as on a live key. Use it in CI, for the compute API and the GitHub Action, and to check client code before you add balance.