Documentation Index
Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
Use this file to discover all available pages before exploring further.
POST /v1/sessions
Creates a new session. A Session is a conversation container between an Agent and the user. The newly created session is in the idle state and can be triggered by sending events through the Events API.
| Header | Required | Description |
|---|
Authorization | Yes | Bearer $QODER_PAT |
Content-Type | Yes | application/json |
Request body
| Field | Type | Required | Description |
|---|
agent | string | Yes | Agent ID with the agent_ prefix |
environment_id | string | Yes | Environment ID with the env_ prefix |
title | string | No | Session title |
metadata | object | No | Custom metadata key-value pairs |
delta_flush_interval_ms | integer | No | Delta flush interval in milliseconds. Range 50–5000, default 100 |
memory_store_ids | array | No | List of associated Memory Store IDs |
resources | array | No | List of file resources (gated at M3) |
vault_ids | array | No | List of Vault IDs (gated at M3) |
Example request
curl -X POST https://openapi.qoder.sh/api/v1/cloud/sessions \
-H "Authorization: Bearer $QODER_PAT" \
-H "Content-Type: application/json" \
-d '{
"agent": "agent_019e390add9f7bac9b6cc806db46fcbd",
"environment_id": "env_019e2590d33f711fabf42f2857cecd8a",
"title": "My session",
"metadata": {"purpose": "customer-support"}
}'
Example response
HTTP 201 Created
Returns the full Session object.
{
"id": "sess_019e3bb1e8c171fd9abbb1477ffb84cc",
"type": "session",
"agent_id": "agent_019e390add9f7bac9b6cc806db46fcbd",
"agent": {
"id": "agent_019e390add9f7bac9b6cc806db46fcbd",
"type": "agent",
"name": "test-agent-e2e",
"description": "E2E test agent",
"model": "ultimate",
"instructions": "You are a test assistant.",
"system": "You are a test assistant.",
"tools": [],
"mcp_servers": [],
"default_environment": "",
"version": 2,
"created_at": "2026-05-18T03:04:33.952256Z",
"updated_at": "2026-05-18T03:05:28.023697Z"
},
"environment_id": "env_019e2590d33f711fabf42f2857cecd8a",
"title": "My session",
"status": "idle",
"resources": [],
"vault_ids": [],
"memory_store_ids": [],
"usage": {
"input_tokens": 0,
"output_tokens": 0,
"cache_read_input_tokens": 0,
"cache_creation": {
"ephemeral_5m_input_tokens": 0,
"ephemeral_1h_input_tokens": 0
}
},
"created_at": "2026-05-18T15:26:15.747298Z",
"updated_at": "2026-05-18T15:26:15.747298Z"
}
Response fields
| Field | Type | Description |
|---|
id | string | Session unique identifier with the sess_ prefix |
type | string | Always "session" |
agent_id | string | Associated Agent ID |
agent | object | Full Agent object (includes name, model, tools, etc.) |
environment_id | string | Associated Environment ID |
title | string | Session title |
status | string | Session status: idle, processing, cancelled |
resources | array | Associated file resources |
vault_ids | array | List of associated Vault IDs |
memory_store_ids | array | List of associated Memory Store IDs |
usage | object | Token usage statistics |
created_at | string | Creation time (ISO 8601) |
updated_at | string | Last update time (ISO 8601) |
Errors
| HTTP | Type | Trigger |
|---|
| 400 | invalid_request_error | Malformed request body or missing required field |
| 401 | authentication_error | PAT invalid or expired |
| 404 | not_found_error | Agent or Environment does not exist |
