Skip to main content
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.

​
Headers

HeaderRequiredDescription
AuthorizationYesBearer $QODER_PAT
Content-TypeYesapplication/json

​
Request body

FieldTypeRequiredDescription
agentobjectYesAgent reference object: {"id": "<agent_id>", "version": <int>}. A plain string "agent_xxx" is accepted for backward compatibility (uses latest version) but not recommended.
environment_idstringYesEnvironment ID with the env_ prefix
titlestringNoSession title
metadataobjectNoCustom metadata key-value pairs
delta_flush_interval_msintegerNoDelta flush interval in milliseconds. Range 50–5000, default 100
memory_store_idsarrayNoList of associated Memory Store IDs
resourcesarrayNoList of file resources (gated at M3)
vault_idsarrayNoList of Vault IDs (gated at M3)

​
Example request

curl -X POST https://api.qoder.com/api/v1/cloud/sessions \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {"id": "agent_019e390add9f7bac9b6cc806db46fcbd", "version": 2},
    "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": "doc-test-agent",
    "description": "Documentation example Agent",
    "model": "ultimate",
    "instructions": "You are a test assistant.",
    "system": "You are a test assistant.",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
      }
    ],
    "mcp_servers": [
      {
        "type": "url",
        "name": "weather-service",
        "url": "https://mcp.example.com/sse"
      }
    ],
    "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

FieldTypeDescription
idstringSession unique identifier with the sess_ prefix
typestringAlways "session"
agent_idstringAssociated Agent ID
agentobjectFull Agent object (includes name, model, tools, etc.)
environment_idstringAssociated Environment ID
titlestringSession title
statusstringSession status: idle, processing, canceling
resourcesarrayAssociated file resources
vault_idsarrayList of associated Vault IDs
memory_store_idsarrayList of associated Memory Store IDs
usageobjectToken usage statistics
created_atstringCreation time (ISO 8601)
updated_atstringLast update time (ISO 8601)

​
Errors

HTTPTypeTrigger
400invalid_request_errorMalformed request body or missing required field
401authentication_errorPAT invalid or expired
404not_found_errorAgent or Environment does not exist
See Errors for the full error envelope.