> ## 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.

# Session data structures

> Shared Session, resource, event, and thread structures.

## Session object

Returned by create, get, list, update, and archive endpoints.

| Field                   | Type                                           | Description                                                                                                                                                                                                                                          |
| ----------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                    | string                                         | Session ID with the `sess_` prefix                                                                                                                                                                                                                   |
| `type`                  | string                                         | Always `"session"`                                                                                                                                                                                                                                   |
| `agent`                 | object                                         | Agent snapshot used by this Session. See [Session embedded agent](#session-embedded-agent) for the field shape                                                                                                                                       |
| `environment_id`        | string                                         | Environment ID used by this Session                                                                                                                                                                                                                  |
| `status`                | string                                         | Session lifecycle status: `rescheduling`, `running`, `idle`, `canceling`, or `terminated`. `canceling` is a transient state returned by the Cancel endpoint acknowledgement; poll the Session or listen for status events to observe the final state |
| `title`                 | string \| null                                 | Session title                                                                                                                                                                                                                                        |
| `metadata`              | object                                         | Session metadata                                                                                                                                                                                                                                     |
| `environment_variables` | object                                         | Session-level environment variables exported into the agent runtime, returned as a JSON object (`{"NAME":"value"}`). Empty Sessions return `{}`. The request format is a single string (see [Create a Session](/cloud-agents/api/sessions/create))   |
| `resources`             | array of [Session resource](#session-resource) | File, GitHub repository, or Memory Store resources attached to the Session                                                                                                                                                                           |
| `vault_ids`             | array of string                                | Vault IDs attached to the Session                                                                                                                                                                                                                    |
| `deployment_id`         | string \| null                                 | Deployment ID when the Session was created by a Deployment, otherwise `null`                                                                                                                                                                         |
| `outcome_evaluations`   | array                                          | Outcome evaluation results. New Sessions return `[]`                                                                                                                                                                                                 |
| `stats`                 | [Session stats](#session-stats)                | Session statistics                                                                                                                                                                                                                                   |
| `archived_at`           | string \| null                                 | Archive time, or `null` when not archived                                                                                                                                                                                                            |
| `created_at`            | string                                         | Creation time                                                                                                                                                                                                                                        |
| `updated_at`            | string                                         | Last update time                                                                                                                                                                                                                                     |

Session responses no longer include legacy fields such as `agent_id`, `turn_status`, `memory_store_ids`, or `usage`.

## Agent reference

`agent` in create requests can be either a string Agent ID or this object:

| Field     | Type    | Required               | Description                                                                                                                                                           |
| --------- | ------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`      | string  | Yes                    | Agent ID with the `agent_` prefix                                                                                                                                     |
| `type`    | string  | Yes (object form only) | Must be the literal `"agent"`. Missing or other values return 400 when the object form is used. The bare-string form (passing the Agent ID directly) skips this check |
| `version` | integer | No                     | Agent version to snapshot. Omit or pass `0` to use the latest active version                                                                                          |

## Session embedded agent

The `agent` returned inside a [Session object](#session-object) is the Agent snapshot pinned to the Session, but several Agent fields are stripped before they are exposed:

* `created_at`, `updated_at` — never included on the embedded Agent.
* `archived`, `archived_at` — never included; the Session preserves access to the snapshot regardless of the source Agent's archive state.
* `metadata` — Agent-level metadata is stripped; only Session-level `metadata` is exposed.
* `instructions` — replaced by `system`.

For a coordinator multi-agent setup, `agent.multiagent.agents[]` is hydrated server-side from stub `{type, id, version}` references into full Agent definitions (see [Multiagent roster element](#multiagent-roster-element)). Inside a [Session Thread object](#session-thread-object), the `agent` field additionally drops the `multiagent` block — coordinator threads only carry the per-agent snapshot.

### `agent.model.effective_context_window`

Sessions return an additional response-only `effective_context_window` (int64, in tokens) inside `agent.model`. It is the runtime-resolved context window the Session will use for this Agent (after applying environment-level overrides). Absent or non-positive values are omitted; clients should treat the field as informational.

## Session resource

`resources[]` is a union distinguished by `type`.

### File resource

| Field        | Type   | Required      | Description                                                                            |
| ------------ | ------ | ------------- | -------------------------------------------------------------------------------------- |
| `id`         | string | Response only | Resource ID                                                                            |
| `type`       | string | Yes           | `"file"`                                                                               |
| `file_id`    | string | Yes           | File ID with the `file_` prefix. The file must be ready                                |
| `mount_path` | string | No            | Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>` when omitted |
| `created_at` | string | Response only | Resource creation time                                                                 |
| `updated_at` | string | Response only | Resource update time                                                                   |

### GitHub repository resource

| Field                 | Type   | Required         | Description                                                                        |
| --------------------- | ------ | ---------------- | ---------------------------------------------------------------------------------- |
| `id`                  | string | Response only    | Resource ID                                                                        |
| `type`                | string | Yes              | `"github_repository"`                                                              |
| `url`                 | string | Yes              | Repository URL                                                                     |
| `authorization_token` | string | Yes (write only) | GitHub token used to access the repository. It is not returned in responses        |
| `mount_path`          | string | No               | Clone target path in the container. Defaults from the repository name when omitted |
| `checkout`            | object | No               | Git checkout target, for example `{"type":"branch","name":"main"}`                 |
| `created_at`          | string | Response only    | Resource creation time                                                             |
| `updated_at`          | string | Response only    | Resource update time                                                               |

### Memory Store resource

| Field             | Type           | Required      | Description                                                                                                              |
| ----------------- | -------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `type`            | string         | Yes           | `"memory_store"`                                                                                                         |
| `memory_store_id` | string         | Yes           | Memory Store ID with the `memstore_` prefix                                                                              |
| `access`          | string \| null | No            | Optional access mode. Allowed values: `"read_write"`, `"read_only"`. Empty string or omitted means default (no override) |
| `instructions`    | string \| null | No            | Optional instructions stored on the Session resource. Maximum 4096 characters                                            |
| `name`            | string \| null | Response only | Current Memory Store name when available                                                                                 |
| `description`     | string         | Response only | Current Memory Store description when available                                                                          |
| `mount_path`      | string \| null | Response only | Current implementation returns `null` unless an existing resource snapshot contains a value                              |

Memory Store resources do not include `id`, `created_at`, or `updated_at` fields.

## Session stats

| Field              | Type   | Description                                                  |
| ------------------ | ------ | ------------------------------------------------------------ |
| `active_seconds`   | number | Active processing time in seconds. New Sessions start at `0` |
| `duration_seconds` | number | Session duration in seconds. New Sessions start at `0`       |

## Multiagent roster element

When the embedded Agent declares `multiagent.type = "coordinator"`, every entry inside `agent.multiagent.agents[]` returned by Session endpoints is hydrated from the original stub references into a full Agent definition (subject to the same field stripping as the [Session embedded agent](#session-embedded-agent), and additionally without its own `multiagent` field).

| Field              | Type             | Description                                                                                                   |
| ------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------- |
| `type`             | string           | `"agent"` for a sibling Agent reference, or `"self"` for the coordinator itself                               |
| `id`               | string           | Agent ID. Present for `type = "agent"`; mirrors the coordinator's own ID when `type = "self"`                 |
| `version`          | integer          | Pinned Agent version. Present for `type = "agent"`                                                            |
| `name`             | string           | Hydrated Agent name                                                                                           |
| `description`      | string \| null   | Hydrated Agent description                                                                                    |
| `system`           | string           | Hydrated Agent system prompt (replaces `instructions`)                                                        |
| `model`            | string \| object | Same shape as on the embedded Agent, including `effective_context_window` when set                            |
| Other Agent fields | varies           | Tools, MCP servers, skills, and other Agent fields, with the same field stripping rules as the embedded Agent |

Stub references that fail to resolve (for example, the referenced Agent version no longer exists) are returned unchanged.

## Event object

Events returned by send, list, and stream endpoints are event-specific JSON objects. Public event responses expose only the documented public fields for each event type.

| Field          | Type   | Description                                                                             |
| -------------- | ------ | --------------------------------------------------------------------------------------- |
| `id`           | string | Event ID with the `evt_` prefix                                                         |
| `type`         | string | Event type                                                                              |
| `processed_at` | string | Present when the event has been processed. Many agent-generated events omit this field. |

Depending on `type`, an event may also include fields such as `content`, `input`, `name`, `tool_use_id`, `mcp_tool_use_id`, `custom_tool_use_id`, `result`, `deny_message`, `rubric`, `outcome_id`, `session_thread_id`, `stop_reason`, `error`, or `usage`.

## Client event request types

`POST /api/v1/cloud/sessions/{session_id}/events` accepts exactly these client-sent event types:

| Type                      | Required fields         | Notes                                                                                                                                                                   |
| ------------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user.message`            | `content`               | `content` must be a non-empty array of content blocks                                                                                                                   |
| `user.interrupt`          | none                    | `session_thread_id` is optional and is echoed as `null` when omitted                                                                                                    |
| `user.tool_confirmation`  | `tool_use_id`, `result` | `result` must be `allow` or `deny`; `deny_message` is optional                                                                                                          |
| `user.tool_result`        | `tool_use_id`           | Use this to return a built-in tool result from a self-hosted worker. `content` is optional; when present, it must be an array of content blocks. `is_error` is optional |
| `user.custom_tool_result` | `custom_tool_use_id`    | `content` is optional; when present, it must be an array of content blocks. `is_error` is optional                                                                      |
| `user.define_outcome`     | `description`, `rubric` | `rubric` is an object such as `{"type":"text","content":"..."}` or `{"type":"file","file_id":"file_..."}`; `max_iterations` is optional                                 |
| `system.message`          | `content`               | `content` must be a non-empty array of text content blocks; the event must follow a user/tool result event                                                              |

## Public event types

List and stream endpoints can expose these event types:

`user.message`, `user.interrupt`, `user.tool_confirmation`, `user.custom_tool_result`, `user.define_outcome`, `user.tool_result`, `system.message`, `agent.custom_tool_use`, `agent.mcp_tool_result`, `agent.mcp_tool_use`, `agent.message`, `agent.thinking`, `agent.thread_context_compacted`, `agent.thread_message_received`, `agent.thread_message_sent`, `agent.tool_result`, `agent.tool_use`, `session.deleted`, `session.error`, `session.status_idle`, `session.status_rescheduled`, `session.status_running`, `session.status_terminated`, `session.thread_created`, `session.thread_status_idle`, `session.thread_status_rescheduled`, `session.thread_status_running`, `session.thread_status_terminated`, `session.updated`, `span.model_request_start`, `span.model_request_end`, `span.outcome_evaluation_start`, `span.outcome_evaluation_ongoing`, and `span.outcome_evaluation_end`.

## Event delta stream frames

A **buffered event** is a complete public Event object emitted after generation finishes and recorded in Session event history. It is the authoritative result.

`event_start` and `event_delta` are stream-only SSE payloads used for incremental output. They are not public Event objects and do not appear in event list/history responses. Their JSON payloads have no top-level `id` or `processed_at`; the SSE `id:` field carries the ID of the event being streamed and can be used with `Last-Event-ID`.

### Event start frame

An `event_start` frame identifies the public event whose incremental output has begun.

| Field   | Type   | Description              |
| ------- | ------ | ------------------------ |
| `type`  | string | Always `"event_start"`   |
| `event` | object | Streamed event reference |

The `event` object has these fields:

| Field  | Type   | Description                                                                                          |
| ------ | ------ | ---------------------------------------------------------------------------------------------------- |
| `id`   | string | Event ID with the `evt_` prefix. The SSE `id:`, related deltas, and buffered event use this same ID. |
| `type` | string | `"agent.message"` or `"agent.thinking"`                                                              |

An `agent.message` start is followed by text `event_delta` frames. An `agent.thinking` start is start-only: no delta follows, and the buffered `agent.thinking` event with the same ID marks the end of that thinking phase when one is emitted.

```json theme={null}
{
  "type": "event_start",
  "event": {
    "id": "evt_00jjujk9fbnr4wkj2gh8",
    "type": "agent.message"
  }
}
```

### Event delta frame

An `event_delta` frame appends text to an incrementally streamed `agent.message`.

| Field      | Type   | Description                                                     |
| ---------- | ------ | --------------------------------------------------------------- |
| `type`     | string | Always `"event_delta"`                                          |
| `event_id` | string | ID from the matching `event_start.event.id` and SSE `id:` field |
| `delta`    | object | Content delta                                                   |

The `delta` object has these fields:

| Field     | Type    | Description                                           |
| --------- | ------- | ----------------------------------------------------- |
| `type`    | string  | Always `"content_delta"`                              |
| `index`   | integer | Zero-based index of the content block being updated   |
| `content` | object  | Text fragment with `type: "text"` and a `text` string |

```json theme={null}
{
  "type": "event_delta",
  "event_id": "evt_00jjujk9fbnr4wkj2gh8",
  "delta": {
    "type": "content_delta",
    "index": 0,
    "content": {
      "type": "text",
      "text": "Hello"
    }
  }
}
```

## Model request span events

`span.model_request_start` marks the beginning of one model request.

| Field          | Type   | Description                         |
| -------------- | ------ | ----------------------------------- |
| `id`           | string | Event ID with the `evt_` prefix     |
| `processed_at` | string | RFC 3339 timestamp                  |
| `type`         | string | Always `"span.model_request_start"` |

`span.model_request_end` marks completion of that model request.

| Field                    | Type    | Description                                                   |
| ------------------------ | ------- | ------------------------------------------------------------- |
| `id`                     | string  | Event ID with the `evt_` prefix                               |
| `is_error`               | boolean | Whether the model request ended with an error or cancellation |
| `model_request_start_id` | string  | ID of the corresponding `span.model_request_start` event      |
| `processed_at`           | string  | RFC 3339 timestamp                                            |
| `type`                   | string  | Always `"span.model_request_end"`                             |

Model request span responses do not expose model usage or internal timing metadata.

## Session Thread object

In managed-agent scenarios, each thread within a Session is represented by this structure.

| Field              | Type           | Description                                                                                                                                               |
| ------------------ | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`               | string         | Thread ID with the `sthr_` prefix                                                                                                                         |
| `type`             | string         | Always `"session_thread"`                                                                                                                                 |
| `session_id`       | string         | Owning Session ID                                                                                                                                         |
| `parent_thread_id` | string \| null | Parent thread ID. `null` for the coordinator thread                                                                                                       |
| `agent`            | object         | Agent snapshot used by this thread. Same shape as the [Session embedded agent](#session-embedded-agent), with the `multiagent` block additionally removed |
| `status`           | string         | Thread lifecycle status: `running`, `idle`, `rescheduling`, or `terminated`                                                                               |
| `stats`            | object \| null | Thread statistics. Current implementation returns `null`                                                                                                  |
| `archived_at`      | string \| null | Archive time, or `null` when not archived                                                                                                                 |
| `created_at`       | string         | Creation time                                                                                                                                             |
| `updated_at`       | string         | Last update time                                                                                                                                          |

Thread responses no longer include legacy fields such as `agent_id`, `agent_version`, `name`, `role`, `stop_reason`, `created_by_tool_use_id`, or `usage`.