Using the API
Everything the console and the CLI do goes through the same HTTP API, so you can do it from your own code too.
Hosts
| Host | Use it for |
|---|---|
https://api.sandscale.dev |
The default. It routes to the region of your request and defaults to the United States. |
https://api.us.sandscale.dev |
The United States, directly. |
https://api.eu.sandscale.dev |
Europe, directly, once Sandscale opens there. |
Paths start with /api/v1. Sign-in endpoints (/oauth2/...) and the discovery documents under /.well-known/ sit at the root of the same host. See Regions for what is global and what lives in one region.
A first request
Create an API key in the console under your account settings, then send it as a bearer token:
export SANDSCALE_API_KEY=nia_...
curl https://api.sandscale.dev/api/v1/sandbox/instances \
-H "Authorization: Bearer $SANDSCALE_API_KEY"
Authentication covers API keys, signing in as yourself and tokens for agents.
Requests and responses
- Request bodies are JSON. Send
Content-Type: application/json. - Responses are JSON unless an endpoint says otherwise (logs, files and archives are streamed as they are).
- Identifiers are UUIDs. Times are RFC 3339 timestamps in UTC.
- Values in braces in a path, such as
{orgID}, are ones you fill in.{orgID}is your organization’s ID;sandscale whoami --jsonprints it asorg_id. - Every response carries an
X-Request-IDheader. Quote it when you contact support.
Errors
A refused request answers with an HTTP status and a JSON body that names the reason:
{ "error": { "code": "lease_expired", "message": "the lease has ended", "request_id": "..." } }
Program against code, not message. Errors lists the codes you meet on every endpoint, and each endpoint in the API reference lists its own.
Limits
Requests are rate limited and plans set quotas. A 429 answer carries Retry-After. See Limits and retries.
Find an endpoint
The API reference lists every endpoint by area, with its parameters, request and response fields and error codes. It is generated from the server’s code. SDKs for TypeScript and Python are coming soon; until then use any HTTP client, or the CLI, which prints JSON with --json.