Create a session

POST /v1/sessions

Creates a session for an agent, optionally with files and a first message.

Without initial_events the session is idle until you send its first message. With one message it starts at once and is running. If the request fails, it returns an error and no session. If the server already created the session’s task in the Context app, it archives it.

Files sent with a mount_path are copied to the agent’s disk, read-only, before the first turn. If a file can’t be copied, the session still runs and the file stays in the session’s inputs/ folder.

The key must have the tasks:create capability. For what each capability allows, see Keys.

Headers

Name	Type	Required	Default	Description
`x-context-owner-user-id`	`string`	No		The ID of the member who owns the session. A service account key can name any active member of its organization. The member owns the session, sees it in the Context app, and must be able to run the agent. A service account key reads and writes only the sessions it created, including those it created for other members. A personal key can name only its own owner. Send this header or `x-context-owner-user-email`, not both. Without either, the key’s owner owns the session. Only this endpoint takes the owner headers.
`x-context-owner-user-email`	`string`	No		The email of the member who owns the session. The same rules apply as for `x-context-owner-user-id`. Send this header or `x-context-owner-user-id`, not both.

Body

Name	Type	Required	Default	Description
`agent`	`string \| {type: "agent", id, version?}`	Yes		An agent ID from List agents. The object form is also accepted. Each agent has one version, so `version` must be `1` or left out. Any other field in the object returns `400`. An unknown agent ID returns `403`, not `404`.
`environment_id`	`string`	Yes		The environment to run the session in: `env_default`. Any other ID returns `404`. See Environments.
`title`	`string`	No	The first 80 characters of the first message, or `API session`	The session’s title. The maximum length is 280 characters.
`initial_events`	`array<object>`	No		The events to start the session with. The array can hold at most one event, and it must be a `user.message`. See Send events. The response can return before the first turn starts. Before you send another message, wait for `session.status_running` on the event stream.
`resources`	`array<object>`	No		The files to give the agent. Each is a `{type: "file", file_id, mount_path}` object, with a `file_id` from Upload a file. Up to 50 files. A request with more than 50 files returns `500` instead of a named `400`, which is a known defect.
`resources[].mount_path`	`string \| null`	No	`null`	Where to put the file on the agent’s disk, read-only. A path under `/workspace/` or `/mnt/session/uploads/` is used as given. Any other absolute path is placed under `/mnt/session/uploads`, so `/data/a.csv` becomes `/mnt/session/uploads/data/a.csv`. The maximum length is 4096 characters, and 255 bytes per path segment. Without it, the file is only in the session’s `inputs/` folder.
`metadata`	`object`	No		Not supported. Omit it or send `{}`. Any other value returns `400`.
`vault_ids`	`array<string>`	No		Not supported. Omit it or send `[]`. Any other value returns `400`.
`budget`	`object \| null`	No		Not supported. Omit it or send `null`. Any other value returns `400`.

Response

Returns 200 with the session object. For every field, see Sessions.

{
  "id": "dd13d728-93e3-440a-874c-4efeb58c97e0",
  "agent": {
    "id": "6f1c2a9e-0d4b-4c57-9a3e-2b7d8e1f4c60",
    "description": "Answers questions about the sales pipeline",
    "execution_identity": {
      "type": "service_account"
    },
    "mcp_servers": [],
    "model": {
      "id": "default"
    },
    "multiagent": null,
    "name": "Research Assistant",
    "skills": [],
    "system": null,
    "tools": [],
    "type": "agent",
    "version": 1
  },
  "archived_at": null,
  "budget": null,
  "created_at": "2026-10-21T01:42:16.079Z",
  "environment_id": "env_default",
  "metadata": {},
  "outcome_evaluations": [],
  "resources": [
    {
      "id": "329409ba-f288-4b44-9c73-14a18150edee",
      "created_at": "2026-10-21T01:41:11.028Z",
      "file_id": "329409ba-f288-4b44-9c73-14a18150edee",
      "mount_path": "inputs/cities.csv",
      "type": "file",
      "updated_at": "2026-10-21T01:41:11.028Z"
    }
  ],
  "stats": {},
  "status": "running",
  "title": "Quarterly city report",
  "type": "session",
  "updated_at": "2026-10-21T01:42:16.079Z",
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "cache_read_input_tokens": 0,
    "cache_creation": {
      "ephemeral_5m_input_tokens": 0,
      "ephemeral_1h_input_tokens": 0
    },
    "active_seconds": 0,
    "list_cost": null
  },
  "vault_ids": []
}

Errors

This endpoint can return these errors as well as the common errors.

Status	`error.type`	Cause and fix
400	`invalid_request_error`	A resource isn’t a file. Send each resource as `{type: "file", file_id}`, with an optional `mount_path`.
400	`invalid_request_error`	A `mount_path` is empty, relative, ends in `/`, holds `.`, `..`, a repeated `/` or a control character, or is too long. Send a normalized absolute path.
400	`invalid_request_error`	More than 100 files have a `mount_path`, two files name the same path, a path sits below another mounted file, or a mounted file is listed twice. Give each mounted file its own path, and list it once.
400	`invalid_request_error`	An owner header is empty, or the request sends both `x-context-owner-user-id` and `x-context-owner-user-email`. Send one header with a member’s ID or email, or omit both so the key’s owner owns the session.
400	`invalid_request_error`	The named owner isn’t an active member of this key’s organization. Check the ID or email.
400	`invalid_request_error`	`initial_events` holds more than one event, or one that isn’t a `user.message`. Send at most one `user.message`, then send the rest with Send events.
400	`invalid_request_error`	The title is over 280 characters. Shorten it.
400	`invalid_request_error`	The body sends non-empty `metadata` or `vault_ids`, a non-null `budget`, or agent overrides (any field in the `agent` object besides `type`, `id` and `version`). Remove them.
400	`invalid_request_error`	A `file_id` names a file a session produced, which can’t be attached. Download it and upload it, then attach the upload.
400	`invalid_request_error`	`Agent "<name>" (<id>) is not in a workspace this session can run in.` The agent isn’t in a workspace the session’s owner works in. Create the agent with `metadata.workspace_id` set to a workspace the owner works in, or pick an agent that is in one.
403	`permission_error`	The key lacks `tasks:create`, or isn’t allowed to run this agent. An unknown agent ID returns the same `403`. Check the agent ID and the key’s capabilities.
403	`permission_error`	A personal key names a member other than its owner. Use a service account key to create sessions for other members, or omit the header.
403	`permission_error`	The named owner can’t run this agent. Pick an agent the member can run, or name another member.
404	`not_found_error`	`environment_id` isn’t `env_default`. Check the ID with List environments.
404	`not_found_error`	A `file_id` isn’t a file this key can read. Check the ID with List files.

Example

curl -sS -X POST "$CONTEXT_BASE_URL/v1/sessions" -H "x-api-key: $CONTEXT_API_KEY" -H "content-type: application/json" \
  -d '{
    "agent": "6f1c2a9e-0d4b-4c57-9a3e-2b7d8e1f4c60",
    "environment_id": "env_default",
    "title": "Quarterly city report",
    "resources": [{"type": "file", "file_id": "329409ba-f288-4b44-9c73-14a18150edee"}],
    "initial_events": [{"type": "user.message", "content": [{"type": "text", "text": "Read the attached cities.csv and name the largest city."}]}]
  }'

session = client.beta.sessions.create(
    agent="6f1c2a9e-0d4b-4c57-9a3e-2b7d8e1f4c60",
    environment_id="env_default",
    title="Quarterly city report",
    resources=[{"type": "file", "file_id": "329409ba-f288-4b44-9c73-14a18150edee"}],
    initial_events=[{"type": "user.message", "content": [{"type": "text", "text": "Read the attached cities.csv and name the largest city."}]}],
)

const session = await client.beta.sessions.create({
  agent: "6f1c2a9e-0d4b-4c57-9a3e-2b7d8e1f4c60",
  environment_id: "env_default",
  title: "Quarterly city report",
  resources: [{ type: "file", file_id: "329409ba-f288-4b44-9c73-14a18150edee" }],
  initial_events: [{ type: "user.message", content: [{ type: "text", text: "Read the attached cities.csv and name the largest city." }] }],
})