Create New Session

Precreate a session

Use a registered session database and supply db_id when multiple database IDs are available. Choose the session type and matching component ID for the database that the subsequent run will use. For the example agent server:

curl --fail-with-body 'http://127.0.0.1:7777/sessions?type=agent' \
  -H "Authorization: Bearer $OS_SECURITY_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"agent_id":"reference-agent","session_name":"Planning","session_state":{"phase":"start"}}'

Reuse the returned session_id in that agent's run request. Authenticated request identity overrides the body's user_id. An existing supplied session ID returns 409 instead of overwriting it. Session state is stored within session data; reserved runtime metadata is scrubbed.

POST/sessions

Create a new empty session with optional configuration. Useful for pre-creating sessions with specific session_state, metadata, or other properties before running any agent/team/workflow interactions. The session can later be used by providing its session_id in run requests.

Authorization

HTTPBearer
AuthorizationBearer <token>

In: header

Query Parameters

type?SessionType

Type of session to create (agent, team, or workflow)

Default"agent"

Value in

  • "agent"
  • "team"
  • "workflow"
db_id?|

Database ID to create session in

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Session configuration data

Default{}

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl --request POST 'https://example.com/sessions' \  --header 'Content-Type: application/json' \  --data-raw '{}'
{  "user_id": "user-123",  "agent_session_id": "new-session-id",  "session_id": "new-session-id",  "session_name": "New Session",  "session_state": {    "key": "value"  },  "metadata": {    "key": "value"  },  "agent_id": "agent-1",  "created_at": "2025-10-21T12:00:00Z",  "updated_at": "2025-10-21T12:00:00Z"}