HTTP and WebSocket API

Call the API directly when you write a client in another language, or to debug. /openapi.json describes the platform HTTP routes: request and response fields, authentication, required headers, response codes, and downloads. The model server and its binary session stream are separate interfaces, described below. Responses may add fields; clients should ignore fields they do not recognize.

Note: If you use Python, use the Python SDK. It does everything on this page, and checks that each answer matches your request and is fresh.

Two servers

• The platform, at https://yellowandblack.dev, handles keys, credit, and opening and closing sessions. Its routes start with /v1/platform/.
• A model server runs one model. When you open a session, the platform returns the server's address as endpoint, and a session pass as grant. Your robot's data goes to the assigned inference gateway. In the Modal layout the gateway has its own container on the CPU host and forwards observations to a private GPU worker.

Authentication

Send your key to the platform:

Authorization: Bearer yb_live_...

Send the session pass to the model server. Never send it your key.

Authorization: Bearer <grant.token>

A pass works for one session, for about 15 minutes. To renew it, get a new pass with POST .../model-sessions/{id}/renew, then send the new pass to the model server with POST /v1/sessions/{id}/renew. Otherwise the session closes with credential_expired when the old pass runs out.

Errors

Every error has the same shape:

{
  "error": {
    "code": "capacity",
    "message": "The ready model has no free session slot; retry shortly",
    "retry": true
  }
}

Look up code on Errors. retry, when present, says whether repeating the call can help. Some errors also carry rate (the model's current price) or fields (the inputs that were wrong).

Safe retries

POST .../model-sessions needs an Idempotency-Key header: a value you choose, 8 to 128 characters. Send the same value when you retry, so a retry never opens a second session. The same value with a different body fails with idempotency_conflict. A ready new session returns 201; an idempotent replay returns 200. On-demand startup returns 202, including an idempotent replay that is still starting. It has state: starting, startup_by, and no grant. Poll the session URL; once its state is granted, call its /renew route to obtain a scoped grant. DELETE cancels startup and releases its credit hold. Startup is not billed. The Python SDK handles this wait automatically. Replaying a finished session returns its record without a new grant. Deployment creation and checkout also require an Idempotency-Key of 8 to 128 characters.

Platform routes

Paths start with /v1/platform. {project} is your project's ID, from GET /me.

Exports are live reports, not frozen snapshots. Concurrent changes may be absent or reflect different times. Account JSON's exported_at is the generation start. Exports cannot be resumed. Usage CSV succeeds only after the report is fully prepared, up to 8 MiB. To verify receipt, require X-YB-Export-Version: 1, then compare the decoded UTF-8 response bytes with X-YB-Export-Bytes (decimal byte count) and X-YB-Export-SHA256 (lowercase hexadecimal SHA-256). Do not use HTTP Content-Length for decoded-byte verification when compression is present. X-YB-Export-Rows counts CSV records excluding the header; quoted fields may contain newlines. The console performs the byte-count and digest checks before offering a download. Keep the metadata if you need to verify a saved CSV later.

export_too_large returns 422; export_busy, export_timeout and export_failed return 503. These generation errors return JSON instead of CSV. A transfer failure after headers can only interrupt the response: reject any incomplete or unverifiable body. Account JSON does not use these CSV headers.

The body for opening a session:

Model server routes

Paths are relative to the session's endpoint.

The session stream

Each session has one WebSocket. Every message is a binary MessagePack map. NumPy arrays travel as maps with the keys __ndarray__, dtype, shape and data. Each key is a MessagePack binary string, not a text string. dtype is a NumPy type string such as |u1, and data holds the array's bytes in C order. Turn WebSocket compression off. The SDK's codec.py and client.py are the reference implementation.

1. The model server first sends {"type": "ready", ...}, naming the session.
2. You send one observation:

{
    "version": 1,
    "type": "observation",
    "session_id": "ses_...",
    "epoch": 0,  # the episode: goes up by one with each reset
    "sequence": 1,  # goes up by one with each observation in an episode
    "captured_ns": 0,  # your clock when the cameras took the pictures; sent back to you
    "budget_ms": 2000.0,  # time left before the answer is useless
    "observation": {...},  # the model's data format
}

3. The server answers {"type": "actions", "actions": <array>, ...}: the next moves. The answer repeats session_id, epoch, sequence, captured_ns and model_revision. Check each one against your request before using the moves.
4. Or it answers {"type": "error", "code": ..., "sequence": ...}, for example expired (too late) or superseded (replaced by newer data). The session stays open.
5. {"type": "reset", ...} means answers for earlier episodes no longer count. {"type": "closed", "reason": ...} ends the session. Errors lists the reasons.