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 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 :<environment> (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.