> ## Documentation Index > Fetch the complete documentation index at: https://docs.reactor.inc/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > To build and serve your own model, start at /deploy/development/quickstart and /deploy/development/overview. Deploying is the default path: reactor init scaffolds a workspace, reactor auth login authenticates, and reactor model deploy registers the model, publishes the release with the weights/ folder, and activates it on Reactor's GPUs, in one command from that workspace. Docker must be running, because the publish step builds the image locally. Bump model.version in reactor.yaml before redeploying a change, because a release that already has an image is reactivated as it is. Deployment access is granted per account, so contact team@reactor.inc if a deploy is refused. Every key in reactor.yaml is documented at /deploy/platform/reactor-yaml. Model code imports reactor_runtime; Python client code imports reactor_sdk. The runtime overview explains the model interface. Running the model on your own machine with reactor run is optional and needs a GPU you attach with --gpus; /deploy/development/local-testing covers that loop and pairs a complete brightness model with a Python client test in a separate brightness-test workspace. > Reactor hosts multiple models, each with its own connect slug (modelName) and command/event schema. The video model catalog — slug, typed SDK package, and links to its schema — is at /model-api-reference/overview. Robotics policy documentation starts at /robotics/overview; The launch policies are Cosmos Nano DROID (/robotics/cosmos/nano-policy-droid/), DreamZero DROID (/robotics/dreamzero/droid/), and FLUX Action DROID (/robotics/flux-action/droid/), organized by model family and embodiment. Some models expose one slug per experience (e.g. HappyOyster); always take the slug from the model's own pages, never guess it. > Fastest path to a working app: `npx create-reactor-app my-app --model=` scaffolds a complete app with secure auth wired up. Typed TypeScript SDKs are published as @reactor-models/; Python uses the base reactor-sdk package. > Auth: exchange an API key (rk_...) for a JWT via POST https://api.reactor.inc/tokens from your server. Never put the API key in client-side code. > Append .md to any docs URL for clean Markdown. Search these docs via the MCP server at https://docs.reactor.inc/mcp. # Create a session > Starts a session on a model and places it on an instance that serves that model. The response returns at once, in state `CREATED`; attach a client afterwards with the [Transport](#tag/Transport) endpoints. Callable with an API key or a session token by a `developer` (or Reactor staff). The account must also be allowed to use the model: it owns the model, the model is public, or the owner granted the account access. A model the caller may not use answers exactly like a model that does not exist (`404`), so the answer never shows that a private model exists. **Model names.** `model.name` must be a full `owner/name`, such as `reactor/helios`. A bare name is refused with `404` and a hint naming the full name. Append `:` (the environment's name or ID) to open a session on a non-production environment of a model your account owns or was granted, for example `your-org/your-model:staging`. `:production` and no suffix both run on the production deployment. A suffix that is a release version, such as `:1.2.3`, is not an environment and stays part of the name. **`extra_configs`.** Every value is a string, and the model receives every key unchanged. The Reactor API itself reads only `generation` and `file_ids`: - `starting_input`: a JSON-encoded object, `{"state": {...}, "commands": [{"command": "...", "data": {...}}]}`, that the model applies when the session starts, before any client connects. Each `state` key `k` becomes the command `set_k` with data `{"k": value}`; `commands` then run in order. The model's runtime validates it, not this endpoint: invalid JSON is ignored, a wrong shape makes the session close without running (`ended.reason` `START_REFUSED`), and a refused command does not stop the others. `201` is returned in every case. - `steps`: a positive integer, such as `"1"`. The session closes after this many completed steps. A streamed session with `steps` runs, and is billed, with no client connected. - `generation`: `"streamed"` (the default) or `"stepped"`. Any other value, including a different spelling, is a `400` and creates no session. The mode the model actually runs in appears as `generation` on `GET /sessions/{session_id}`. - `file_ids`: a JSON-encoded list of up to 16 lowercase file IDs from `POST /files`. The model receives each file under `upload_id` equal to its `file_id`. Every file must exist, belong to your account, not be expired, and have its bytes uploaded, or the request is a `400` that names the file. **Limits.** Session quotas (`concurrent_sessions`, `sessions_per_minute`, and their per-model variants) answer `429 quota_exceeded`. When no instance of the model can take the session, the answer is also `429`; retry when capacity frees up. An account with no funds answers `402`, except for a session on a model the account owns. ## OpenAPI ````yaml /openapi.yaml post /sessions openapi: 3.1.0 info: title: Reactor Platform API version: '1' description: > The Reactor Platform API mints session tokens, starts and operates sessions, negotiates media transport, and manages your account, models, and deployments. Every path is relative to `https://api.reactor.inc`. See the [Introduction](/platform-api/introduction) and [Authentication](/platform-api/authentication) pages for credentials, versioning, and errors. contact: name: Reactor support url: https://docs.reactor.inc/resources/support servers: - url: https://api.reactor.inc description: Production security: - apiKey: [] tags: - name: Status description: >- Public, unauthenticated endpoints for service health, pricing, and the values the API accepts. - name: Tokens description: > Exchange a long-lived API key for a short-lived, session-scoped token that a client can use to create and operate sessions without holding the key. - name: Users description: > Read your own user record, your account's roster, and account memberships, and manage member roles as an account admin. - name: API Keys description: >- Revoke API keys. Use the [Dashboard](https://reactor.inc/dashboard) to list or create keys. The CLI can also create a key with `reactor auth login`. - name: Sessions description: > Create, inspect, and end sessions. A session holds one running model for one client application; media and messages flow over a transport you attach to it afterwards. - name: Transport description: > Attach a client to a session. WebRTC signaling carries ICE servers, SDP, and ICE candidates; a LiveKit room connection lets the session join a room you host. - name: Files description: > Upload files a model reads, either for one running session or ahead of time for sessions you have not started yet. - name: Recordings description: > Fetch the recorded video of a session as an HLS playlist, during the session or after it ends. - name: Accounts description: > Read and manage the account your credential acts in: its name and slug, its credit balance, its effective quotas, and its accelerator capacity. - name: Invitations description: > Invite people to your account by email, and manage pending invitations. The recipient accepts from the emailed link while signed in to the dashboard. - name: Usage description: > List the sessions your account has run, filter them by status, date, model, or API key, and read exact session totals for a date window. - name: Models description: > Register, read, update, and delete the models your account serves, and list the models you can use. The `reactor model` CLI commands are built on these endpoints. - name: Releases description: > Register a model's versioned releases, push their container image, and deploy a release with a per-region instance plan. - name: Model Weights description: > Upload and inspect the weights bundle of a release: single-request uploads, multipart uploads for large files, and the server-side finalize that marks a bundle complete. - name: Model Schemas description: > Attach an OpenAPI schema to a release that describes the model's commands, messages, and tracks. Schemas of public models are readable without credentials. - name: Model Access description: | Share a private model with other accounts, one environment at a time. - name: Projects description: > A project is the deploy identity of a model you serve on Reactor. Each model is one project, with its own UUID. Creating a project also creates its `production` environment. - name: Environments description: > An environment is a named deploy target of a project, such as `production` or `staging`. Each write to an environment creates its next revision, and the newest revision is what the environment runs. Environment access grants let another account start sessions on one environment. - name: Revisions description: > A revision is an immutable, numbered snapshot of one environment: its model image, weights, resources, instances, and variables. An environment's revisions, newest first, are its change log. - name: Images description: > Model images are the container images pushed to your model's repository, named by digest. Experimental: this API can change without notice. - name: Weight Sets description: > A weight set is a version-2 weights bundle, named by its set digest. Push the files, then put the manifest. Available when weight sets are enabled for your account. Experimental: this API can change without notice. - name: Tags description: > A tag is a movable name on one model image or one weight set of a project. A release of the model is a read-only tag. Experimental: this API can change without notice. paths: /sessions: post: tags: - Sessions summary: Create a session description: > Starts a session on a model and places it on an instance that serves that model. The response returns at once, in state `CREATED`; attach a client afterwards with the [Transport](#tag/Transport) endpoints. Callable with an API key or a session token by a `developer` (or Reactor staff). The account must also be allowed to use the model: it owns the model, the model is public, or the owner granted the account access. A model the caller may not use answers exactly like a model that does not exist (`404`), so the answer never shows that a private model exists. **Model names.** `model.name` must be a full `owner/name`, such as `reactor/helios`. A bare name is refused with `404` and a hint naming the full name. Append `:` (the environment's name or ID) to open a session on a non-production environment of a model your account owns or was granted, for example `your-org/your-model:staging`. `:production` and no suffix both run on the production deployment. A suffix that is a release version, such as `:1.2.3`, is not an environment and stays part of the name. **`extra_configs`.** Every value is a string, and the model receives every key unchanged. The Reactor API itself reads only `generation` and `file_ids`: - `starting_input`: a JSON-encoded object, `{"state": {...}, "commands": [{"command": "...", "data": {...}}]}`, that the model applies when the session starts, before any client connects. Each `state` key `k` becomes the command `set_k` with data `{"k": value}`; `commands` then run in order. The model's runtime validates it, not this endpoint: invalid JSON is ignored, a wrong shape makes the session close without running (`ended.reason` `START_REFUSED`), and a refused command does not stop the others. `201` is returned in every case. - `steps`: a positive integer, such as `"1"`. The session closes after this many completed steps. A streamed session with `steps` runs, and is billed, with no client connected. - `generation`: `"streamed"` (the default) or `"stepped"`. Any other value, including a different spelling, is a `400` and creates no session. The mode the model actually runs in appears as `generation` on `GET /sessions/{session_id}`. - `file_ids`: a JSON-encoded list of up to 16 lowercase file IDs from `POST /files`. The model receives each file under `upload_id` equal to its `file_id`. Every file must exist, belong to your account, not be expired, and have its bytes uploaded, or the request is a `400` that names the file. **Limits.** Session quotas (`concurrent_sessions`, `sessions_per_minute`, and their per-model variants) answer `429 quota_exceeded`. When no instance of the model can take the session, the answer is also `429`; retry when capacity frees up. An account with no funds answers `402`, except for a session on a model the account owns. operationId: createSession parameters: - $ref: '#/components/parameters/ApiVersion' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SessionCreateRequest' examples: basic: summary: Start a session value: model: name: reactor/helios client_info: sdk_version: 3.4.0 sdk_type: js environment: summary: Start a session on a staging environment value: model: name: your-org/your-model:staging startingInput: summary: Run one step from a file, with no client connected value: model: name: reactor/fast-h3 extra_configs: file_ids: '["3f2b9c1e-6a1d-4c7e-9b2a-0d5e8f1a2b3c"]' starting_input: >- {"state": {"seed": 42}, "commands": [{"command": "enqueue", "data": {"starting_frame": {"upload_id": "3f2b9c1e-6a1d-4c7e-9b2a-0d5e8f1a2b3c"}}}]} steps: '1' stepped: summary: Start a stepped session value: model: name: your-org/your-model extra_configs: generation: stepped responses: '201': description: The session was created. headers: Reactor-API-Version: description: The server's current API version. schema: type: string content: application/json: schema: $ref: '#/components/schemas/SessionCreateResponse' example: session_id: 85ded560-014c-42df-8902-89dfbca8fa00 model: name: reactor/helios version: 1.4.0 server_info: server_version: 1.5.11 state: CREATED cluster: 054e2495-c685-450f-9ceb-57f185b7300a zone: us-west '400': description: > The body is not valid JSON, is larger than 1 MiB, or has no `model.name`; `extra_configs.generation` is not `streamed` or `stepped`; or `extra_configs.file_ids` is malformed, names more than 16 files, or names a file that does not exist, belongs to another account, has expired, or has no uploaded bytes. No session is created. content: application/json: schema: $ref: '#/components/schemas/Error' '401': $ref: '#/components/responses/Unauthorized' '402': description: > The account cannot pay for the session. `error` is `credits_depleted` (add funds), `billing_not_setup` (finish billing setup), or `billing_status_unknown`. `url` links to the billing page. content: application/json: schema: $ref: '#/components/schemas/SessionBillingError' example: error: credits_depleted message: Your balance is depleted. Please add funds to continue. url: https://www.reactor.inc/dashboard/account?section=billing '403': description: > The caller may not start this session: the body sets `session_id` (the server assigns it); the account is inactive or still on the waitlist; the account's session quota is zero; or, for a session token, the model or environment is outside the token's scope or the token's session limit is reached. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: > The model does not exist or the caller may not use it, the name is bare (the message names the full `owner/name`), or the named environment does not exist. When an environment suffix is present, `error` is `not_found` and `resource` is `model` or `environment`. content: application/json: schema: $ref: '#/components/schemas/Error' examples: environment: summary: Unknown environment value: error: not_found message: environment "nope" not found resource: environment bareName: summary: Bare model name value: error: 'model "helios" needs its org: did you mean reactor/helios?' '426': description: > `Reactor-API-Version` is older than the oldest version the server supports. content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: > A session quota was hit (`error` is `quota_exceeded`, with the quota's type, limit, and current usage), or no instance of the model can take the session right now (`error` is a sentence). When `Retry-After` is present, wait at least that long. Each retry counts against `sessions_per_minute`. headers: Retry-After: schema: type: integer description: Seconds to wait before retrying when known. content: application/json: schema: anyOf: - $ref: '#/components/schemas/SessionQuotaExceededError' - $ref: '#/components/schemas/Error' examples: quota: summary: Concurrent-session quota value: error: quota_exceeded message: 'quota exceeded: concurrent_sessions (limit=5, current=5)' quota_type: concurrent_sessions limit: 5 current: 5 model: reactor/helios capacity: summary: No capacity value: error: >- no available capacity: model instances are busy; retry shortly '501': description: > `Reactor-API-Accept-Version` asks for a newer API version than the server supports. content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: > A check the request depends on could not run: capacity state (`Retry-After: 1`), quota (`quota_check_failed`), billing (`billing_check_failed`), file lookup, or model lookup (`unavailable`). No session was created. Retry with backoff. headers: Retry-After: schema: type: integer description: Seconds to wait before retrying when set. content: application/json: schema: $ref: '#/components/schemas/Error' security: - apiKey: [] - sessionToken: [] components: parameters: ApiVersion: name: Reactor-API-Version in: header required: false description: >- The API protocol version the client speaks. Currently `1`. Older versions than the server's minimum get `426`. schema: type: string example: '1' schemas: SessionCreateRequest: type: object required: - model properties: model: $ref: '#/components/schemas/SessionModelRef' client_info: $ref: '#/components/schemas/SessionClientInfo' extra_configs: $ref: '#/components/schemas/SessionExtraConfigs' SessionCreateResponse: type: object required: - session_id - state properties: session_id: type: string format: uuid model: $ref: '#/components/schemas/SessionModel' server_info: $ref: '#/components/schemas/SessionServerInfo' state: $ref: '#/components/schemas/SessionState' cluster: type: string description: An opaque placement ID. Not an address. zone: type: string description: >- The Reactor region serving the session, such as `us-west`. Omitted when unknown. Error: type: object required: - error properties: error: type: string description: >- A stable error code (for example `not_found`) on newer routes, or a sentence on older ones. When `message` is present, branch on `error`. message: type: string description: >- A human-readable explanation. Do not parse it; its wording may change. resource: type: string description: The type of the resource a `not_found` refers to. reason: type: string description: >- A more specific cause for `failed_precondition`, `aborted`, and some `invalid_request` errors. SessionBillingError: type: object required: - error properties: error: type: string enum: - credits_depleted - billing_not_setup - billing_status_unknown message: type: string url: type: string format: uri description: The billing page where the account can fix this. SessionQuotaExceededError: type: object required: - error - quota_type - limit - current properties: error: type: string enum: - quota_exceeded message: type: string quota_type: type: string enum: - concurrent_sessions - concurrent_sessions_per_model - sessions_per_minute - sessions_per_minute_per_model - connections_per_session limit: type: integer current: type: integer model: type: string description: The requested model name. hint: type: string description: >- Guidance when an account-wide limit is hit while a per-model quota of the same kind exists. retry_after_seconds: type: integer description: >- Seconds until a rate quota admits another session. Matches `Retry-After`. SessionModelRef: type: object required: - name properties: name: type: string description: > The full `owner/name` of the model, optionally followed by `:` (an environment's name or ID). example: reactor/helios SessionClientInfo: type: object description: The SDK the client uses. Optional, and recorded for diagnostics. properties: sdk_version: type: string description: The SDK's version, as `major.minor.patch`. example: 3.4.0 sdk_type: type: string description: The SDK's language. enum: - js - python - cpp - swift - java - android SessionExtraConfigs: type: object description: > Free-form string values passed to the model unchanged. The keys below have defined meanings; any other key is for the model to interpret. additionalProperties: type: string properties: starting_input: type: string description: > A JSON-encoded object with optional `state` (an object) and `commands` (a list of `{"command": "...", "data": {...}}`). Applied when the session starts. steps: type: string description: >- A positive integer, such as `"1"`. The session closes after this many completed steps. generation: type: string enum: - streamed - stepped default: streamed description: How the model generates frames. file_ids: type: string description: >- A JSON-encoded list of up to 16 lowercase file IDs from `POST /files`. SessionModel: type: object properties: name: type: string description: The model name, as requested (including any environment suffix). example: reactor/helios version: type: string description: The model's version. example: 1.4.0 SessionServerInfo: type: object properties: server_version: type: string description: The Reactor API's version. example: 1.5.11 SessionState: type: string description: The session's lifecycle state. enum: - CREATED - PENDING - WAITING - SUSPENDED - ACTIVE - INACTIVE - CLOSED responses: Unauthorized: description: The credential is missing, invalid, or expired. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: apiKey: type: http scheme: bearer description: >- A Reactor API key (`rk_...`), sent as `Authorization: Bearer rk_...`. Keep it on a server. sessionToken: type: http scheme: bearer bearerFormat: JWT description: >- A session-scoped JWT minted by `POST /tokens`. Accepted on `/sessions` and `/clips` only. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.