Skip to main content
POST /api/v1/cloud/sessions Creates a Session. The new Session starts in the idle state; send events to begin work.

​
Headers

HeaderRequiredDescription
AuthorizationYesBearer $QODER_PAT
Content-TypeYesapplication/json

​
Request body

FieldTypeRequiredDescription
agentstring or objectYesAgent ID, or an object with id, mandatory type: "agent", and optional version. See Agent reference
environment_idstringYesExisting Environment ID with the env_ prefix
titlestring | nullNoSession title
metadataobjectNoSession metadata
environment_variablesstringNoSession-level environment variables to inject into the agent runtime, formatted as a single string of KEY=VALUE pairs separated by ; (or newlines, full-width ； is also accepted). The response field is a JSON object — see Validation. Not supported on self-hosted environments
incremental_streaming_enabledbooleanNoEnables incremental streaming events for this Session. Default: false. When true, list and stream event APIs expose incremental agent events such as agent.message_start, agent.content_block_delta, and agent.message_stop in addition to the final full events
resourcesarrayNoFile, GitHub repository, or Memory Store resources to attach at creation
vault_idsarrayNoVault IDs available to the Session
Legacy request fields environment, delta_flush_interval_ms, vaults, and memory_store_ids are not supported. Use resources[] with type: "memory_store" to attach Memory Stores.

​
Environment variables validation

Names must match [A-Za-z_][A-Za-z0-9_]*. Reserved names SERVER_ENDPOINT, USER_ID, WORK_DIR, and any name with the CAW_ or QODER_ prefix are rejected. Each value cannot exceed 8 KiB; the entire field cannot exceed 64 entries or 64 KiB combined. Duplicate keys, malformed entries, or use on self-hosted environments return 400 invalid_request_error.

​
Resource parameters

Resource typeRequired fieldsOptional fields
filetype, file_idmount_path
github_repositorytype, url, authorization_tokenmount_path, checkout
memory_storetype, memory_store_idaccess, instructions
Self-hosted environments currently do not support Session resources.

​
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", "type": "agent", "version": 2},
    "environment_id": "env_019e2590d33f711fabf42f2857cecd8a",
    "title": "Code review session",
    "metadata": {"purpose": "review"},
    "environment_variables": "FEATURE_FLAG=on;LOG_LEVEL=debug",
    "incremental_streaming_enabled": true,
    "resources": [
      {
        "type": "github_repository",
        "url": "https://github.com/your-org/your-repo",
        "mount_path": "/data/workspace/your-repo",
        "authorization_token": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      },
      {
        "type": "memory_store",
        "memory_store_id": "memstore_019eed05b61e78cea61bfd366e072878",
        "access": "read_write",
        "instructions": "Use this memory for long-lived project context."
      }
    ],
    "vault_ids": ["vault_019eed0519807975983d0ffc4b4b4c79"]
  }'

​
Example response

HTTP 200 OK Returns a Session object. 
{
  "id": "sess_019e3bb1e8c171fd9abbb1477ffb84cc",
  "type": "session",
  "agent": {
    "id": "agent_019e390add9f7bac9b6cc806db46fcbd",
    "type": "agent",
    "name": "doc-test-agent",
    "description": "Documentation example Agent",
    "model": {
      "id": "ultimate",
      "effective_context_window": 200000
    },
    "system": "You are a test assistant.",
    "tools": [],
    "skills": [],
    "mcp_servers": [],
    "version": 2
  },
  "environment_id": "env_019e2590d33f711fabf42f2857cecd8a",
  "title": "Code review session",
  "status": "idle",
  "metadata": {"purpose": "review"},
  "environment_variables": {"FEATURE_FLAG": "on", "LOG_LEVEL": "debug"},
  "incremental_streaming_enabled": true,
  "resources": [],
  "vault_ids": ["vault_019eed0519807975983d0ffc4b4b4c79"],
  "deployment_id": null,
  "outcome_evaluations": [],
  "stats": {"active_seconds": 0, "duration_seconds": 0},
  "archived_at": null,
  "created_at": "2026-05-18T15:26:15.747298Z",
  "updated_at": "2026-05-18T15:26:15.747298Z"
}

​
Errors

HTTPTypeTrigger
400invalid_request_errorMalformed request, missing required field, unsupported legacy field, or invalid resource
401authentication_errorPAT invalid or expired
404not_found_errorAgent, Environment, file, Memory Store, or Vault does not exist
409invalid_request_errorA referenced file is not ready, or resource paths/IDs conflict
HTTP 400 Bad Request 
{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "invalid_request_error",
    "message": "Field 'agent' is required."
  }
}
HTTP 404 Not Found 
{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "not_found_error",
    "message": "Agent 'agent_does_not_exist_0000000000000000000000000000' was not found."
  }
}
Note: an agent value without the agent_ prefix (or an environment_id without the env_ prefix) is also resolved to a 404 not_found_error rather than a 400. See Errors for the full error envelope.

Start a session

Run an agent against an environment as a stateful conversation.