The Jio client uses a small JSON control API plus an upgraded SSH stream. The API is experimental; route names and schemas can change before a stable release.
Authentication
Send the operator-issued key as a bearer token:
Authorization: Bearer <JIO_API_KEY>Use HTTPS for remote HTTP endpoints. The CLI also supports custom endpoints and CA certificates. Never put the bearer key in browser code or logs.
Client-facing routes
| Method | Route | Purpose |
|---|---|---|
GET | /v0/health | Discover session-create capabilities and sizes |
POST | /v0/sessions | Create a session |
GET | /v0/sessions/{id} | Read current session state |
POST | /v0/sessions/{id}/stop | Stop compute and retain files |
POST | /v0/sessions/{id}/start | Start a stopped session |
DELETE | /v0/sessions/{id} | Destroy a session |
GET | /v0/sessions/{id}/ssh | Upgrade to the authenticated SSH stream |
GET | /v1/usage | Read account limits and reservations |
GET | /v1/sessions?after={cursor} | List account sessions |
Standalone Core and hosted control-plane endpoints expose different subsets. The
CLI probes capabilities and returns unsupported when an endpoint lacks a route.
Create a session
The hosted compatibility request contains a caller-generated session ID, one strict Ed25519 public key, and a size:
{
"session_id": "0123456789abcdef0123456789abcdef",
"client_public_key": "ssh-ed25519 AAAA...",
"size": "medium"
}Send Prefer: respond-async to allow a 202 response while creation continues:
{
"session_id": "0123456789abcdef0123456789abcdef",
"state": "starting"
}Poll GET /v0/sessions/{id} until the session is ready. The official client also
validates that returned identity, size, template, resource, network, storage, and
timing fields are internally consistent.
Lifecycle fencing
Start and stop require the latest numeric generation in If-Match and a unique
Idempotency-Key:
If-Match: 3
Idempotency-Key: 7f6d2d7f0cb14a2da119fd7f82b84277If the generation changed, refresh the session instead of blindly retrying. Treat
503 responses that say the outcome may be unknown as reconciliation events:
read the session or account list before issuing another mutation.
Direct use
Prefer the CLI or pin the source client library. A direct HTTP integration must also implement key generation, SSH host-key verification, upgraded stream access, idempotency, generation fencing, polling, bounded responses, and cleanup.