> ## 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. # 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](/cloud-agents/api/sessions/schemas#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](#environment-variables-validation). Not supported on self-hosted environments | | `incremental_streaming_enabled` | boolean | No | Enables 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 | | `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 ```bash theme={null} 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](/cloud-agents/api/sessions/schemas#session-object). ```json theme={null} { "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 | 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** ```json theme={null} { "type": "error", "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14", "error": { "type": "invalid_request_error", "message": "Field 'agent' is required." } } ``` **HTTP 404 Not Found** ```json theme={null} { "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](/cloud-agents/api/conventions/errors) for the full error envelope. ## Related Run an agent against an environment as a stateful conversation.