Create a session

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 <PAT or SAT>`
`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
`budget`	object \| null	No	Total session budget (model and sandbox credits), e.g. `{"type":"limit","max_credit_cost":"100.00"}`. Omit it or pass `null` to create the Session without a limit. See Session budget.
`title`	string \| null	No	Session title
`metadata`	object	No	Session metadata
`environment_variables`	object	No	Session-level environment variables to inject into the agent runtime, provided as a map of string keys to string values (`{"NAME":"value"}`). See Validation. Not supported on self-hosted environments
`resources`	array	No	File, GitHub, generic Git, or Memory Store resources to attach at creation
`vault_ids`	array	No	Vault IDs available to the Session

Use resources[] with type: "memory_store" to attach Memory Stores.

Environment variables validation

Names must match [A-Za-z_][A-Za-z0-9_]*, and all values must be strings. 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 map cannot exceed 64 entries or 64 KiB combined. Invalid keys or values, 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`
`git_repository`	`type`, `url`	`password`, `mount_path`, `checkout`
`memory_store`	`type`, `memory_store_id`	`access`, `instructions`

Use github_repository for github.com; its existing username/token-optional behavior is preserved. Use git_repository for GitLab, Gitee, Bitbucket, and other HTTP(S) Git services. Public repositories need neither a username nor a password, for example https://gitlab.com/group/repo.git. For private repositories or push, include the provider username in the URL and set password to the account password or the Access Token/PAT required by the provider. Username and password must be provided together.

{
  "type": "git_repository",
  "url": "https://username@gitlab.com/group/repo.git",
  "password": "<PASSWORD_OR_ACCESS_TOKEN>",
  "checkout": {"type": "branch", "name": "main"}
}

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",
  "usage": {"model_credits": 0, "sandbox_runtime_credits": 0, "total_credits": 0}
}

Errors

HTTP	Type	Trigger
400	`invalid_request_error`	Malformed request, missing required field, unsupported field, or invalid resource
401	`authentication_error`	PAT or SAT 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.

Start a session

Run an agent against an environment as a stateful conversation.

​Headers

​Request body

​Environment variables validation

​Resource parameters

​Example request

​Example response

​Errors

​Related