> ## Documentation Index > Fetch the complete documentation index at: https://docs.labelbox.com/llms.txt > Use this file to discover all available pages before exploring further. # Get root session tree and timeline > Returns every session in the root session's tree, its threads, and the first bounded page of the merged chronological event log. When next_event_id is set, more events remain and should be fetched with managedAgentsListSessionEvents rather than by re-reading the tree. Any session id in the tree is accepted; the read resolves to its root. ## OpenAPI ````yaml /recursion/openapi.yaml get /managed-agents/v1/sessions/{sessionId}/tree openapi: 3.1.0 info: title: Managed Agents API version: 0.14.0 description: >- The Recursion Managed Agents REST API. Authenticate with a Recursion API key as a bearer token. An organization-scoped key acts in its own organization and needs nothing else; a tenant-scoped key must also send `x-organization-id` with an organization id or `default`. Field names follow each operation's published schema. servers: - url: https://api.recursion.labelbox.com security: - bearerAuth: [] paths: /managed-agents/v1/sessions/{sessionId}/tree: get: tags: - Sessions summary: Get root session tree and timeline description: >- Returns every session in the root session's tree, its threads, and the first bounded page of the merged chronological event log. When next_event_id is set, more events remain and should be fetched with managedAgentsListSessionEvents rather than by re-reading the tree. Any session id in the tree is accepted; the read resolves to its root. operationId: managedAgentsGetSessionTree parameters: - description: >- Opt-in compatibility mode. images rehydrates private image refs under strict response caps; omitted by default. in: query name: hydrate schema: description: >- Opt-in compatibility mode. images rehydrates private image refs under strict response caps; omitted by default. enum: - images type: string - description: >- Set to signed to add a short-lived url (and url_expires_at) to stored image blocks within the per-read signing budget. Omitted when signing is unavailable or the budget is exhausted; the authenticated managedAgentsGetSessionImage endpoint always works. in: query name: image_urls schema: description: >- Set to signed to add a short-lived url (and url_expires_at) to stored image blocks within the per-read signing budget. Omitted when signing is unavailable or the budget is exhausted; the authenticated managedAgentsGetSessionImage endpoint always works. enum: - signed type: string - description: >- External event payloads hydrate by default. Set refs to return bounded stubs and private reference metadata only. in: query name: payloads schema: description: >- External event payloads hydrate by default. Set refs to return bounded stubs and private reference metadata only. enum: - refs type: string - description: >- Any session id (UUID) in the tree; the read resolves to its root session. in: path name: sessionId required: true schema: description: >- Any session id (UUID) in the tree; the read resolves to its root session. format: uuid type: string - $ref: '#/components/parameters/RecursionTenantId' - $ref: '#/components/parameters/RecursionOrganizationId' responses: '200': content: application/json: schema: $ref: '#/components/schemas/TreeResult' description: >- A whole multi-agent session tree: every session and thread in it, plus a bounded page of the merged chronological event log. Returned when reading the tree containing a given session. headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '400': description: Bad Request. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorInvalidRequest' x-recursion-error-codes: - invalid_request headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '401': description: Unauthorized. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorUnauthorized' x-recursion-error-codes: - unauthorized headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorForbidden' x-recursion-error-codes: - forbidden headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '404': description: Not Found. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorNotFound' x-recursion-error-codes: - not_found headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '413': description: Payload Too Large. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorPayloadTooLarge' x-recursion-error-codes: - payload_too_large headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '429': headers: Retry-After: description: When to retry, as delay seconds or an HTTP date. schema: type: string recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' description: Too Many Requests. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorRateLimitExceeded' x-recursion-error-codes: - rate_limit_exceeded '500': description: Internal Server Error. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorInternalError' x-recursion-error-codes: - internal_error headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '502': description: A dependent service returned an invalid response. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorDependencyFailure' x-recursion-error-codes: - bad_gateway headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '503': description: Service Unavailable. content: application/json: schema: oneOf: - $ref: >- #/components/schemas/ManagedAgentsApiErrorContentStoreUnavailable - $ref: >- #/components/schemas/ManagedAgentsApiErrorContentStoreUnconfigured - $ref: >- #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable - $ref: >- #/components/schemas/ManagedAgentsApiErrorServiceUnavailable discriminator: propertyName: code mapping: content_store_unavailable: >- #/components/schemas/ManagedAgentsApiErrorContentStoreUnavailable content_store_unconfigured: >- #/components/schemas/ManagedAgentsApiErrorContentStoreUnconfigured managed_agents_unavailable: >- #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable service_unavailable: >- #/components/schemas/ManagedAgentsApiErrorServiceUnavailable x-recursion-error-codes: - content_store_unavailable - content_store_unconfigured - managed_agents_unavailable - service_unavailable headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '504': headers: Retry-After: description: When to retry, as delay seconds or an HTTP date. schema: type: string recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' description: A dependent service timed out. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorDependencyTimeout' x-recursion-error-codes: - gateway_timeout components: parameters: RecursionTenantId: name: x-tenant-id in: header required: false description: >- Optional tenant consistency check. When present, it must name the tenant bound to the API key, including when x-organization-id is `default`. schema: type: string minLength: 1 RecursionOrganizationId: name: x-organization-id in: header required: false description: >- Organization in which to act. Required for a tenant-scoped API key. Optional for an organization-scoped key, where it must name that same organization. The value may be an organization id or `default`. schema: type: string minLength: 1 schemas: TreeResult: description: >- A whole multi-agent session tree: every session and thread in it, plus a bounded page of the merged chronological event log. Returned when reading the tree containing a given session. properties: events: description: >- One page of the tree's events merged into a single chronological log across all sessions. Bounded by response size, so the page length is not a fixed count. items: $ref: '#/components/schemas/Event' type: - array - 'null' next_event_id: description: >- Cursor to pass as the starting point of the next event page. Present only when more events remain; absent on the last page. type: string root_session_id: description: >- Root session of the multi-agent tree this result covers (UUID). Equal to session_id for a root session. type: string sessions: description: >- Every session in the tree, root and subagents alike. Always complete; only the event log is paged. items: $ref: '#/components/schemas/Session' type: - array - 'null' threads: description: >- Thread registry rows for the tree's context-isolated execution streams. Imported RL children appear when their import supplied thread names; older imports without names use session-derived fallback rows. items: $ref: '#/components/schemas/SessionThread' type: - array - 'null' required: - root_session_id - sessions - threads - events type: object additionalProperties: false ManagedAgentsApiErrorInvalidRequest: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - invalid_request message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorUnauthorized: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - unauthorized message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorForbidden: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - forbidden message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorNotFound: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - not_found message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorPayloadTooLarge: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - payload_too_large message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorRateLimitExceeded: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - rate_limit_exceeded message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorInternalError: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - internal_error message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorDependencyFailure: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - bad_gateway message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorContentStoreUnavailable: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - content_store_unavailable message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorContentStoreUnconfigured: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - content_store_unconfigured message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorManagedAgentsUnavailable: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - managed_agents_unavailable message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorServiceUnavailable: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - service_unavailable message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorDependencyTimeout: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - gateway_timeout message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. Event: description: >- One durable entry in a session's transcript: a message, a tool call or result, an approval, or a status change, with the provider message body and the token accounting for the call that produced it. Returned when listing or streaming a session's events. properties: actor: description: >- Who produced this event, as a namespaced identifier: human:… for a person, system:… for the service itself, or an agent identity. type: string agent_id: description: Agent that produced this event (UUID). type: string cache_read_tokens: description: >- Prompt tokens served from the provider's prompt cache, billed at the cached rate. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 cache_write_tokens: description: Prompt tokens written into the provider's prompt cache. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 causal_event_id: description: >- Event that caused this one (UUID). Unlike parent_event_id this expresses causality rather than nesting. type: string content: $ref: '#/components/schemas/EventContent' description: >- The event payload as provider-shaped content blocks. Passed through to and from the model provider without reinterpretation. content_hydration_status: description: >- Read-time status when external EventContent was hydrated or could not be hydrated. enum: - hydrated - refs_only - missing - corrupt - unavailable - oversized type: string content_payload_bytes: description: Byte size of the canonical external EventContent JSON. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 content_payload_ref: description: >- Private whole-event content reference. Read the content through managedAgentsGetSessionEventContent; this reference cannot be fetched directly. type: string content_payload_sha256: description: >- Lowercase SHA-256 digest of the canonical external EventContent JSON. type: string content_ref: description: >- Image cleanup prefix or typed multi-image envelope. This is independent of whole-event payload storage. type: string cost_micros: description: >- Accrued cost in micro-USD (1,000,000 = 1 USD). Integer to avoid float rounding across many small charges. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 created_at: description: RFC 3339 timestamp of when this record was created. Server-assigned. format: date-time type: string environment_id: description: Sandbox environment the producing session was executing in (UUID). type: string event_id: description: >- Identifier for this event (UUID). Server-assigned unless the append supplied one. Chronologically sortable, and the column a transcript is ordered by. type: string event_status: description: >- Outcome marker for events that can fail: pending, completed, warning, or error. Empty when not applicable. type: string event_type: description: >- What kind of event this is. One of message, tool_invocation, tool_result, approval_request, approval_decision, summary, plan_update, session_status, artifact, advisor_intervention, or outcome_evaluation. type: string finish_reason: description: >- Why the provider stopped generating, in the provider vocabulary (for example end_turn, max_tokens, tool_use). Passed through verbatim. type: string inference_config: $ref: '#/components/schemas/InferenceConfig' description: >- Sampling and tool settings this inference ran with, as resolved at call time. input_tokens: description: Prompt tokens billed for this unit of work. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 latency_ms: description: Wall-clock duration of the provider call in milliseconds. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 model: $ref: '#/components/schemas/ModelRef' description: >- Snapshot of the model reference as it was at call time, so a later model change does not rewrite history. model_ref_id: description: >- Canonical model reference used for this inference (UUID). Empty on events not produced by a model call. type: string organization_id: description: >- Organization that owns this record. Resolved from the API key; never accepted from the caller. type: string output_tokens: description: Completion tokens billed for this unit of work. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 parent_event_id: description: >- Event this one is nested under in the transcript tree (UUID), for example a tool result under its invocation. type: string prompt_tokens: description: >- Estimated tokens this event contributes when rendered into a future provider request. A memoized estimate for context-budget planning, not billed provider usage. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 provider_model_id: description: >- Provider's own model identifier as sent on the wire, which may differ from the canonical model reference. type: string provider_request_id: description: >- Provider's request identifier for this inference, for correlating with provider-side logs. type: string provider_type: description: >- Model provider family that served this inference, for example anthropic, openai, or vertex. type: string role: description: >- Message role in the provider vocabulary: system, user, or assistant. Set on message events; empty on events that are not turns. type: string sandbox_instance_id: description: >- Concrete sandbox instance the event was produced on. Provider-assigned, not a UUID. type: string schema_version: description: >- Event schema version this row was written under. Server-assigned; readers should tolerate unknown newer values. type: integer minimum: -9007199254740991 maximum: 9007199254740991 session_id: description: Session this event belongs to (UUID). type: string thread_id: description: >- Thread within a multi-agent session that produced this event (UUID). Empty on a single-agent session. type: string tool_name: description: >- Name of the tool being invoked or reporting a result. Set on tool events only. type: string tool_use_id: description: >- Provider's tool-call identifier, correlating a tool_invocation with its tool_result. type: string turn_id: description: Groups every event produced within one model turn. type: string required: - schema_version - event_type - actor - content - inference_config - session_id - event_id - created_at type: object additionalProperties: false Session: description: >- One durable agent run: its lifecycle status (active, awaiting_human, completed, failed, cancelled), the agent version, environment, model, and credentials it was pinned to, and its place in a multi-agent tree. Returned when starting, reading, or listing sessions; imported RL rollouts appear as sessions too and run no agent loop. properties: access_policy: type: string enum: - platform_internal description: >- Present only when reading a platform-managed session directly; these sessions are omitted from session lists. active_handoff: $ref: '#/components/schemas/ActiveHandoff' description: >- Current browser handoff, including its exclusive driver claim and deadline. Absent when no browser handoff is active. Never contains the short-lived access URL. agent_id: description: >- Agent this session runs (UUID). Empty for imported sessions that were not started from an agent. type: string agent_snapshot: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- The definition of the agent version this session runs, frozen so later edits to the agent cannot change this session's behavior. Written at start; it changes only when the session moves to another version of its agent, which agent_version_id shows. type: object agent_version_id: description: >- Agent version this session runs (UUID), pinned at start so a later edit to the agent cannot change a running session. It changes only when the session moves to another version of its agent. type: string computer_use: description: >- Whether this session has a computer-enabled environment and a display that passed its readiness probe. type: boolean concurrency_slot_held: description: >- Whether this root session currently occupies the agent's max_concurrent_sessions slot. True while admitted and non-terminal. False exclusively while an active queued root waits to start. Omitted for unlimited agents, child sessions, legacy rows, and terminal or deleted sessions. type: boolean config: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- Resolved per-session runtime settings written at start, including the snapshotted MCP servers and tool bindings, multi-agent roster, and delegation depth limits. The settings an agent version owns change only when the session moves to another version of its agent. Read-only to callers. type: - object - 'null' costState: description: >- final once the session has ended, its sandbox has stopped, and every charge has settled: costUsd will not change unless the session is resumed. so_far while it can still grow. Present exactly when costUsd is. enum: - final - so_far type: string costUsd: description: >- Billed cost of this session's whole tree as an exact canonical decimal USD string. On Recursion, a writer's cost also includes linked cloned outcome evaluation roots, counting each ledger charge once; manual evaluations remain independent. On other surfaces, cost remains tree-only. Compute still running is included as an estimate; the figure is final once every included tree has ended and settled. Returned by managedAgentsGetSession and managedAgentsListSessions only, and absent when it cannot be read. examples: - '1.234567' type: string created_at: description: RFC 3339 timestamp of when this record was created. Server-assigned. format: date-time type: string credential_refs: description: >- Explicit allowlist of individual credentials the session may use; null or empty when none are listed. Read credential_refs_configured to tell an intentionally empty allowlist from a legacy session granted whole vaults. items: $ref: '#/components/schemas/VaultCredentialRef' type: - array - 'null' x-recursion-nullable-collection: null-is-domain-value credential_refs_configured: description: >- True when credential_refs is an explicit allowlist. False on legacy sessions granted every credential in their vaults, which would otherwise be indistinguishable from an empty allowlist. type: boolean effective_model: description: >- Provider-qualified model string this session runs, including any per-session model override. Written at start; it changes only when the session moves to another version of its agent. Prefer this over resolving model_ref_id or the current agent version when displaying the model a session runs. type: string environment_id: description: Environment whose sandbox definition this session runs in (UUID). type: string execution_state: description: >- Where the agent loop is. Empty for sessions without a loop, such as imported rollouts. provisioning includes any automatic setup-image refresh before sandbox creation. The deployment's compute-ready timeout (five minutes by default) bounds sandbox readiness after refresh, not the setup run itself. A failed setup or sandbox timeout fails the session with the reason in failure. This field, read from the session itself, is the authoritative status -- a session's event stream is written on a separate path and can lag it, so an empty event list does not mean the session is still starting. enum: - provisioning - queued - running - idle - completed type: string external_source_id: description: >- Identifier of the session's counterpart in the external_source_type system, so a caller can find the session again from that side. Set together with external_source_type. type: string external_source_type: description: >- Kind of external system this session is correlated to, e.g. slack_thread. Set together with external_source_id and filterable when listing sessions. type: string failure: $ref: '#/components/schemas/SessionFailure' description: >- Structured terminal failure. Omitted for healthy sessions and legacy rows. forked_at_event_id: description: >- Event in the parent session (UUID) this session was forked from, so the fork's starting context is identifiable. Set only on forks. type: string kind: description: >- What produced the session: api_call, chat, subagent (delegated by another session), or session_analyst (a platform-started read-only assistant that answers questions about another session tree). enum: - api_call - chat - rollout - subagent - benchmark - evaluation - reflection - session_analyst type: string last_activity_at: description: >- RFC 3339 timestamp of when the agent loop last made progress. Distinct from updated_at, which any metadata write touches. Absent for sessions that run no loop. format: date-time type: string metadata: additionalProperties: type: string description: >- Caller-defined string key/value pairs supplied when the session was started, e.g. ids from your own system. Immutable, present on root sessions only, and filterable with metadata=key:value or metadata_key=key on GET /managed-agents/v1/sessions. At most 32 entries; keys use letters, digits, '_', '.', and '-' up to 64 characters; values are 1-512 characters. type: object model_ref_id: description: >- Model reference the session's turns run on (UUID), resolved from the agent version or the start request. Written at start; it changes only when the session moves to another version of its agent. type: string model_snapshot: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- The resolved model reference and inference settings this session runs, frozen for the same reason as agent_snapshot. Written at start; it changes only when the session moves to another version of its agent. type: object organization_id: description: >- Organization that owns this record. Resolved from the API key; never accepted from the caller. type: string parent_session_id: description: >- Session that created this one (UUID) — the delegating session for a subagent, or the source session for a fork. Empty on a root session. type: string project_id: description: >- Billing project this session is attributed to: the project_id sent on session start, the default_project_id of its agent, or the project of the session it was started from. Omitted when the session names no project. type: string root_session_id: description: >- Root session of the multi-agent tree this session belongs to (UUID). Equal to session_id for a root session. type: string sandbox_instance_id: description: >- Provider-assigned id of the sandbox instance serving this session. Empty before provisioning finishes; historical self_hosted sessions may also have no instance id. type: string sandbox_provider: description: >- Sandbox runtime that provisioned this session's compute, from the supported sandbox providers list. type: string session_id: description: Identifier for this session (UUID). Server-assigned. type: string session_path: description: >- Position of this session within its tree, as a slash-delimited path of session ids. "/" for a root session. type: string source_refs: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- Secondary provenance ids from the originating system beyond the primary external source, e.g. an imported rollout's problem, problem-version, and run ids. type: object status: $ref: '#/components/schemas/SessionStatus' description: >- Coarse session state shared with RL rollout imports: active, awaiting_human (for a rollout, carries no score), completed, failed, or cancelled. For where a running agent loop is, read execution_state instead. stop_reason: description: >- Why the loop is not running. Set whenever execution_state is idle or completed. sleeping means the agent chose to wait and the session resumes on the next message or at wake_at; awaiting_subagents means a coordinator is waiting on delegated work; out_of_credit and tenant_suspended pause before new work and continue on the next message after the tenant is admitted again; an out_of_credit pause from the last 72 hours also continues on its own within about a minute once the tenant is admitted again. type: string updated_at: description: >- RFC 3339 timestamp of the last change to this record. Server-assigned. format: date-time type: string user_id: description: >- User the session was started on behalf of, resolved from the request scope. type: string vault_ids: description: >- Vaults (UUIDs) the session may draw credentials from. Combine with credential_refs to narrow the grant to specific credentials. items: type: string type: array wake_at: description: >- RFC 3339 timestamp at which a sleeping session wakes itself if nobody messages it first. Absent unless the agent scheduled a timed wait. format: date-time type: string required: - root_session_id - session_path - session_id - organization_id - kind - status - computer_use - credential_refs - credential_refs_configured - config - created_at - updated_at type: object additionalProperties: false SessionThread: description: >- One context-isolated execution stream inside a multi-agent session tree, as registered in the thread registry. Returned when listing a session's threads or reading a whole session tree. properties: agent_id: description: Agent this thread runs (UUID). type: string agent_version_id: description: >- Agent version this thread runs (UUID). Absent when the thread was not pinned to a specific version. type: string archived_at: description: >- RFC 3339 timestamp of when this thread was archived and stopped appearing as an active stream. Absent while the thread is not archived. format: date-time type: string created_at: description: RFC 3339 timestamp of when this record was created. Server-assigned. format: date-time type: string name: description: >- Human-readable label for this thread, supplied when it was spawned. Optional and never interpreted by the service. type: string parent_session_id: description: >- Session the spawning thread belongs to (UUID). Absent on the tree's top-level thread. type: string parent_thread_id: description: >- Thread that spawned this one (UUID). Absent on the tree's top-level thread. type: string role: description: >- What the thread exists to do within the tree, for example subagent, grader, or advisor. Not a chat message role. type: string root_session_id: description: >- Root session of the multi-agent tree this thread belongs to (UUID). Equal to session_id for a root session. type: string session_id: description: Session this thread belongs to (UUID). type: string session_path: description: >- Slash-joined ancestry of session ids from the tree root down to the session whose events this thread's events are stored under, for example "/root-id/child-id". type: string status: description: >- Thread lifecycle: running (executing now), idle (awaiting more input), or terminated (finished; see stop_reason). type: string stop_reason: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- Structured reason the thread last stopped, forwarded from the agent loop, for example {"type": "end_turn"} or {"type": "error", "message": ...}. Absent while the thread has not stopped. type: object thread_id: description: >- Identifier for this thread within its session tree (UUID). Server-assigned. For a subagent thread it is the child session id, so the thread and the session carrying its events resolve each other directly. type: string thread_path: description: >- Slash-joined ancestry of this thread within the tree, used to order threads for display. Defaults to session_path when the thread has no deeper nesting of its own. type: string updated_at: description: >- RFC 3339 timestamp of the last change to this record. Server-assigned. format: date-time type: string required: - root_session_id - session_path - thread_id - session_id - agent_id - thread_path - role - status - created_at - updated_at type: object additionalProperties: false ManagedAgentsApiErrorDetails: type: object properties: field: description: >- Request field or header responsible for the error, when one can be identified. type: string issues: description: >- Boundary-validation failures as path-prefixed human-readable messages. type: array items: type: string requestId: description: Request correlation identifier for support and log lookup. type: string retryable: description: >- Server advice about failure transience. `true` means transient, `false` means non-transient, and absence gives no advice. Automatic replay is allowed only when this field is not `false` and the operation-specific retry and idempotency contract permits replay. type: boolean additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. EventContent: description: >- The body of a session event, shaped like a provider message: content blocks plus the stop reason and token usage the provider returned. Every event in a session transcript carries one. properties: assistantInteraction: $ref: '#/components/schemas/AssistantInteraction' description: >- One state of a typed request an assistant put in front of the reader: questions, a solution blueprint, or a plan of changes. Present on the approval_request events of an assistant session, one per state the interaction passes through. blocks: description: >- Ordered content blocks of this message, in the provider's content-block form. Empty for events that carry no message body. items: $ref: '#/components/schemas/ContentBlock' type: - array - 'null' metadata: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- Extra key/value detail about this event that is not part of the message body, such as the ingest subtype or the sandbox working directory. type: object plan: description: Plan items reported by the agent, present on a plan_update event. items: $ref: '#/components/schemas/PlanItem' type: array stop_reason: description: >- The provider's own stop_reason for the assistant turn, recorded verbatim, e.g. end_turn, tool_use, or max_tokens. Absent on events that are not a model response. type: string tools: description: >- Tool definitions that were in scope for the turn, as sent to the provider. Recorded on the session's system message so a transcript shows what the model could call. items: $ref: '#/components/schemas/ToolDefinition' type: array usage: $ref: '#/components/schemas/Usage' description: >- Token counts the provider reported for the call that produced this message. Absent when the event is not a model response. required: - blocks type: object additionalProperties: false InferenceConfig: description: >- Sampling and generation settings for a model call, mirroring the provider's own request parameters. Set it on an agent or a session to govern every turn, and read it back on a model event to see what the call actually used. properties: max_tokens: description: >- Upper bound on tokens the model may generate for one assistant turn (the provider's max_tokens). Omit or 0 to use the model reference's default. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 provider_params: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- Recognized provider-specific settings are thinking, thinkingDisplay and output_config for native Anthropic messages; thinkingConfig for native Gemini; and promptCache, promptCacheTTL and promptCacheSharedTTL for prompt caching. Unknown top-level keys are ignored, not passed through. Omitting all three cache settings enables automatic policy: explicit caching stays enabled and eligible Anthropic requests may use 1h shared retention when recent usage and current pricing evidence predict savings; otherwise shared retention is 5m. Setting promptCache or either TTL explicitly keeps operator-configured retention. promptCache true enables explicit markers; false disables them and ignores both TTL settings. With caching enabled, both TTL settings accept only 5m or 1h on models using native Anthropic messages. promptCacheTTL defaults to 5m for user-context anchors and history. promptCacheSharedTTL controls tools and system instructions, defaults to promptCacheTTL under explicit configuration, and cannot be shorter than promptCacheTTL. Authored thinking objects and enabled cache TTL settings are validated at agent/version writes and session start. type: object reasoning_effort: description: >- Provider-native reasoning depth value. For a model from the models catalog, use one of its supportedReasoningEfforts; omit it to follow the provider's current default. type: string temperature: description: >- Sampling temperature passed through to the provider, typically 0.0-2.0. Lower values are more deterministic. Omit to use the provider default. type: number top_p: description: >- Nucleus-sampling probability mass (0.0-1.0) passed through to the provider. Prefer setting either this or temperature, not both. Omit to use the provider default. type: number type: object additionalProperties: false ModelRef: description: >- Snapshot of the model that served one inference call, recorded on the event so a transcript stays interpretable after the catalog entry changes. Returned on model events; also accepted when pinning a session to a specific model. properties: base_url: description: >- Endpoint the request was sent to, for models not served at their provider's default endpoint. Empty means the provider's default endpoint. type: string capabilities: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- Declared model capability flags, e.g. tool use, vision, or extended thinking support, as recorded from the catalog entry at call time. type: object context_window: description: >- Maximum total tokens the model accepts in one request, prompt plus completion, as recorded from the catalog entry at call time. 0 means unknown. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 max_output_tokens: description: >- Maximum completion tokens the model can emit in one response, as recorded from the catalog entry at call time. 0 means unknown. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 metadata: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- Extra key/value data copied from the catalog entry. Some keys are read by the service to shape the request, such as base_url and reasoning_style. type: object model: description: >- Provider's own model id as sent on the wire, e.g. model-name or provider/model-name. type: string model_ref_id: description: >- Model reference in the catalog this snapshot was resolved from (UUID). Empty when the session named a models-catalog id instead of a catalog entry. type: string model_version: description: >- Provider-specific version or snapshot pin recorded alongside the model id, when the catalog entry declares one. type: string provider: description: >- Provider family that served the call, e.g. anthropic, openai, vertex, or mock. Carries the same value as provider_type and is kept for older readers. type: string provider_id: description: >- Model provider record whose credentials and base URL were used (UUID). type: string provider_type: description: >- Provider family that served the call, e.g. anthropic, openai, vertex, or mock. Selects which wire protocol the request used. type: string serving_backend: description: >- Serving stack behind a self-hosted model, e.g. vllm. Empty for models called through a hosted provider API. type: string required: - provider - model type: object additionalProperties: false ActiveHandoff: description: >- Public, credential-free state of a browser handoff that is awaiting a person, currently driven by one, or being resolved back to the agent. properties: access_expires_at: description: >- Latest time the current display access remains usable; never later than deadline_at. format: date-time type: string deadline_at: description: When the handoff automatically expires and the agent resumes. format: date-time type: string handoff_id: description: Stable identifier for this browser handoff. type: string reason: description: Why the agent asked a person to take over the shared browser. type: string requested_at: description: When the agent requested the handoff. format: date-time type: string state: description: >- Whether nobody has opened access yet, one person currently owns the display, or hand-back/deadline resolution is being delivered. enum: - awaiting_user - user_driving - resolved type: string wake_cause: description: >- Resolution cause once resolved: user_handed_back, deadline_elapsed, cancelled, or interrupted. type: string required: - handoff_id - reason - requested_at - deadline_at - state type: object additionalProperties: false PlatformSafeJsonValue: description: >- A JSON value whose integer members stay within the exact ECMAScript safe-integer range at every nesting level. oneOf: - type: 'null' - type: boolean - type: string - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: number not: type: integer - type: array items: $ref: '#/components/schemas/PlatformSafeJsonValue' - additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' type: object VaultCredentialRef: description: >- A pointer to one credential inside one vault. Used to grant a session specific credentials rather than every credential in a vault. properties: credential_id: description: Credential to select inside vault_id. type: string vault_id: description: >- Vault holding the credential. Required, because credential ids are unique only within a vault. type: string required: - vault_id - credential_id type: object additionalProperties: false SessionFailure: description: >- Structured, sanitized reason a session terminated abnormally. Present on a session only after a terminal failure; healthy and legacy sessions omit it. properties: at: description: Time the terminal failure was persisted. format: date-time type: string category: description: >- Who can act on this failure: transient (wait or retry), caller_error (change the request or configuration, retrying as-is will not help), or internal (report it). retryable=false with category=caller_error is a fixable mistake, not an outage. A retryable failure is never caller_error: if the platform will retry, changing the request is not the fix. enum: - transient - caller_error - internal type: string code: description: Stable machine-readable failure code. type: string message: description: >- Sanitized bounded operator-facing message; never contains raw provider response bodies or credentials. type: string phase: description: >- Lifecycle phase that failed, such as provisioning, setup, workflow, or model. type: string retryable: description: >- Whether the platform will retry, or a retry of the same request may succeed on its own. False does not mean permanently broken -- read category to tell a transient condition from a request the caller must change. type: boolean required: - phase - code - message - retryable - category - at type: object additionalProperties: false SessionStatus: description: Coarse session state shared by Managed Agents and imported RL rollouts. enum: - active - awaiting_human - completed - failed - cancelled type: string AssistantInteraction: description: >- A typed request for the reader's input that an assistant put in front of them: questions, a solution blueprint, or a plan of changes. Each state is recorded as one event; the latest event per interactionId is the current state. properties: blueprint: $ref: '#/components/schemas/AssistantBlueprint' description: The solution design, on a blueprint interaction. decision: $ref: '#/components/schemas/AssistantDecision' description: The person's decision, once one was made. digest: description: >- Digest of this revision's content. A decision names it so a person decides exactly what they were shown. type: string interactionId: description: >- Stable id of the interaction. Revisions of a blueprint or plan keep it. type: string kind: description: >- What is being asked: questions, a solution blueprint, or a plan of changes. enum: - question - blueprint - plan type: string origin: description: >- Who wrote this revision: the assistant, or the person through an inline edit. enum: - assistant - user type: string plan: $ref: '#/components/schemas/AssistantPlan' description: The changes, on a plan interaction. questions: description: The questions, on a question interaction. items: $ref: '#/components/schemas/AssistantQuestion' type: array requestedAt: description: When this revision was put in front of the reader. format: date-time type: string revision: description: >- Revision number, starting at 1. Only the latest revision of a pending interaction can be decided. minimum: 1 type: integer maximum: 9007199254740991 status: description: Lifecycle state of the interaction. enum: - pending - answered - accepted - revision_requested - cancelled - superseded - executing - completed - failed type: string stepResults: description: What each approved step did, once a plan executes. items: $ref: '#/components/schemas/AssistantPlanStepResult' type: array summary: description: One or two sentences on why this is being asked. type: string title: description: Short heading for the interaction. type: string required: - interactionId - kind - revision - digest - status - origin - title - requestedAt type: object additionalProperties: false ContentBlock: description: >- One block of message content: text, image, tool_use, tool_result, thinking, or a provider passthrough. The type field says which fields apply, and provider-native payloads are carried through verbatim. properties: byte_size: description: Decoded image byte size. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 content: description: >- Nested blocks carrying a tool_result payload, so a tool can return both text and images. items: $ref: '#/components/schemas/ContentBlock' type: array context: description: >- A document block's context: what the model should know about the document before reading it, disclosed as its first paragraph. type: string data: description: >- Base64 image bytes. Omitted from default reads and present only for legacy storage or explicit hydrate=images responses. type: string encrypted_content: description: >- Sealed reasoning payload for providers that return reasoning encrypted. Opaque to clients; replay it verbatim. type: string height: description: Validated image height in pixels. type: integer minimum: -9007199254740991 maximum: 9007199254740991 id: description: >- Provider-assigned id of a tool_use block. Echo it back as tool_use_id on the matching tool_result. type: string input: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- Tool arguments the model produced for a tool_use block, matching that tool's input schema. type: object is_error: description: >- True when a tool_result reports that the tool call failed; the nested content then carries the error detail. type: boolean media_type: description: >- Declared media type; inline computer-use images allow image/jpeg, image/png, and image/webp. type: string name: description: Name of the tool the model is invoking, on a tool_use block. type: string omitted_bytes: description: Original byte count reported by a redacted image placeholder. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 payload: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- Provider-native block body, stored verbatim for block types this schema does not model. Passed through unchanged. provider: description: >- Provider that emitted a passthrough block, e.g. anthropic or openai, telling readers how to interpret payload. type: string provider_payload: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- Original provider block exactly as received, kept alongside the normalized fields for lossless replay. redacted: description: >- True when the block's content was withheld (redacted thinking, or an image dropped by redaction); the remaining fields describe what was removed. type: boolean semantic_hint: description: >- Coarse hint about what an unmodeled provider block represents, so a reader can render it without provider-specific logic. type: string sha256: description: Lowercase SHA-256 digest of decoded image bytes. type: string signature: description: >- Provider-issued signature over a thinking block, or the thought signature a Gemini tool_use block was issued with, required for the provider to accept that block on a later turn. Opaque; replay it verbatim. type: string source: $ref: '#/components/schemas/ContentBlockSource' description: >- Where a user-sent image or document block's bytes came from when they were named rather than sent inline: {type: "file", file_id}. Kept on the stored block as provenance after the bytes were copied into the session; an image block then also carries the session's own uri. summary: description: >- Readable summary blocks a provider returns alongside sealed or long-form reasoning. items: $ref: '#/components/schemas/ContentBlock' type: array text: description: Text of a text block, or the reasoning text of a thinking block. type: string title: description: >- A document block's title, disclosed to the model beside the document. type: string tool_use_id: description: Id of the tool_use block that this tool_result answers. type: string type: description: >- Block discriminator: text, image, document (a user-sent block naming a file by id, inlined as text when the message is accepted), tool_use, tool_result, thinking, redacted_thinking, or a provider passthrough type. Which of the other fields apply depends on this value. type: string uri: description: >- Private typed content reference. Fetch it through managedAgentsGetSessionImage; clients cannot read this URI directly. type: string url: description: >- Short-lived HTTPS URL for the image bytes. Present only when the read asked for image_urls=signed and the deployment has signing configured. Never stored; fetch a fresh read after url_expires_at. type: string url_expires_at: description: When url stops working. Absent whenever url is. format: date-time type: string width: description: Validated image width in pixels. type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - type type: object additionalProperties: false PlanItem: description: >- One step of a plan or to-do list an agent reported while working. Appears on an event's content when the agent's harness emits a plan; the service records it without acting on it. properties: content: description: Text of the planned step as the agent wrote it. type: string id: description: >- Identifier for this plan entry, stable across the turns that update it. type: string status: description: >- Progress value the agent reported for this step. Passed through as written and not interpreted by the service. type: string required: - id - content - status type: object additionalProperties: false ToolDefinition: description: >- One tool as it was offered to the model, in the Anthropic and OpenAI tool-definition vocabulary. Recorded on the event for a model turn so a reader can see exactly what the model could call. properties: description: description: >- Natural-language explanation of what the tool does and when to use it, supplied to the model verbatim. type: string input_schema: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- JSON Schema for the tool's arguments. Passed to the model provider unchanged. type: - object - 'null' name: description: >- Tool name the model calls, matching the name on the resulting tool_use content block. type: string required: - name - description - input_schema type: object additionalProperties: false Usage: description: >- Token counts and cost for a single unit of work, in the provider's usage vocabulary. Attached to an event's content for the model turn that produced it; see session usage for whole-session totals. properties: cache_read_tokens: description: >- Prompt tokens served from the provider's prompt cache, billed at the cached rate. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 cache_write_tokens: description: Prompt tokens written into the provider's prompt cache. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 cost_usd: description: Accrued cost in USD, derived from cost_micros for display. format: double type: number input_tokens: description: Prompt tokens billed for this unit of work. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 output_tokens: description: Completion tokens billed for this unit of work. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 type: object additionalProperties: false AssistantBlueprint: description: >- A solution design for the reader's use case: what starts the work, the agents, the capabilities it uses and what it produces. properties: agents: description: The agents and the part each plays. items: $ref: '#/components/schemas/AssistantBlueprintAgent' type: array capabilities: description: >- Platform capabilities the design uses, each resolved against the capability catalog. items: $ref: '#/components/schemas/AssistantBlueprintCapability' type: array checkpoints: description: Where a person reviews or decides. items: type: string type: array costClass: description: Rough running cost. enum: - low - medium - high type: string environment: description: The environment the agents run in, in words. type: string evaluation: description: How success is judged. type: string gaps: description: What the platform cannot do directly, said plainly. items: type: string type: array outputs: description: What the work produces. items: type: string type: array trigger: $ref: '#/components/schemas/AssistantBlueprintTrigger' description: What starts the work. required: - trigger - agents - capabilities type: object additionalProperties: false AssistantDecision: description: The reader's decision on an interaction. properties: answers: description: Answers, on a question interaction. items: $ref: '#/components/schemas/AssistantQuestionAnswer' type: array comments: description: Comments pinned to steps or fields, with a revision request. items: $ref: '#/components/schemas/AssistantComment' type: array decidedAt: description: When the decision was recorded. format: date-time type: string decidedBy: description: The user who decided. type: string decision: description: >- What was decided. superseded_by_interaction means the assistant replaced the interaction with a different one before the reader decided. enum: - answered - accepted - approved - revision_requested - cancelled - superseded_by_interaction type: string note: description: The reader's note. type: string required: - decision - decidedAt type: object additionalProperties: false AssistantPlan: description: An ordered set of changes the reader approves, edits, or asks to revise. properties: prerequisites: description: >- Setup the plan cannot do itself; approval waits for each one the server can check. items: $ref: '#/components/schemas/AssistantPlanPrerequisite' type: array steps: description: Changes in execution order. items: $ref: '#/components/schemas/AssistantPlanStep' type: array required: - steps type: object additionalProperties: false AssistantQuestion: description: One typed question of a question interaction. properties: allowOther: description: Whether a select question also accepts a free-text answer. type: boolean input: description: How the question is answered. enum: - single_select - multi_select - short_text - long_text - confirm - picker type: string multiple: description: Whether a picker question accepts more than one resource. type: boolean optional: description: Whether the question may be left unanswered. type: boolean options: description: >- The choices of a select or picker question. Picker options are resolved by the server from resources the reader can access. items: $ref: '#/components/schemas/AssistantQuestionOption' type: array picker: description: Which kind of resource a picker question selects. enum: - agent - environment - skill - vault - model - agent_template - environment_template type: string prompt: description: The question. type: string questionId: description: Id of the question within the interaction. type: string required: - questionId - prompt - input type: object additionalProperties: false AssistantPlanStepResult: description: What one approved plan step did. properties: link: description: Console path to it. type: string message: description: Detail, or the error. type: string resourceId: description: The id of what it created or changed. type: string resourceKind: description: What it created or changed. type: string status: description: >- How it ended, or running while it runs. uncertain means the outcome could not be confirmed and the step was not retried. enum: - running - completed - failed - skipped - uncertain type: string stepId: description: The plan step this result is for. type: string required: - stepId - status type: object additionalProperties: false ContentBlockSource: description: >- Where a user-sent image or document block takes its bytes from when the caller names a file instead of carrying them: a file from the organization's catalog, read and copied into the session when the message is accepted, so the block the transcript keeps names both the source and the copy. properties: file_id: type: string minLength: 1 description: Nonempty id of an unexpired file in the caller's organization. type: type: string const: file description: Always file. required: - type - file_id type: object additionalProperties: false AssistantBlueprintAgent: description: One agent of a blueprint and the part it plays. properties: model: description: The model it runs on, when chosen. type: string responsibilities: description: What it does. type: string role: description: The agent's role. type: string required: - role type: object additionalProperties: false AssistantBlueprintCapability: description: >- One platform capability a blueprint uses, resolved against the capability catalog. properties: capabilityId: description: Id from the capability catalog. type: string kind: description: Capability kind, resolved by the server. type: string name: description: Customer-facing name, resolved by the server. type: string purpose: description: Why the design uses it. type: string status: description: Its status in this organization, resolved by the server. type: string required: - capabilityId - name - kind - status type: object additionalProperties: false AssistantBlueprintTrigger: description: What starts the work a blueprint describes. properties: detail: description: The schedule or the event, in words. type: string kind: description: Manual, on a schedule, or on an outside event. enum: - manual - schedule - event type: string required: - kind type: object additionalProperties: false AssistantQuestionAnswer: description: The reader's answer to one question. properties: optionIds: description: >- Selected option ids, for select, picker and confirm questions (confirm answers with yes or no). items: type: string type: array questionId: description: The question answered. type: string text: description: Free text, for text questions or an Other answer. maxLength: 4000 type: string required: - questionId type: object additionalProperties: false AssistantComment: description: A comment pinned to a step or field of a blueprint or plan. properties: field: description: The field commented on. type: string stepId: description: The step commented on. type: string text: description: The comment. maxLength: 2000 type: string required: - text type: object additionalProperties: false AssistantPlanPrerequisite: description: >- Setup a plan cannot do itself; approval waits for it when the server can check it. properties: capabilityId: description: The capability it unlocks. type: string detail: description: Why, and anything to choose while doing it. type: string kind: description: >- What the reader has to do. The server checks connect_integration and needs_admin when they name a capability; add_vault_credential is a reminder it cannot check. enum: - connect_integration - add_vault_credential - needs_admin type: string label: description: What to do, in words. type: string link: description: Console path that starts the setup. type: string prerequisiteId: description: Id within the plan. type: string satisfied: description: >- Whether the server found it done when this revision was written; false for a prerequisite it cannot check. type: boolean required: - prerequisiteId - kind - label - satisfied type: object additionalProperties: false AssistantPlanStep: description: >- One change of a plan: an action and the exact request it runs on approval. properties: action: description: The action, from the closed set the assistant can propose. type: string costClass: description: Whether approving the step can spend credit. enum: - none - model_spend type: string dependsOn: description: Earlier steps whose results this step uses. items: type: string type: array enabled: description: Whether the step runs on approval. type: boolean fields: description: How to render the step's input as a form. items: $ref: '#/components/schemas/AssistantPlanField' type: array input: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- The action's request, as the server validated and normalized it. A value {"$ref": "steps.."} is filled from an earlier step's result. type: - object - 'null' optional: description: Whether the reader may turn the step off. type: boolean stepId: description: >- Id of the step within the plan; later steps refer to its outputs by it. type: string title: description: What the step does, in words. type: string warnings: description: Things the reader should know before approving. items: type: string type: array required: - stepId - action - title - enabled - input - costClass type: object additionalProperties: false AssistantQuestionOption: description: One choice of a select or picker question, or of a plan field. properties: description: description: Optional detail shown under the label. type: string label: description: What the reader sees. type: string optionId: description: Id to answer with. type: string required: - optionId - label type: object additionalProperties: false AssistantPlanField: description: How a console renders one field of a plan step's input. properties: help: description: Short guidance shown with the field. type: string label: description: Field label. type: string name: description: Top-level key in the step input. type: string options: description: Choices for select and picker widgets, resolved by the server. items: $ref: '#/components/schemas/AssistantQuestionOption' type: array required: description: Whether the field must have a value. type: boolean widget: description: The control to render. enum: - text - long_text - markdown - code - select - multi_select - model_picker - environment_picker - agent_picker - skill_picker - vault_reference - key_list - number - boolean - resources - json type: string required: - name - label - widget type: object additionalProperties: false headers: RecursionOrganizationId: description: Organization id resolved for this request. schema: type: string minLength: 1 RecursionTenantId: description: Tenant id resolved for this request. schema: type: string minLength: 1 securitySchemes: bearerAuth: type: http scheme: bearer description: A Recursion API key, created in the console under API keys. ````