> ## 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. # Create an agent and immutable version ## OpenAPI ````yaml /recursion/openapi.yaml post /managed-agents/v1/agents 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/agents: post: tags: - Agents summary: Create an agent and immutable version operationId: managedAgentsCreateAgent parameters: - description: >- Replay-protection key in an organization-wide namespace shared by keyed mutations. It must contain 1 to 256 visible ASCII characters and be sent as exactly one header value. Request identity is the exact HTTP method, escaped path, raw query, and raw body bytes. For the legacy automation-run route only, the historical fingerprint ignores top-level JSON formatting and object-key order and removes the retired top-level idempotency_key field. The same request replays the original successful response; any different request returns 409 idempotency_conflict, and an active matching request returns 409 idempotency_in_progress. Completed receipts are retained for approximately 24 hours, pending claims may be reclaimed after approximately 1 hour, and no deduplication is guaranteed after expiry. in: header name: Idempotency-Key schema: description: >- Replay-protection key in an organization-wide namespace shared by keyed mutations. It must contain 1 to 256 visible ASCII characters and be sent as exactly one header value. Request identity is the exact HTTP method, escaped path, raw query, and raw body bytes. For the legacy automation-run route only, the historical fingerprint ignores top-level JSON formatting and object-key order and removes the retired top-level idempotency_key field. The same request replays the original successful response; any different request returns 409 idempotency_conflict, and an active matching request returns 409 idempotency_in_progress. Completed receipts are retained for approximately 24 hours, pending claims may be reclaimed after approximately 1 hour, and no deduplication is guaranteed after expiry. maxLength: 256 minLength: 1 pattern: ^[!-~]+$ type: string - $ref: '#/components/parameters/RecursionTenantId' - $ref: '#/components/parameters/RecursionOrganizationId' requestBody: content: application/json: schema: $ref: '#/components/schemas/StandaloneCreateAgentRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/StandaloneAgent' description: >- A configured standalone Managed Agent: its versioned execution definition plus current mutable classification tags. Publishing the execution definition mints a new immutable version; applying tags does not. headers: Idempotency-Replayed: description: True when this response replays an earlier completed request. schema: type: boolean style: simple recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '400': description: Bad Request. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ManagedAgentsApiErrorInvalidJson' - $ref: '#/components/schemas/ManagedAgentsApiErrorInvalidRequest' discriminator: propertyName: code mapping: invalid_json: '#/components/schemas/ManagedAgentsApiErrorInvalidJson' invalid_request: '#/components/schemas/ManagedAgentsApiErrorInvalidRequest' x-recursion-error-codes: - invalid_json - 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' '409': headers: Retry-After: description: >- When present, delay in seconds or an HTTP-date after which the caller may retry; absence supplies no retry advice. schema: type: string style: simple recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' description: Conflict. content: application/json: schema: oneOf: - $ref: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyConflict - $ref: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyInProgress discriminator: propertyName: code mapping: idempotency_conflict: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyConflict idempotency_in_progress: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyInProgress x-recursion-error-codes: - idempotency_conflict - idempotency_in_progress '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' '415': description: Unsupported Media Type. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorUnsupportedMediaType' x-recursion-error-codes: - unsupported_media_type 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/ManagedAgentsApiErrorIdempotencyUnavailable - $ref: >- #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable - $ref: >- #/components/schemas/ManagedAgentsApiErrorModelProviderMetadataMissing - $ref: >- #/components/schemas/ManagedAgentsApiErrorModelProviderUnconfigured - $ref: >- #/components/schemas/ManagedAgentsApiErrorModelProviderUnreachable - $ref: >- #/components/schemas/ManagedAgentsApiErrorServiceUnavailable discriminator: propertyName: code mapping: idempotency_unavailable: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyUnavailable managed_agents_unavailable: >- #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable model_gateway_metadata_missing: >- #/components/schemas/ManagedAgentsApiErrorModelProviderMetadataMissing model_gateway_unconfigured: >- #/components/schemas/ManagedAgentsApiErrorModelProviderUnconfigured model_gateway_unreachable: >- #/components/schemas/ManagedAgentsApiErrorModelProviderUnreachable service_unavailable: >- #/components/schemas/ManagedAgentsApiErrorServiceUnavailable x-recursion-error-codes: - idempotency_unavailable - managed_agents_unavailable - model_gateway_metadata_missing - model_gateway_unconfigured - model_gateway_unreachable - 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: StandaloneCreateAgentRequest: description: >- Request body for creating a standalone Managed Agent: its system prompt, model, tool surface, and default vault grants. Sessions snapshot the agent version at start, so later edits do not change a running session. properties: built_in_integrations: description: >- Built-in integrations this agent may use, each naming an active organization connection an admin added on the Integrations page. A non-empty tools list narrows this agent below the connection's organization allow-list; omission inherits it. Sessions receive short-lived access restricted to the effective tools; nothing is granted through a vault. Omit or send [] for no connections. Carried in full on every version write. items: $ref: '#/components/schemas/BuiltInIntegration' maxItems: 25 type: array default_credential_refs: description: >- Individual default items within default_vault_ids. The list is a whitelist across every default vault, not a filter within one, so it must name every item the agent should receive. Omit to select every item the default vaults hold when the agent is saved. The selection is stored with the agent version, so a credential added to one of those vaults later is not included until the agent is saved again with it selected. [] alongside a non-empty default_vault_ids is rejected because it would select none. items: $ref: '#/components/schemas/VaultCredentialRef' type: array default_project_id: description: >- Billing project copied into sessions started from this agent when their create request omits project_id. A non-empty session project_id overrides it. Accepted only on a model that GET /managed-agents/v1/models marks requiresProject; refused with 400 for an organization whose model list has no such model. type: - 'null' - string default_rubric: description: >- Markdown rubric; each list item is one criterion. When set, every session of this agent that starts with a message is graded against it by default, with that message as the objective. Must contain at least one gradeable markdown list item. An explicit session outcome overrides the default. type: - 'null' - string default_vault_ids: description: >- Vaults granted by default when a session create request omits vault_ids. default_credential_refs may narrow their items. items: type: string type: array description: description: >- Optional free-text note about what the agent is for. Not sent to the model. type: string disabled_integration_mcp_providers: description: >- Native integration providers whose MCP tools sessions of this agent do not receive even though the grant is present; the agent's own mcp_servers are never affected. github is accepted but ignored, because a GitHub grant always keeps its MCP tools alongside git and gh in the sandbox. Omitting the field means none, on managedAgentsCreateAgent as on managedAgentsCreateAgentVersion. items: type: string type: array fileHistoryEnabled: description: >- Whether sessions started from this agent may search and read the session outputs its earlier sessions saved, with search_agent_files and read_agent_file. Omit to leave it off. Checked again on every search and read, so turning it off takes effect at once. type: - 'null' - boolean max_concurrent_sessions: description: >- Maximum number of this agent's ordinary root sessions that may run or wait on compute at once. Omit for unlimited. Sessions beyond the cap are accepted with execution_state=queued and wait until a slot frees; child/subagent sessions and outcome evaluation passes do not take a slot. Carried in full on every version write: omitting it publishes a version with no cap. maximum: 10000 minimum: 1 type: - 'null' - integer mcp_servers: description: >- Remote MCP servers whose tools are added to the agent's tool surface. Each entry is an object with name and url, e.g. {"name": "docs", "url": "https://example.com/mcp"}. Credentials come from the vaults granted to the session, and the discovered tool list is snapshotted at session start, so a later edit here does not change a running session. items: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' type: object type: array metadata: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- Free-form caller-owned JSON stored with the agent and returned on reads. Not interpreted by the service and never sent to the model. type: object model: description: >- Public model id copied from GET /managed-agents/v1/models (for example anthropic/claude-sonnet-5-5). Agent reads return the same public id. An id the catalog does not list is rejected with a list of available public ids. type: string model_config: $ref: '#/components/schemas/InferenceConfigRequest' description: >- Default inference config applied to sessions started from this agent. Omit model_config or send {} to use provider defaults; null is invalid. reasoning_effort is normalized and validated for direct providers, and must exactly match the selected catalog model's supportedReasoningEfforts. An unsupported reasoning_effort, including any value for a catalog model that lists no exact options, returns 400. Authored provider_params.thinking objects are validated. When prompt caching is enabled, invalid provider_params.promptCacheTTL or provider_params.promptCacheSharedTTL values, incompatible models, and shared retention shorter than promptCacheTTL return 400. These checks run on agent and version writes and again at session start; a model catalog that cannot be read to verify settings returns 503. multiagent: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- Multiagent roster: the delegation targets this agent may hand work to, an optional advisor entry, and the interventionist posture. Snapshotted at session start; a child roster may tighten the recursion depth ceiling, never widen it. type: object name: description: >- Human-readable label for the agent. Required, and not blank; surrounding whitespace is trimmed. type: string nativeIntegrations: description: >- Native connections this agent may use, with provider-enforced permission and resource restrictions. Omit or send [] for none. Stored in full on each agent version; secrets remain on the connection. items: $ref: '#/components/schemas/NativeIntegration' maxItems: 25 type: array skills: description: >- Skill declarations made available to the agent, passed through as given and snapshotted into the session at start. Capped at the 100 skills a session can carry. items: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' type: object maxItems: 100 type: array system: description: System prompt for the agent. type: string template: $ref: '#/components/schemas/TemplateRef' description: Reviewed template id and revision used to prefill this definition. web_search_enabled: default: true description: >- Whether sessions started from this agent may use the native web_search tool. Omit to enable it. The setting is snapshotted when a session starts. type: boolean required: - name - model - system type: object additionalProperties: false StandaloneAgent: description: >- A configured standalone Managed Agent: its versioned execution definition plus current mutable classification tags. Publishing the execution definition mints a new immutable version; applying tags does not. properties: agent_id: description: >- Server-assigned id of the agent, used in the agent, agent-version, and session routes. type: string built_in_integrations: description: >- Built-in integrations this agent may use, each naming an active organization connection an admin added on the Integrations page. A non-empty tools list narrows this agent below the connection's organization allow-list; omission inherits it. Sessions receive short-lived access restricted to the effective tools. Not a vault grant: nothing about these appears under credential access. A version write carries the list in full: omitting it publishes a version with none. items: $ref: '#/components/schemas/BuiltInIntegration' type: array created_at: description: Server-assigned RFC 3339 timestamp of when the agent was created. format: date-time type: string default_credential_refs: description: >- Narrows the default vaults to individual credentials. Every credential is selected when a vault is first added, and may then be unchecked. items: $ref: '#/components/schemas/VaultCredentialRef' type: - array - 'null' default_project_id: description: >- Billing project copied into new sessions when their create request omits project_id. A non-empty session project_id overrides it. Carried in full on every version write: omitting it publishes a version with no default. type: string default_rubric: description: >- Markdown rubric that sessions of this agent are graded against by default when they start with a message. A session that supplies its own outcome ignores this entirely. Carried in full on every version write: omitting it publishes a version with no rubric. type: string default_vault_ids: description: >- Vaults whose credentials are copied into a new session when its create request omits vault_ids. Sending an explicit empty list on the session still overrides these. items: type: string type: - array - 'null' description: description: Free-text note about what this agent is for. type: string disabled_integration_mcp_providers: description: >- Native integration providers whose MCP tools new sessions of this agent do not receive, even though the grant is present. Suppresses integration-derived servers only, never the agent's own mcp_servers. github is ignored, because a GitHub grant always keeps its MCP tools alongside git and gh in the sandbox. items: type: string type: - array - 'null' execution_compatibility: description: >- Whether this exact agent definition is compatible with the standalone execution context. Omitted by deployments that do not compute it; a client must treat any present value other than compatible as incompatible. enum: - compatible - incompatible type: string fileHistoryEnabled: description: >- Whether new sessions may search and read the session outputs this agent's earlier sessions saved. Omitted means off. type: boolean latest_agent_version_id: description: >- Server-maintained id of the newest version of this agent; sessions started without an explicit version use it. type: string max_concurrent_sessions: description: >- Maximum number of this agent's ordinary root sessions that may run or wait on compute at once. Omit for unlimited. Sessions beyond the cap are accepted with execution_state=queued and wait until a slot frees; child/subagent sessions and outcome evaluation passes do not take a slot. Carried in full on every version write: omitting it publishes a version with no cap. maximum: 10000 minimum: 1 type: integer mcp_servers: description: >- Remote MCP servers to attach. Each entry is an object with name (the label the server's tools are grouped under) and url (its http/https endpoint); any further keys are passed to the runtime unchanged. Credentials come from the vaults granted to the session, not from this entry. Tools are discovered and snapshotted at session start. items: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' type: object type: - array - 'null' metadata: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- Caller-owned key/value data stored with the agent and returned unchanged. type: object model: description: >- Public model id from GET /managed-agents/v1/models, for example anthropic/claude-sonnet-5-5. Agent reads return the same public id. An id the catalog does not list is rejected here, before the session starts. type: string model_config: $ref: '#/components/schemas/InferenceConfig' description: >- Default inference settings applied to every turn unless a session overrides them. multiagent: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- Multi-agent orchestration settings, such as subagent definitions and delegation limits. type: object name: description: >- Human-readable label shown wherever agents are listed. Not required to be unique. type: string nativeIntegrations: description: >- Native connections this agent may use, with provider-enforced permission and resource restrictions. Omit or send [] for none. Stored in full on each agent version; secrets remain on the connection. items: $ref: '#/components/schemas/NativeIntegration' maxItems: 25 type: array organization_id: description: >- Organization that owns the agent. Server-assigned from the authenticated principal; never accepted from the caller. type: string skills: description: >- Skill packages loaded into the agent's runtime, each an entry with the skill reference and its metadata. items: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' type: object type: - array - 'null' supports_new_sessions: description: >- Whether this agent type supports new sessions here. Other start requirements still apply. Existing sessions and agent editing remain available when false. type: boolean system: description: System prompt prepended to every conversation this agent runs. type: string tags: description: >- Current organization-scoped classification tags applied to this agent. Always an array. Tags are mutable catalog metadata and are deliberately absent from AgentVersion and session runtime snapshots. items: $ref: '#/components/schemas/StandaloneTag' type: array template: $ref: '#/components/schemas/TemplateRef' description: >- Reviewed template revision this agent's current version started from. updated_at: description: >- Server-assigned RFC 3339 timestamp of the most recent update to the agent. format: date-time type: string web_search_enabled: default: true description: >- Whether new sessions may use the native web_search tool. Omitted on legacy agents and interpreted as enabled. type: boolean required: - organization_id - agent_id - name - model - model_config - system - mcp_servers - default_vault_ids - default_credential_refs - disabled_integration_mcp_providers - skills - tags - created_at - updated_at type: object additionalProperties: false ManagedAgentsApiErrorInvalidJson: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - invalid_json 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. 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. ManagedAgentsApiErrorIdempotencyConflict: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - idempotency_conflict 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. ManagedAgentsApiErrorIdempotencyInProgress: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - idempotency_in_progress 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. ManagedAgentsApiErrorUnsupportedMediaType: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - unsupported_media_type 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. ManagedAgentsApiErrorIdempotencyUnavailable: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - idempotency_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. 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. ManagedAgentsApiErrorModelProviderMetadataMissing: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - model_gateway_metadata_missing 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. ManagedAgentsApiErrorModelProviderUnconfigured: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - model_gateway_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. ManagedAgentsApiErrorModelProviderUnreachable: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - model_gateway_unreachable 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. BuiltInIntegration: description: >- One built-in integration an agent may use, named by its organization connection. The agent may narrow the connection's organization tool allow-list. properties: connection_id: description: >- Organization integration connection (UUID) the agent may use. Must belong to the caller's organization, be a built-in integration connection, and be active. type: string tools: description: >- Optional subset of the connection's organization tool allow-list. Omit or send an empty list to inherit all organization-enabled tools. A non-empty list limits this agent to exactly those tools, subject to later organization changes. items: type: string maxItems: 200 type: array required: - connection_id type: object additionalProperties: false 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 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 InferenceConfigRequest: 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: - 'null' - 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: - 'null' - number type: object additionalProperties: false NativeIntegration: description: >- A native connection and its agent-owned runtime permission and resource policy. properties: connectionId: description: Active native connection in this organization. format: uuid type: string permission: description: >- Provider permission preset, bounded by the connection's authorization. type: string resources: description: >- Optional resource subset. Omit to inherit all resources available through the connection. An explicit empty list is rejected. items: type: string maxItems: 500 minItems: 1 type: array uniqueItems: true tools: description: >- Standalone GitHub or Slack MCP tools this agent may use. Omit on existing grants to retain the prior tool access; new standalone grants select tools explicitly. An explicit empty list is rejected. items: type: string maxItems: 200 minItems: 1 type: array uniqueItems: true required: - connectionId - permission type: object additionalProperties: false TemplateRef: description: Reviewed template id and revision copied into this resource. properties: id: description: Stable template id. type: string revision: description: Reviewed catalog revision. type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - id - revision 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 StandaloneTag: description: >- An organization-scoped classification definition. Applying or removing it changes only catalog membership: it does not update the agent, mint an AgentVersion, or affect running sessions. properties: color: description: 'Display color in #RRGGBB form.' examples: - '#14b8a6' maxLength: 7 minLength: 7 pattern: ^#[0-9A-Fa-f]{6}$ type: string created_at: description: Server-assigned RFC 3339 timestamp of when the tag was created. format: date-time type: string description: description: >- Optional operator-facing explanation of the classification, up to 280 characters. maxLength: 280 type: string label: description: >- Display label, trimmed by the service. Unique case-insensitively among live tags in this organization. maxLength: 32 minLength: 1 type: string organization_id: description: >- Organization that owns the tag. Server-assigned from the authenticated principal and never accepted as authority from the request body. type: string tag_id: description: Server-assigned tag id (UUID). format: uuid type: string updated_at: description: >- Server-assigned RFC 3339 timestamp of the most recent definition update. format: date-time type: string required: - organization_id - tag_id - label - color - 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. 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. ````