> ## Documentation Index > Fetch the complete documentation index at: https://oma-codex-session-events-atomic-log.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Create Session > Create Session through the OMA API. Every request requires `?beta=true`. ## OpenAPI ````yaml /openapi/oma.en.json post /v1/sessions openapi: 3.1.0 info: title: OMA API Reference version: 1.0.0 description: Open Managed Agents application API reference. servers: - url: http://localhost:38080 description: Local OMA server security: - omaApiKey: [] - omaBearer: [] paths: /v1/sessions: post: summary: Create Session operationId: BetaCreateSession parameters: - name: beta in: query required: true description: Selects the beta API contract for this endpoint. Must be `true`. schema: type: boolean enum: - true - name: anthropic-version in: header required: false schema: type: string - name: anthropic-beta in: header required: false schema: type: string items: type: string x-stainless-override-schema: x-stainless-param: betas x-stainless-extend-default: true type: array description: Optional header to specify the beta version(s) you want to use. items: $ref: '#/components/schemas/AnthropicBeta' x-default: managed-agents-2026-04-01 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BetaManagedAgentsCreateSessionParams' responses: '200': description: Successful response (OK) content: application/json: schema: $ref: '#/components/schemas/BetaManagedAgentsSession' '400': description: Invalid argument - The client specified an invalid argument content: application/json: schema: $ref: '#/components/schemas/BetaErrorResponse' '401': description: >- Unauthenticated - The request does not have valid authentication credentials content: application/json: schema: $ref: '#/components/schemas/BetaErrorResponse' '403': description: >- Permission denied - The caller does not have permission to execute the specified operation content: application/json: schema: $ref: '#/components/schemas/BetaErrorResponse' '404': description: Not found - Some requested entity was not found content: application/json: schema: $ref: '#/components/schemas/BetaErrorResponse' '408': description: >- Deadline exceeded - The deadline expired before the operation could complete content: application/json: schema: $ref: '#/components/schemas/BetaErrorResponse' '409': description: Aborted - The operation was aborted due to concurrency issue content: application/json: schema: $ref: '#/components/schemas/BetaErrorResponse' '412': description: >- Failed precondition - Operation was rejected because the system is not in required state content: application/json: schema: $ref: '#/components/schemas/BetaErrorResponse' '413': description: Out of range - Operation was attempted past the valid range content: application/json: schema: $ref: '#/components/schemas/BetaErrorResponse' '429': description: >- Resource exhausted - Some resource has been exhausted (rate limiting) content: application/json: schema: $ref: '#/components/schemas/BetaErrorResponse' '431': description: Request header fields too large - Request metadata was too large content: application/json: schema: $ref: '#/components/schemas/BetaErrorResponse' '499': description: Cancelled - The operation was cancelled by the client content: application/json: schema: $ref: '#/components/schemas/BetaErrorResponse' '500': description: Internal - Internal server error content: application/json: schema: $ref: '#/components/schemas/BetaErrorResponse' '501': description: Unimplemented - The operation is not implemented or supported content: application/json: schema: $ref: '#/components/schemas/BetaErrorResponse' '503': description: Unavailable - The service is currently unavailable content: application/json: schema: $ref: '#/components/schemas/BetaErrorResponse' '504': description: Deadline exceeded - Upstream service did not respond in time content: application/json: schema: $ref: '#/components/schemas/BetaErrorResponse' components: schemas: BetaManagedAgentsCreateSessionParams: description: Request parameters for creating a `session`. type: object additionalProperties: false required: - agent - environment_id properties: agent: description: >- Agent identifier. Accepts the `agent` ID string, which pins the latest version for the session, or an `agent` object with both id and version specified. allOf: - $ref: >- #/components/schemas/BetaManagedAgentsCreateSessionAgentUnionParams examples: - agent_011CZkYpogX7uDKUyvBTophP environment_id: description: >- ID of the `environment` defining the container configuration for this session. type: string minLength: 1 maxLength: 128 examples: - env_011CZkZ9X2dpNyB7HsEFoRfW title: description: Human-readable session title. type: string maxLength: 500 nullable: true examples: - 'Order #1234 inquiry' metadata: description: >- Arbitrary key-value metadata attached to the session. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. type: object additionalProperties: type: string resources: description: >- Resources (e.g. repositories, files) to mount into the session's container. type: array items: $ref: '#/components/schemas/BetaManagedAgentsSessionResourceParams' vault_ids: description: >- Vault IDs for stored credentials the agent can use during the session. type: array items: type: string initial_events: description: >- Initial events to send to the `session` at creation, processed in order. Supports `user.message` and `user.define_outcome` events. Maximum 50 events. type: array items: $ref: '#/components/schemas/BetaManagedAgentsSessionInitialEventParams' budget: description: >- Enforced spend ceiling for the session. Omit to create an uncapped session. Every model the session can run — the agent's model and each callable agent's model — must have a public list price, or the request is rejected with reason `model_not_budgetable`. allOf: - $ref: '#/components/schemas/BetaManagedAgentsBudget' example: agent: agent_011CZkYpogX7uDKUyvBTophP environment_id: env_011CZkZ9X2dpNyB7HsEFoRfW title: 'Order #1234 inquiry' BetaManagedAgentsSession: description: A Managed Agents `session`. type: object additionalProperties: false required: - type - id - status - created_at - updated_at - environment_id - title - metadata - agent - resources - vault_ids - outcome_evaluations - usage - stats - archived_at - budget properties: type: type: string enum: - session examples: - session id: type: string examples: - sesn_011CZkZAtmR3yMPDzynEDxu7 status: $ref: '#/components/schemas/BetaManagedAgentsSessionStatus' examples: - idle created_at: $ref: '#/components/schemas/BetaTimestamp' examples: - '2026-03-15T10:00:00Z' updated_at: $ref: '#/components/schemas/BetaTimestamp' examples: - '2026-03-15T10:00:00Z' environment_id: type: string examples: - env_011CZkZ9X2dpNyB7HsEFoRfW title: type: string nullable: true examples: - 'Order #1234 inquiry' metadata: type: object additionalProperties: type: string examples: - key: value agent: $ref: '#/components/schemas/BetaManagedAgentsSessionAgent' examples: - type: agent id: agent_011CZkYpogX7uDKUyvBTophP version: 1 name: My First Agent description: A general-purpose starter agent. model: id: claude-sonnet-4-6 speed: standard system: >- You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end. tools: - type: agent_toolset_20260401 default_config: enabled: true permission_policy: type: always_ask configs: [] mcp_servers: - type: url name: example-mcp url: https://example-server.modelcontextprotocol.io/sse skills: - type: anthropic skill_id: xlsx version: '1' - type: custom skill_id: skill_011CZkZFNu9hAbo3jZPRgTlx version: '2' multiagent: null resources: type: array items: $ref: '#/components/schemas/BetaManagedAgentsSessionResource' examples: - - type: file id: sesrsc_011CZkZBJq5dWxk9fVLNcPht file_id: file_011CNha8iCJcU1wXNR6q4V8w mount_path: /uploads/receipt.pdf created_at: '2026-03-15T10:00:00Z' updated_at: '2026-03-15T10:00:00Z' - type: github_repository id: sesrsc_011CZkZCKr6eXyl0gWMOdQiu url: https://github.com/example-org/example-repo mount_path: /workspace/example-repo checkout: type: branch name: main created_at: '2026-03-15T10:00:00Z' updated_at: '2026-03-15T10:00:00Z' vault_ids: description: >- Vault IDs attached to the session at creation. Empty when no vaults were supplied. type: array items: type: string examples: - - vlt_011CZkZDLs7fYzm1hXNPeRjv outcome_evaluations: description: >- Per-outcome evaluation state. One entry per define_outcome event sent to the session. type: array items: $ref: '#/components/schemas/BetaManagedAgentsOutcomeEvaluationResource' examples: - - type: outcome_evaluation outcome_id: outc_011CZkZRSw2kEfs6ncTVljxP description: Produce a 2-page summary as summary.md result: satisfied iteration: 0 completed_at: '2026-03-15T10:02:31Z' explanation: All five sections present with inline citations. usage: description: Cumulative token usage for the session. allOf: - $ref: '#/components/schemas/BetaManagedAgentsSessionUsage' examples: - input_tokens: 0 output_tokens: 0 cache_read_input_tokens: 0 stats: description: Timing statistics for the session. allOf: - $ref: '#/components/schemas/BetaManagedAgentsSessionStats' examples: - duration_seconds: 0 active_seconds: 0 archived_at: description: When the session was archived. Null if not archived. allOf: - $ref: '#/components/schemas/BetaTimestamp' nullable: true examples: - null deployment_id: description: >- Deployment ID when the session was created from a deployment reference. Null otherwise. type: string nullable: true budget: description: The session's enforced spend ceiling, or null when no budget is set. allOf: - $ref: '#/components/schemas/BetaManagedAgentsBudget' nullable: true examples: - null example: type: session id: sesn_011CZkZAtmR3yMPDzynEDxu7 status: idle created_at: '2026-03-15T10:00:00Z' updated_at: '2026-03-15T10:00:00Z' archived_at: null budget: null environment_id: env_011CZkZ9X2dpNyB7HsEFoRfW title: 'Order #1234 inquiry' metadata: {} agent: type: agent id: agent_011CZkYpogX7uDKUyvBTophP version: 1 name: My First Agent description: A general-purpose starter agent. model: id: claude-sonnet-4-6 speed: standard system: >- You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end. tools: - type: agent_toolset_20260401 default_config: enabled: true permission_policy: type: always_ask configs: [] mcp_servers: - type: url name: example-mcp url: https://example-server.modelcontextprotocol.io/sse skills: - type: anthropic skill_id: xlsx version: '1' - type: custom skill_id: skill_011CZkZFNu9hAbo3jZPRgTlx version: '2' multiagent: null resources: - type: file id: sesrsc_011CZkZBJq5dWxk9fVLNcPht file_id: file_011CNha8iCJcU1wXNR6q4V8w mount_path: /uploads/receipt.pdf created_at: '2026-03-15T10:00:00Z' updated_at: '2026-03-15T10:00:00Z' - type: github_repository id: sesrsc_011CZkZCKr6eXyl0gWMOdQiu url: https://github.com/example-org/example-repo mount_path: /workspace/example-repo checkout: type: branch name: main created_at: '2026-03-15T10:00:00Z' updated_at: '2026-03-15T10:00:00Z' vault_ids: - vlt_011CZkZDLs7fYzm1hXNPeRjv usage: input_tokens: 0 output_tokens: 0 cache_read_input_tokens: 0 stats: duration_seconds: 0 active_seconds: 0 outcome_evaluations: - type: outcome_evaluation outcome_id: outc_011CZkZRSw2kEfs6ncTVljxP description: Produce a 2-page summary as summary.md result: satisfied iteration: 0 completed_at: '2026-03-15T10:02:31Z' explanation: All five sections present with inline citations. BetaErrorResponse: properties: error: discriminator: mapping: api_error: $ref: '#/components/schemas/BetaAPIError' authentication_error: $ref: '#/components/schemas/BetaAuthenticationError' billing_error: $ref: '#/components/schemas/BetaBillingError' invalid_request_error: $ref: '#/components/schemas/BetaInvalidRequestError' not_found_error: $ref: '#/components/schemas/BetaNotFoundError' overloaded_error: $ref: '#/components/schemas/BetaOverloadedError' permission_error: $ref: '#/components/schemas/BetaPermissionError' rate_limit_error: $ref: '#/components/schemas/BetaRateLimitError' timeout_error: $ref: '#/components/schemas/BetaGatewayTimeoutError' propertyName: type oneOf: - $ref: '#/components/schemas/BetaInvalidRequestError' - $ref: '#/components/schemas/BetaAuthenticationError' - $ref: '#/components/schemas/BetaBillingError' - $ref: '#/components/schemas/BetaPermissionError' - $ref: '#/components/schemas/BetaNotFoundError' - $ref: '#/components/schemas/BetaRateLimitError' - $ref: '#/components/schemas/BetaGatewayTimeoutError' - $ref: '#/components/schemas/BetaAPIError' - $ref: '#/components/schemas/BetaOverloadedError' title: Error request_id: anyOf: - type: string - type: 'null' default: null title: Request Id type: const: error default: error title: Type type: string required: - error - request_id - type title: ErrorResponse type: object BetaManagedAgentsCreateSessionAgentUnionParams: oneOf: - type: string - oneOf: - $ref: '#/components/schemas/BetaManagedAgentsAgentParams' - $ref: '#/components/schemas/BetaManagedAgentsAgentWithOverridesParams' discriminator: propertyName: type mapping: agent: $ref: '#/components/schemas/BetaManagedAgentsAgentParams' agent_with_overrides: $ref: '#/components/schemas/BetaManagedAgentsAgentWithOverridesParams' BetaManagedAgentsSessionResourceParams: description: Union of resources that can be mounted into a session. type: object discriminator: propertyName: type mapping: github_repository: $ref: >- #/components/schemas/BetaManagedAgentsGitHubRepositoryResourceParams file: $ref: '#/components/schemas/BetaManagedAgentsFileResourceParams' memory_store: $ref: '#/components/schemas/BetaManagedAgentsMemoryStoreResourceParam' oneOf: - $ref: '#/components/schemas/BetaManagedAgentsGitHubRepositoryResourceParams' - $ref: '#/components/schemas/BetaManagedAgentsFileResourceParams' - $ref: '#/components/schemas/BetaManagedAgentsMemoryStoreResourceParam' example: type: file file_id: file_011CNha8iCJcU1wXNR6q4V8w mount_path: /uploads/receipt.pdf BetaManagedAgentsSessionInitialEventParams: description: >- An event sent to the `session` immediately after it is created. Supports `user.message` and `user.define_outcome`. type: object discriminator: propertyName: type mapping: user.message: $ref: '#/components/schemas/BetaManagedAgentsUserMessageEventParams' user.define_outcome: $ref: '#/components/schemas/BetaManagedAgentsUserDefineOutcomeEventParams' oneOf: - $ref: '#/components/schemas/BetaManagedAgentsUserMessageEventParams' - $ref: '#/components/schemas/BetaManagedAgentsUserDefineOutcomeEventParams' BetaManagedAgentsBudget: description: >- An enforced spend ceiling on a session. Discriminated on `type`; `limit` is the only kind currently supported. type: object discriminator: propertyName: type mapping: limit: $ref: '#/components/schemas/BetaManagedAgentsBudgetLimit' oneOf: - $ref: '#/components/schemas/BetaManagedAgentsBudgetLimit' BetaManagedAgentsSessionStatus: type: string description: SessionStatus enum enum: - rescheduling - running - idle - terminated BetaTimestamp: description: A timestamp in RFC 3339 format type: string format: date-time BetaManagedAgentsSessionAgent: description: >- Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. type: object additionalProperties: false required: - type - id - version - name - description - model - system - tools - mcp_servers - skills - multiagent properties: type: type: string enum: - agent examples: - agent id: type: string examples: - agent_011CZkYpogX7uDKUyvBTophP version: type: integer format: int32 examples: - 1 name: type: string examples: - My First Agent description: type: string nullable: true examples: - A general-purpose starter agent. model: $ref: '#/components/schemas/BetaManagedAgentsModelConfig' examples: - id: claude-sonnet-4-6 speed: standard system: type: string nullable: true examples: - >- You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end. tools: type: array items: $ref: '#/components/schemas/BetaManagedAgentsAgentTool' examples: - - type: agent_toolset_20260401 default_config: enabled: true permission_policy: type: always_ask configs: [] mcp_servers: type: array items: $ref: '#/components/schemas/BetaManagedAgentsMCPServer' examples: - - type: url name: example-mcp url: https://example-server.modelcontextprotocol.io/sse skills: type: array items: $ref: '#/components/schemas/BetaManagedAgentsSkill' examples: - - type: anthropic skill_id: xlsx version: '1' - type: custom skill_id: skill_011CZkZFNu9hAbo3jZPRgTlx version: '2' multiagent: description: >- Resolved multiagent orchestration configuration. Null when the agent is single-threaded. allOf: - $ref: '#/components/schemas/BetaManagedAgentsSessionMultiagent' nullable: true examples: - null example: type: agent id: agent_011CZkYpogX7uDKUyvBTophP version: 1 name: My First Agent description: A general-purpose starter agent. model: id: claude-sonnet-4-6 speed: standard system: >- You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end. tools: - type: agent_toolset_20260401 default_config: enabled: true permission_policy: type: always_ask configs: [] mcp_servers: - type: url name: example-mcp url: https://example-server.modelcontextprotocol.io/sse skills: - type: anthropic skill_id: xlsx version: '1' - type: custom skill_id: skill_011CZkZFNu9hAbo3jZPRgTlx version: '2' multiagent: null BetaManagedAgentsSessionResource: type: object discriminator: propertyName: type mapping: github_repository: $ref: '#/components/schemas/BetaManagedAgentsGitHubRepositoryResource' file: $ref: '#/components/schemas/BetaManagedAgentsFileResource' memory_store: $ref: '#/components/schemas/BetaManagedAgentsMemoryStoreResource' oneOf: - $ref: '#/components/schemas/BetaManagedAgentsGitHubRepositoryResource' - $ref: '#/components/schemas/BetaManagedAgentsFileResource' - $ref: '#/components/schemas/BetaManagedAgentsMemoryStoreResource' BetaManagedAgentsOutcomeEvaluationResource: description: >- Evaluation state for a single outcome defined via a define_outcome event. type: object additionalProperties: false required: - type - outcome_id - description - result - iteration - completed_at - explanation properties: type: type: string enum: - outcome_evaluation examples: - outcome_evaluation outcome_id: description: Server-generated outc_ ID for this outcome. type: string examples: - outc_011CZkZRSw2kEfs6ncTVljxP description: description: What the agent should produce. type: string examples: - Produce a 2-page summary as summary.md result: description: >- Current evaluation state. `pending` before the agent begins work; `running` while producing or revising; `evaluating` while the grader scores; `satisfied`/`max_iterations_reached`/`failed`/`interrupted` are terminal. type: string examples: - satisfied iteration: description: 0-indexed revision cycle the outcome is currently on. type: integer format: int32 examples: - 0 completed_at: description: >- When the outcome reached a terminal result. Null while pending/running/evaluating. allOf: - $ref: '#/components/schemas/BetaTimestamp' nullable: true examples: - '2026-03-15T10:02:31Z' explanation: description: >- Grader's verdict text from the most recent evaluation. For satisfied, explains why criteria are met; for needs_revision (intermediate), what's missing; for failed, why unrecoverable. type: string nullable: true examples: - All five sections present with inline citations. example: type: outcome_evaluation outcome_id: outc_011CZkZRSw2kEfs6ncTVljxP description: Produce a 2-page summary as summary.md result: satisfied iteration: 0 completed_at: '2026-03-15T10:02:31Z' explanation: All five sections present with inline citations. BetaManagedAgentsSessionUsage: description: Cumulative token usage for a session across all turns. type: object additionalProperties: false properties: input_tokens: description: Total input tokens consumed across all turns. type: integer format: int32 output_tokens: description: Total output tokens generated across all turns. type: integer format: int32 cache_read_input_tokens: description: Total tokens read from prompt cache. type: integer format: int32 cache_creation: description: >- Tokens used to create prompt cache entries, broken down by cache TTL. allOf: - $ref: '#/components/schemas/BetaManagedAgentsCacheCreationUsage' list_cost: description: >- Cumulative list cost of the session across all turns, priced at public list rates. Absent until cost tracking is available for the session. allOf: - $ref: '#/components/schemas/BetaMonetaryAmount' nullable: true server_tool_use: description: >- Cumulative server-executed tool usage across all turns. Absent until server-tool tracking is available for the session. allOf: - $ref: '#/components/schemas/BetaManagedAgentsServerToolUsage' nullable: true active_seconds: description: >- Cumulative time in seconds during which the session had at least one thread in running status. Overlapping activity from concurrent threads is counted once, unlike `stats.active_seconds`, which sums each thread's own active time. This is the duration the session's runtime cost is priced on. type: number format: double BetaManagedAgentsSessionStats: description: Timing statistics for a session. type: object additionalProperties: false properties: duration_seconds: description: >- Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. type: number format: double active_seconds: description: >- Cumulative time in seconds the session spent in running status. Excludes idle time. type: number format: double BetaAPIError: properties: message: default: Internal server error title: Message type: string type: const: api_error default: api_error title: Type type: string required: - message - type title: APIError type: object BetaAuthenticationError: properties: message: default: Authentication error title: Message type: string type: const: authentication_error default: authentication_error title: Type type: string required: - message - type title: AuthenticationError type: object BetaBillingError: properties: message: default: Billing error title: Message type: string type: const: billing_error default: billing_error title: Type type: string required: - message - type title: BillingError type: object BetaInvalidRequestError: properties: message: default: Invalid request title: Message type: string type: const: invalid_request_error default: invalid_request_error title: Type type: string required: - message - type title: InvalidRequestError type: object BetaNotFoundError: properties: message: default: Not found title: Message type: string type: const: not_found_error default: not_found_error title: Type type: string required: - message - type title: NotFoundError type: object BetaOverloadedError: properties: message: default: Overloaded title: Message type: string type: const: overloaded_error default: overloaded_error title: Type type: string required: - message - type title: OverloadedError type: object BetaPermissionError: properties: message: default: Permission denied title: Message type: string type: const: permission_error default: permission_error title: Type type: string required: - message - type title: PermissionError type: object BetaRateLimitError: properties: message: default: Rate limited title: Message type: string type: const: rate_limit_error default: rate_limit_error title: Type type: string required: - message - type title: RateLimitError type: object BetaGatewayTimeoutError: properties: message: default: Request timeout title: Message type: string type: const: timeout_error default: timeout_error title: Type type: string required: - message - type title: GatewayTimeoutError type: object BetaManagedAgentsAgentParams: description: >- Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version type: object additionalProperties: false required: - id - type properties: id: description: The `agent` ID. type: string minLength: 1 maxLength: 128 type: type: string enum: - agent version: description: >- The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. type: integer format: int32 BetaManagedAgentsAgentWithOverridesParams: description: >- Reference to an `agent` plus optional configuration overrides. Each provided field replaces the agent's value for the caller's use; the agent resource is unchanged. type: object additionalProperties: false required: - type - id properties: type: type: string enum: - agent_with_overrides id: description: The `agent` ID. type: string minLength: 1 maxLength: 128 version: description: The specific `agent` version to use. Omit to use the latest version. type: integer format: int32 model: description: >- Replacement model. Accepts the model string, e.g. `claude-opus-4-6`, or a `model_config` object. Omit to use the agent's model. allOf: - $ref: '#/components/schemas/BetaManagedAgentsModelParams' system: description: >- Replacement system prompt. Up to 100,000 characters. Set to null to clear the agent's system prompt; omit to preserve it. type: string maxLength: 100000 nullable: true tools: description: >- Replacement tool list. Full replacement: the provided array becomes the tool configuration. Send an empty array to clear; omit to preserve the agent's tools. type: array items: $ref: '#/components/schemas/BetaManagedAgentsAgentToolParams' mcp_servers: description: >- Replacement MCP server list. Full replacement: the provided array becomes the MCP servers. Send an empty array to clear; omit to preserve the agent's servers. type: array items: $ref: '#/components/schemas/BetaManagedAgentsMCPServerParams' skills: description: >- Replacement skill list. Full replacement: the provided array becomes the skills. Send an empty array to clear; omit to preserve the agent's skills. type: array items: $ref: '#/components/schemas/BetaManagedAgentsSkillParams' BetaManagedAgentsGitHubRepositoryResourceParams: description: Mount a GitHub repository into the session's container. type: object additionalProperties: false required: - type - url - authorization_token properties: type: type: string enum: - github_repository examples: - github_repository url: description: Github URL of the repository type: string minLength: 1 maxLength: 2048 examples: - https://github.com/example-org/example-repo authorization_token: description: GitHub authorization token used to clone the repository. type: string minLength: 1 maxLength: 4096 examples: - ghp_exampletoken mount_path: description: Mount path in the container. Defaults to `/workspace/`. type: string minLength: 1 maxLength: 4096 nullable: true checkout: description: >- Branch or commit to check out. Defaults to the repository's default branch. allOf: - $ref: '#/components/schemas/BetaManagedAgentsRepositoryCheckout' nullable: true example: type: github_repository url: https://github.com/example-org/example-repo authorization_token: ghp_exampletoken BetaManagedAgentsFileResourceParams: description: Mount a file uploaded via the Files API into the session. type: object additionalProperties: false required: - type - file_id properties: type: type: string enum: - file examples: - file file_id: description: ID of a previously uploaded file. type: string minLength: 1 maxLength: 128 examples: - file_011CNha8iCJcU1wXNR6q4V8w mount_path: description: >- Mount path in the container. Defaults to `/mnt/session/uploads/`. type: string minLength: 1 maxLength: 4096 nullable: true examples: - /uploads/receipt.pdf example: type: file file_id: file_011CNha8iCJcU1wXNR6q4V8w mount_path: /uploads/receipt.pdf BetaManagedAgentsMemoryStoreResourceParam: description: Parameters for attaching a memory store to an agent session. type: object additionalProperties: false required: - type - memory_store_id properties: type: type: string enum: - memory_store memory_store_id: description: >- The memory store ID (memstore_...). Must belong to the caller's organization and workspace. type: string access: description: >- Access mode for the mounted store. Defaults to read_write. read_only mounts the store as a read-only filesystem. allOf: - $ref: '#/components/schemas/BetaManagedAgentsMountMode' nullable: true instructions: description: >- Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. type: string maxLength: 4096 nullable: true BetaManagedAgentsUserMessageEventParams: description: Parameters for sending a user message to the session. type: object additionalProperties: false required: - type - content properties: type: type: string enum: - user.message examples: - user.message content: description: Array of content blocks for the user message. type: array items: $ref: '#/components/schemas/BetaManagedAgentsUserContentBlock' examples: - - type: text text: 'Where is my order #1234?' example: type: user.message content: - type: text text: 'Where is my order #1234?' BetaManagedAgentsUserDefineOutcomeEventParams: description: >- Parameters for defining an outcome the agent should work toward. The agent begins work on receipt. type: object additionalProperties: false required: - type - description - rubric properties: type: type: string enum: - user.define_outcome examples: - user.define_outcome description: description: What the agent should produce. This is the task specification. type: string examples: - Produce a 2-page summary as summary.md rubric: description: How to grade the outcome. Text or file reference. allOf: - $ref: '#/components/schemas/BetaManagedAgentsRubricParams' examples: - type: text content: Must cover all five sections; cite sources inline. max_iterations: description: Eval→revision cycles before giving up. Default 3, max 20. type: integer format: int32 nullable: true examples: - 3 example: type: user.define_outcome description: Produce a 2-page summary as summary.md rubric: type: text content: Must cover all five sections; cite sources inline. max_iterations: 3 BetaManagedAgentsBudgetLimit: description: >- A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`. type: object additionalProperties: false required: - type - max_list_cost properties: type: type: string enum: - limit max_list_cost: description: >- Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge. allOf: - $ref: '#/components/schemas/BetaMonetaryAmount' BetaManagedAgentsModelConfig: description: Model identifier and configuration. type: object additionalProperties: false required: - id properties: id: $ref: '#/components/schemas/BetaManagedAgentsModel' effort: description: >- How hard the model works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. allOf: - $ref: '#/components/schemas/BetaManagedAgentsEffort' examples: - type: low inference_geo: description: >- Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. type: string examples: - inference_geo speed: description: >- Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. allOf: - $ref: '#/components/schemas/BetaManagedAgentsSpeed' examples: - standard example: id: claude-sonnet-4-6 effort: type: low inference_geo: inference_geo speed: standard BetaManagedAgentsAgentTool: description: Union type for tool configurations returned in API responses. type: object discriminator: propertyName: type mapping: agent_toolset_20260401: $ref: '#/components/schemas/BetaManagedAgentsAgentToolset20260401' mcp_toolset: $ref: '#/components/schemas/BetaManagedAgentsMCPToolset' custom: $ref: '#/components/schemas/BetaManagedAgentsCustomTool' oneOf: - $ref: '#/components/schemas/BetaManagedAgentsAgentToolset20260401' - $ref: '#/components/schemas/BetaManagedAgentsMCPToolset' - $ref: '#/components/schemas/BetaManagedAgentsCustomTool' BetaManagedAgentsMCPServer: description: >- Union type for MCP server connection definitions returned in API responses. type: object discriminator: propertyName: type mapping: url: $ref: '#/components/schemas/BetaManagedAgentsMCPServerURLDefinition' oneOf: - $ref: '#/components/schemas/BetaManagedAgentsMCPServerURLDefinition' BetaManagedAgentsSkill: description: Resolved skill as returned in API responses. discriminator: propertyName: type mapping: anthropic: $ref: '#/components/schemas/BetaManagedAgentsAnthropicSkill' custom: $ref: '#/components/schemas/BetaManagedAgentsCustomSkill' oneOf: - $ref: '#/components/schemas/BetaManagedAgentsAnthropicSkill' - $ref: '#/components/schemas/BetaManagedAgentsCustomSkill' BetaManagedAgentsSessionMultiagent: description: >- Resolved multiagent orchestration configuration as returned on a `session`. discriminator: propertyName: type mapping: coordinator: $ref: '#/components/schemas/BetaManagedAgentsSessionMultiagentCoordinator' oneOf: - $ref: '#/components/schemas/BetaManagedAgentsSessionMultiagentCoordinator' BetaManagedAgentsGitHubRepositoryResource: type: object additionalProperties: false required: - type - id - url - mount_path - created_at - updated_at properties: type: type: string enum: - github_repository examples: - github_repository id: type: string examples: - sesrsc_011CZkZCKr6eXyl0gWMOdQiu url: type: string examples: - https://github.com/example-org/example-repo mount_path: type: string examples: - /workspace/example-repo checkout: $ref: '#/components/schemas/BetaManagedAgentsRepositoryCheckout' nullable: true examples: - type: branch name: main created_at: $ref: '#/components/schemas/BetaTimestamp' examples: - '2026-03-15T10:00:00Z' updated_at: $ref: '#/components/schemas/BetaTimestamp' examples: - '2026-03-15T10:00:00Z' example: type: github_repository id: sesrsc_011CZkZCKr6eXyl0gWMOdQiu url: https://github.com/example-org/example-repo mount_path: /workspace/example-repo checkout: type: branch name: main created_at: '2026-03-15T10:00:00Z' updated_at: '2026-03-15T10:00:00Z' BetaManagedAgentsFileResource: type: object additionalProperties: false required: - type - id - file_id - mount_path - created_at - updated_at properties: type: type: string enum: - file examples: - file id: type: string examples: - sesrsc_011CZkZBJq5dWxk9fVLNcPht file_id: type: string examples: - file_011CNha8iCJcU1wXNR6q4V8w mount_path: type: string examples: - /uploads/receipt.pdf created_at: $ref: '#/components/schemas/BetaTimestamp' examples: - '2026-03-15T10:00:00Z' updated_at: $ref: '#/components/schemas/BetaTimestamp' examples: - '2026-03-15T10:00:00Z' example: type: file id: sesrsc_011CZkZBJq5dWxk9fVLNcPht file_id: file_011CNha8iCJcU1wXNR6q4V8w mount_path: /uploads/receipt.pdf created_at: '2026-03-15T10:00:00Z' updated_at: '2026-03-15T10:00:00Z' BetaManagedAgentsMemoryStoreResource: description: A memory store attached to an agent session. type: object additionalProperties: false required: - type - memory_store_id properties: type: type: string enum: - memory_store memory_store_id: description: >- The memory store ID (memstore_...). Must belong to the caller's organization and workspace. type: string access: description: >- Access mode for the mounted store. Defaults to read_write. read_only mounts the store as a read-only filesystem. allOf: - $ref: '#/components/schemas/BetaManagedAgentsMountMode' nullable: true name: description: >- Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource. type: string nullable: true description: description: >- Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description. type: string instructions: description: >- Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. type: string maxLength: 4096 nullable: true mount_path: description: >- Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only. type: string nullable: true BetaManagedAgentsCacheCreationUsage: description: Prompt-cache creation token usage broken down by cache lifetime. type: object additionalProperties: false properties: ephemeral_1h_input_tokens: description: Tokens used to create 1-hour ephemeral cache entries. type: integer format: int32 ephemeral_5m_input_tokens: description: Tokens used to create 5-minute ephemeral cache entries. type: integer format: int32 BetaMonetaryAmount: description: A monetary amount in a specific currency. type: object additionalProperties: false required: - currency - amount properties: currency: description: >- Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced. allOf: - $ref: '#/components/schemas/BetaCurrency' examples: - USD amount: description: >- Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied. type: string examples: - '2500' example: currency: USD amount: '2500' BetaManagedAgentsServerToolUsage: description: >- Cumulative count of server-executed tool invocations, broken down by tool. type: object additionalProperties: false properties: web_search_requests: description: Number of server-executed web search requests. type: integer format: int32 examples: - 3 web_fetch_requests: description: Number of server-executed web fetch requests. type: integer format: int32 examples: - 0 example: web_search_requests: 3 web_fetch_requests: 0 BetaManagedAgentsModelParams: oneOf: - title: BetaManagedAgentsModel allOf: - $ref: '#/components/schemas/BetaManagedAgentsModel' x-stainless-skip: - go - cli - $ref: '#/components/schemas/BetaManagedAgentsModelConfigParams' BetaManagedAgentsAgentToolParams: description: Union type for tool configurations in the tools array. type: object discriminator: propertyName: type mapping: agent_toolset_20260401: $ref: '#/components/schemas/BetaManagedAgentsAgentToolset20260401Params' mcp_toolset: $ref: '#/components/schemas/BetaManagedAgentsMCPToolsetParams' custom: $ref: '#/components/schemas/BetaManagedAgentsCustomToolParams' oneOf: - $ref: '#/components/schemas/BetaManagedAgentsAgentToolset20260401Params' - $ref: '#/components/schemas/BetaManagedAgentsMCPToolsetParams' - $ref: '#/components/schemas/BetaManagedAgentsCustomToolParams' BetaManagedAgentsMCPServerParams: description: Union type for MCP server connection definitions. type: object discriminator: propertyName: type mapping: url: $ref: '#/components/schemas/BetaManagedAgentsURLMCPServerParams' oneOf: - $ref: '#/components/schemas/BetaManagedAgentsURLMCPServerParams' BetaManagedAgentsSkillParams: description: Skill to load in the session container. discriminator: propertyName: type mapping: anthropic: $ref: '#/components/schemas/BetaManagedAgentsAnthropicSkillParams' custom: $ref: '#/components/schemas/BetaManagedAgentsCustomSkillParams' oneOf: - $ref: '#/components/schemas/BetaManagedAgentsAnthropicSkillParams' - $ref: '#/components/schemas/BetaManagedAgentsCustomSkillParams' BetaManagedAgentsRepositoryCheckout: type: object discriminator: propertyName: type mapping: branch: $ref: '#/components/schemas/BetaManagedAgentsBranchCheckout' commit: $ref: '#/components/schemas/BetaManagedAgentsCommitCheckout' oneOf: - $ref: '#/components/schemas/BetaManagedAgentsBranchCheckout' - $ref: '#/components/schemas/BetaManagedAgentsCommitCheckout' BetaManagedAgentsMountMode: type: string description: Access mode for an attached memory store. enum: - read_write - read_only BetaManagedAgentsUserContentBlock: description: Content block in a user message. Can be `text`, `image`, or `document`. type: object discriminator: propertyName: type mapping: text: $ref: '#/components/schemas/BetaManagedAgentsTextBlock' image: $ref: '#/components/schemas/BetaManagedAgentsImageBlock' document: $ref: '#/components/schemas/BetaManagedAgentsDocumentBlock' redacted: $ref: '#/components/schemas/BetaManagedAgentsRedactedBlock' oneOf: - $ref: '#/components/schemas/BetaManagedAgentsTextBlock' - $ref: '#/components/schemas/BetaManagedAgentsImageBlock' - $ref: '#/components/schemas/BetaManagedAgentsDocumentBlock' - $ref: '#/components/schemas/BetaManagedAgentsRedactedBlock' BetaManagedAgentsRubricParams: description: Rubric for grading the quality of an outcome. discriminator: propertyName: type mapping: file: $ref: '#/components/schemas/BetaManagedAgentsFileRubricParams' text: $ref: '#/components/schemas/BetaManagedAgentsTextRubricParams' oneOf: - $ref: '#/components/schemas/BetaManagedAgentsFileRubricParams' - $ref: '#/components/schemas/BetaManagedAgentsTextRubricParams' BetaManagedAgentsModel: title: BetaManagedAgentsModel description: |- The model that will power your agent. See models for additional details and options. anyOf: - type: string - const: claude-sonnet-5 description: High-performance model for coding and agents x-stainless-nominal: false - const: claude-fable-5 description: >- Next generation of intelligence for the hardest knowledge work and coding problems x-stainless-nominal: false - const: claude-opus-5 description: Powerful intelligence for long-running agents and coding x-stainless-nominal: false - const: claude-opus-4-8 description: Powerful intelligence for long-running agents and coding x-stainless-nominal: false - const: claude-opus-4-7 description: Powerful intelligence for long-running agents and coding x-stainless-nominal: false - const: claude-opus-4-6 description: Powerful intelligence for long-running agents and coding x-stainless-nominal: false - const: claude-sonnet-4-6 description: Best combination of speed and intelligence x-stainless-nominal: false - const: claude-haiku-4-5 description: Fastest model with near-frontier intelligence x-stainless-nominal: false - const: claude-haiku-4-5-20251001 description: Fastest model with near-frontier intelligence x-stainless-nominal: false - const: claude-opus-4-5 description: Powerful intelligence for long-running agents and coding x-stainless-nominal: false - const: claude-opus-4-5-20251101 description: Powerful intelligence for long-running agents and coding x-stainless-nominal: false - const: claude-sonnet-4-5 description: High-performance model for agents and coding x-stainless-nominal: false - const: claude-sonnet-4-5-20250929 description: High-performance model for agents and coding x-stainless-nominal: false BetaManagedAgentsEffort: description: >- How hard the model works on each turn. Sets `output_config.effort` on every Messages call the session makes. type: object discriminator: propertyName: type mapping: low: $ref: '#/components/schemas/BetaManagedAgentsEffortLow' medium: $ref: '#/components/schemas/BetaManagedAgentsEffortMedium' high: $ref: '#/components/schemas/BetaManagedAgentsEffortHigh' xhigh: $ref: '#/components/schemas/BetaManagedAgentsEffortXhigh' max: $ref: '#/components/schemas/BetaManagedAgentsEffortMax' oneOf: - $ref: '#/components/schemas/BetaManagedAgentsEffortLow' - $ref: '#/components/schemas/BetaManagedAgentsEffortMedium' - $ref: '#/components/schemas/BetaManagedAgentsEffortHigh' - $ref: '#/components/schemas/BetaManagedAgentsEffortXhigh' - $ref: '#/components/schemas/BetaManagedAgentsEffortMax' BetaManagedAgentsSpeed: type: string description: >- Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. enum: - standard - fast BetaManagedAgentsAgentToolset20260401: type: object additionalProperties: false required: - configs - default_config - type properties: configs: type: array items: $ref: '#/components/schemas/BetaManagedAgentsAgentToolConfig' default_config: $ref: '#/components/schemas/BetaManagedAgentsAgentToolsetDefaultConfig' type: type: string enum: - agent_toolset_20260401 BetaManagedAgentsMCPToolset: type: object additionalProperties: false required: - configs - default_config - mcp_server_name - type properties: configs: type: array items: $ref: '#/components/schemas/BetaManagedAgentsMCPToolConfig' default_config: $ref: '#/components/schemas/BetaManagedAgentsMCPToolsetDefaultConfig' mcp_server_name: type: string type: type: string enum: - mcp_toolset BetaManagedAgentsCustomTool: description: A custom tool as returned in API responses. type: object additionalProperties: false required: - description - input_schema - name - type properties: description: type: string input_schema: $ref: '#/components/schemas/BetaManagedAgentsCustomToolInputSchema' name: type: string type: type: string enum: - custom BetaManagedAgentsMCPServerURLDefinition: description: URL-based MCP server connection as returned in API responses. type: object additionalProperties: false required: - name - type - url properties: name: type: string examples: - example-mcp type: type: string enum: - url examples: - url url: type: string examples: - https://example-server.modelcontextprotocol.io/sse example: type: url name: example-mcp url: https://example-server.modelcontextprotocol.io/sse BetaManagedAgentsAnthropicSkill: description: A resolved OMA-managed skill. type: object additionalProperties: false required: - skill_id - type - version properties: skill_id: type: string examples: - xlsx type: type: string enum: - anthropic examples: - anthropic version: type: string examples: - '1' example: type: anthropic skill_id: xlsx version: '1' BetaManagedAgentsCustomSkill: description: A resolved user-created custom skill. type: object additionalProperties: false required: - skill_id - type - version properties: skill_id: type: string examples: - skill_011CZkZFNu9hAbo3jZPRgTlx type: type: string enum: - custom examples: - custom version: type: string examples: - '2' example: type: custom skill_id: skill_011CZkZFNu9hAbo3jZPRgTlx version: '2' BetaManagedAgentsSessionMultiagentCoordinator: description: >- Resolved coordinator topology with full agent definitions for each roster member. type: object additionalProperties: false required: - type - agents properties: type: type: string enum: - coordinator agents: description: >- Full `agent` definitions the coordinator may spawn as session threads. type: array items: $ref: '#/components/schemas/BetaManagedAgentsSessionRosterEntry' BetaCurrency: type: string enum: - USD BetaManagedAgentsModelConfigParams: description: An object that defines additional configuration control over model use type: object additionalProperties: false required: - id properties: id: $ref: '#/components/schemas/BetaManagedAgentsModel' effort: description: >- How hard the model works on each inference call. Accepts a bare level string (`"high"`) or `{"type": "high"}`. On create, omitting it resolves the per-model default; on update, omitting it leaves the stored value unchanged. allOf: - $ref: '#/components/schemas/BetaManagedAgentsEffortParams' nullable: true inference_geo: description: >- Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. On update, `model` is whole-object replacement — omitting inference_geo clears it. type: string nullable: true speed: description: Inference speed mode. Defaults to `standard`. allOf: - $ref: '#/components/schemas/BetaManagedAgentsSpeed' nullable: true example: id: claude-opus-4-8 BetaManagedAgentsAgentToolset20260401Params: description: >- Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. type: object additionalProperties: false required: - type properties: type: type: string enum: - agent_toolset_20260401 configs: description: Per-tool configuration overrides. type: array items: $ref: '#/components/schemas/BetaManagedAgentsAgentToolConfigParams' default_config: description: Default configuration applied to all tools in this set. allOf: - $ref: >- #/components/schemas/BetaManagedAgentsAgentToolsetDefaultConfigParams nullable: true BetaManagedAgentsMCPToolsetParams: description: Configuration for tools from an MCP server defined in `mcp_servers`. type: object additionalProperties: false required: - mcp_server_name - type properties: mcp_server_name: description: >- Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. type: string minLength: 1 maxLength: 255 type: type: string enum: - mcp_toolset configs: description: Per-tool configuration overrides. type: array items: $ref: '#/components/schemas/BetaManagedAgentsMCPToolConfigParams' default_config: description: Default configuration for all tools from this server. allOf: - $ref: >- #/components/schemas/BetaManagedAgentsMCPToolsetDefaultConfigParams nullable: true BetaManagedAgentsCustomToolParams: description: >- A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. type: object additionalProperties: false required: - description - input_schema - name - type properties: description: description: >- Description of what the tool does, shown to the agent to help it decide when to use the tool. type: string minLength: 1 input_schema: description: JSON Schema defining the expected input parameters for the tool. allOf: - $ref: '#/components/schemas/BetaManagedAgentsCustomToolInputSchema' name: description: >- Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. type: string minLength: 1 maxLength: 128 type: type: string enum: - custom BetaManagedAgentsURLMCPServerParams: description: URL-based MCP server connection. type: object additionalProperties: false required: - name - type - url properties: name: description: >- Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. type: string minLength: 1 maxLength: 255 examples: - example-mcp type: type: string enum: - url examples: - url url: description: Endpoint URL for the MCP server. type: string maxLength: 2048 examples: - https://example-server.modelcontextprotocol.io/sse example: type: url name: example-mcp url: https://example-server.modelcontextprotocol.io/sse BetaManagedAgentsAnthropicSkillParams: description: An OMA-managed skill. type: object additionalProperties: false required: - skill_id - type properties: skill_id: description: Identifier of the OMA skill (e.g., "xlsx"). type: string minLength: 1 maxLength: 64 examples: - xlsx type: type: string enum: - anthropic examples: - anthropic version: description: Version to pin. Defaults to latest if omitted. type: string minLength: 1 maxLength: 64 nullable: true examples: - '1' example: type: anthropic skill_id: xlsx version: '1' BetaManagedAgentsCustomSkillParams: description: A user-created custom skill. type: object additionalProperties: false required: - skill_id - type properties: skill_id: description: Tagged ID of the custom skill (e.g., "skill_01XJ5..."). type: string minLength: 1 maxLength: 64 examples: - skill_011CZkZFNu9hAbo3jZPRgTlx type: type: string enum: - custom examples: - custom version: description: Version to pin. Defaults to latest if omitted. type: string minLength: 1 maxLength: 64 nullable: true examples: - '2' example: type: custom skill_id: skill_011CZkZFNu9hAbo3jZPRgTlx version: '2' BetaManagedAgentsBranchCheckout: type: object additionalProperties: false required: - type - name properties: type: type: string enum: - branch examples: - branch name: description: Branch name to check out. type: string minLength: 1 maxLength: 255 examples: - main example: type: branch name: main BetaManagedAgentsCommitCheckout: type: object additionalProperties: false required: - type - sha properties: type: type: string enum: - commit sha: description: Full commit SHA to check out. type: string minLength: 7 maxLength: 64 BetaManagedAgentsTextBlock: description: Regular text content. type: object additionalProperties: false required: - type - text properties: type: type: string enum: - text examples: - text text: description: The text content. type: string minLength: 1 examples: - 'Where is my order #1234?' example: type: text text: 'Where is my order #1234?' BetaManagedAgentsImageBlock: description: >- Image content specified directly as base64 data or as a reference via a URL. type: object additionalProperties: false required: - type - source properties: type: type: string enum: - image source: description: The source of the image data. allOf: - $ref: '#/components/schemas/BetaManagedAgentsImageSource' BetaManagedAgentsDocumentBlock: description: >- Document content, either specified directly as base64 data, as text, or as a reference via a URL. type: object additionalProperties: false required: - type - source properties: type: type: string enum: - document source: description: The source of the document data. allOf: - $ref: '#/components/schemas/BetaManagedAgentsDocumentSource' title: description: The title of the document. type: string nullable: true context: description: Additional context about the document for the model. type: string nullable: true BetaManagedAgentsRedactedBlock: description: Placeholder for content withheld by OMA model policy. type: object additionalProperties: false required: - type properties: type: type: string enum: - redacted BetaManagedAgentsFileRubricParams: description: Rubric referenced by a file uploaded via the Files API. type: object additionalProperties: false required: - type - file_id properties: type: type: string enum: - file examples: - file file_id: description: ID of the rubric file. type: string examples: - file_011CNha8iCJcU1wXNR6q4V8w example: type: file file_id: file_011CNha8iCJcU1wXNR6q4V8w BetaManagedAgentsTextRubricParams: description: Rubric content provided inline as text. type: object additionalProperties: false required: - type - content properties: type: type: string enum: - text examples: - text content: description: >- Rubric content. Plain text or markdown — the grader treats it as freeform text. Maximum 262144 characters. type: string maxLength: 262144 examples: - Must cover all five sections; cite sources inline. example: type: text content: Must cover all five sections; cite sources inline. BetaManagedAgentsEffortLow: description: Low effort. Favors latency over reasoning depth. type: object additionalProperties: false required: - type properties: type: type: string enum: - low BetaManagedAgentsEffortMedium: description: Medium effort. Balances latency and reasoning depth. type: object additionalProperties: false required: - type properties: type: type: string enum: - medium BetaManagedAgentsEffortHigh: description: High effort. Favors reasoning depth. type: object additionalProperties: false required: - type properties: type: type: string enum: - high BetaManagedAgentsEffortXhigh: description: Extra-high effort. Not all models accept this level. type: object additionalProperties: false required: - type properties: type: type: string enum: - xhigh BetaManagedAgentsEffortMax: description: Maximum effort. Favors reasoning depth over latency. type: object additionalProperties: false required: - type properties: type: type: string enum: - max BetaManagedAgentsAgentToolConfig: description: Configuration for a specific agent tool. type: object additionalProperties: false required: - enabled - name - permission_policy properties: enabled: type: boolean name: $ref: '#/components/schemas/BetaManagedAgentsAgentToolName' permission_policy: $ref: '#/components/schemas/BetaManagedAgentsPermissionPolicy' BetaManagedAgentsAgentToolsetDefaultConfig: description: Resolved default configuration for agent tools. type: object additionalProperties: false required: - enabled - permission_policy properties: enabled: type: boolean permission_policy: $ref: '#/components/schemas/BetaManagedAgentsPermissionPolicy' BetaManagedAgentsMCPToolConfig: description: Resolved configuration for a specific MCP tool. type: object additionalProperties: false required: - enabled - name - permission_policy properties: enabled: type: boolean name: type: string permission_policy: $ref: '#/components/schemas/BetaManagedAgentsPermissionPolicy' BetaManagedAgentsMCPToolsetDefaultConfig: description: Resolved default configuration for all tools from an MCP server. type: object additionalProperties: false required: - enabled - permission_policy properties: enabled: type: boolean permission_policy: $ref: '#/components/schemas/BetaManagedAgentsPermissionPolicy' BetaManagedAgentsCustomToolInputSchema: additionalProperties: true description: JSON Schema for custom tool input parameters. properties: type: const: object title: Type type: string properties: anyOf: - type: object additionalProperties: true - type: 'null' title: Properties x-stainless-skip: - terraform required: anyOf: - items: type: string type: array - type: 'null' title: Required required: - type type: object BetaManagedAgentsSessionRosterEntry: description: A session-resolved multiagent roster entry. discriminator: propertyName: type mapping: agent: $ref: '#/components/schemas/BetaManagedAgentsSessionThreadAgent' advisor: $ref: '#/components/schemas/BetaManagedAgentsAdvisor' oneOf: - $ref: '#/components/schemas/BetaManagedAgentsSessionThreadAgent' - $ref: '#/components/schemas/BetaManagedAgentsAdvisor' BetaManagedAgentsEffortParams: oneOf: - $ref: '#/components/schemas/BetaManagedAgentsEffortLevel' - $ref: '#/components/schemas/BetaManagedAgentsEffort' BetaManagedAgentsAgentToolConfigParams: description: Configuration override for a specific tool within a toolset. type: object additionalProperties: false required: - name properties: name: $ref: '#/components/schemas/BetaManagedAgentsAgentToolName' enabled: description: >- Whether this tool is enabled and available to the model. Overrides the default_config setting. type: boolean nullable: true permission_policy: description: >- Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. allOf: - $ref: '#/components/schemas/BetaManagedAgentsPermissionPolicy' nullable: true BetaManagedAgentsAgentToolsetDefaultConfigParams: description: Default configuration for all tools in a toolset. type: object additionalProperties: false properties: enabled: description: >- Whether tools are enabled and available to the model by default. Defaults to true if not specified. type: boolean nullable: true permission_policy: description: >- Default permission policy for tools. Controls whether tool calls are auto-approved or require confirmation. allOf: - $ref: '#/components/schemas/BetaManagedAgentsPermissionPolicy' nullable: true BetaManagedAgentsMCPToolConfigParams: description: Configuration override for a specific MCP tool. type: object additionalProperties: false required: - name properties: name: description: Name of the MCP tool to configure. 1-128 characters. type: string minLength: 1 maxLength: 128 enabled: description: >- Whether this tool is enabled. Overrides the `default_config` setting. type: boolean nullable: true permission_policy: description: >- Permission policy for this tool. Overrides the `default_config` setting. allOf: - $ref: '#/components/schemas/BetaManagedAgentsPermissionPolicy' nullable: true BetaManagedAgentsMCPToolsetDefaultConfigParams: description: Default configuration for all tools from an MCP server. type: object additionalProperties: false properties: enabled: description: >- Whether tools are enabled by default. Defaults to true if not specified. type: boolean nullable: true permission_policy: description: Default permission policy for tools from this server. allOf: - $ref: '#/components/schemas/BetaManagedAgentsPermissionPolicy' nullable: true BetaManagedAgentsImageSource: description: Union type for image source variants. type: object discriminator: propertyName: type mapping: base64: $ref: '#/components/schemas/BetaManagedAgentsBase64ImageSource' url: $ref: '#/components/schemas/BetaManagedAgentsURLImageSource' file: $ref: '#/components/schemas/BetaManagedAgentsFileImageSource' oneOf: - $ref: '#/components/schemas/BetaManagedAgentsBase64ImageSource' - $ref: '#/components/schemas/BetaManagedAgentsURLImageSource' - $ref: '#/components/schemas/BetaManagedAgentsFileImageSource' BetaManagedAgentsDocumentSource: description: Union type for document source variants. type: object discriminator: propertyName: type mapping: base64: $ref: '#/components/schemas/BetaManagedAgentsBase64DocumentSource' text: $ref: '#/components/schemas/BetaManagedAgentsPlainTextDocumentSource' url: $ref: '#/components/schemas/BetaManagedAgentsURLDocumentSource' file: $ref: '#/components/schemas/BetaManagedAgentsFileDocumentSource' oneOf: - $ref: '#/components/schemas/BetaManagedAgentsBase64DocumentSource' - $ref: '#/components/schemas/BetaManagedAgentsPlainTextDocumentSource' - $ref: '#/components/schemas/BetaManagedAgentsURLDocumentSource' - $ref: '#/components/schemas/BetaManagedAgentsFileDocumentSource' BetaManagedAgentsAgentToolName: type: string description: Built-in agent tool identifier. enum: - bash - edit - read - write - glob - grep - web_fetch - web_search BetaManagedAgentsPermissionPolicy: description: Permission policy for tool execution. type: object discriminator: propertyName: type mapping: always_allow: $ref: '#/components/schemas/BetaManagedAgentsAlwaysAllowPolicy' always_ask: $ref: '#/components/schemas/BetaManagedAgentsAlwaysAskPolicy' oneOf: - $ref: '#/components/schemas/BetaManagedAgentsAlwaysAllowPolicy' - $ref: '#/components/schemas/BetaManagedAgentsAlwaysAskPolicy' BetaManagedAgentsSessionThreadAgent: description: >- Resolved `agent` definition for a single `session_thread`. Snapshot of the agent at thread creation time. The multiagent roster is not repeated here; read it from `Session.agent`. type: object additionalProperties: false required: - type - id - version - name - description - model - system - tools - mcp_servers - skills properties: type: type: string enum: - agent examples: - agent id: type: string examples: - agent_011CZkYqphY8vELVzwCUpqiQ version: type: integer format: int32 examples: - 1 name: type: string examples: - Researcher description: type: string nullable: true examples: - A focused research subagent. model: $ref: '#/components/schemas/BetaManagedAgentsModelConfig' examples: - id: claude-sonnet-4-6 speed: standard system: type: string nullable: true examples: - >- You are a research subagent that gathers and summarises sources for the coordinating agent. tools: type: array items: $ref: '#/components/schemas/BetaManagedAgentsAgentTool' examples: - - type: agent_toolset_20260401 default_config: enabled: true permission_policy: type: always_ask configs: [] mcp_servers: type: array items: $ref: '#/components/schemas/BetaManagedAgentsMCPServer' examples: - [] skills: type: array items: $ref: '#/components/schemas/BetaManagedAgentsSkill' examples: - [] example: type: agent id: agent_011CZkYqphY8vELVzwCUpqiQ version: 1 name: Researcher description: A focused research subagent. model: id: claude-sonnet-4-6 speed: standard system: >- You are a research subagent that gathers and summarises sources for the coordinating agent. tools: - type: agent_toolset_20260401 default_config: enabled: true permission_policy: type: always_ask configs: [] mcp_servers: [] skills: [] BetaManagedAgentsAdvisor: description: >- Platform advisor roster entry: a model the session's primary thread may consult mid-turn. type: object additionalProperties: false required: - model - type properties: model: description: The advisor model id. type: string type: type: string enum: - advisor BetaManagedAgentsEffortLevel: type: string description: >- How hard the model works on each turn. Higher levels favor reasoning depth over latency. Not all models accept every level; invalid combinations are rejected at create time. enum: - low - medium - high - xhigh - max BetaManagedAgentsBase64ImageSource: description: Base64-encoded image data. type: object additionalProperties: false required: - type - media_type - data properties: type: type: string enum: - base64 media_type: description: >- MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). type: string minLength: 1 data: description: Base64-encoded image data. type: string minLength: 1 BetaManagedAgentsURLImageSource: description: Image referenced by URL. type: object additionalProperties: false required: - type - url properties: type: type: string enum: - url url: description: URL of the image to fetch. type: string minLength: 1 BetaManagedAgentsFileImageSource: description: Image referenced by file ID. type: object additionalProperties: false required: - type - file_id properties: type: type: string enum: - file file_id: description: ID of a previously uploaded file. type: string minLength: 1 BetaManagedAgentsBase64DocumentSource: description: Base64-encoded document data. type: object additionalProperties: false required: - type - media_type - data properties: type: type: string enum: - base64 media_type: description: MIME type of the document (e.g., "application/pdf"). type: string minLength: 1 data: description: Base64-encoded document data. type: string minLength: 1 BetaManagedAgentsPlainTextDocumentSource: description: Plain text document content. type: object additionalProperties: false required: - type - media_type - data properties: type: type: string enum: - text media_type: description: MIME type of the text content. Must be "text/plain". type: string enum: - text/plain data: description: The plain text content. type: string minLength: 1 BetaManagedAgentsURLDocumentSource: description: Document referenced by URL. type: object additionalProperties: false required: - type - url properties: type: type: string enum: - url url: description: URL of the document to fetch. type: string minLength: 1 BetaManagedAgentsFileDocumentSource: description: Document referenced by file ID. type: object additionalProperties: false required: - type - file_id properties: type: type: string enum: - file file_id: description: ID of a previously uploaded file. type: string minLength: 1 BetaManagedAgentsAlwaysAllowPolicy: description: Tool calls are automatically approved without user confirmation. type: object additionalProperties: false required: - type properties: type: type: string enum: - always_allow BetaManagedAgentsAlwaysAskPolicy: description: Tool calls require user confirmation before execution. type: object additionalProperties: false required: - type properties: type: type: string enum: - always_ask securitySchemes: omaApiKey: type: apiKey in: header name: X-Api-Key description: OMA workspace API key. x-default: sk-ant-local-default omaBearer: type: http scheme: bearer description: OMA workspace API key sent as a bearer token. ````