Create a session

Create a new Session bound to an Agent and Environment.

POST /api/v1/cloud/sessions

Creates a Session. The new Session starts in the idle state; send events to begin work.

Headers

Header	Required	Description
Authorization	Yes	Bearer $QODER_PAT
Content-Type	Yes	application/json

Request body

Field	Type	Required	Description
agent	string or object	Yes	Agent ID, or an object with id, mandatory type: "agent", and optional version. See Agent reference
environment_id	string	Yes	Existing Environment ID with the env_ prefix
title	string | null	No	Session title
metadata	object	No	Session metadata
environment_variables	string	No	Session-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
resources	array	No	File, GitHub repository, or Memory Store resources to attach at creation
vault_ids	array	No	Vault 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 type	Required fields	Optional fields
file	type, file_id	mount_path
github_repository	type, url, authorization_token	mount_path, checkout
memory_store	type, memory_store_id	access, 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",
    "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"},
  "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

HTTP	Type	Trigger
400	invalid_request_error	Malformed request, missing required field, unsupported legacy field, or invalid resource
401	authentication_error	PAT invalid or expired
404	not_found_error	Agent, Environment, file, Memory Store, or Vault does not exist
409	invalid_request_error	A 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.

Related

Start a session

Run an agent against an environment as a stateful conversation.