Create a new session

curl --request POST \
  --url https://api.example.com/sessions/ \
  --header 'Content-Type: application/json' \
  --header 'x-user-id: <x-user-id>' \
  --data '
{
  "agent_id": "<string>",
  "workspace_id": "<string>",
  "name": "<string>",
  "chat_model_config": {
    "type": "<string>",
    "credential_id": "<string>",
    "model": "<string>",
    "parameters": {}
  },
  "fallback_chat_model_config": {
    "type": "<string>",
    "credential_id": "<string>",
    "model": "<string>",
    "parameters": {}
  }
}
'

{
  "session_id": "<string>"
}

sessions

Create a new session

Create (or resume) a session for a given agent and workspace.

At most one session exists per (user_id, agent_id, workspace_id) triple — a second call with the same triple updates the existing session rather than creating a duplicate.

Args: body (CreateSessionRequest): Agent, workspace, and model config. user_id (str): Injected authenticated user ID. storage (StorageBase): Injected storage backend.

Returns: CreateSessionResponse: The session identifier.

Raises: HTTPException: 404 if the agent or credential does not exist or does not belong to the authenticated user.

POST

sessions

Create a new session

curl --request POST \
  --url https://api.example.com/sessions/ \
  --header 'Content-Type: application/json' \
  --header 'x-user-id: <x-user-id>' \
  --data '
{
  "agent_id": "<string>",
  "workspace_id": "<string>",
  "name": "<string>",
  "chat_model_config": {
    "type": "<string>",
    "credential_id": "<string>",
    "model": "<string>",
    "parameters": {}
  },
  "fallback_chat_model_config": {
    "type": "<string>",
    "credential_id": "<string>",
    "model": "<string>",
    "parameters": {}
  }
}
'

{
  "session_id": "<string>"
}

Headers

x-user-id

string

required

Caller's user ID. Temporary header-based identity; will be replaced by JWT auth.

Body

application/json

Request body for creating a new session.

agent_id

string

required

Agent this session belongs to.

workspace_id

string | null

Workspace this session belongs to.

name

string | null

Display name. Defaults to current datetime if omitted.

chat_model_config

ChatModelConfig · object

Model provider and parameters. Can be set later via PATCH.

Show child attributes

fallback_chat_model_config

ChatModelConfig · object

Fallback model used when the primary model fails. Can be set later via PATCH.

Show child attributes

Response

Successful Response

Response body after creating a session.

session_id

string

required

Server-assigned session identifier.

List sessions for an agent Delete a session