Skip to main content
POST
Requires version 2.0.1 or later of the Archetype platform.

Overview

This endpoint opens a session on one of the available models. A session gets its own values and its own state, on a copy of the model it shares with other callers’ sessions. Queries you send to the session use them. Queries sent straight to /api/inference/query, /chat/completions, or /responses share one stream on the model instead. The session belongs to you. Any role can open one. The call returns 201 once the session can be queried, which can take up to 60 seconds. Don’t retry before the call returns. A session runs until you cancel it, until it sits idle for 30 minutes, or until the copy of the model holding it goes away. That last case happens when the copy is replaced or lost, for example during a platform release. The session then reads failed or cancelled, and it doesn’t come back. When a call on a session returns 409 with code session_not_running, open a new session. You don’t need to read error first.
Each model limits how many sessions are open at once: 16 per organization and 32 per copy of the model. The organization limit counts each model separately, so your sessions on other models don’t count toward it.

Request

string
required
The model to open the session on: its name or any of its other names, 1 to 128 characters. See Available Models.
object
Values the session runs with, by name, in place of the model’s own. Each must be a value the model declares for sessions; any other key returns 422 with code invalid_session_values, naming the key. Values are fixed for the life of the session. Omitted, null, and {} all mean none.

Response

Returns 201 with the session object.

Important Notes

  • 400 means model is missing, empty, or not a string, or the body doesn’t parse.
  • 404 means no model has that name.
  • 422 with invalid_session_values means a key in values can’t be set on a session. Nothing was created.
  • 429 with session_limit_reached means your organization already holds as many open sessions on this model as it may, or every copy of the model is full. Cancel a session or wait for an idle one to end. Nothing was created.
  • 502 with worker_unavailable means the session couldn’t be opened. Nothing was created; retry.
  • 503 with unavailable means no copy of the model can take a session right now, for example while a new copy is starting. Retry. Queries that don’t use a session may still work meanwhile.