API overview

Base URL, authentication, content type, response shape, and versioning.

The Jettson API is JSON over HTTPS. Every endpoint works from any HTTP client — SDKs optional.

Base URL

text
https://jettson.dev/api/v1

All API endpoints live under /v1. Older versions get notice periods (90+ days) before removal; we'll never delete a v1 endpoint without warning.

Authentication

Every request needs an Authorization: Bearer … header with an API key from /console/api-keys.

bash
curl https://jettson.dev/api/v1/agents \
  -H "Authorization: Bearer $JETTSON_API_KEY"

See Authentication for the full key model.

Content type

Send Content-Type: application/json on every request with a body. Responses are always JSON; we set Content-Type: application/json and you can trust it.

bash
curl -X POST https://jettson.dev/api/v1/agents \
  -H "Authorization: Bearer $JETTSON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task": "..."}'

Response shape

Successful responses are the resource itself or a { data: [...], next_cursor: ... } envelope for paginated lists.

Errors are always wrapped:

json
{
  "error": {
    "code": "rate_limited",
    "message": "Too many spawn requests...",
    "details": { ... }
  }
}

See Errors for the full catalog of codes.

HTTP status codes

| Status | Meaning | | --- | --- | | 200 | Request succeeded; body is the resource or list | | 201 | Resource created (e.g. spawn, memory put) | | 204 | Success, no content (e.g. delete) | | 400 | Validation failed — bad body, bad key, bad query | | 401 | Missing or invalid API key | | 402 | Plan quota exceeded; upgrade or wait for reset | | 404 | Resource not found | | 429 | Rate limit or concurrency limit hit; honor Retry-After | | 500 | Internal error — safe to retry with backoff | | 503 | Provider issue (e.g. Jettson Cloud unavailable); retry with backoff |

Versioning

v1 is stable. Backwards-incompatible changes ship under v2 with a parallel path; we keep v1 running for at least 90 days after a v2 lands, and we'll email account owners well before deprecation.

Additions (new fields, new endpoints) happen in v1 without bumping the version. Your code should ignore unknown response fields gracefully.

What's not in the API yet

| Feature | Status | Ships | | --- | --- | --- | | Programmatic API-key management | Console only today | Q3 | | Webhooks for agent lifecycle | Not yet | Q3 | | Streaming progress (SSE / WebSocket) | Console-only today | Q4 | | Custom tool registration | Not yet | With SDKs | | Node + Python SDKs | curl only today | Next release |

Related