openapi: 3.2.0 info: title: OpenAI Agents API description: The OpenAI REST API. Please see https://platform.openai.com/docs/api-reference for more details. version: 2.3.0 termsOfService: https://openai.com/policies/terms-of-use contact: name: OpenAI Support url: https://help.openai.com/ license: name: MIT identifier: MIT servers: - url: https://api.openai.com/v1 security: - ApiKeyAuth: [] tags: - name: Agents paths: /agents/environments/{environment_id}: get: operationId: retrieveAgentEnvironment summary: Retrieve an agent environment description: Retrieves an execution environment's connection status and safe installed metadata. See environment lifecycle. tags: - Agents parameters: - name: environment_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 description: The ID of the environment. responses: '200': description: The requested environment. content: application/json: schema: $ref: '#/components/schemas/PublicEnvironmentResource' '400': description: The request was invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '401': description: Authentication or project context was missing. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': description: The requested session or event was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '409': description: The request conflicted with the current session state. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '500': description: An internal error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '503': description: The service is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' /agents/environments/{environment_id}/files: get: operationId: listAgentEnvironmentFiles summary: List agent environment files description: Lists live files on a connected execution environment with optional directory filtering and opaque cursor pagination. See environment files. tags: - Agents parameters: - name: environment_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 description: The ID of the environment. - name: path in: query required: false schema: type: - string - 'null' minLength: 0 maxLength: 1048576 description: Restrict the listing to this absolute workspace directory. - name: limit in: query required: false schema: type: - integer - 'null' format: int64 minimum: 1 maximum: 100 description: The maximum number of files to return, between 1 and 100. - name: order in: query required: false schema: $ref: '#/components/schemas/ListOrderParam' description: Sort by case-sensitive path components. Defaults to descending. - name: page in: query required: false schema: type: string minLength: 0 maxLength: 1048576 description: The opaque token from the previous page. Keep the same path, order, and limit. responses: '200': description: A page of live environment files. content: application/json: schema: $ref: '#/components/schemas/EnvironmentFileListResource' '400': description: The request was invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '401': description: Authentication or project context was missing. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': description: The requested session or event was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '409': description: The request conflicted with the current session state. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '500': description: An internal error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '503': description: The service is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' post: operationId: createAgentEnvironmentFile summary: Create an agent environment file description: Copies inline bytes or a Files API file into a connected execution environment. See environment files. tags: - Agents parameters: - name: environment_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 description: The ID of the environment. requestBody: content: application/json: schema: $ref: '#/components/schemas/HostedEnvironmentFileParam' responses: '201': description: The created live environment file. content: application/json: schema: $ref: '#/components/schemas/EnvironmentFileResource' '400': description: The request was invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '401': description: Authentication or project context was missing. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': description: The requested session or event was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '409': description: The request conflicted with the current session state. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '500': description: An internal error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '503': description: The service is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' /agents/sessions/{session_id}/subagents: get: operationId: listAgentSessionSubagents summary: List session subagents description: Lists subagents in a session, including nested and closed subagents. See subagent workflows. tags: - Agents parameters: - name: session_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 description: The ID of the session. - name: limit in: query required: false schema: type: integer format: int64 minimum: 1 maximum: 100 default: 20 description: The maximum number of resources to return, between 1 and 100. Defaults to 20. - name: order in: query required: false schema: $ref: '#/components/schemas/ListOrderParam' default: desc description: The order in which resources are returned. Defaults to `desc`. - name: after in: query required: false schema: type: string minLength: 0 maxLength: 1048576 description: Return resources after this resource ID in the selected order. responses: '200': description: The requested subagents. content: application/json: schema: type: object properties: object: type: string enum: - list default: list x-stainless-const: true description: The object type, which is always `list`. data: type: array items: $ref: '#/components/schemas/SubagentResource' minItems: 0 maxItems: 2000 description: The resources returned in this page, in the requested sort order. first_id: type: - string - 'null' minLength: 0 description: The ID of the first resource in `data`, or `null` if the page is empty. last_id: type: - string - 'null' minLength: 0 description: The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. has_more: type: boolean description: Whether there are more resources to retrieve after this page. required: - object - data - first_id - last_id - has_more additionalProperties: false description: A page of Agents API resources, with IDs for retrieving additional pages. '400': description: The request was invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '401': description: Authentication or project context was missing. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '403': description: The API key lacks the required permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': description: The requested session or event was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '409': description: The request conflicted with the current session state. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '500': description: An internal error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '503': description: The service is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' /agents/sessions/{session_id}/subagents/{subagent_id}: get: operationId: retrieveAgentSessionSubagent summary: Retrieve a session subagent description: Retrieves a subagent belonging to this session. See subagent workflows. tags: - Agents parameters: - name: session_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 description: The ID of the session. - name: subagent_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 description: The ID of the subagent in this session. responses: '200': description: The requested subagent. content: application/json: schema: $ref: '#/components/schemas/SubagentResource' '400': description: The request was invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '401': description: Authentication or project context was missing. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '403': description: The API key lacks the required permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': description: The requested session or event was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '409': description: The request conflicted with the current session state. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '500': description: An internal error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '503': description: The service is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' /agents/sessions/{session_id}/subagents/{subagent_id}/items: get: operationId: listAgentSessionSubagentItems summary: List subagent items description: Lists this subagent's own items across all of its turns. See subagent workflows. tags: - Agents parameters: - name: session_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 description: The ID of the session. - name: subagent_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 description: The ID of the subagent in this session. - name: limit in: query required: false schema: type: integer format: int64 minimum: 1 maximum: 100 default: 20 description: The maximum number of resources to return, between 1 and 100. Defaults to 20. - name: order in: query required: false schema: $ref: '#/components/schemas/ListOrderParam' default: desc description: The order in which resources are returned. Defaults to `desc`. - name: after in: query required: false schema: type: string minLength: 0 maxLength: 1048576 description: Return resources after this resource ID in the selected order. responses: '200': description: The requested subagent history. content: application/json: schema: $ref: '#/components/schemas/SessionItemListResource' '400': description: The request was invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '401': description: Authentication or project context was missing. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '403': description: The API key lacks the required permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': description: The requested session or event was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '409': description: The request conflicted with the current session state. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '500': description: An internal error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '503': description: The service is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' /agents/sessions/{session_id}/subagents/{subagent_id}/turns: get: operationId: listAgentSessionSubagentTurns summary: List subagent turns description: Lists all turns of this subagent, including turns after a resume. See subagent workflows. tags: - Agents parameters: - name: session_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 description: The ID of the session. - name: subagent_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 description: The ID of the subagent in this session. - name: limit in: query required: false schema: type: integer format: int64 minimum: 1 maximum: 100 default: 20 description: The maximum number of resources to return, between 1 and 100. Defaults to 20. - name: order in: query required: false schema: $ref: '#/components/schemas/ListOrderParam' default: desc description: The order in which resources are returned. Defaults to `desc`. - name: after in: query required: false schema: type: string minLength: 0 maxLength: 1048576 description: Return resources after this resource ID in the selected order. responses: '200': description: The requested subagent history. content: application/json: schema: $ref: '#/components/schemas/SessionTurnListResource' description: A page of turns from an agent session or subagent. '400': description: The request was invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '401': description: Authentication or project context was missing. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '403': description: The API key lacks the required permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': description: The requested session or event was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '409': description: The request conflicted with the current session state. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '500': description: An internal error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '503': description: The service is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' /agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}: get: operationId: retrieveAgentSessionSubagentTurn summary: Retrieve a subagent turn description: Retrieves a turn belonging to this subagent. See subagent workflows. tags: - Agents parameters: - name: session_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 description: The ID of the session. - name: subagent_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 description: The ID of the subagent in this session. - name: turn_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 description: The ID of a turn belonging to this subagent. responses: '200': description: The requested subagent history. content: application/json: schema: $ref: '#/components/schemas/TurnResource' '400': description: The request was invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '401': description: Authentication or project context was missing. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '403': description: The API key lacks the required permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': description: The requested session or event was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '409': description: The request conflicted with the current session state. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '500': description: An internal error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '503': description: The service is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' /agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}/items: get: operationId: listAgentSessionSubagentTurnItems summary: List subagent turn items description: Lists items belonging to one turn of this subagent. See subagent workflows. tags: - Agents parameters: - name: session_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 description: The ID of the session. - name: subagent_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 description: The ID of the subagent in this session. - name: turn_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 description: The ID of a turn belonging to this subagent. - name: limit in: query required: false schema: type: integer format: int64 minimum: 1 maximum: 100 default: 20 description: The maximum number of resources to return, between 1 and 100. Defaults to 20. - name: order in: query required: false schema: $ref: '#/components/schemas/ListOrderParam' default: desc description: The order in which resources are returned. Defaults to `desc`. - name: after in: query required: false schema: type: string minLength: 0 maxLength: 1048576 description: Return resources after this resource ID in the selected order. responses: '200': description: The requested subagent history. content: application/json: schema: $ref: '#/components/schemas/SessionItemListResource' '400': description: The request was invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '401': description: Authentication or project context was missing. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '403': description: The API key lacks the required permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': description: The requested session or event was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '409': description: The request conflicted with the current session state. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '500': description: An internal error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '503': description: The service is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' /agents: get: operationId: listAgents summary: List agents description: Lists reusable agents in the current project. See agent configuration. tags: - Agents parameters: - name: limit in: query required: false schema: type: - integer - 'null' format: int64 minimum: 1 description: The maximum number of resources to return. - name: order in: query required: false schema: $ref: '#/components/schemas/ListOrderParam' default: desc description: The order in which resources are returned. Defaults to `desc`. - name: after in: query required: false schema: type: string minLength: 0 maxLength: 1048576 description: Return resources after this resource ID in the selected order. responses: '200': description: A page of agents. content: application/json: schema: $ref: '#/components/schemas/AgentListResource' description: A page of reusable agents. '400': description: The request was invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '401': description: Authentication or project context was missing. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': description: The requested session or event was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '409': description: The request conflicted with the current session state. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '500': description: An internal error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '503': description: The service is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' post: operationId: createAgent summary: Create an agent description: Creates a reusable agent without storing credentials. See agent configuration. tags: - Agents requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateAgentParams' responses: '201': description: The created agent. content: application/json: schema: $ref: '#/components/schemas/AgentResource' '400': description: The request was invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '401': description: Authentication or project context was missing. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': description: The requested session or event was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '409': description: The request conflicted with the current session state. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '500': description: An internal error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '503': description: The service is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' /agents/{agent_id}: get: operationId: retrieveAgent summary: Retrieve an agent description: Retrieves a reusable agent by ID. See agent configuration. tags: - Agents parameters: - name: agent_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 description: The ID of the reusable agent. responses: '200': description: The requested agent. content: application/json: schema: $ref: '#/components/schemas/AgentResource' '400': description: The request was invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '401': description: Authentication or project context was missing. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': description: The requested session or event was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '409': description: The request conflicted with the current session state. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '500': description: An internal error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '503': description: The service is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' post: operationId: updateAgent summary: Update an agent description: Updates a reusable agent. See agent configuration. tags: - Agents parameters: - name: agent_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 description: The ID of the reusable agent. requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateAgentParams' responses: '200': description: The updated agent. content: application/json: schema: $ref: '#/components/schemas/AgentResource' '400': description: The request was invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '401': description: Authentication or project context was missing. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': description: The requested session or event was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '409': description: The request conflicted with the current session state. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '500': description: An internal error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '503': description: The service is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' delete: operationId: deleteAgent summary: Delete an agent description: Deletes a reusable agent. See agent configuration. tags: - Agents parameters: - name: agent_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 description: The ID of the reusable agent. responses: '200': description: The deleted agent. content: application/json: schema: $ref: '#/components/schemas/DeletedAgentResource' '400': description: The request was invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '401': description: Authentication or project context was missing. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': description: The requested session or event was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '409': description: The request conflicted with the current session state. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '500': description: An internal error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '503': description: The service is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' /agents/environments/templates: get: operationId: listAgentEnvironmentTemplates summary: List agent environment templates description: Lists reusable environment templates without returning confidential values. See reusing a hosted setup. tags: - Agents parameters: - name: limit in: query required: false schema: type: integer format: int64 minimum: 1 maximum: 100 default: 20 description: The maximum number of resources to return, between 1 and 100. Defaults to 20. - name: order in: query required: false schema: $ref: '#/components/schemas/ListOrderParam' default: desc description: The order in which resources are returned. Defaults to `desc`. - name: after in: query required: false schema: type: string minLength: 0 maxLength: 1048576 description: Return resources after this resource ID in the selected order. responses: '200': description: A page of environment templates. content: application/json: schema: $ref: '#/components/schemas/EnvironmentTemplateListResource' description: A page of reusable environment templates. '400': description: The request was invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '401': description: Authentication or project context was missing. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '403': description: The API key lacks the required management permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': description: The requested environment definition was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '500': description: An internal error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '503': description: The service is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' post: operationId: createAgentEnvironmentTemplate summary: Create an agent environment template description: Creates reusable environment configuration without returning confidential setup commands or environment values. See reusing a hosted setup. tags: - Agents requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateEnvironmentTemplateParams' responses: '201': description: The created environment template. content: application/json: schema: $ref: '#/components/schemas/EnvironmentTemplateResource' '400': description: The request was invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '401': description: Authentication or project context was missing. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '403': description: The API key lacks the required management permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': description: The requested environment definition was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '500': description: An internal error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '503': description: The service is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' /agents/environments/templates/{environment_template_id}: get: operationId: retrieveAgentEnvironmentTemplate summary: Retrieve an agent environment template description: Retrieves reusable environment configuration without returning confidential values. See reusing a hosted setup. tags: - Agents parameters: - name: environment_template_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 description: The ID of the reusable environment template. responses: '200': description: The requested environment template. content: application/json: schema: $ref: '#/components/schemas/EnvironmentTemplateResource' '400': description: The request was invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '401': description: Authentication or project context was missing. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '403': description: The API key lacks the required management permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': description: The requested environment definition was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '500': description: An internal error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '503': description: The service is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' post: operationId: updateAgentEnvironmentTemplate summary: Update an agent environment template description: Updates reusable environment configuration without returning confidential values. See reusing a hosted setup. tags: - Agents parameters: - name: environment_template_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 description: The ID of the reusable environment template. requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateEnvironmentTemplateParams' responses: '200': description: The updated environment template. content: application/json: schema: $ref: '#/components/schemas/EnvironmentTemplateResource' '400': description: The request was invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '401': description: Authentication or project context was missing. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '403': description: The API key lacks the required management permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': description: The requested environment definition was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '409': description: The request conflicted with the current environment state. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '500': description: An internal error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '503': description: The service is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' delete: operationId: deleteAgentEnvironmentTemplate summary: Delete an agent environment template description: Deletes reusable environment configuration and all confidential template inputs. See reusing a hosted setup. tags: - Agents parameters: - name: environment_template_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 description: The ID of the reusable environment template. responses: '200': description: The deleted environment template. content: application/json: schema: $ref: '#/components/schemas/DeletedEnvironmentTemplateResource' '400': description: The request was invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '401': description: Authentication or project context was missing. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '403': description: The API key lacks the required management permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': description: The requested environment definition was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '409': description: The request conflicted with the current environment state. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '500': description: An internal error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '503': description: The service is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' /agents/sessions: get: operationId: listAgentSessions summary: List agent sessions description: Lists managed agent sessions using ID-based pagination and the requested sort order. See managing sessions. tags: - Agents parameters: - name: limit in: query required: false schema: type: - integer - 'null' format: int64 minimum: 1 description: The maximum number of resources to return. - name: order in: query required: false schema: $ref: '#/components/schemas/ListOrderParam' default: desc description: Sort order by the `created_at` timestamp. Use `asc` for ascending order or `desc` for descending order. Defaults to `desc`. - name: agent_id in: query required: false schema: type: string minLength: 0 maxLength: 1048576 description: Only return sessions whose root agent has this ID. Omit to return sessions for all agents. - name: after in: query required: false schema: type: string minLength: 0 maxLength: 1048576 description: Return resources after this resource ID in the selected order. responses: '200': description: A page of sessions. content: application/json: schema: $ref: '#/components/schemas/SessionListResource' description: A paginated list of sessions. '400': description: The request was invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '401': description: Authentication or project context was missing. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '403': description: The API key lacks the required permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': description: The requested session or event was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '409': description: The request conflicted with the current session state. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '500': description: An internal error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '503': description: The service is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' post: operationId: createAgentSession summary: Create an agent session description: Creates a managed agent session, optionally submits initial input, and returns the session or streams its events when stream is true. See running sessions. tags: - Agents requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateAgentSessionParams' responses: '201': description: The created session or its event stream. content: application/json: schema: $ref: '#/components/schemas/SessionResource' text/event-stream: schema: $ref: '#/components/schemas/SessionEvent' '400': description: The request was invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '401': description: Authentication or project context was missing. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '403': description: The API key lacks the required permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': description: The requested session or event was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '409': description: The request conflicted with the current session state. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '500': description: An internal error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '503': description: The service is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' x-oai-streaming: request_field: stream response_status_code: 201 /agents/sessions/{session_id}: get: operationId: retrieveAgentSession summary: Retrieve an agent session description: Retrieves the current state of a managed agent session. See managing sessions. tags: - Agents parameters: - name: session_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 description: The ID of the session. responses: '200': description: The requested session. content: application/json: schema: $ref: '#/components/schemas/SessionResource' '400': description: The request was invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '401': description: Authentication or project context was missing. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '403': description: The API key lacks the required permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': description: The requested session or event was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '409': description: The request conflicted with the current session state. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '500': description: An internal error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '503': description: The service is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' post: operationId: updateAgentSession summary: Update an agent session description: Updates session metadata, model, reasoning effort, or service tier. Model settings apply to subsequent turns. Omitted fields are unchanged. See managing sessions. tags: - Agents parameters: - name: session_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 description: The ID of the session. requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateAgentSessionParams' responses: '200': description: The updated session. content: application/json: schema: $ref: '#/components/schemas/SessionResource' '400': description: The request was invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '401': description: Authentication or project context was missing. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '403': description: The API key lacks the required permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': description: The requested session or event was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '409': description: The request conflicted with the current session state. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '500': description: An internal error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '503': description: The service is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' delete: operationId: deleteAgentSession summary: Delete an agent session description: Removes a managed agent session from the public API and returns a deletion confirmation. If backend execution has ended, deletion can cancel a still-open public turn and abandon unpublished outputs. Running execution must be cancelled first. Physical cleanup may continue asynchronously. See managing sessions. tags: - Agents parameters: - name: session_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 description: The ID of the session. responses: '200': description: The deleted session. content: application/json: schema: $ref: '#/components/schemas/DeletedSessionResource' '400': description: The request was invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '401': description: Authentication or project context was missing. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '403': description: The API key lacks the required permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': description: The requested session or event was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '409': description: The request conflicted with the current session state. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '500': description: An internal error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '503': description: The service is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' /agents/sessions/{session_id}/artifacts: get: operationId: listAgentSessionArtifacts summary: List agent session artifacts description: Lists immutable artifacts published by completed hosted session turns. See session artifacts. tags: - Agents parameters: - name: session_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 description: The ID of the session. - name: order in: query required: false schema: $ref: '#/components/schemas/ListOrderParam' description: Sort by creation time and ID. Defaults to descending. - name: environment_id in: query required: false schema: type: - string - 'null' minLength: 0 maxLength: 1048576 description: Restrict the listing to artifacts produced by this environment. - name: limit in: query required: false schema: type: - integer - 'null' format: int64 minimum: 1 maximum: 100 description: The maximum number of artifacts to return, between 1 and 100. - name: after in: query required: false schema: type: - string - 'null' minLength: 0 maxLength: 1048576 description: Return artifacts after this immutable artifact ID. responses: '200': description: A page of durable session artifacts. content: application/json: schema: $ref: '#/components/schemas/SessionArtifactListResource' description: A page of durable artifacts published by a session. '400': description: The request was invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '401': description: Authentication or project context was missing. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '403': description: The API key lacks the required permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': description: The requested session or event was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '409': description: The request conflicted with the current session state. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '500': description: An internal error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '503': description: The service is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' /agents/sessions/{session_id}/artifacts/{artifact_id}: get: operationId: retrieveAgentSessionArtifact summary: Retrieve an agent session artifact description: Retrieves immutable metadata for one durable session artifact. See session artifacts. tags: - Agents parameters: - name: session_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 description: The ID of the session that owns the artifact. - name: artifact_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 description: The immutable session artifact ID. responses: '200': description: The requested session artifact. content: application/json: schema: $ref: '#/components/schemas/SessionArtifactResource' '400': description: The request was invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '401': description: Authentication or project context was missing. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '403': description: The API key lacks the required permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': description: The requested session or event was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '409': description: The request conflicted with the current session state. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '500': description: An internal error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '503': description: The service is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' delete: operationId: deleteAgentSessionArtifact summary: Delete an agent session artifact description: Deletes an immutable session artifact without deleting its live environment file or original Files API object. See session artifacts. tags: - Agents parameters: - name: session_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 description: The ID of the session that owns the artifact. - name: artifact_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 description: The immutable session artifact ID. responses: '200': description: The deleted session artifact. content: application/json: schema: $ref: '#/components/schemas/DeletedSessionArtifactResource' '400': description: The request was invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '401': description: Authentication or project context was missing. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '403': description: The API key lacks the required permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': description: The requested session or event was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '409': description: The request conflicted with the current session state. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '500': description: An internal error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '503': description: The service is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' /agents/sessions/{session_id}/artifacts/{artifact_id}/content: get: operationId: retrieveAgentSessionArtifactContent summary: Retrieve agent session artifact content description: Downloads immutable session artifact bytes after the execution environment expires. See session artifacts. tags: - Agents parameters: - name: session_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 description: The ID of the session that owns the artifact. - name: artifact_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 description: The immutable session artifact ID. responses: '200': description: The immutable artifact contents. content: application/octet-stream: schema: type: string format: binary '400': description: The request was invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '401': description: Authentication or project context was missing. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '403': description: The API key lacks the required permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': description: The requested session or event was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '409': description: The request conflicted with the current session state. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '500': description: An internal error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '503': description: The service is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' /agents/sessions/{session_id}/events: get: operationId: listAgentSessionEvents summary: Stream agent session events description: Streams live events for an agent session. See session events. tags: - Agents parameters: - name: session_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 description: The ID of the session. responses: '200': description: A live stream of session events. content: text/event-stream: schema: $ref: '#/components/schemas/SessionEvent' '400': description: The request was invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '401': description: Authentication or project context was missing. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '403': description: The API key lacks the required permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': description: The requested session or event was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '409': description: The request conflicted with the current session state. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '500': description: An internal error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '503': description: The service is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' x-oai-streaming: request_field: null response_status_code: 200 post: operationId: createAgentSessionEvents summary: Create agent session input events description: Submits message, cancellation, or tool-result events to a managed agent session. Cancellation can recover a still-open turn whose backend execution has ended by marking it cancelled and abandoning unpublished outputs. Saved results, published files, and existing terminal outcomes are preserved. HTTP 202 confirms acceptance, not durable completion. See session events. tags: - Agents parameters: - name: session_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 description: The ID of the session. - name: Idempotency-Key in: header required: false schema: type: string minLength: 1 maxLength: 256 description: An optional client-generated key that makes retries of submitted messages idempotent. requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateSessionEventsParams' responses: '202': description: The events were accepted. '400': description: The request was invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '401': description: Authentication or project context was missing. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '403': description: The API key lacks the required permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': description: The requested session or event was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '409': description: The request conflicted with the current session state. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '500': description: An internal error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '503': description: The service is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' /agents/sessions/{session_id}/items: get: operationId: listAgentSessionItems summary: List agent session items description: Lists items produced by the session's root agent, including its interactions with subagents. Each subagent has its own item history. See inspecting agent output. tags: - Agents parameters: - name: session_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 description: The ID of the session. - name: limit in: query required: false schema: type: integer format: int64 minimum: 1 maximum: 100 default: 20 description: The maximum number of resources to return, between 1 and 100. Defaults to 20. - name: order in: query required: false schema: $ref: '#/components/schemas/ListOrderParam' default: desc description: The order in which resources are returned. Defaults to `desc`. - name: after in: query required: false schema: type: string minLength: 0 maxLength: 1048576 description: Return resources after this resource ID in the selected order. responses: '200': description: A page of session items. content: application/json: schema: $ref: '#/components/schemas/SessionItemListResource' '400': description: The request was invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '401': description: Authentication or project context was missing. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '403': description: The API key lacks the required permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': description: The requested session or event was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '409': description: The request conflicted with the current session state. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '500': description: An internal error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '503': description: The service is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' /agents/sessions/{session_id}/turns: get: operationId: listAgentSessionTurns summary: List agent session turns description: Lists turns by creation time and turn ID. The after cursor is exclusive in the selected order. See session turns. tags: - Agents parameters: - name: session_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 description: The ID of the session. - name: limit in: query required: false schema: type: integer format: int64 minimum: 1 maximum: 100 default: 20 description: The maximum number of resources to return, between 1 and 100. Defaults to 20. - name: order in: query required: false schema: $ref: '#/components/schemas/ListOrderParam' default: desc description: The order in which resources are returned. Defaults to `desc`. - name: after in: query required: false schema: type: string minLength: 0 maxLength: 1048576 description: Return resources after this resource ID in the selected order. responses: '200': description: A page of session turns. content: application/json: schema: $ref: '#/components/schemas/SessionTurnListResource' description: A page of turns from an agent session or subagent. '400': description: The request was invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '401': description: Authentication or project context was missing. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': description: The requested session or event was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '409': description: The request conflicted with the current session state. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '500': description: An internal error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '503': description: The service is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' /agents/sessions/{session_id}/turns/{turn_id}: get: operationId: retrieveAgentSessionTurn summary: Retrieve an agent session turn description: Retrieves a turn's current status, timestamps, usage, and error. Returns 404 if the turn does not belong to the session. See session turns. tags: - Agents parameters: - name: session_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 description: The ID of the session that owns the turn. - name: turn_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 description: The ID of the turn. responses: '200': description: The requested turn. content: application/json: schema: $ref: '#/components/schemas/TurnResource' '400': description: The request was invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '401': description: Authentication or project context was missing. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': description: The requested session or event was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '409': description: The request conflicted with the current session state. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '500': description: An internal error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '503': description: The service is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' components: schemas: EnvironmentTemplateListResource: type: object properties: object: type: string enum: - list default: list x-stainless-const: true description: The object type, which is always `list`. data: type: array items: $ref: '#/components/schemas/EnvironmentTemplateResource' minItems: 0 maxItems: 2000 description: The resources returned in this page, in the requested sort order. first_id: type: - string - 'null' minLength: 0 description: The ID of the first resource in `data`, or `null` if the page is empty. last_id: type: - string - 'null' minLength: 0 description: The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. has_more: type: boolean description: Whether there are more resources to retrieve after this page. required: - object - data - first_id - last_id - has_more additionalProperties: false description: A page of Agents API resources, with IDs for retrieving additional pages. AgentToolConfigParamWebSearch: type: object properties: type: type: string enum: - web_search default: web_search x-stainless-const: true description: The type of the object. Always `web_search`. mode: anyOf: - $ref: '#/components/schemas/WebSearchModeParam' - type: 'null' description: The source used for web search results. Defaults to `live`. context_size: anyOf: - $ref: '#/components/schemas/WebSearchContextSizeParam' - type: 'null' description: The amount of search context made available to the model. Defaults to `medium`. allowed_domains: type: - array - 'null' items: type: string minLength: 0 maxLength: 1048576 minItems: 0 maxItems: 16384 description: Domains the search may include. location: anyOf: - $ref: '#/components/schemas/WebSearchLocationParam' - type: 'null' description: Approximate location used to localize search results. required: - type additionalProperties: false description: Web search. SessionEventAgentSessionTurnContentPartAdded: type: object properties: type: type: string enum: - agent.session.turn.content_part.added default: agent.session.turn.content_part.added x-stainless-const: true description: The type of the object. Always `agent.session.turn.content_part.added`. event_id: type: string minLength: 0 description: The unique ID of the event. session_id: type: string minLength: 0 description: The ID of the session associated with the event. turn_id: type: - string - 'null' minLength: 0 description: The ID of the turn associated with the event, when applicable. item_id: type: string minLength: 0 description: The ID of the message item. output_index: type: integer format: int64 minimum: 0 maximum: 4294967295 description: The index of the item in the turn output. content_index: type: integer format: int64 minimum: 0 maximum: 4294967295 description: The index of the content part in the message. part: $ref: '#/components/schemas/OutputTextResource' description: The initial content part. required: - type - event_id - session_id - turn_id - item_id - output_index - content_index - part additionalProperties: false description: Emitted when an output text content part is added. InterruptSubagentCallItemResource: type: object properties: type: type: string enum: - interrupt_subagent_call default: interrupt_subagent_call x-stainless-const: true x-enumDescriptions: - The current public item type. description: The item type. Always `interrupt_subagent_call`. id: type: string minLength: 0 description: The ID of the tool call item. turn_id: type: string minLength: 0 description: The ID of the turn that contains this item. status: $ref: '#/components/schemas/FunctionCallStatusResource' description: The status of the tool call. sender_agent_id: type: string minLength: 0 description: The ID of the agent requesting the interrupt. recipient_agent_id: type: string minLength: 0 description: The ID of the agent to interrupt. required: - type - id - turn_id - status - sender_agent_id - recipient_agent_id additionalProperties: false description: A request to interrupt a subagent's current turn. The subagent remains available. InputContentParamInputText: type: object properties: type: type: string enum: - input_text default: input_text x-stainless-const: true description: The type of the object. Always `input_text`. text: type: string minLength: 0 maxLength: 1048576 description: The text sent to the model. required: - type - text additionalProperties: false description: Text input to the model. McpTransportResource: oneOf: - $ref: '#/components/schemas/McpTransportResourceHttp' - $ref: '#/components/schemas/McpTransportResourceStdio' discriminator: propertyName: type mapping: http: '#/components/schemas/McpTransportResourceHttp' stdio: '#/components/schemas/McpTransportResourceStdio' x-oai-discriminator-values: - http - stdio description: The transport used to connect to an MCP server. HostedEnvironmentFileResourceFileId: type: object properties: type: type: string enum: - file_id default: file_id x-stainless-const: true description: The type of the object. Always `file_id`. id: type: string minLength: 0 description: The session-scoped ID of the file in the execution environment. file_id: type: string minLength: 0 description: The ID of the uploaded file. path: type: string minLength: 0 description: The file's absolute path inside the environment. size_bytes: type: integer format: int64 minimum: 0 description: The decoded file size in bytes. required: - type - id - file_id - path - size_bytes additionalProperties: false description: A file copied from the OpenAI Files API. InlineCapabilitySourceParam: oneOf: - $ref: '#/components/schemas/InlineCapabilitySourceParamBase64' discriminator: propertyName: type mapping: base64: '#/components/schemas/InlineCapabilitySourceParamBase64' x-oai-discriminator-values: - base64 description: The encoded ZIP archive for an inline skill or plugin. FunctionCallItemResource: type: object properties: type: type: string enum: - function_call default: function_call x-stainless-const: true description: The item type. Always `function_call`. id: type: string minLength: 0 description: The ID of the function call item. turn_id: type: string minLength: 0 description: The ID of the turn that contains this item. call_id: type: string minLength: 0 description: The ID used to submit the function result. name: type: string minLength: 0 description: The name of the function to call. arguments: description: The arguments to pass to the function. status: $ref: '#/components/schemas/FunctionCallStatusResource' description: The status of the function call. required: - type - id - turn_id - call_id - name - arguments - status additionalProperties: false description: A function call produced by the agent. CreateEnvironmentTemplateParams: type: object properties: packages: anyOf: - $ref: '#/components/schemas/EnvironmentPackagesParam' - type: 'null' description: Packages to install in the environment. Defaults to empty package lists. setup_commands: type: - array - 'null' items: $ref: '#/components/schemas/SetupCommandParam' minItems: 0 maxItems: 16 description: Ordered, confidential setup commands. Command bodies are never returned. network: anyOf: - $ref: '#/components/schemas/NetworkPolicyParam' - type: 'null' description: Network access policy for the environment. Defaults to disabled for GA requests and enabled for alpha/beta requests. env: type: - object - 'null' additionalProperties: type: string minLength: 0 maxLength: 1048576 propertyNames: type: string minLength: 1 maxLength: 256 minProperties: 0 maxProperties: 1024 description: Environment variables made available to the agent. capability_directories: type: - array - 'null' items: type: string minLength: 0 maxLength: 1048576 minItems: 0 maxItems: 16384 description: Directories that contain capabilities exposed to the agent. Defaults to an empty list. skills: type: - array - 'null' items: $ref: '#/components/schemas/HostedSkillParam' minItems: 0 maxItems: 200 description: Skills referenced by ID or provided as inline ZIP archives. Defaults to an empty list. plugins: type: - array - 'null' items: $ref: '#/components/schemas/HostedPluginParam' minItems: 0 maxItems: 32 description: Plugins provided as inline ZIP archives. Defaults to an empty list. files: type: - array - 'null' items: $ref: '#/components/schemas/HostedEnvironmentFileParam' minItems: 0 maxItems: 50 description: Files available before the agent starts. Defaults to an empty list. name: type: - string - 'null' minLength: 1 maxLength: 256 description: An optional human-readable display name for the template. additionalProperties: false description: Parameters for creating a reusable, project-scoped OpenAI-hosted environment template. SessionStatusResource: type: string enum: - idle - in_progress - requires_action - failed x-enumDescriptions: - The session has no turn in progress and is ready for input. A hosted environment may still be provisioning. - The session is processing a turn. - The session is waiting for one or more required actions. - The session failed. description: The current status of a session. SessionEventAgentSessionTurnReasoningSummaryTextDelta: type: object properties: type: type: string enum: - agent.session.turn.reasoning_summary_text.delta default: agent.session.turn.reasoning_summary_text.delta x-stainless-const: true description: The type of the object. Always `agent.session.turn.reasoning_summary_text.delta`. event_id: type: string minLength: 0 description: The unique ID of the event. session_id: type: string minLength: 0 description: The ID of the session associated with the event. turn_id: type: - string - 'null' minLength: 0 description: The ID of the turn associated with the event, when applicable. item_id: type: string minLength: 0 description: The ID of the reasoning item. output_index: type: integer format: int64 minimum: 0 maximum: 4294967295 description: The index of the item in the turn output. summary_index: type: integer format: int64 minimum: 0 maximum: 4294967295 description: The index of the summary content part. delta: type: string minLength: 0 description: The summary text that was appended. required: - type - event_id - session_id - turn_id - item_id - output_index - summary_index - delta additionalProperties: false description: Emitted when text is appended to a reasoning summary. UpdateSessionAgentParam: type: object properties: model: type: string minLength: 0 maxLength: 1048576 description: The model for subsequent turns. Omit to keep the current model. reasoning: $ref: '#/components/schemas/UpdateSessionReasoningParam' description: Reasoning settings to update. Omit to keep the current effort. service_tier: anyOf: - $ref: '#/components/schemas/ServiceTierParam' - type: 'null' description: Omit to keep the current tier. Null resets it to auto. additionalProperties: false description: Model settings that can change after session creation. HostedPluginResourceInline: type: object properties: type: type: string enum: - inline default: inline x-stainless-const: true description: The type of the object. Always `inline`. name: type: string minLength: 0 description: The installed plugin name. description: type: string minLength: 0 description: The installed plugin description. required: - type - name - description additionalProperties: false description: A plugin installed from an inline ZIP archive. TurnStatusResource: type: string enum: - queued - in_progress - waiting - completed - failed - cancelled x-enumDescriptions: - The turn is waiting to start. - The turn is in progress. - The turn is waiting for external input. - The turn completed successfully. - The turn failed. - The turn was cancelled. description: The current status of a turn. SessionEventError: type: object properties: type: type: string enum: - error default: error x-stainless-const: true description: The type of the object. Always `error`. event_id: type: string minLength: 0 description: The unique ID of the event. session_id: type: string minLength: 0 description: The ID of the session associated with the event. error: $ref: '#/components/schemas/SessionErrorResource' description: The error that occurred. required: - type - event_id - session_id - error additionalProperties: false description: Emitted when a turn or session fails. x-oaiMeta: example: type: error event_id: event_123 session_id: sess_123 error: type: server_error code: null message: The session failed due to an internal server error. param: null McpTransportResourceStdio: type: object properties: type: type: string enum: - stdio default: stdio x-stainless-const: true description: The type of the object. Always `stdio`. command: type: string minLength: 0 description: The command used to start the MCP server. args: type: array items: type: string minLength: 0 minItems: 0 maxItems: 2000 description: Arguments passed to the MCP server command. cwd: type: string minLength: 0 description: The working directory used to start the MCP server. env_vars: type: array items: type: string minLength: 0 minItems: 0 maxItems: 2000 description: Environment variable names inherited from the execution environment. required: - type - command - args - cwd - env_vars additionalProperties: false description: Starts an MCP server as a local process. SubagentObjectResource: type: string enum: - agent.session.subagent default: agent.session.subagent x-stainless-const: true description: The object type for a subagent. VerbosityResource: type: string enum: - low - medium - high description: The amount of text produced by an agent. TextFormatResourceText: type: object properties: type: type: string enum: - text default: text x-stainless-const: true description: The type of the object. Always `text`. required: - type additionalProperties: false description: Generates ordinary text without a structured-output constraint. SessionTurnListResource: type: object properties: object: type: string enum: - list default: list x-stainless-const: true description: The object type, which is always `list`. data: type: array items: $ref: '#/components/schemas/TurnResource' minItems: 0 maxItems: 2000 description: The resources returned in this page, in the requested sort order. first_id: type: - string - 'null' minLength: 0 description: The ID of the first resource in `data`, or `null` if the page is empty. last_id: type: - string - 'null' minLength: 0 description: The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. has_more: type: boolean description: Whether there are more resources to retrieve after this page. required: - object - data - first_id - last_id - has_more additionalProperties: false description: A page of Agents API resources, with IDs for retrieving additional pages. SessionTurnErrorResource: type: object properties: code: $ref: '#/components/schemas/SessionTurnErrorCodeResource' description: A stable, machine-readable failure category. message: type: string minLength: 0 description: A customer-safe explanation of the failure. required: - code - message additionalProperties: false description: A customer-safe error describing why a session request failed. AgentToolConfigParamFunction: type: object properties: type: type: string enum: - function default: function x-stainless-const: true description: The type of the object. Always `function`. name: type: string minLength: 0 maxLength: 1048576 description: The name of the function. description: type: string minLength: 0 maxLength: 1048576 description: A description of what the function does. parameters: type: object additionalProperties: {} propertyNames: type: string minLength: 1 maxLength: 256 minProperties: 0 maxProperties: 1024 description: A JSON Schema object describing the function's arguments. defer_loading: type: boolean default: false description: Whether this function is deferred and discovered through tool search. Defaults to `false`. required: - type - name - description - parameters additionalProperties: false description: A function defined by the application. InputContentResource: oneOf: - $ref: '#/components/schemas/InputContentResourceInputText' - $ref: '#/components/schemas/InputContentResourceInputImage' discriminator: propertyName: type mapping: input_text: '#/components/schemas/InputContentResourceInputText' input_image: '#/components/schemas/InputContentResourceInputImage' x-oai-discriminator-values: - input_text - input_image description: User-provided content recorded in a session item. InputContentResourceInputImage: type: object properties: type: type: string enum: - input_image default: input_image x-stainless-const: true description: The type of the object. Always `input_image`. image_url: type: string minLength: 0 description: The URL of the image supplied to the agent, which may be a base64-encoded data URL. required: - type - image_url additionalProperties: false description: Image input recorded in a session item. TextFormatResourceJsonSchema: type: object properties: type: type: string enum: - json_schema default: json_schema x-stainless-const: true description: The type of the object. Always `json_schema`. schema: type: object additionalProperties: {} propertyNames: type: string minLength: 0 minProperties: 0 description: The JSON Schema that generated text must match. required: - type - schema additionalProperties: false description: Constrains generated text to a JSON Schema. McpConnectionOriginParam: type: string enum: - service - environment x-enumDescriptions: - Uses the Managed Agents service network. - Uses the session's execution environment. description: Where outbound MCP HTTP connections originate. WebSearchContextSizeParam: type: string enum: - low - medium - high description: The amount of web search context made available to the model. SessionEventAgentSessionTurnItemDone: type: object properties: type: type: string enum: - agent.session.turn.item.done default: agent.session.turn.item.done x-stainless-const: true description: The type of the object. Always `agent.session.turn.item.done`. event_id: type: string minLength: 0 description: The unique ID of the event. session_id: type: string minLength: 0 description: The ID of the session associated with the event. turn_id: type: - string - 'null' minLength: 0 description: The ID of the turn associated with the event, when applicable. output_index: type: integer format: int64 minimum: 0 maximum: 4294967295 description: The index of the output item in the turn output. item: $ref: '#/components/schemas/AgentOutputItemResource' description: The completed output item. required: - type - event_id - session_id - turn_id - output_index - item additionalProperties: false description: Emitted when an output item is complete. MessagePhaseResource: type: string enum: - commentary - final_answer x-enumDescriptions: - Commentary produced while the agent works. - The agent's final answer. description: The phase of an assistant message. ErrorResponse-2: type: object properties: error: $ref: '#/components/schemas/ErrorBodyResource' description: The error returned by the API. required: - error additionalProperties: false description: An API error response. SessionInputParam: oneOf: - $ref: '#/components/schemas/SessionInputParamAgentSessionInputMessage' - $ref: '#/components/schemas/SessionInputParamAgentSessionInputCancel' - $ref: '#/components/schemas/SessionInputParamAgentSessionInputToolResult' discriminator: propertyName: type mapping: agent.session.input.message: '#/components/schemas/SessionInputParamAgentSessionInputMessage' agent.session.input.cancel: '#/components/schemas/SessionInputParamAgentSessionInputCancel' agent.session.input.tool_result: '#/components/schemas/SessionInputParamAgentSessionInputToolResult' x-oai-discriminator-values: - agent.session.input.message - agent.session.input.cancel - agent.session.input.tool_result description: Input submitted to an existing session. SessionEventAgentSessionTurnReasoningSummaryPartAdded: type: object properties: type: type: string enum: - agent.session.turn.reasoning_summary_part.added default: agent.session.turn.reasoning_summary_part.added x-stainless-const: true description: The type of the object. Always `agent.session.turn.reasoning_summary_part.added`. event_id: type: string minLength: 0 description: The unique ID of the event. session_id: type: string minLength: 0 description: The ID of the session associated with the event. turn_id: type: - string - 'null' minLength: 0 description: The ID of the turn associated with the event, when applicable. item_id: type: string minLength: 0 description: The ID of the reasoning item. output_index: type: integer format: int64 minimum: 0 maximum: 4294967295 description: The index of the item in the turn output. summary_index: type: integer format: int64 minimum: 0 maximum: 4294967295 description: The index of the summary content part. part: $ref: '#/components/schemas/SummaryTextResource' description: The initial summary part. required: - type - event_id - session_id - turn_id - item_id - output_index - summary_index - part additionalProperties: false description: Emitted when a reasoning summary content part is added. SessionEnvironmentStatusResource: type: string enum: - pending - ready - connected - disconnected - failed x-enumDescriptions: - The environment is being prepared. - The environment is ready to connect. - The environment is connected. - The environment is disconnected. - The environment failed to connect. description: The connection status of a session environment. SessionEventAgentSessionTurnReasoningSummaryTextDone: type: object properties: type: type: string enum: - agent.session.turn.reasoning_summary_text.done default: agent.session.turn.reasoning_summary_text.done x-stainless-const: true description: The type of the object. Always `agent.session.turn.reasoning_summary_text.done`. event_id: type: string minLength: 0 description: The unique ID of the event. session_id: type: string minLength: 0 description: The ID of the session associated with the event. turn_id: type: - string - 'null' minLength: 0 description: The ID of the turn associated with the event, when applicable. item_id: type: string minLength: 0 description: The ID of the reasoning item. output_index: type: integer format: int64 minimum: 0 maximum: 4294967295 description: The index of the item in the turn output. summary_index: type: integer format: int64 minimum: 0 maximum: 4294967295 description: The index of the summary content part. text: type: string minLength: 0 description: The complete reasoning summary text. required: - type - event_id - session_id - turn_id - item_id - output_index - summary_index - text additionalProperties: false description: Emitted when a reasoning summary content part is complete. InputContentParam: oneOf: - $ref: '#/components/schemas/InputContentParamInputText' - $ref: '#/components/schemas/InputContentParamInputImage' discriminator: propertyName: type mapping: input_text: '#/components/schemas/InputContentParamInputText' input_image: '#/components/schemas/InputContentParamInputImage' x-oai-discriminator-values: - input_text - input_image description: Content included in an input message. HostedPluginParam: oneOf: - $ref: '#/components/schemas/HostedPluginParamInline' discriminator: propertyName: type mapping: inline: '#/components/schemas/HostedPluginParamInline' x-oai-discriminator-values: - inline description: A plugin installed in an OpenAI-hosted environment. EnvironmentStatusResource: type: string enum: - pending - connected - disconnected - expired - failed x-enumDescriptions: - '' - '' - '' - '' - '' description: The public lifecycle status of an execution environment. ErrorBodyResource: type: object properties: type: type: string minLength: 0 description: The error type. code: type: string minLength: 0 description: A machine-readable error code. message: type: string minLength: 0 description: A human-readable error message. param: type: - string - 'null' minLength: 0 description: The request parameter that caused the error, or null for a request-wide error. required: - type - code - message - param additionalProperties: false description: Details about an API error. OutputTokensDetailsResource: type: object properties: reasoning_tokens: type: integer format: int64 description: The number of output tokens used for reasoning. required: - reasoning_tokens additionalProperties: false description: A breakdown of output token usage for a session or turn. NetworkAccessParam: type: string enum: - enabled - disabled - restricted x-enumDescriptions: - Allows unrestricted network access. - Disables network access. - Allows access only to configured domains. description: The network access mode for an OpenAI-hosted environment. SessionEvent: oneOf: - $ref: '#/components/schemas/SessionEventError' - $ref: '#/components/schemas/SessionEventAgentSessionEnvironmentReady' - $ref: '#/components/schemas/SessionEventAgentSessionEnvironmentReset' - $ref: '#/components/schemas/SessionEventAgentOutputCommandExecutionOutputDelta' - $ref: '#/components/schemas/SessionEventAgentSessionCreated' - $ref: '#/components/schemas/SessionEventAgentSessionTurnCreated' - $ref: '#/components/schemas/SessionEventAgentSessionTurnInProgress' - $ref: '#/components/schemas/SessionEventAgentSessionTurnCompleted' - $ref: '#/components/schemas/SessionEventAgentSessionTurnFailed' - $ref: '#/components/schemas/SessionEventAgentSessionTurnCancelled' - $ref: '#/components/schemas/SessionEventAgentSessionTurnItemAdded' - $ref: '#/components/schemas/SessionEventAgentSessionIdle' - $ref: '#/components/schemas/SessionEventAgentSessionInProgress' - $ref: '#/components/schemas/SessionEventAgentSessionRequiresAction' - $ref: '#/components/schemas/SessionEventAgentSessionFailed' - $ref: '#/components/schemas/SessionEventAgentSessionEnvironmentPending' - $ref: '#/components/schemas/SessionEventAgentSessionEnvironmentConnected' - $ref: '#/components/schemas/SessionEventAgentSessionEnvironmentDisconnected' - $ref: '#/components/schemas/SessionEventAgentSessionEnvironmentFailed' - $ref: '#/components/schemas/SessionEventAgentSessionSubagentCreated' - $ref: '#/components/schemas/SessionEventAgentSessionSubagentActive' - $ref: '#/components/schemas/SessionEventAgentSessionSubagentClosed' - $ref: '#/components/schemas/SessionEventAgentSessionTurnItemDone' - $ref: '#/components/schemas/SessionEventAgentSessionTurnContentPartAdded' - $ref: '#/components/schemas/SessionEventAgentSessionTurnContentPartDone' - $ref: '#/components/schemas/SessionEventAgentSessionTurnOutputTextDelta' - $ref: '#/components/schemas/SessionEventAgentSessionTurnOutputTextDone' - $ref: '#/components/schemas/SessionEventAgentSessionTurnReasoningSummaryPartAdded' - $ref: '#/components/schemas/SessionEventAgentSessionTurnReasoningSummaryPartDone' - $ref: '#/components/schemas/SessionEventAgentSessionTurnReasoningSummaryTextDelta' - $ref: '#/components/schemas/SessionEventAgentSessionTurnReasoningSummaryTextDone' discriminator: propertyName: type mapping: error: '#/components/schemas/SessionEventError' agent.session.environment.ready: '#/components/schemas/SessionEventAgentSessionEnvironmentReady' agent.session.environment.reset: '#/components/schemas/SessionEventAgentSessionEnvironmentReset' agent.output.command_execution_output.delta: '#/components/schemas/SessionEventAgentOutputCommandExecutionOutputDelta' agent.session.created: '#/components/schemas/SessionEventAgentSessionCreated' agent.session.turn.created: '#/components/schemas/SessionEventAgentSessionTurnCreated' agent.session.turn.in_progress: '#/components/schemas/SessionEventAgentSessionTurnInProgress' agent.session.turn.completed: '#/components/schemas/SessionEventAgentSessionTurnCompleted' agent.session.turn.failed: '#/components/schemas/SessionEventAgentSessionTurnFailed' agent.session.turn.cancelled: '#/components/schemas/SessionEventAgentSessionTurnCancelled' agent.session.turn.item.added: '#/components/schemas/SessionEventAgentSessionTurnItemAdded' agent.session.idle: '#/components/schemas/SessionEventAgentSessionIdle' agent.session.in_progress: '#/components/schemas/SessionEventAgentSessionInProgress' agent.session.requires_action: '#/components/schemas/SessionEventAgentSessionRequiresAction' agent.session.failed: '#/components/schemas/SessionEventAgentSessionFailed' agent.session.environment.pending: '#/components/schemas/SessionEventAgentSessionEnvironmentPending' agent.session.environment.connected: '#/components/schemas/SessionEventAgentSessionEnvironmentConnected' agent.session.environment.disconnected: '#/components/schemas/SessionEventAgentSessionEnvironmentDisconnected' agent.session.environment.failed: '#/components/schemas/SessionEventAgentSessionEnvironmentFailed' agent.session.subagent.created: '#/components/schemas/SessionEventAgentSessionSubagentCreated' agent.session.subagent.active: '#/components/schemas/SessionEventAgentSessionSubagentActive' agent.session.subagent.closed: '#/components/schemas/SessionEventAgentSessionSubagentClosed' agent.session.turn.item.done: '#/components/schemas/SessionEventAgentSessionTurnItemDone' agent.session.turn.content_part.added: '#/components/schemas/SessionEventAgentSessionTurnContentPartAdded' agent.session.turn.content_part.done: '#/components/schemas/SessionEventAgentSessionTurnContentPartDone' agent.session.turn.output_text.delta: '#/components/schemas/SessionEventAgentSessionTurnOutputTextDelta' agent.session.turn.output_text.done: '#/components/schemas/SessionEventAgentSessionTurnOutputTextDone' agent.session.turn.reasoning_summary_part.added: '#/components/schemas/SessionEventAgentSessionTurnReasoningSummaryPartAdded' agent.session.turn.reasoning_summary_part.done: '#/components/schemas/SessionEventAgentSessionTurnReasoningSummaryPartDone' agent.session.turn.reasoning_summary_text.delta: '#/components/schemas/SessionEventAgentSessionTurnReasoningSummaryTextDelta' agent.session.turn.reasoning_summary_text.done: '#/components/schemas/SessionEventAgentSessionTurnReasoningSummaryTextDone' x-oai-discriminator-values: - error - agent.session.environment.ready - agent.session.environment.reset - agent.output.command_execution_output.delta - agent.session.created - agent.session.turn.created - agent.session.turn.in_progress - agent.session.turn.completed - agent.session.turn.failed - agent.session.turn.cancelled - agent.session.turn.item.added - agent.session.idle - agent.session.in_progress - agent.session.requires_action - agent.session.failed - agent.session.environment.pending - agent.session.environment.connected - agent.session.environment.disconnected - agent.session.environment.failed - agent.session.subagent.created - agent.session.subagent.active - agent.session.subagent.closed - agent.session.turn.item.done - agent.session.turn.content_part.added - agent.session.turn.content_part.done - agent.session.turn.output_text.delta - agent.session.turn.output_text.done - agent.session.turn.reasoning_summary_part.added - agent.session.turn.reasoning_summary_part.done - agent.session.turn.reasoning_summary_text.delta - agent.session.turn.reasoning_summary_text.done description: An event emitted by a Managed Agents session. SessionEventAgentSessionCreated: type: object properties: type: type: string enum: - agent.session.created default: agent.session.created x-stainless-const: true description: The type of the object. Always `agent.session.created`. event_id: type: string minLength: 0 description: The unique ID of the event. session: $ref: '#/components/schemas/SessionResource' description: The session that was created. required: - type - event_id - session additionalProperties: false description: Emitted when a session is created. SubagentResource: type: object properties: id: type: string minLength: 0 description: The ID of the subagent. object: $ref: '#/components/schemas/SubagentObjectResource' description: The object type. Always `agent.session.subagent`. session_id: type: string minLength: 0 description: The ID of the session that owns the subagent. name: type: - string - 'null' minLength: 0 description: The runner-assigned nickname, or null when unavailable. instructions: type: - array - 'null' items: $ref: '#/components/schemas/AgentContentResource' minItems: 0 maxItems: 2000 description: Initial task content, or null when unavailable. Text may contain placeholders for images or audio when only a preview is available. parent_agent_id: type: string minLength: 0 description: The ID of the agent that created this subagent. status: $ref: '#/components/schemas/SubagentStatusResource' description: The current status of the subagent. opened_at: type: integer format: int64 description: The Unix timestamp, in seconds, when the subagent was first opened. Resuming does not change it. closed_at: type: - integer - 'null' format: int64 description: The Unix timestamp, in seconds, when the subagent was closed. Null while active, including after resume. required: - id - object - session_id - name - instructions - parent_agent_id - status - opened_at - closed_at additionalProperties: false description: A subagent created within a session. MultiAgentConfigResource: type: object properties: enabled: type: boolean description: Whether subagent tools are enabled. Defaults to false. max_concurrent_subagents: type: - integer - 'null' format: int64 minimum: 1 maximum: 4294967295 description: Maximum number of subagents that may run concurrently, or null when disabled. Defaults to 6 when enabled. required: - enabled - max_concurrent_subagents additionalProperties: false description: The resolved configuration for creating and coordinating subagents. EnvironmentParam: oneOf: - $ref: '#/components/schemas/EnvironmentParamNone' - $ref: '#/components/schemas/EnvironmentParamOpenaiHosted' - $ref: '#/components/schemas/EnvironmentParamSelfHosted' discriminator: propertyName: type mapping: none: '#/components/schemas/EnvironmentParamNone' openai_hosted: '#/components/schemas/EnvironmentParamOpenaiHosted' self_hosted: '#/components/schemas/EnvironmentParamSelfHosted' x-oai-discriminator-values: - none - openai_hosted - self_hosted description: The execution environment and optional reusable template for a session. EnvironmentResourceNone: type: object properties: type: type: string enum: - none default: none x-stainless-const: true description: The type of the object. Always `none`. required: - type additionalProperties: false description: The session talks to CCA without selecting or provisioning an execution environment. CreateAgentSessionParams: type: object properties: metadata: type: - object - 'null' additionalProperties: type: string minLength: 0 maxLength: 512 propertyNames: type: string minLength: 1 maxLength: 64 minProperties: 0 maxProperties: 16 description: Up to 16 string key-value pairs, with keys up to 64 and values up to 512 characters. Omission or null defaults to an empty map. agent: $ref: '#/components/schemas/SessionAgentConfigParam' description: Agent configuration. With `agent_id`, supplied fields override the saved agent for this session. Without `agent_id`, `model` is required. agent_id: type: string minLength: 0 maxLength: 64 description: The ID of a saved reusable agent. Omit `agent` to use its configuration unchanged. environment: $ref: '#/components/schemas/EnvironmentParam' description: An inline execution environment or a reference to an environment template. vault_ids: type: - array - 'null' items: type: string minLength: 0 maxLength: 1048576 minItems: 0 maxItems: 16384 description: The IDs of vaults made available to the session. input: anyOf: - $ref: '#/components/schemas/CreateSessionInputParam' - type: 'null' description: Initial input to submit when the session is created. A string is shorthand for a single user message. Required when `environment.type` is `none`, or when `stream` is `true` for an environment that is not `self_hosted`; optional for self-hosted and non-streaming execution environments. stream: type: boolean default: false description: Whether to stream session events as server-sent events. Defaults to `false`. required: - environment additionalProperties: false description: Parameters for creating a Managed Agents session. SessionEventAgentSessionEnvironmentReady: type: object properties: type: type: string enum: - agent.session.environment.ready default: agent.session.environment.ready x-stainless-const: true description: The type of the object. Always `agent.session.environment.ready`. event_id: type: string minLength: 0 description: The unique ID of the event. session_id: type: string minLength: 0 description: The ID of the session associated with the event. turn_id: type: - string - 'null' minLength: 0 description: The ID of the turn associated with the event, when applicable. environment: $ref: '#/components/schemas/SessionEnvironmentStateResource' description: The current environment state. required: - type - event_id - session_id - turn_id - environment additionalProperties: false description: Emitted when a hosted session environment is ready to connect. ReasoningEffortParam: type: string enum: - none - minimal - low - medium - high - xhigh - max description: The amount of reasoning effort the model should use. SessionInputParamAgentSessionInputMessage: type: object properties: type: type: string enum: - agent.session.input.message default: agent.session.input.message x-stainless-const: true description: The type of the object. Always `agent.session.input.message`. input: type: array items: $ref: '#/components/schemas/InputMessageParam' minItems: 0 maxItems: 16384 description: The user messages to add to the session. required: - type - input additionalProperties: false description: Adds one or more user messages and starts a turn. SessionRequiredActionResourceFunctionCall: type: object properties: type: type: string enum: - function_call default: function_call x-stainless-const: true description: The type of the object. Always `function_call`. turn_id: type: string minLength: 0 description: The ID of the turn that requested the function call. call_id: type: string minLength: 0 description: The ID to include when submitting the function result. name: type: string minLength: 0 description: The function name. arguments: description: The arguments supplied by the model. required: - type - turn_id - call_id - name - arguments additionalProperties: false description: Run a function tool and submit its result. SessionInputParamAgentSessionInputCancel: type: object properties: type: type: string enum: - agent.session.input.cancel default: agent.session.input.cancel x-stainless-const: true description: The type of the object. Always `agent.session.input.cancel`. required: - type additionalProperties: false description: Cancels the session's active turn. McpTransportResourceHttp: type: object properties: type: type: string enum: - http default: http x-stainless-const: true description: The type of the object. Always `http`. server_url: type: string minLength: 0 description: The URL of the MCP server. required: - type - server_url additionalProperties: false description: Connects to an MCP server over HTTP. SessionEventAgentSessionTurnCancelled: type: object properties: type: type: string enum: - agent.session.turn.cancelled default: agent.session.turn.cancelled x-stainless-const: true description: The type of the object. Always `agent.session.turn.cancelled`. event_id: type: string minLength: 0 description: The unique ID of the event. session_id: type: string minLength: 0 description: The ID of the session associated with the event. turn_id: type: string minLength: 0 description: The ID of the turn associated with the event. turn: $ref: '#/components/schemas/TurnResource' description: The cancelled turn. usage: anyOf: - $ref: '#/components/schemas/TokenUsageResource' - type: 'null' description: Token usage by the root agent during the turn, when available. required: - type - event_id - session_id - turn_id - turn - usage additionalProperties: false description: Emitted when a turn is cancelled. SendSubagentInputCallItemResource: type: object properties: type: type: string enum: - send_subagent_input_call default: send_subagent_input_call x-stainless-const: true x-enumDescriptions: - The current public item type. description: The item type. Always `send_subagent_input_call`. id: type: string minLength: 0 description: The ID of the tool call item. turn_id: type: string minLength: 0 description: The ID of the turn that contains this item. status: $ref: '#/components/schemas/FunctionCallStatusResource' description: The status of the tool call. sender_agent_id: type: string minLength: 0 description: The ID of the agent sending the input. recipient_agent_id: type: string minLength: 0 description: The ID of the agent receiving the input. content: type: array items: $ref: '#/components/schemas/AgentContentResource' minItems: 0 maxItems: 2000 description: The input sent to the receiving agent. required: - type - id - turn_id - status - sender_agent_id - recipient_agent_id - content additionalProperties: false description: A request to send input to another agent. SessionArtifactResource: type: object properties: id: type: string minLength: 0 description: The immutable artifact ID. object: type: string enum: - agent.session.artifact default: agent.session.artifact x-stainless-const: true description: The object type. Always `agent.session.artifact`. session_id: type: string minLength: 0 description: The ID of the session that owns the artifact. environment_id: type: string minLength: 0 description: The ID of the environment that produced the artifact. turn_id: type: string minLength: 0 description: The ID of the completed turn that published the artifact. path: type: string minLength: 0 description: The original absolute file path in the execution environment. size_bytes: type: integer format: int64 minimum: 0 description: The immutable artifact size in bytes. created_at: type: integer format: int64 description: The Unix timestamp, in seconds, when the artifact was published. required: - id - object - session_id - environment_id - turn_id - path - size_bytes - created_at additionalProperties: false description: An immutable file published by a completed hosted session turn. SessionEventAgentSessionEnvironmentReset: type: object properties: type: type: string enum: - agent.session.environment.reset default: agent.session.environment.reset x-stainless-const: true description: The type of the object. Always `agent.session.environment.reset`. event_id: type: string minLength: 0 description: The unique ID of the event. session_id: type: string minLength: 0 description: The ID of the session associated with the event. turn_id: type: - string - 'null' minLength: 0 description: The associated turn, when applicable. environment_id: type: string minLength: 0 description: The stable environment ID, retained across sandbox replacements. reset_count: type: integer format: int64 minimum: 0 description: Monotonically increasing reset number. Repeated notifications share this number. required: - type - event_id - session_id - turn_id - environment_id - reset_count additionalProperties: false description: Emitted after a hosted sandbox is replaced. Conversation history survives; changes to the previous sandbox's files and processes do not. PersistedAgentToolConfigParamFunction: type: object properties: type: type: string enum: - function default: function x-stainless-const: true description: The type of the object. Always `function`. name: type: string minLength: 0 maxLength: 1048576 description: The name of the function. description: type: string minLength: 0 maxLength: 1048576 description: A description of what the function does. parameters: type: object additionalProperties: {} propertyNames: type: string minLength: 1 maxLength: 256 minProperties: 0 maxProperties: 1024 description: A JSON Schema object describing the function's arguments. defer_loading: type: boolean default: false description: Whether this function is deferred and discovered through tool search. Defaults to `false`. required: - type - name - description - parameters additionalProperties: false description: A function defined by the application. MessageItemResource: type: object properties: type: type: string enum: - message default: message x-stainless-const: true description: The item type. Always `message`. id: type: - string - 'null' minLength: 0 description: The ID of this item, or null for legacy user messages whose ID was not recorded. turn_id: type: string minLength: 0 description: The ID of the turn that contains this item. role: $ref: '#/components/schemas/SessionMessageRoleResource' description: The role of the message author. content: type: array items: $ref: '#/components/schemas/MessageContentResource' minItems: 0 maxItems: 2000 description: The content of the message. User messages contain input text or images; assistant messages contain output text. status: $ref: '#/components/schemas/OutputItemStatusResource' description: The status of the message. User messages are always `completed`. phase: anyOf: - $ref: '#/components/schemas/MessagePhaseResource' - type: 'null' description: The phase of an assistant message. Null for user messages. required: - type - id - turn_id - role - content - status - phase additionalProperties: false description: A user or assistant message recorded in a session. PersistedAgentToolConfigParamMcp: type: object properties: type: type: string enum: - mcp default: mcp x-stainless-const: true description: The type of the object. Always `mcp`. server_label: type: string minLength: 0 maxLength: 1048576 description: A label used to identify the MCP server in tool calls. credential_id: type: - string - 'null' minLength: 0 maxLength: 1048576 description: The vault credential selected for this MCP server. Optional when exactly one attached credential matches the server URL. transport: $ref: '#/components/schemas/PersistedMcpTransportConfigParam' description: The credential-free transport used to connect to the MCP server. request_metadata: type: - object - 'null' additionalProperties: {} propertyNames: type: string minLength: 1 maxLength: 256 minProperties: 0 maxProperties: 1024 description: Metadata included with requests to this MCP server. allowed_tools: type: - array - 'null' items: type: string minLength: 0 maxLength: 1048576 minItems: 0 maxItems: 16384 description: The MCP tools the agent may call. All server tools are allowed when omitted. required: type: boolean default: false description: Whether this MCP server must initialize before the first turn. Defaults to `false`. connection_origin: anyOf: - $ref: '#/components/schemas/McpConnectionOriginParam' - type: 'null' description: Selects where outbound MCP HTTP connections originate. required: - type - server_label - transport additionalProperties: false description: Tools provided by a remote MCP server without stored credentials. HostedPluginParamInline: type: object properties: type: type: string enum: - inline default: inline x-stainless-const: true description: The type of the object. Always `inline`. name: type: string minLength: 1 maxLength: 64 description: The plugin name declared in `.codex-plugin/plugin.json`. description: type: string minLength: 0 maxLength: 1048576 description: The plugin description declared in `.codex-plugin/plugin.json`. source: $ref: '#/components/schemas/InlineCapabilitySourceParam' description: The inline ZIP archive. required: - type - name - description - source additionalProperties: false description: Supplies a plugin ZIP directly in the session request. PersistedMcpTransportConfigParamStdio: type: object properties: type: type: string enum: - stdio default: stdio x-stainless-const: true description: The type of the object. Always `stdio`. command: type: string minLength: 0 maxLength: 1048576 description: The command used to start the MCP server. args: type: - array - 'null' items: type: string minLength: 0 maxLength: 1048576 minItems: 0 maxItems: 16384 description: Arguments passed to the MCP server command. cwd: type: string minLength: 0 maxLength: 1048576 description: The working directory used to start the MCP server. env_vars: type: - array - 'null' items: type: string minLength: 0 maxLength: 1048576 minItems: 0 maxItems: 16384 description: Environment variable names to inherit from the selected execution environment. required: - type - command - cwd additionalProperties: false description: Starts an MCP server as a local process. SessionEventAgentSessionTurnOutputTextDelta: type: object properties: type: type: string enum: - agent.session.turn.output_text.delta default: agent.session.turn.output_text.delta x-stainless-const: true description: The type of the object. Always `agent.session.turn.output_text.delta`. event_id: type: string minLength: 0 description: The unique ID of the event. session_id: type: string minLength: 0 description: The ID of the session associated with the event. turn_id: type: - string - 'null' minLength: 0 description: The ID of the turn associated with the event, when applicable. item_id: type: string minLength: 0 description: The ID of the message item. output_index: type: integer format: int64 minimum: 0 maximum: 4294967295 description: The index of the item in the turn output. content_index: type: integer format: int64 minimum: 0 maximum: 4294967295 description: The index of the content part in the message. delta: type: string minLength: 0 description: The text that was appended. required: - type - event_id - session_id - turn_id - item_id - output_index - content_index - delta additionalProperties: false description: Emitted when text is appended to an output text content part. WaitForSubagentsCallItemResource: type: object properties: type: type: string enum: - wait_for_subagents_call default: wait_for_subagents_call x-stainless-const: true x-enumDescriptions: - The current public item type. description: The item type. Always `wait_for_subagents_call`. id: type: string minLength: 0 description: The ID of the tool call item. turn_id: type: string minLength: 0 description: The ID of the turn that contains this item. status: $ref: '#/components/schemas/FunctionCallStatusResource' description: The status of the tool call. sender_agent_id: type: string minLength: 0 description: The ID of the agent waiting for results. recipient_agent_ids: type: array items: type: string minLength: 0 minItems: 0 maxItems: 2000 description: The IDs of the agents to wait for. required: - type - id - turn_id - status - sender_agent_id - recipient_agent_ids additionalProperties: false description: A request to wait for one or more subagents. UpdateEnvironmentTemplateParams: type: object properties: name: type: - string - 'null' minLength: 1 maxLength: 256 description: A replacement human-readable display name, or `null` to clear the name. packages: anyOf: - $ref: '#/components/schemas/EnvironmentPackagesParam' - type: 'null' description: Packages installed before the runtime network policy applies. setup_commands: type: - array - 'null' items: $ref: '#/components/schemas/SetupCommandParam' minItems: 0 maxItems: 16 description: Replacement confidential setup commands, never included in returned resources. network: anyOf: - $ref: '#/components/schemas/NetworkPolicyParam' - type: 'null' description: Network access available after setup completes. Omit to preserve the current policy, or pass `null` to reset to disabled for GA requests or enabled for alpha/beta requests. env: type: - object - 'null' additionalProperties: type: string minLength: 0 maxLength: 1048576 propertyNames: type: string minLength: 1 maxLength: 256 minProperties: 0 maxProperties: 1024 description: Replacement confidential environment values. capability_directories: type: - array - 'null' items: type: string minLength: 0 maxLength: 1048576 minItems: 0 maxItems: 16384 description: Directories that expose capabilities to the agent. skills: type: - array - 'null' items: $ref: '#/components/schemas/HostedSkillParam' minItems: 0 maxItems: 200 description: Replacement skill configuration installed for each new session. plugins: type: - array - 'null' items: $ref: '#/components/schemas/HostedPluginParam' minItems: 0 maxItems: 32 description: Replacement plugin configuration installed for each new session. files: type: - array - 'null' items: $ref: '#/components/schemas/HostedEnvironmentFileParam' minItems: 0 maxItems: 50 description: Replacement file configuration materialized for each new session. additionalProperties: false description: Fields to replace on an existing reusable OpenAI-hosted environment template. SessionEventAgentSessionFailed: type: object properties: type: type: string enum: - agent.session.failed default: agent.session.failed x-stainless-const: true description: The type of the object. Always `agent.session.failed`. event_id: type: string minLength: 0 description: The unique ID of the event. session: $ref: '#/components/schemas/SessionResource' description: The failed session. required: - type - event_id - session additionalProperties: false description: Emitted when a session fails. SubagentStatusResource: type: string enum: - active - closed x-enumDescriptions: - The subagent remains available, including while idle between turns. - The subagent is closed. description: The current status of a subagent. HostedTemplateSkillResourceInline: type: object properties: type: type: string enum: - inline default: inline x-stainless-const: true description: The type of the object. Always `inline`. name: type: string minLength: 0 description: The skill name declared in `SKILL.md`. description: type: string minLength: 0 description: The skill description declared in `SKILL.md`. required: - type - name - description additionalProperties: false description: Safe metadata for an inline skill archive. EnvironmentTypeResource: type: string enum: - openai_hosted - self_hosted description: The kind of execution environment. McpTransportConfigParamStdio: type: object properties: type: type: string enum: - stdio default: stdio x-stainless-const: true description: The type of the object. Always `stdio`. command: type: string minLength: 0 maxLength: 1048576 description: The command used to start the MCP server. args: type: - array - 'null' items: type: string minLength: 0 maxLength: 1048576 minItems: 0 maxItems: 16384 description: Arguments passed to the MCP server command. cwd: type: string minLength: 0 maxLength: 1048576 description: The working directory used to start the MCP server. env: type: - object - 'null' additionalProperties: type: string minLength: 0 maxLength: 1048576 propertyNames: type: string minLength: 1 maxLength: 256 minProperties: 0 maxProperties: 1024 description: Environment variables set for the MCP server process. env_vars: type: - array - 'null' items: type: string minLength: 0 maxLength: 1048576 minItems: 0 maxItems: 16384 description: Environment variable names to inherit from the selected execution environment. required: - type - command - cwd additionalProperties: false description: Starts an MCP server as a local process. AgentListResource: type: object properties: object: type: string enum: - list default: list x-stainless-const: true description: The object type, which is always `list`. data: type: array items: $ref: '#/components/schemas/AgentResource' minItems: 0 maxItems: 2000 description: The resources returned in this page, in the requested sort order. first_id: type: - string - 'null' minLength: 0 description: The ID of the first resource in `data`, or `null` if the page is empty. last_id: type: - string - 'null' minLength: 0 description: The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. has_more: type: boolean description: Whether there are more resources to retrieve after this page. required: - object - data - first_id - last_id - has_more additionalProperties: false description: A page of Agents API resources, with IDs for retrieving additional pages. InlineCapabilitySourceParamBase64: type: object properties: type: type: string enum: - base64 default: base64 x-stainless-const: true description: The type of the object. Always `base64`. media_type: type: string enum: - application/zip default: application/zip x-stainless-const: true x-enumDescriptions: - A ZIP archive. description: The archive media type, always `application/zip`. data: type: string minLength: 1 maxLength: 70254592 description: Standard-base64 encoded ZIP archive bytes. required: - type - media_type - data additionalProperties: false description: Provides ZIP bytes encoded with standard base64. HostedSkillParam: oneOf: - $ref: '#/components/schemas/HostedSkillParamSkillReference' - $ref: '#/components/schemas/HostedSkillParamInline' discriminator: propertyName: type mapping: skill_reference: '#/components/schemas/HostedSkillParamSkillReference' inline: '#/components/schemas/HostedSkillParamInline' x-oai-discriminator-values: - skill_reference - inline description: A skill installed in an OpenAI-hosted environment. SessionAgentResource: type: object properties: id: type: string minLength: 0 description: The ID of the agent. name: type: - string - 'null' minLength: 0 description: The reusable agent's name when the session was created, or null if no name was saved. Later changes to the agent's name do not affect this value. model: type: string minLength: 0 description: The model used by the agent. reasoning: $ref: '#/components/schemas/ReasoningResource' description: The agent's reasoning configuration. text: $ref: '#/components/schemas/TextResource' description: Configuration for text generated by the agent. service_tier: $ref: '#/components/schemas/ServiceTierResource' description: The effective service-tier policy for model requests. Defaults to `auto`. instructions: type: - string - 'null' minLength: 0 description: Custom instructions appended to the agent's default base instructions. tools: type: array items: $ref: '#/components/schemas/AgentToolResource' minItems: 0 maxItems: 2000 description: Tools available to the agent. multi_agent: $ref: '#/components/schemas/MultiAgentConfigResource' description: Configuration for creating and coordinating subagents. required: - id - name - model - reasoning - text - service_tier - instructions - tools - multi_agent additionalProperties: false description: The effective agent configuration for a session. SessionEventAgentSessionTurnCreated: type: object properties: type: type: string enum: - agent.session.turn.created default: agent.session.turn.created x-stainless-const: true description: The type of the object. Always `agent.session.turn.created`. event_id: type: string minLength: 0 description: The unique ID of the event. session_id: type: string minLength: 0 description: The ID of the session associated with the event. turn_id: type: string minLength: 0 description: The ID of the turn associated with the event. turn: $ref: '#/components/schemas/TurnResource' description: The turn at the time it was created. required: - type - event_id - session_id - turn_id - turn additionalProperties: false description: Emitted when a turn is created. HostedTemplateFileResource: oneOf: - $ref: '#/components/schemas/HostedTemplateFileResourceFileId' - $ref: '#/components/schemas/HostedTemplateFileResourceInline' discriminator: propertyName: type mapping: file_id: '#/components/schemas/HostedTemplateFileResourceFileId' inline: '#/components/schemas/HostedTemplateFileResourceInline' x-oai-discriminator-values: - file_id - inline description: Safe metadata for a file configured by an environment template. EnvironmentPackagesParam: type: object properties: python: type: - array - 'null' items: type: string minLength: 0 maxLength: 1048576 minItems: 0 maxItems: 16384 description: Python packages to install. Defaults to an empty list. system: type: - array - 'null' items: type: string minLength: 0 maxLength: 1048576 minItems: 0 maxItems: 16384 description: System packages to install. Defaults to an empty list. npm: type: - array - 'null' items: type: string minLength: 0 maxLength: 1048576 minItems: 0 maxItems: 16384 description: npm packages to install globally. Defaults to an empty list. additionalProperties: false description: Packages to install in an OpenAI-hosted environment. SessionEventAgentSessionEnvironmentConnected: type: object properties: type: type: string enum: - agent.session.environment.connected default: agent.session.environment.connected x-stainless-const: true description: The type of the object. Always `agent.session.environment.connected`. event_id: type: string minLength: 0 description: The unique ID of the event. session_id: type: string minLength: 0 description: The ID of the session associated with the event. turn_id: type: - string - 'null' minLength: 0 description: The ID of the turn associated with the event, when applicable. environment: $ref: '#/components/schemas/SessionEnvironmentStateResource' description: The current environment state. required: - type - event_id - session_id - turn_id - environment additionalProperties: false description: Emitted when a session environment connects. SessionEventAgentSessionRequiresAction: type: object properties: type: type: string enum: - agent.session.requires_action default: agent.session.requires_action x-stainless-const: true description: The type of the object. Always `agent.session.requires_action`. event_id: type: string minLength: 0 description: The unique ID of the event. session: $ref: '#/components/schemas/SessionResource' description: The session and its current required actions. required: - type - event_id - session additionalProperties: false description: Emitted when a session is waiting for one or more required actions. WebSearchActionResource: oneOf: - $ref: '#/components/schemas/WebSearchActionResourceSearch' - $ref: '#/components/schemas/WebSearchActionResourceOpenPage' - $ref: '#/components/schemas/WebSearchActionResourceFindInPage' - $ref: '#/components/schemas/WebSearchActionResourceOther' discriminator: propertyName: type mapping: search: '#/components/schemas/WebSearchActionResourceSearch' open_page: '#/components/schemas/WebSearchActionResourceOpenPage' find_in_page: '#/components/schemas/WebSearchActionResourceFindInPage' other: '#/components/schemas/WebSearchActionResourceOther' x-oai-discriminator-values: - search - open_page - find_in_page - other description: An action performed by the web search tool. McpTransportConfigParam: oneOf: - $ref: '#/components/schemas/McpTransportConfigParamHttp' - $ref: '#/components/schemas/McpTransportConfigParamStdio' discriminator: propertyName: type mapping: http: '#/components/schemas/McpTransportConfigParamHttp' stdio: '#/components/schemas/McpTransportConfigParamStdio' x-oai-discriminator-values: - http - stdio description: The transport used to connect to an MCP server. SessionRequiredActionResource: oneOf: - $ref: '#/components/schemas/SessionRequiredActionResourceFunctionCall' - $ref: '#/components/schemas/SessionRequiredActionResourceEnvironmentConnection' discriminator: propertyName: type mapping: function_call: '#/components/schemas/SessionRequiredActionResourceFunctionCall' environment_connection: '#/components/schemas/SessionRequiredActionResourceEnvironmentConnection' x-oai-discriminator-values: - function_call - environment_connection description: An action that must be completed before a session can continue. PersistedAgentToolConfigParam: oneOf: - $ref: '#/components/schemas/PersistedAgentToolConfigParamFunction' - $ref: '#/components/schemas/PersistedAgentToolConfigParamToolSearch' - $ref: '#/components/schemas/PersistedAgentToolConfigParamProgrammaticToolCalling' - $ref: '#/components/schemas/PersistedAgentToolConfigParamMcp' - $ref: '#/components/schemas/PersistedAgentToolConfigParamWebSearch' discriminator: propertyName: type mapping: function: '#/components/schemas/PersistedAgentToolConfigParamFunction' tool_search: '#/components/schemas/PersistedAgentToolConfigParamToolSearch' programmatic_tool_calling: '#/components/schemas/PersistedAgentToolConfigParamProgrammaticToolCalling' mcp: '#/components/schemas/PersistedAgentToolConfigParamMcp' web_search: '#/components/schemas/PersistedAgentToolConfigParamWebSearch' x-oai-discriminator-values: - function - tool_search - programmatic_tool_calling - mcp - web_search description: A tool that can be stored on a reusable agent without session credentials. SessionMessageRoleResource: type: string enum: - user - assistant description: The author of a session message. EnvironmentTemplateResource: type: object properties: id: type: string minLength: 0 description: The ID of the reusable environment template. name: type: - string - 'null' minLength: 0 description: An optional human-readable display name for the template. object: type: string enum: - agent.environment.template default: agent.environment.template x-stainless-const: true description: The object type. Always `agent.environment.template`. created_at: type: integer format: int64 description: The Unix timestamp, in seconds, when the template was created. updated_at: type: integer format: int64 description: The Unix timestamp, in seconds, when the template was last updated. packages: $ref: '#/components/schemas/EnvironmentPackagesResource' description: Packages installed in each fresh OpenAI-hosted environment. network: $ref: '#/components/schemas/NetworkPolicyResource' description: Runtime network access for each OpenAI-hosted environment. capability_directories: type: array items: type: string minLength: 0 minItems: 0 maxItems: 2000 description: Directories that expose capabilities to the agent. skills: type: array items: $ref: '#/components/schemas/HostedTemplateSkillResource' minItems: 0 maxItems: 200 description: Safe skill metadata, preserving unresolved version selectors. plugins: type: array items: $ref: '#/components/schemas/HostedPluginResource' minItems: 0 maxItems: 32 description: Safe plugin metadata, excluding inline archive contents. files: type: array items: $ref: '#/components/schemas/HostedTemplateFileResource' minItems: 0 maxItems: 50 description: Safe file metadata, excluding contents and session-scoped file IDs. required: - id - name - object - created_at - updated_at - packages - network - capability_directories - skills - plugins - files additionalProperties: false description: Reusable configuration that provisions a fresh OpenAI-hosted environment for each session. NetworkPolicyParam: type: object properties: access: $ref: '#/components/schemas/NetworkAccessParam' description: The environment's network access mode. allowed_domains: type: - array - 'null' items: type: string minLength: 0 maxLength: 1048576 minItems: 0 maxItems: 16384 description: Domains the environment may access when network access is restricted. required: - access additionalProperties: false description: Network access for an OpenAI-hosted environment. ListOrderParam: type: string enum: - asc - desc x-enumDescriptions: - Returns resources in ascending order. - Returns resources in descending order. description: The order in which paginated resources are returned. HostedTemplateFileResourceFileId: type: object properties: type: type: string enum: - file_id default: file_id x-stainless-const: true description: The type of the object. Always `file_id`. file_id: type: string minLength: 0 description: The ID of the uploaded file. path: type: string minLength: 0 description: The file's absolute path inside the environment. required: - type - file_id - path additionalProperties: false description: A project-scoped Files API reference resolved separately for each session. HostedSkillResourceInline: type: object properties: type: type: string enum: - inline default: inline x-stainless-const: true description: The type of the object. Always `inline`. name: type: string minLength: 0 description: The installed skill name. description: type: string minLength: 0 description: The installed skill description. required: - type - name - description additionalProperties: false description: A skill installed from an inline ZIP archive. WebSearchLocationParam: type: object properties: country: type: - string - 'null' minLength: 0 maxLength: 1048576 description: The two-letter ISO country code, such as `US`. region: type: - string - 'null' minLength: 0 maxLength: 1048576 description: The region or state name. city: type: - string - 'null' minLength: 0 maxLength: 1048576 description: The city name. timezone: type: - string - 'null' minLength: 0 maxLength: 1048576 description: The IANA timezone, such as `America/Los_Angeles`. additionalProperties: false description: Approximate user location used to localize web search results. SessionEnvironmentStateResource: type: object properties: id: type: string minLength: 0 description: The public ID of the environment. type: type: string minLength: 0 description: The environment type. status: $ref: '#/components/schemas/SessionEnvironmentStatusResource' description: The environment's connection status. error: anyOf: - $ref: '#/components/schemas/SessionEnvironmentErrorResource' - type: 'null' description: The error reported while preparing the environment, if any. required: - id - type - status - error additionalProperties: false description: The current state of a session environment. SessionEventAgentSessionTurnInProgress: type: object properties: type: type: string enum: - agent.session.turn.in_progress default: agent.session.turn.in_progress x-stainless-const: true description: The type of the object. Always `agent.session.turn.in_progress`. event_id: type: string minLength: 0 description: The unique ID of the event. session_id: type: string minLength: 0 description: The ID of the session associated with the event. turn_id: type: string minLength: 0 description: The ID of the turn associated with the event. turn: $ref: '#/components/schemas/TurnResource' description: The turn at the time it started running. required: - type - event_id - session_id - turn_id - turn additionalProperties: false description: Emitted when a turn starts running. UpdateAgentParams: type: object properties: model: type: string minLength: 0 maxLength: 1048576 description: The model to use for the agent. The requested model name is preserved. reasoning: anyOf: - $ref: '#/components/schemas/ReasoningParam' - type: 'null' description: Configuration for model reasoning. Omit to keep the current settings; pass `null` to reset to the model's default effort. text: anyOf: - $ref: '#/components/schemas/TextParam' - type: 'null' description: Configuration for text generated by the agent. service_tier: anyOf: - $ref: '#/components/schemas/ServiceTierParam' - type: 'null' description: The service tier used for model requests. instructions: type: - string - 'null' minLength: 0 maxLength: 1048576 description: Additional instructions appended to the agent's default base instructions. Omit to leave unchanged. multi_agent: anyOf: - $ref: '#/components/schemas/MultiAgentConfigCurrentParam' - type: 'null' description: Configuration for creating and coordinating subagents. metadata: type: - object - 'null' additionalProperties: type: string minLength: 0 maxLength: 512 propertyNames: type: string minLength: 1 maxLength: 64 minProperties: 0 maxProperties: 16 description: Replaces all metadata. Omit to leave unchanged, or pass null or {} to clear it. Up to 16 string key-value pairs, with keys up to 64 and values up to 512 characters. name: type: - string - 'null' minLength: 0 maxLength: 128 description: A replacement name. Omit to leave unchanged, or pass null to clear it. tools: type: - array - 'null' items: $ref: '#/components/schemas/PersistedAgentToolConfigParam' minItems: 0 maxItems: 2000 description: Tools available to the agent. additionalProperties: false description: Fields to replace on an existing reusable agent. AgentToolConfigParam: oneOf: - $ref: '#/components/schemas/AgentToolConfigParamFunction' - $ref: '#/components/schemas/AgentToolConfigParamToolSearch' - $ref: '#/components/schemas/AgentToolConfigParamProgrammaticToolCalling' - $ref: '#/components/schemas/AgentToolConfigParamMcp' - $ref: '#/components/schemas/AgentToolConfigParamWebSearch' discriminator: propertyName: type mapping: function: '#/components/schemas/AgentToolConfigParamFunction' tool_search: '#/components/schemas/AgentToolConfigParamToolSearch' programmatic_tool_calling: '#/components/schemas/AgentToolConfigParamProgrammaticToolCalling' mcp: '#/components/schemas/AgentToolConfigParamMcp' web_search: '#/components/schemas/AgentToolConfigParamWebSearch' x-oai-discriminator-values: - function - tool_search - programmatic_tool_calling - mcp - web_search description: A tool available to the agent. EnvironmentFilePageObjectResource: type: string enum: - page default: page x-stainless-const: true description: The object type for a page of files in an execution environment. FunctionCallOutputResource: oneOf: - type: string minLength: 0 - type: array items: $ref: '#/components/schemas/InputContentResource' minItems: 0 maxItems: 2000 description: The text or model-input content supplied as a function result. DeletedSessionArtifactResource: type: object properties: id: type: string minLength: 0 description: The ID of the deleted session artifact. object: type: string enum: - agent.session.artifact.deleted default: agent.session.artifact.deleted x-stainless-const: true description: The object type. Always `agent.session.artifact.deleted`. deleted: type: boolean description: Whether the session artifact was deleted. Always `true`. required: - id - object - deleted additionalProperties: false description: Confirmation that an immutable session artifact was deleted. DeletedSessionResource: type: object properties: id: type: string minLength: 0 description: The ID of the deleted session. object: type: string enum: - agent.session.deleted default: agent.session.deleted x-stainless-const: true description: The object type. Always `agent.session.deleted`. deleted: type: boolean description: Whether the session has been removed from the public API. Always `true`. Physical cleanup may still be in progress. required: - id - object - deleted additionalProperties: false description: A Managed Agents session removed from the public API. Physical cleanup may continue asynchronously. EnvironmentResourceSelfHosted: type: object properties: type: type: string enum: - self_hosted default: self_hosted x-stainless-const: true description: The type of the object. Always `self_hosted`. remote_url: type: string minLength: 0 description: Pass this URL unchanged to `codex exec-server --remote` when connecting this environment. id: type: string minLength: 0 description: The public ID of the environment. workspace_directory: type: string minLength: 0 description: The absolute project directory inside the environment. Defaults to `/workspace`. capability_directories: type: array items: type: string minLength: 0 minItems: 0 maxItems: 2000 description: Directories that contain capabilities exposed to the agent. required: - type - remote_url - id - workspace_directory - capability_directories additionalProperties: false description: An environment hosted by the application. FunctionCallStatusResource: type: string enum: - in_progress - completed - failed - incomplete x-enumDescriptions: - The call is in progress. - The call completed successfully. - The call failed. - The call stopped before completing. description: The status of a tool call. MessageContentResourceInputImage: type: object properties: type: type: string enum: - input_image default: input_image x-stainless-const: true description: The type of the object. Always `input_image`. image_url: type: string minLength: 0 description: The URL of the image supplied by the user, which may be a base64-encoded data URL. required: - type - image_url additionalProperties: false description: An image supplied by the user. WebSearchActionResourceFindInPage: type: object properties: type: type: string enum: - find_in_page default: find_in_page x-stainless-const: true description: The type of the object. Always `find_in_page`. url: type: - string - 'null' minLength: 0 description: The URL of the page that was searched. pattern: type: - string - 'null' minLength: 0 description: The text pattern that was searched for. required: - type - url - pattern additionalProperties: false description: Finds text within a web page. AgentToolResource: oneOf: - $ref: '#/components/schemas/AgentToolResourceFunction' - $ref: '#/components/schemas/AgentToolResourceProgrammaticToolCalling' - $ref: '#/components/schemas/AgentToolResourceMcp' - $ref: '#/components/schemas/AgentToolResourceWebSearch' discriminator: propertyName: type mapping: function: '#/components/schemas/AgentToolResourceFunction' programmatic_tool_calling: '#/components/schemas/AgentToolResourceProgrammaticToolCalling' mcp: '#/components/schemas/AgentToolResourceMcp' web_search: '#/components/schemas/AgentToolResourceWebSearch' x-oai-discriminator-values: - function - programmatic_tool_calling - mcp - web_search description: A tool available to the agent. TurnObjectResource: type: string enum: - agent.session.turn default: agent.session.turn x-stainless-const: true description: The object type for a turn. TokenUsageResource: type: object properties: input_tokens: type: integer format: int64 description: The number of input tokens used by the agent. input_tokens_details: $ref: '#/components/schemas/InputTokensDetailsResource' description: A breakdown of the agent's input token usage. output_tokens: type: integer format: int64 description: The number of output tokens generated by the agent. output_tokens_details: $ref: '#/components/schemas/OutputTokensDetailsResource' description: A breakdown of the agent's output token usage. total_tokens: type: integer format: int64 description: The total number of input and output tokens used by the agent. required: - input_tokens - input_tokens_details - output_tokens - output_tokens_details - total_tokens additionalProperties: false description: Recorded token usage for a session or turn. Usage is best effort and may change. SessionAgentConfigParam: type: object properties: model: type: string minLength: 0 maxLength: 1048576 description: The model to use for the agent. The requested model name is preserved. reasoning: anyOf: - $ref: '#/components/schemas/ReasoningParam' - type: 'null' description: Configuration for model reasoning. Omit to keep the current settings; pass `null` to reset to the model's default effort. text: anyOf: - $ref: '#/components/schemas/TextParam' - type: 'null' description: Configuration for text generated by the agent. service_tier: anyOf: - $ref: '#/components/schemas/ServiceTierParam' - type: 'null' description: The service tier used for model requests. instructions: type: - string - 'null' minLength: 0 maxLength: 1048576 description: Additional instructions appended to the agent's default base instructions. Omit to leave unchanged. multi_agent: anyOf: - $ref: '#/components/schemas/MultiAgentConfigCurrentParam' - type: 'null' description: Configuration for creating and coordinating subagents. tools: type: - array - 'null' items: $ref: '#/components/schemas/AgentToolConfigParam' minItems: 0 maxItems: 16384 description: Tools available to the agent. Omit to inherit, or pass null to clear them. additionalProperties: false description: Agent configuration for a session. Omitted fields inherit from `agent_id` when supplied. Supplied objects and arrays replace the whole field; null resets nullable fields. MessageContentResourceInputText: type: object properties: type: type: string enum: - input_text default: input_text x-stainless-const: true description: The type of the object. Always `input_text`. text: type: string minLength: 0 description: The text supplied by the user. required: - type - text additionalProperties: false description: Text supplied by the user. TextFormatParamText: type: object properties: type: type: string enum: - text default: text x-stainless-const: true description: The type of the object. Always `text`. required: - type additionalProperties: false description: Generates ordinary text without a structured-output constraint. HostedPluginResource: oneOf: - $ref: '#/components/schemas/HostedPluginResourceInline' discriminator: propertyName: type mapping: inline: '#/components/schemas/HostedPluginResourceInline' x-oai-discriminator-values: - inline description: A plugin installed in an OpenAI-hosted environment. SessionListResource: type: object properties: object: type: string enum: - list default: list x-stainless-const: true description: The object type, which is always `list`. data: type: array items: $ref: '#/components/schemas/SessionResource' minItems: 0 maxItems: 2000 description: The resources returned in this page, in the requested sort order. first_id: type: - string - 'null' minLength: 0 description: The ID of the first resource in `data`, or `null` if the page is empty. last_id: type: - string - 'null' minLength: 0 description: The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. has_more: type: boolean description: Whether there are more resources to retrieve after this page. required: - object - data - first_id - last_id - has_more additionalProperties: false description: A page of Agents API resources, with IDs for retrieving additional pages. SessionEventAgentSessionTurnFailed: type: object properties: type: type: string enum: - agent.session.turn.failed default: agent.session.turn.failed x-stainless-const: true description: The type of the object. Always `agent.session.turn.failed`. event_id: type: string minLength: 0 description: The unique ID of the event. session_id: type: string minLength: 0 description: The ID of the session associated with the event. turn_id: type: string minLength: 0 description: The ID of the turn associated with the event. turn: $ref: '#/components/schemas/TurnResource' description: The failed turn. usage: anyOf: - $ref: '#/components/schemas/TokenUsageResource' - type: 'null' description: Token usage by the root agent during the turn, when available. required: - type - event_id - session_id - turn_id - turn - usage additionalProperties: false description: Emitted when a turn fails. PersistedMcpTransportResource: oneOf: - $ref: '#/components/schemas/PersistedMcpTransportResourceHttp' - $ref: '#/components/schemas/PersistedMcpTransportResourceStdio' discriminator: propertyName: type mapping: http: '#/components/schemas/PersistedMcpTransportResourceHttp' stdio: '#/components/schemas/PersistedMcpTransportResourceStdio' x-oai-discriminator-values: - http - stdio description: A credential-free transport used to connect to an MCP server. HostedTemplateSkillResource: oneOf: - $ref: '#/components/schemas/HostedTemplateSkillResourceSkillReference' - $ref: '#/components/schemas/HostedTemplateSkillResourceInline' discriminator: propertyName: type mapping: skill_reference: '#/components/schemas/HostedTemplateSkillResourceSkillReference' inline: '#/components/schemas/HostedTemplateSkillResourceInline' x-oai-discriminator-values: - skill_reference - inline description: Safe metadata for a skill configured by an environment template. SessionEnvironmentErrorResource: type: object properties: type: type: string minLength: 0 description: The error type. code: type: string minLength: 0 description: A machine-readable error code. message: type: string minLength: 0 description: A human-readable error message. required: - type - code - message additionalProperties: false description: An error reported while preparing a session environment. VerbosityParam: type: string enum: - low - medium - high x-enumDescriptions: - Produces less text. - Uses the default amount of text. - Produces more text. description: The amount of text the model should produce. SessionEventAgentSessionInProgress: type: object properties: type: type: string enum: - agent.session.in_progress default: agent.session.in_progress x-stainless-const: true description: The type of the object. Always `agent.session.in_progress`. event_id: type: string minLength: 0 description: The unique ID of the event. session: $ref: '#/components/schemas/SessionResource' description: The session that started processing. required: - type - event_id - session additionalProperties: false description: Emitted when a session starts processing a turn. PersistedAgentToolResource: oneOf: - $ref: '#/components/schemas/PersistedAgentToolResourceFunction' - $ref: '#/components/schemas/PersistedAgentToolResourceToolSearch' - $ref: '#/components/schemas/PersistedAgentToolResourceProgrammaticToolCalling' - $ref: '#/components/schemas/PersistedAgentToolResourceMcp' - $ref: '#/components/schemas/PersistedAgentToolResourceWebSearch' discriminator: propertyName: type mapping: function: '#/components/schemas/PersistedAgentToolResourceFunction' tool_search: '#/components/schemas/PersistedAgentToolResourceToolSearch' programmatic_tool_calling: '#/components/schemas/PersistedAgentToolResourceProgrammaticToolCalling' mcp: '#/components/schemas/PersistedAgentToolResourceMcp' web_search: '#/components/schemas/PersistedAgentToolResourceWebSearch' x-oai-discriminator-values: - function - tool_search - programmatic_tool_calling - mcp - web_search description: A credential-free tool available to a reusable agent. NetworkPolicyResource: type: object properties: access: $ref: '#/components/schemas/NetworkAccessResource' description: The environment's network access mode. allowed_domains: type: array items: type: string minLength: 0 minItems: 0 maxItems: 2000 description: Domains the environment may access when network access is restricted. required: - access - allowed_domains additionalProperties: false description: Network access for an OpenAI-hosted environment. InputContentParamInputImage: type: object properties: type: type: string enum: - input_image default: input_image x-stainless-const: true description: The type of the object. Always `input_image`. image_url: type: string minLength: 0 maxLength: 1048576 description: The URL of the image sent to the model. required: - type - image_url additionalProperties: false description: Image input to the model. DeletedAgentResource: type: object properties: id: type: string minLength: 0 description: The ID of the deleted agent. object: type: string enum: - agent.deleted default: agent.deleted x-stainless-const: true description: The object type. Always `agent.deleted`. deleted: type: boolean description: Whether the agent was deleted. Always `true`. required: - id - object - deleted additionalProperties: false description: A deleted reusable agent. AgentResource: type: object properties: id: type: string minLength: 0 description: The ID of the reusable agent. object: type: string enum: - agent default: agent x-stainless-const: true description: The object type. Always `agent`. created_at: type: integer format: int64 description: The Unix timestamp, in seconds, when the agent was created. updated_at: type: integer format: int64 description: The Unix timestamp, in seconds, when the agent was last updated. name: type: - string - 'null' minLength: 0 description: A human-readable name for the agent, or null if it is unnamed. metadata: type: object additionalProperties: type: string minLength: 0 propertyNames: type: string minLength: 0 minProperties: 0 description: Custom string key-value pairs attached to the agent. model: type: string minLength: 0 description: The requested model name used for inference. reasoning: $ref: '#/components/schemas/ReasoningResource' description: The resolved reasoning configuration, including the model default for an omitted effort. text: $ref: '#/components/schemas/TextResource' description: The resolved configuration for text generated by the agent. service_tier: $ref: '#/components/schemas/ServiceTierResource' description: The resolved service-tier policy used for model requests. instructions: type: - string - 'null' minLength: 0 description: Custom instructions appended to the agent's default base instructions. tools: type: array items: $ref: '#/components/schemas/PersistedAgentToolResource' minItems: 0 maxItems: 2000 description: Tools available to the agent. multi_agent: $ref: '#/components/schemas/MultiAgentConfigResource' description: The resolved configuration for creating and coordinating subagents. required: - id - object - created_at - updated_at - name - metadata - model - reasoning - text - service_tier - instructions - tools - multi_agent additionalProperties: false description: A reusable agent scoped to the caller's project. CreateSessionEventsParams: type: object properties: events: type: array items: $ref: '#/components/schemas/SessionInputParam' minItems: 0 maxItems: 16384 description: The input events to submit to the session. required: - events additionalProperties: false description: Input events submitted to an existing session. AgentToolConfigParamMcp: type: object properties: type: type: string enum: - mcp default: mcp x-stainless-const: true description: The type of the object. Always `mcp`. server_label: type: string minLength: 0 maxLength: 1048576 description: A label used to identify the MCP server in tool calls. credential_id: type: - string - 'null' minLength: 0 maxLength: 1048576 description: The attached vault credential used to authenticate this MCP server. Optional when exactly one attached credential matches the server URL. transport: $ref: '#/components/schemas/McpTransportConfigParam' description: The transport used to connect to the MCP server. request_metadata: type: - object - 'null' additionalProperties: {} propertyNames: type: string minLength: 1 maxLength: 256 minProperties: 0 maxProperties: 1024 description: Metadata included with requests to this MCP server. allowed_tools: type: - array - 'null' items: type: string minLength: 0 maxLength: 1048576 minItems: 0 maxItems: 16384 description: The MCP tools the agent may call. All server tools are allowed when omitted. required: type: boolean default: false description: Whether this MCP server must initialize before the first turn. Defaults to `false`. connection_origin: anyOf: - $ref: '#/components/schemas/McpConnectionOriginParam' - type: 'null' description: Selects where outbound MCP HTTP connections originate. Omitted or `service` uses the Managed Agents service network; `environment` uses the session's selected environment. required: - type - server_label - transport additionalProperties: false description: Tools provided by a remote MCP server. EnvironmentPackagesResource: type: object properties: python: type: array items: type: string minLength: 0 maxLength: 1048576 minItems: 0 maxItems: 16384 description: Python packages installed in the environment. system: type: array items: type: string minLength: 0 maxLength: 1048576 minItems: 0 maxItems: 16384 description: System packages installed in the environment. npm: type: array items: type: string minLength: 0 maxLength: 1048576 minItems: 0 maxItems: 16384 description: npm packages installed globally in the environment. required: - python - system - npm additionalProperties: false description: Packages installed in an OpenAI-hosted environment. AgentOutputItemResource: oneOf: - $ref: '#/components/schemas/AssistantMessageItemResource' - $ref: '#/components/schemas/ReasoningItemResource' - $ref: '#/components/schemas/FunctionCallItemResource' - $ref: '#/components/schemas/McpCallItemResource' - $ref: '#/components/schemas/WebSearchCallItemResource' - $ref: '#/components/schemas/CommandExecutionItemResource' - $ref: '#/components/schemas/CreateSubagentCallItemResource' - $ref: '#/components/schemas/SendSubagentInputCallItemResource' - $ref: '#/components/schemas/ResumeSubagentCallItemResource' - $ref: '#/components/schemas/WaitForSubagentsCallItemResource' - $ref: '#/components/schemas/InterruptSubagentCallItemResource' - $ref: '#/components/schemas/CloseSubagentCallItemResource' discriminator: propertyName: type mapping: message: '#/components/schemas/AssistantMessageItemResource' reasoning: '#/components/schemas/ReasoningItemResource' function_call: '#/components/schemas/FunctionCallItemResource' mcp_call: '#/components/schemas/McpCallItemResource' web_search_call: '#/components/schemas/WebSearchCallItemResource' command_execution: '#/components/schemas/CommandExecutionItemResource' interrupt_subagent_call: '#/components/schemas/InterruptSubagentCallItemResource' create_subagent_call: '#/components/schemas/CreateSubagentCallItemResource' send_subagent_input_call: '#/components/schemas/SendSubagentInputCallItemResource' resume_subagent_call: '#/components/schemas/ResumeSubagentCallItemResource' wait_for_subagents_call: '#/components/schemas/WaitForSubagentsCallItemResource' close_subagent_call: '#/components/schemas/CloseSubagentCallItemResource' x-oai-discriminator-values: - message - reasoning - function_call - mcp_call - web_search_call - command_execution - create_subagent_call - send_subagent_input_call - resume_subagent_call - wait_for_subagents_call - interrupt_subagent_call - close_subagent_call description: An output item produced by an agent. AgentToolConfigParamToolSearch: type: object properties: type: type: string enum: - tool_search default: tool_search x-stainless-const: true description: The type of the object. Always `tool_search`. required: - type additionalProperties: false description: Discovers deferred function tools and loads them into the model context. SessionEventAgentSessionIdle: type: object properties: type: type: string enum: - agent.session.idle default: agent.session.idle x-stainless-const: true description: The type of the object. Always `agent.session.idle`. event_id: type: string minLength: 0 description: The unique ID of the event. session: $ref: '#/components/schemas/SessionResource' description: The session that became idle. required: - type - event_id - session additionalProperties: false description: Emitted when a session becomes idle. HostedEnvironmentFileParamInline: type: object properties: type: type: string enum: - inline default: inline x-stainless-const: true description: The type of the object. Always `inline`. data: type: string minLength: 0 maxLength: 6990508 description: The standard-base64-encoded file contents. path: type: string minLength: 1 maxLength: 4096 description: The absolute destination path inside `/workspace`. required: - type - data - path additionalProperties: false description: A file supplied directly as standard-base64 data. McpTransportConfigParamHttp: type: object properties: type: type: string enum: - http default: http x-stainless-const: true description: The type of the object. Always `http`. server_url: type: string minLength: 0 maxLength: 1048576 description: The URL of the MCP server. authorization: type: - string - 'null' minLength: 0 maxLength: 1048576 description: The authorization value sent to the MCP server, if any. headers: type: - object - 'null' additionalProperties: type: string minLength: 0 maxLength: 1048576 propertyNames: type: string minLength: 1 maxLength: 256 minProperties: 0 maxProperties: 1024 description: Additional HTTP headers sent to the MCP server. required: - type - server_url additionalProperties: false description: Connects to an MCP server over HTTP. SessionEventAgentSessionEnvironmentPending: type: object properties: type: type: string enum: - agent.session.environment.pending default: agent.session.environment.pending x-stainless-const: true description: The type of the object. Always `agent.session.environment.pending`. event_id: type: string minLength: 0 description: The unique ID of the event. session_id: type: string minLength: 0 description: The ID of the session associated with the event. turn_id: type: - string - 'null' minLength: 0 description: The ID of the turn associated with the event, when applicable. environment: $ref: '#/components/schemas/SessionEnvironmentStateResource' description: The current environment state. required: - type - event_id - session_id - turn_id - environment additionalProperties: false description: Emitted while a session environment is being prepared. HostedSkillParamInline: type: object properties: type: type: string enum: - inline default: inline x-stainless-const: true description: The type of the object. Always `inline`. name: type: string minLength: 1 maxLength: 64 description: The skill name declared in `SKILL.md`. description: type: string minLength: 0 maxLength: 1048576 description: The skill description declared in `SKILL.md`. source: $ref: '#/components/schemas/InlineCapabilitySourceParam' description: The inline ZIP archive. required: - type - name - description - source additionalProperties: false description: Supplies a skill ZIP directly in the session request. PersistedAgentToolResourceWebSearch: type: object properties: type: type: string enum: - web_search default: web_search x-stainless-const: true description: The type of the object. Always `web_search`. mode: $ref: '#/components/schemas/WebSearchModeResource' description: The source used for web search results. context_size: $ref: '#/components/schemas/WebSearchContextSizeResource' description: The amount of search context made available to the model. Defaults to `medium`. allowed_domains: type: - array - 'null' items: type: string minLength: 0 minItems: 0 maxItems: 2000 description: Allowed search domains, or `null` when the search is unrestricted. location: anyOf: - $ref: '#/components/schemas/WebSearchLocationResource' - type: 'null' description: Approximate location used to localize search results, if provided. required: - type - mode - context_size - allowed_domains - location additionalProperties: false description: Web search. EnvironmentFileResource: type: object properties: object: type: string enum: - agent.environment.file default: agent.environment.file x-stainless-const: true description: The object type. Always `agent.environment.file`. environment_id: type: string minLength: 0 description: The ID of the environment containing this file. path: type: string minLength: 0 description: The absolute file path inside the environment's workspace. size_bytes: type: integer format: int64 minimum: 0 description: The file size in bytes. required: - object - environment_id - path - size_bytes additionalProperties: false description: A live file in an execution environment. ServiceTierParam: type: string enum: - auto - default - flex - priority - fast x-enumDescriptions: - Selects the service tier automatically. - Uses the default service tier. - Uses the flex service tier. - Uses the priority service tier. - Uses the fast service tier. description: The service tier used for model requests. SessionRequiredActionResourceEnvironmentConnection: type: object properties: type: type: string enum: - environment_connection default: environment_connection x-stainless-const: true description: The type of the object. Always `environment_connection`. environment_id: type: string minLength: 0 description: The ID of the environment to reconnect. required: - type - environment_id additionalProperties: false description: Reconnect a session environment. SessionArtifactListResource: type: object properties: object: type: string enum: - list default: list x-stainless-const: true description: The object type, which is always `list`. data: type: array items: $ref: '#/components/schemas/SessionArtifactResource' minItems: 0 maxItems: 2000 description: The resources returned in this page, in the requested sort order. first_id: type: - string - 'null' minLength: 0 description: The ID of the first resource in `data`, or `null` if the page is empty. last_id: type: - string - 'null' minLength: 0 description: The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. has_more: type: boolean description: Whether there are more resources to retrieve after this page. required: - object - data - first_id - last_id - has_more additionalProperties: false description: A page of Agents API resources, with IDs for retrieving additional pages. ReasoningSummaryResource: type: string enum: - concise - detailed - auto x-enumDescriptions: - Returns a concise reasoning summary when supported. - Returns a detailed reasoning summary when supported. - Automatically selects the most detailed summary supported by the model. description: The reasoning summary format requested from an agent. SessionErrorResource: type: object properties: type: type: string minLength: 0 description: The error type. code: type: - string - 'null' minLength: 0 description: The machine-readable error code, if any. message: type: string minLength: 0 description: A customer-safe explanation of the error. param: type: - string - 'null' minLength: 0 description: The request parameter associated with the error, if any. required: - type - code - message - param additionalProperties: false description: An error payload with the same public fields as Responses API streaming errors. UpdateSessionReasoningParam: type: object properties: effort: anyOf: - $ref: '#/components/schemas/ReasoningEffortParam' - type: 'null' description: Omit to keep the current effort. Null selects the model's default effort. additionalProperties: false description: Reasoning effort for subsequent turns. The reasoning summary stays unchanged. AgentToolConfigParamProgrammaticToolCalling: type: object properties: type: type: string enum: - programmatic_tool_calling default: programmatic_tool_calling x-stainless-const: true description: The type of the object. Always `programmatic_tool_calling`. enabled: type: boolean default: true description: Whether tools can be called from model-generated code. Defaults to `true`. required: - type additionalProperties: false description: Enables calling tools from model-generated code. PublicEnvironmentResource: type: object properties: id: type: string minLength: 0 description: The ID of the environment. object: type: string enum: - agent.environment default: agent.environment x-stainless-const: true description: The object type. Always `agent.environment`. type: $ref: '#/components/schemas/EnvironmentTypeResource' description: Whether the environment is hosted by OpenAI or by the application. status: $ref: '#/components/schemas/EnvironmentStatusResource' description: The current environment connection status. plugins: type: array items: $ref: '#/components/schemas/HostedPluginResource' minItems: 0 maxItems: 2000 description: Plugins installed in the environment, without their archive contents. skills: type: array items: $ref: '#/components/schemas/HostedSkillResource' minItems: 0 maxItems: 2000 description: Skills installed in the environment, without their archive contents. files: type: array items: $ref: '#/components/schemas/HostedEnvironmentFileResource' minItems: 0 maxItems: 2000 description: Files installed in the environment, without their contents. required: - id - object - type - status - files - skills - plugins additionalProperties: false description: Safe metadata for a first-class execution environment. CreateSubagentCallItemResource: type: object properties: type: type: string enum: - create_subagent_call default: create_subagent_call x-stainless-const: true x-enumDescriptions: - The current public item type. description: The item type. Always `create_subagent_call`. id: type: string minLength: 0 description: The ID of the tool call item. turn_id: type: string minLength: 0 description: The ID of the turn that contains this item. status: $ref: '#/components/schemas/FunctionCallStatusResource' description: The status of the tool call. agent_id: type: string minLength: 0 description: The ID of the agent that requested the subagent. content: type: array items: $ref: '#/components/schemas/AgentContentResource' minItems: 0 maxItems: 2000 description: The task given to the spawned agent. model: type: - string - 'null' minLength: 0 description: The model requested for the spawned agent. reasoning_effort: type: - string - 'null' minLength: 0 description: The reasoning effort requested for the spawned agent. required: - type - id - turn_id - status - agent_id - content - model - reasoning_effort additionalProperties: false description: A request to spawn a subagent. SessionEventAgentSessionTurnReasoningSummaryPartDone: type: object properties: type: type: string enum: - agent.session.turn.reasoning_summary_part.done default: agent.session.turn.reasoning_summary_part.done x-stainless-const: true description: The type of the object. Always `agent.session.turn.reasoning_summary_part.done`. event_id: type: string minLength: 0 description: The unique ID of the event. session_id: type: string minLength: 0 description: The ID of the session associated with the event. turn_id: type: - string - 'null' minLength: 0 description: The ID of the turn associated with the event, when applicable. item_id: type: string minLength: 0 description: The ID of the reasoning item. output_index: type: integer format: int64 minimum: 0 maximum: 4294967295 description: The index of the item in the turn output. summary_index: type: integer format: int64 minimum: 0 maximum: 4294967295 description: The index of the summary part. part: $ref: '#/components/schemas/SummaryTextResource' description: The completed summary part. status: type: - string - 'null' enum: - incomplete - null description: Present as `incomplete` when summary generation was interrupted. x-stainless-const: true required: - type - event_id - session_id - turn_id - item_id - output_index - summary_index - part - status additionalProperties: false description: Emitted when a reasoning summary part is complete. InputTokensDetailsResource: type: object properties: cached_tokens: type: integer format: int64 description: The number of input tokens retrieved from the prompt cache. required: - cached_tokens additionalProperties: false description: A breakdown of input token usage for a session or turn. SessionEventAgentSessionTurnOutputTextDone: type: object properties: type: type: string enum: - agent.session.turn.output_text.done default: agent.session.turn.output_text.done x-stainless-const: true description: The type of the object. Always `agent.session.turn.output_text.done`. event_id: type: string minLength: 0 description: The unique ID of the event. session_id: type: string minLength: 0 description: The ID of the session associated with the event. turn_id: type: - string - 'null' minLength: 0 description: The ID of the turn associated with the event, when applicable. item_id: type: string minLength: 0 description: The ID of the message item. output_index: type: integer format: int64 minimum: 0 maximum: 4294967295 description: The index of the item in the turn output. content_index: type: integer format: int64 minimum: 0 maximum: 4294967295 description: The index of the content part in the message. text: type: string minLength: 0 description: The complete output text. required: - type - event_id - session_id - turn_id - item_id - output_index - content_index - text additionalProperties: false description: Emitted when an output text content part is complete. SessionEventAgentOutputCommandExecutionOutputDelta: type: object properties: type: type: string enum: - agent.output.command_execution_output.delta default: agent.output.command_execution_output.delta x-stainless-const: true description: The type of the object. Always `agent.output.command_execution_output.delta`. event_id: type: string minLength: 0 description: The unique ID of the event. session_id: type: string minLength: 0 description: The ID of the session associated with the event. turn_id: type: - string - 'null' minLength: 0 description: The ID of the turn associated with the event, when applicable. item_id: type: string minLength: 0 description: The ID of the command execution item. output_index: type: integer format: int64 minimum: 0 maximum: 4294967295 description: The index of the item in the turn output. delta: type: string minLength: 0 description: The output text that was appended. required: - type - event_id - session_id - turn_id - item_id - output_index - delta additionalProperties: false description: Emitted when command execution produces an output delta. EnvironmentResourceOpenaiHosted: type: object properties: type: type: string enum: - openai_hosted default: openai_hosted x-stainless-const: true description: The type of the object. Always `openai_hosted`. id: type: string minLength: 0 description: The public ID of the environment. packages: $ref: '#/components/schemas/EnvironmentPackagesResource' description: Packages installed in the environment. network: $ref: '#/components/schemas/NetworkPolicyResource' description: The effective network access policy for the environment. capability_directories: type: array items: type: string minLength: 0 minItems: 0 maxItems: 2000 description: Directories that contain capabilities exposed to the agent. skills: type: array items: $ref: '#/components/schemas/HostedSkillResource' minItems: 0 maxItems: 2000 description: Skills installed in the environment, excluding their archive contents. plugins: type: array items: $ref: '#/components/schemas/HostedPluginResource' minItems: 0 maxItems: 2000 description: Plugins installed in the environment, excluding their archive contents. files: type: array items: $ref: '#/components/schemas/HostedEnvironmentFileResource' minItems: 0 maxItems: 50 description: Files available in the environment, excluding their contents. required: - type - id - packages - network - capability_directories - skills - plugins - files additionalProperties: false description: An environment hosted by OpenAI. McpConnectionOriginResource: type: string enum: - service - environment description: Where outbound MCP HTTP connections originate. TextParam: type: object properties: format: anyOf: - $ref: '#/components/schemas/TextFormatParam' - type: 'null' description: 'The output format. Omission uses ordinary text (`{"type": "text"}`).' verbosity: anyOf: - $ref: '#/components/schemas/VerbosityParam' - type: 'null' description: The amount of text the model should produce. Defaults to `medium`, matching Responses. additionalProperties: false description: Configuration for text generated by the agent. SessionEventAgentSessionSubagentActive: type: object properties: type: type: string enum: - agent.session.subagent.active default: agent.session.subagent.active x-stainless-const: true description: The type of the object. Always `agent.session.subagent.active`. event_id: type: string minLength: 0 description: The unique ID of the event. subagent: $ref: '#/components/schemas/SubagentResource' description: The subagent that resumed. required: - type - event_id - subagent additionalProperties: false description: Emitted when a closed subagent successfully resumes. SessionItemListResource: type: object properties: object: type: string enum: - list default: list x-stainless-const: true description: The object type, which is always `list`. data: type: array items: $ref: '#/components/schemas/SessionTurnItemResource' minItems: 0 maxItems: 2000 description: The resources returned in this page, in the requested sort order. first_id: type: - string - 'null' minLength: 0 description: The ID of the first resource in `data`, or `null` if the page is empty. last_id: type: - string - 'null' minLength: 0 description: The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. has_more: type: boolean description: Whether there are more resources to retrieve after this page. required: - object - data - first_id - last_id - has_more additionalProperties: false description: A page of messages, reasoning, and tool calls from a session's item history. EnvironmentParamSelfHosted: type: object properties: type: type: string enum: - self_hosted default: self_hosted x-stainless-const: true description: The type of the object. Always `self_hosted`. workspace_directory: type: string minLength: 0 maxLength: 1048576 description: Absolute project directory inside the self-hosted environment. capability_directories: type: - array - 'null' items: type: string minLength: 0 maxLength: 1048576 minItems: 0 maxItems: 16384 description: Directories that contain capabilities exposed to the agent. Defaults to an empty list. required: - type - workspace_directory additionalProperties: false description: An application-hosted environment configured inline. UpdateAgentSessionParams: type: object properties: agent: $ref: '#/components/schemas/UpdateSessionAgentParam' description: Model settings for subsequent turns. Omitted fields stay unchanged. metadata: type: - object - 'null' additionalProperties: type: string minLength: 0 maxLength: 512 propertyNames: type: string minLength: 1 maxLength: 64 minProperties: 0 maxProperties: 16 description: Replaces all metadata. Omit to leave unchanged, or pass null or {} to clear it. Up to 16 string key-value pairs, with keys up to 64 and values up to 512 characters. additionalProperties: false description: Fields to update on an existing session. InputMessageParam: type: object properties: type: type: string enum: - message default: message x-stainless-const: true description: The type of the input item. Always `message`. role: type: string enum: - user default: user x-stainless-const: true description: The role of the message author. Always `user`. content: type: array items: $ref: '#/components/schemas/InputContentParam' minItems: 0 maxItems: 16384 description: The content of the message. required: - role - content additionalProperties: false description: A user message submitted to a session. TurnResource: type: object properties: id: type: string minLength: 0 description: The ID of the turn. object: $ref: '#/components/schemas/TurnObjectResource' description: The object type. Always `agent.session.turn`. session_id: type: string minLength: 0 description: The ID of the session that owns the turn. agent_id: type: string minLength: 0 description: The ID of the agent that ran the turn. subagent_id: type: - string - 'null' minLength: 0 description: The ID of the subagent that ran the turn, if applicable. status: $ref: '#/components/schemas/TurnStatusResource' description: The current status of the turn. created_at: type: integer format: int64 description: The Unix timestamp, in seconds, used to order the turn by creation time. Subagent turns use their start time, falling back to completion time or the subagent opening time when the preceding timestamps are unavailable. started_at: type: - integer - 'null' format: int64 description: The Unix timestamp, in seconds, when the turn started. completed_at: type: - integer - 'null' format: int64 description: The Unix timestamp, in seconds, when the turn reached a terminal state. error: anyOf: - $ref: '#/components/schemas/SessionTurnErrorResource' - type: 'null' description: A customer-safe error. Non-null only for a failed turn. usage: anyOf: - $ref: '#/components/schemas/TokenUsageResource' - type: 'null' description: Best-effort token usage for the turn, or null if unknown. Recorded usage may change. required: - id - object - session_id - agent_id - subagent_id - status - created_at - started_at - completed_at - error - usage additionalProperties: false description: The canonical public representation of a session turn. SessionEventAgentSessionEnvironmentFailed: type: object properties: type: type: string enum: - agent.session.environment.failed default: agent.session.environment.failed x-stainless-const: true description: The type of the object. Always `agent.session.environment.failed`. event_id: type: string minLength: 0 description: The unique ID of the event. session_id: type: string minLength: 0 description: The ID of the session associated with the event. turn_id: type: - string - 'null' minLength: 0 description: The ID of the turn associated with the event, when applicable. environment: $ref: '#/components/schemas/SessionEnvironmentStateResource' description: The current environment state. required: - type - event_id - session_id - turn_id - environment additionalProperties: false description: Emitted when a session environment fails. AssistantMessageItemResource: type: object properties: type: type: string enum: - message default: message x-stainless-const: true description: The item type. Always `message`. id: type: string minLength: 0 description: The ID of the message. turn_id: type: string minLength: 0 description: The ID of the turn that contains this item. role: type: string enum: - assistant default: assistant x-stainless-const: true description: The role of the message author. Always `assistant`. status: $ref: '#/components/schemas/OutputItemStatusResource' description: The status of the message. content: type: array items: $ref: '#/components/schemas/OutputTextResource' minItems: 0 maxItems: 2000 description: The content of the message. phase: anyOf: - $ref: '#/components/schemas/MessagePhaseResource' - type: 'null' description: The phase of the assistant message. required: - type - id - turn_id - role - status - content - phase additionalProperties: false description: An assistant message produced by the agent. FunctionCallOutputItemResource: type: object properties: id: type: string minLength: 0 description: The ID of the function call output item. turn_id: type: string minLength: 0 description: The ID of the turn that contains this item. type: type: string enum: - function_call_output default: function_call_output x-stainless-const: true description: The item type. Always `function_call_output`. call_id: type: string minLength: 0 description: The ID of the function call that produced this output. status: $ref: '#/components/schemas/FunctionCallStatusResource' description: The status of the function call. output: anyOf: - $ref: '#/components/schemas/FunctionCallOutputResource' - type: 'null' description: The function result, if the call succeeded. error: type: - string - 'null' minLength: 0 description: The error message, if the call failed. required: - id - turn_id - type - call_id - status - output - error additionalProperties: false description: The result supplied for a function call. CreateAgentParams: type: object properties: metadata: type: - object - 'null' additionalProperties: type: string minLength: 0 maxLength: 512 propertyNames: type: string minLength: 1 maxLength: 64 minProperties: 0 maxProperties: 16 description: Up to 16 string key-value pairs, with keys up to 64 and values up to 512 characters. Omission or null defaults to an empty map. name: type: - string - 'null' minLength: 0 maxLength: 128 description: A human-readable name for the agent. Omission or null leaves the agent unnamed. model: type: string minLength: 0 maxLength: 1048576 description: The model to use for the agent. The requested model name is preserved. reasoning: anyOf: - $ref: '#/components/schemas/ReasoningParam' - type: 'null' description: Configuration for model reasoning. Omission uses the model's default effort. text: anyOf: - $ref: '#/components/schemas/TextParam' - type: 'null' description: Configuration for generated text. Defaults to the `text` format and medium verbosity. service_tier: anyOf: - $ref: '#/components/schemas/ServiceTierParam' - type: 'null' description: The service tier used for model requests. Defaults to `auto`. instructions: type: - string - 'null' minLength: 0 maxLength: 1048576 description: Additional instructions appended to the agent's default base instructions. Omit or set to null to add no custom instructions. tools: type: - array - 'null' items: $ref: '#/components/schemas/PersistedAgentToolConfigParam' minItems: 0 maxItems: 2000 description: Tools available to the agent. Defaults to an empty list. multi_agent: anyOf: - $ref: '#/components/schemas/MultiAgentConfigCurrentParam' - type: 'null' description: Configuration for creating and coordinating subagents. Subagent tools are disabled by default. required: - model additionalProperties: false description: Parameters for creating a reusable agent. SessionResource: type: object properties: metadata: type: object additionalProperties: type: string minLength: 0 propertyNames: type: string minLength: 0 minProperties: 0 description: Custom string key-value pairs attached to the session. id: type: string minLength: 0 description: The ID of the session. object: type: string enum: - agent.session default: agent.session x-stainless-const: true description: The object type. Always `agent.session`. created_at: type: integer format: int64 description: The Unix timestamp, in seconds, when the session was created. last_active_at: type: integer format: int64 description: The Unix timestamp, in seconds, when the session was last active. status: $ref: '#/components/schemas/SessionStatusResource' description: The current status of the session. required_actions: type: array items: $ref: '#/components/schemas/SessionRequiredActionResource' minItems: 0 maxItems: 2000 description: Actions that must be completed before the session can continue. error: description: The error that caused the session to fail, if any. type: - string - 'null' minLength: 0 agent: $ref: '#/components/schemas/SessionAgentResource' description: The agent running in the session. environment: $ref: '#/components/schemas/EnvironmentResource' description: The execution environment for the session. vault_ids: type: array items: type: string minLength: 0 minItems: 0 maxItems: 2000 description: The IDs of vaults made available to the session. usage: anyOf: - $ref: '#/components/schemas/TokenUsageResource' - type: 'null' description: Best-effort token usage for the session, or null if unknown. Recorded usage may change. required: - metadata - id - object - created_at - last_active_at - status - required_actions - error - agent - environment - vault_ids - usage additionalProperties: false description: A Managed Agents session. TextResource: type: object properties: format: $ref: '#/components/schemas/TextFormatResource' description: The effective output format. Defaults to ordinary text. verbosity: $ref: '#/components/schemas/VerbosityResource' description: The amount of text produced by the agent. Defaults to `medium`. required: - format - verbosity additionalProperties: false description: The text configuration used by an agent. SessionTurnErrorCodeResource: type: string enum: - context_length_exceeded - session_budget_exceeded - usage_limit_exceeded - credit_balance_exhausted - rate_limit_exceeded - server_overloaded - cyber_policy - connection_failed - server_error - authentication_error - invalid_request - resource_not_found - sandbox_error - executor_version_incompatible - active_turn_not_steerable - request_timeout - internal_error x-enumDescriptions: - The request exceeds the model's context window. - The session has reached its usage budget. - The organization has reached a usage, plan, or billing limit. - The organization has no API credits remaining. - The request exceeds the available rate limit. - The model service is temporarily overloaded. - The request was rejected by a safety policy. - The request could not connect to the model service. - The model service encountered an unexpected error. - The API credentials are invalid or lack the required access. - The request contains invalid input or configuration. - The requested model or resource is unavailable. - The request could not complete in its execution environment. - The executor must be upgraded before it can run this turn. - The session cannot accept additional input while a request is running. - The request timed out before the model service responded. - An unexpected internal error prevented the session request from completing. description: Stable public categories for session request failures. SessionEventAgentSessionEnvironmentDisconnected: type: object properties: type: type: string enum: - agent.session.environment.disconnected default: agent.session.environment.disconnected x-stainless-const: true description: The type of the object. Always `agent.session.environment.disconnected`. event_id: type: string minLength: 0 description: The unique ID of the event. session_id: type: string minLength: 0 description: The ID of the session associated with the event. turn_id: type: - string - 'null' minLength: 0 description: The ID of the turn associated with the event, when applicable. environment: $ref: '#/components/schemas/SessionEnvironmentStateResource' description: The current environment state. required: - type - event_id - session_id - turn_id - environment additionalProperties: false description: Emitted when a session environment disconnects. InputContentResourceInputText: type: object properties: type: type: string enum: - input_text default: input_text x-stainless-const: true description: The type of the object. Always `input_text`. text: type: string minLength: 0 description: The text supplied to the agent. required: - type - text additionalProperties: false description: Text input recorded in a session item. EnvironmentParamOpenaiHosted: type: object properties: type: type: string enum: - openai_hosted default: openai_hosted x-stainless-const: true description: The type of the object. Always `openai_hosted`. packages: anyOf: - $ref: '#/components/schemas/EnvironmentPackagesParam' - type: 'null' description: Packages to install in the environment. Defaults to empty package lists. setup_commands: type: - array - 'null' items: $ref: '#/components/schemas/SetupCommandParam' minItems: 0 maxItems: 16 description: Ordered, confidential setup commands. Command bodies are never returned. network: anyOf: - $ref: '#/components/schemas/NetworkPolicyParam' - type: 'null' description: Network access policy for the environment. Defaults to disabled for GA requests and enabled for alpha/beta requests. env: type: - object - 'null' additionalProperties: type: string minLength: 0 maxLength: 1048576 propertyNames: type: string minLength: 1 maxLength: 256 minProperties: 0 maxProperties: 1024 description: Environment variables made available to the agent. capability_directories: type: - array - 'null' items: type: string minLength: 0 maxLength: 1048576 minItems: 0 maxItems: 16384 description: Directories that contain capabilities exposed to the agent. Defaults to an empty list. skills: type: - array - 'null' items: $ref: '#/components/schemas/HostedSkillParam' minItems: 0 maxItems: 200 description: Skills referenced by ID or provided as inline ZIP archives. Defaults to an empty list. plugins: type: - array - 'null' items: $ref: '#/components/schemas/HostedPluginParam' minItems: 0 maxItems: 32 description: Plugins provided as inline ZIP archives. Defaults to an empty list. files: type: - array - 'null' items: $ref: '#/components/schemas/HostedEnvironmentFileParam' minItems: 0 maxItems: 50 description: Files available before the agent starts. Defaults to an empty list. environment_template_id: type: string minLength: 0 maxLength: 64 description: A reusable hosted template applied before inline session configuration. Omitted fields inherit the template; network overrides cannot broaden its policy. required: - type additionalProperties: false description: An existing OpenAI-hosted environment or new inline/template-based hosted configuration. PersistedAgentToolConfigParamProgrammaticToolCalling: type: object properties: type: type: string enum: - programmatic_tool_calling default: programmatic_tool_calling x-stainless-const: true description: The type of the object. Always `programmatic_tool_calling`. enabled: type: boolean default: true description: Whether tools can be called from model-generated code. Defaults to `true`. required: - type additionalProperties: false description: Enables calling tools from model-generated code. AgentToolResourceProgrammaticToolCalling: type: object properties: type: type: string enum: - programmatic_tool_calling default: programmatic_tool_calling x-stainless-const: true description: The type of the object. Always `programmatic_tool_calling`. enabled: type: boolean description: Whether tools can be called from model-generated code. required: - type - enabled additionalProperties: false description: Enables calling tools from model-generated code. OutputTextResource: type: object properties: type: type: string enum: - output_text default: output_text x-stainless-const: true description: The content type. Always `output_text`. text: type: string minLength: 0 description: The text produced by the agent. required: - type - text additionalProperties: false description: A text content part produced by the agent. PersistedMcpTransportConfigParamHttp: type: object properties: type: type: string enum: - http default: http x-stainless-const: true description: The type of the object. Always `http`. server_url: type: string minLength: 0 maxLength: 1048576 description: The URL of the MCP server. headers: type: - object - 'null' additionalProperties: type: string minLength: 0 maxLength: 1048576 propertyNames: type: string minLength: 1 maxLength: 256 minProperties: 0 maxProperties: 1024 description: Non-secret HTTP headers sent to the MCP server. required: - type - server_url additionalProperties: false description: Connects to an MCP server over HTTP. ResumeSubagentCallItemResource: type: object properties: type: type: string enum: - resume_subagent_call default: resume_subagent_call x-stainless-const: true x-enumDescriptions: - The current public item type. description: The item type. Always `resume_subagent_call`. id: type: string minLength: 0 description: The ID of the tool call item. turn_id: type: string minLength: 0 description: The ID of the turn that contains this item. status: $ref: '#/components/schemas/FunctionCallStatusResource' description: The status of the tool call. sender_agent_id: type: string minLength: 0 description: The ID of the agent requesting the resume. recipient_agent_id: type: string minLength: 0 description: The ID of the agent to resume. required: - type - id - turn_id - status - sender_agent_id - recipient_agent_id additionalProperties: false description: A request to resume a subagent. WebSearchModeResource: type: string enum: - disabled - cached - live description: The source used for web search results. PersistedMcpTransportConfigParam: oneOf: - $ref: '#/components/schemas/PersistedMcpTransportConfigParamHttp' - $ref: '#/components/schemas/PersistedMcpTransportConfigParamStdio' discriminator: propertyName: type mapping: http: '#/components/schemas/PersistedMcpTransportConfigParamHttp' stdio: '#/components/schemas/PersistedMcpTransportConfigParamStdio' x-oai-discriminator-values: - http - stdio description: A credential-free transport used to connect to an MCP server. HostedSkillResourceSkillReference: type: object properties: type: type: string enum: - skill_reference default: skill_reference x-stainless-const: true description: The type of the object. Always `skill_reference`. skill_id: type: string minLength: 0 description: The referenced skill ID. version: type: string minLength: 0 description: The concrete skill version installed for this session. name: type: string minLength: 0 description: The installed skill name. description: type: string minLength: 0 description: The installed skill description. required: - type - skill_id - version - name - description additionalProperties: false description: A skill installed from the Skills API. CreateSessionInputParam: oneOf: - type: string minLength: 1 maxLength: 1048576 - type: array items: $ref: '#/components/schemas/InputMessageParam' minItems: 0 maxItems: 16384 description: Initial input submitted when creating a session. EnvironmentParamNone: type: object properties: type: type: string enum: - none default: none x-stainless-const: true description: The type of the object. Always `none`. required: - type additionalProperties: false description: Runs the agent without an execution environment. HostedSkillResource: oneOf: - $ref: '#/components/schemas/HostedSkillResourceSkillReference' - $ref: '#/components/schemas/HostedSkillResourceInline' discriminator: propertyName: type mapping: skill_reference: '#/components/schemas/HostedSkillResourceSkillReference' inline: '#/components/schemas/HostedSkillResourceInline' x-oai-discriminator-values: - skill_reference - inline description: A skill installed in an OpenAI-hosted environment. HostedEnvironmentFileResourceInline: type: object properties: type: type: string enum: - inline default: inline x-stainless-const: true description: The type of the object. Always `inline`. id: type: string minLength: 0 description: The session-scoped ID of the file in the execution environment. path: type: string minLength: 0 description: The file's absolute path inside the environment. size_bytes: type: integer format: int64 minimum: 0 description: The decoded file size in bytes. required: - type - id - path - size_bytes additionalProperties: false description: A file supplied inline when the session was created. NetworkAccessResource: type: string enum: - enabled - disabled - restricted x-enumDescriptions: - Allows unrestricted network access. - Disables network access. - Allows access only to configured domains. description: The network access mode for an OpenAI-hosted environment. WebSearchCallItemResource: type: object properties: type: type: string enum: - web_search_call default: web_search_call x-stainless-const: true description: The item type. Always `web_search_call`. id: type: string minLength: 0 description: The ID of the web search call. turn_id: type: string minLength: 0 description: The ID of the turn that contains this item. status: $ref: '#/components/schemas/OutputItemStatusResource' description: The status of the web search call. action: anyOf: - $ref: '#/components/schemas/WebSearchActionResource' - type: 'null' description: The action performed by the web search tool. required: - type - id - turn_id - status - action additionalProperties: false description: A web search call produced by the agent. SessionEventAgentSessionSubagentCreated: type: object properties: type: type: string enum: - agent.session.subagent.created default: agent.session.subagent.created x-stainless-const: true description: The type of the object. Always `agent.session.subagent.created`. event_id: type: string minLength: 0 description: The unique ID of the event. subagent: $ref: '#/components/schemas/SubagentResource' description: The subagent that was created. required: - type - event_id - subagent additionalProperties: false description: Emitted when a subagent is created. HostedSkillParamSkillReference: type: object properties: type: type: string enum: - skill_reference default: skill_reference x-stainless-const: true description: The type of the object. Always `skill_reference`. skill_id: type: string minLength: 1 maxLength: 64 description: The ID of the skill created through `/v1/skills`. version: type: - string - 'null' minLength: 0 maxLength: 1048576 description: The skill version, a positive integer or `latest`; omission selects the default. required: - type - skill_id additionalProperties: false description: References a skill uploaded through the Skills API. MessageContentResource: oneOf: - $ref: '#/components/schemas/MessageContentResourceInputText' - $ref: '#/components/schemas/MessageContentResourceInputImage' - $ref: '#/components/schemas/MessageContentResourceOutputText' discriminator: propertyName: type mapping: input_text: '#/components/schemas/MessageContentResourceInputText' input_image: '#/components/schemas/MessageContentResourceInputImage' output_text: '#/components/schemas/MessageContentResourceOutputText' x-oai-discriminator-values: - input_text - input_image - output_text description: A content part in a session message. CommandExecutionItemResource: type: object properties: type: type: string enum: - command_execution default: command_execution x-stainless-const: true description: The item type. Always `command_execution`. id: type: string minLength: 0 description: The ID of the command execution item. turn_id: type: string minLength: 0 description: The ID of the turn that contains this item. command: type: string minLength: 0 description: The command that was executed. cwd: type: - string - 'null' minLength: 0 description: The working directory used to execute the command. status: $ref: '#/components/schemas/FunctionCallStatusResource' description: The status of the command execution. output: type: - string - 'null' minLength: 0 description: The command output, if available. exit_code: type: - integer - 'null' format: int64 description: The process exit code, if the command completed. duration_ms: type: - integer - 'null' format: int64 description: The command duration in milliseconds. required: - type - id - turn_id - command - cwd - status - output - exit_code - duration_ms additionalProperties: false description: A command execution produced by the agent. HostedEnvironmentFileParamFileId: type: object properties: type: type: string enum: - file_id default: file_id x-stainless-const: true description: The type of the object. Always `file_id`. file_id: type: string minLength: 1 maxLength: 256 description: The ID of the uploaded file. path: type: string minLength: 1 maxLength: 4096 description: The absolute destination path inside `/workspace`. required: - type - file_id - path additionalProperties: false description: A file previously uploaded through the OpenAI Files API. TextFormatParamJsonSchema: type: object properties: type: type: string enum: - json_schema default: json_schema x-stainless-const: true description: The type of the object. Always `json_schema`. schema: type: object additionalProperties: {} propertyNames: type: string minLength: 1 maxLength: 256 minProperties: 0 maxProperties: 1024 description: The JSON Schema that generated text must match. required: - type - schema additionalProperties: false description: Constrains generated text to a JSON Schema. WebSearchModeParam: type: string enum: - disabled - cached - live x-enumDescriptions: - Disables web search. - Uses cached search results. - Searches the live web. description: The source used for web search results. HostedTemplateFileResourceInline: type: object properties: type: type: string enum: - inline default: inline x-stainless-const: true description: The type of the object. Always `inline`. path: type: string minLength: 0 description: The file's absolute path inside the environment. size_bytes: type: integer format: int64 minimum: 0 description: The decoded size of the inline file in bytes. required: - type - path - size_bytes additionalProperties: false description: Metadata for confidential inline file contents. AgentToolResourceMcp: type: object properties: type: type: string enum: - mcp default: mcp x-stainless-const: true description: The type of the object. Always `mcp`. server_label: type: string minLength: 0 description: A label used to identify the MCP server in tool calls. credential_id: type: - string - 'null' minLength: 0 description: The attached vault credential selected for this MCP server, if any. Optional when exactly one attached credential matches the server URL. transport: $ref: '#/components/schemas/McpTransportResource' description: The transport used to connect to the MCP server. request_metadata: type: object additionalProperties: {} propertyNames: type: string minLength: 0 minProperties: 0 description: Metadata included with requests to this MCP server. allowed_tools: type: - array - 'null' items: type: string minLength: 0 minItems: 0 maxItems: 2000 description: The MCP tools the agent may call. required: type: boolean description: Whether this MCP server must initialize before the first turn. connection_origin: $ref: '#/components/schemas/McpConnectionOriginResource' description: Where outbound MCP HTTP connections originate. required: - type - server_label - credential_id - transport - request_metadata - allowed_tools - required - connection_origin additionalProperties: false description: Tools provided by a remote MCP server. AgentContentResource: oneOf: - $ref: '#/components/schemas/OutputTextResource' - $ref: '#/components/schemas/EncryptedContentResource' discriminator: propertyName: type mapping: output_text: '#/components/schemas/OutputTextResource' encrypted_content: '#/components/schemas/EncryptedContentResource' x-oai-discriminator-values: - output_text - encrypted_content description: A plaintext or encrypted content part exchanged between agents. WebSearchActionResourceSearch: type: object properties: type: type: string enum: - search default: search x-stainless-const: true description: The type of the object. Always `search`. query: type: - string - 'null' minLength: 0 description: The search query, when a single query was used. queries: type: - array - 'null' items: type: string minLength: 0 minItems: 0 maxItems: 2000 description: The search queries, when multiple queries were used. required: - type - query - queries additionalProperties: false description: A search query or group of search queries. McpCallItemResource: type: object properties: type: type: string enum: - mcp_call default: mcp_call x-stainless-const: true description: The item type. Always `mcp_call`. id: type: string minLength: 0 description: The ID of the MCP call item. turn_id: type: string minLength: 0 description: The ID of the turn that contains this item. server_label: type: string minLength: 0 description: The label of the MCP server. name: type: string minLength: 0 description: The name of the MCP tool. arguments: description: The arguments passed to the MCP tool. status: $ref: '#/components/schemas/FunctionCallStatusResource' description: The status of the MCP tool call. output: anyOf: - {} - type: 'null' description: The output returned by the MCP tool, if any. error: anyOf: - {} - type: 'null' description: The error returned by the MCP tool, if any. required: - type - id - turn_id - server_label - name - arguments - status - output - error additionalProperties: false description: A call to a tool on an MCP server. SessionEventAgentSessionTurnItemAdded: type: object properties: type: type: string enum: - agent.session.turn.item.added default: agent.session.turn.item.added x-stainless-const: true description: The type of the object. Always `agent.session.turn.item.added`. event_id: type: string minLength: 0 description: The unique ID of the event. session_id: type: string minLength: 0 description: The ID of the session associated with the event. turn_id: type: - string - 'null' minLength: 0 description: The ID of the turn associated with the event, when applicable. output_index: type: - integer - 'null' format: int64 minimum: 0 maximum: 4294967295 description: The index of the item in the turn output, when the item is agent output. item: $ref: '#/components/schemas/SessionTurnItemResource' description: The item that was added. required: - type - event_id - session_id - turn_id - output_index - item additionalProperties: false description: Emitted when an item is added to a turn. TextFormatResource: oneOf: - $ref: '#/components/schemas/TextFormatResourceText' - $ref: '#/components/schemas/TextFormatResourceJsonSchema' discriminator: propertyName: type mapping: text: '#/components/schemas/TextFormatResourceText' json_schema: '#/components/schemas/TextFormatResourceJsonSchema' x-oai-discriminator-values: - text - json_schema description: The effective output format for generated text. ReasoningItemResource: type: object properties: type: type: string enum: - reasoning default: reasoning x-stainless-const: true description: The item type. Always `reasoning`. id: type: string minLength: 0 description: The ID of the reasoning item. turn_id: type: string minLength: 0 description: The ID of the turn that contains this item. summary: type: array items: $ref: '#/components/schemas/SummaryTextResource' minItems: 0 maxItems: 2000 description: The reasoning summaries produced by the agent. status: anyOf: - $ref: '#/components/schemas/OutputItemStatusResource' - type: 'null' description: The status of the reasoning item. required: - type - id - turn_id - summary - status additionalProperties: false description: A reasoning item produced by the agent. PersistedAgentToolResourceToolSearch: type: object properties: type: type: string enum: - tool_search default: tool_search x-stainless-const: true description: The type of the object. Always `tool_search`. required: - type additionalProperties: false description: Discovers deferred function tools and loads them into the model context. AgentToolResourceWebSearch: type: object properties: type: type: string enum: - web_search default: web_search x-stainless-const: true description: The type of the object. Always `web_search`. mode: $ref: '#/components/schemas/WebSearchModeResource' description: The source used for web search results. context_size: $ref: '#/components/schemas/WebSearchContextSizeResource' description: The amount of search context made available to the model. Defaults to `medium`. allowed_domains: type: - array - 'null' items: type: string minLength: 0 minItems: 0 maxItems: 2000 description: Allowed search domains, or `null` when the search is unrestricted. location: anyOf: - $ref: '#/components/schemas/WebSearchLocationResource' - type: 'null' description: Approximate location used to localize search results, if provided. required: - type - mode - context_size - allowed_domains - location additionalProperties: false description: Web search. SessionEventAgentSessionSubagentClosed: type: object properties: type: type: string enum: - agent.session.subagent.closed default: agent.session.subagent.closed x-stainless-const: true description: The type of the object. Always `agent.session.subagent.closed`. event_id: type: string minLength: 0 description: The unique ID of the event. subagent: $ref: '#/components/schemas/SubagentResource' description: The subagent that was closed. required: - type - event_id - subagent additionalProperties: false description: Emitted when a subagent is closed. HostedTemplateSkillResourceSkillReference: type: object properties: type: type: string enum: - skill_reference default: skill_reference x-stainless-const: true description: The type of the object. Always `skill_reference`. skill_id: type: string minLength: 0 description: The referenced skill ID. version: type: - string - 'null' minLength: 0 description: The requested version selector, including `latest`. required: - type - skill_id - version additionalProperties: false description: A skill resolved afresh from the Skills API whenever a session starts. SessionEventAgentSessionTurnContentPartDone: type: object properties: type: type: string enum: - agent.session.turn.content_part.done default: agent.session.turn.content_part.done x-stainless-const: true description: The type of the object. Always `agent.session.turn.content_part.done`. event_id: type: string minLength: 0 description: The unique ID of the event. session_id: type: string minLength: 0 description: The ID of the session associated with the event. turn_id: type: - string - 'null' minLength: 0 description: The ID of the turn associated with the event, when applicable. item_id: type: string minLength: 0 description: The ID of the message item. output_index: type: integer format: int64 minimum: 0 maximum: 4294967295 description: The index of the item in the turn output. content_index: type: integer format: int64 minimum: 0 maximum: 4294967295 description: The index of the content part in the message. part: $ref: '#/components/schemas/OutputTextResource' description: The completed content part. required: - type - event_id - session_id - turn_id - item_id - output_index - content_index - part additionalProperties: false description: Emitted when an output content part is complete. SummaryTextResource: type: object properties: type: type: string enum: - summary_text default: summary_text x-stainless-const: true description: The content type. Always `summary_text`. text: type: string minLength: 0 description: The reasoning summary text. required: - type - text additionalProperties: false description: A reasoning summary content part. PersistedAgentToolConfigParamWebSearch: type: object properties: type: type: string enum: - web_search default: web_search x-stainless-const: true description: The type of the object. Always `web_search`. mode: anyOf: - $ref: '#/components/schemas/WebSearchModeParam' - type: 'null' description: The source used for web search results. Defaults to `live`. context_size: anyOf: - $ref: '#/components/schemas/WebSearchContextSizeParam' - type: 'null' description: The amount of search context made available to the model. Defaults to `medium`. allowed_domains: type: - array - 'null' items: type: string minLength: 0 maxLength: 1048576 minItems: 0 maxItems: 16384 description: Domains the search may include. location: anyOf: - $ref: '#/components/schemas/WebSearchLocationParam' - type: 'null' description: Approximate location used to localize search results. required: - type additionalProperties: false description: Web search. PersistedAgentToolResourceProgrammaticToolCalling: type: object properties: type: type: string enum: - programmatic_tool_calling default: programmatic_tool_calling x-stainless-const: true description: The type of the object. Always `programmatic_tool_calling`. enabled: type: boolean description: Whether tools can be called from model-generated code. required: - type - enabled additionalProperties: false description: Enables calling tools from model-generated code. TextFormatParam: oneOf: - $ref: '#/components/schemas/TextFormatParamText' - $ref: '#/components/schemas/TextFormatParamJsonSchema' discriminator: propertyName: type mapping: text: '#/components/schemas/TextFormatParamText' json_schema: '#/components/schemas/TextFormatParamJsonSchema' x-oai-discriminator-values: - text - json_schema description: The output format for generated text. SessionInputParamAgentSessionInputToolResult: type: object properties: type: type: string enum: - agent.session.input.tool_result default: agent.session.input.tool_result x-stainless-const: true description: The type of the object. Always `agent.session.input.tool_result`. turn_id: type: string minLength: 0 maxLength: 1048576 description: The ID of the turn that requested the function call. call_id: type: string minLength: 0 maxLength: 1048576 description: The ID of the function call. success: type: boolean description: Whether the function call succeeded. output: anyOf: - $ref: '#/components/schemas/FunctionCallOutputParam' - type: 'null' description: The function result when the call succeeded. error: type: - string - 'null' minLength: 0 maxLength: 1048576 description: The error message when the call failed. required: - type - turn_id - call_id - success additionalProperties: false description: Submits the result of a function call. ReasoningEffortResource: type: string enum: - none - minimal - low - medium - high - xhigh - max description: The amount of reasoning effort used by an agent. PersistedAgentToolResourceMcp: type: object properties: type: type: string enum: - mcp default: mcp x-stainless-const: true description: The type of the object. Always `mcp`. server_label: type: string minLength: 0 description: A label used to identify the MCP server in tool calls. credential_id: type: - string - 'null' minLength: 0 description: The vault credential selected for this MCP server, if any. transport: $ref: '#/components/schemas/PersistedMcpTransportResource' description: The credential-free transport used to connect to the MCP server. request_metadata: type: object additionalProperties: {} propertyNames: type: string minLength: 0 minProperties: 0 description: Metadata included with requests to this MCP server. allowed_tools: type: - array - 'null' items: type: string minLength: 0 minItems: 0 maxItems: 2000 description: The MCP tools the agent may call, or null when all server tools are allowed. required: type: boolean description: Whether this MCP server must initialize before the first turn. connection_origin: $ref: '#/components/schemas/McpConnectionOriginResource' description: Where outbound MCP HTTP connections originate. required: - type - server_label - credential_id - transport - request_metadata - allowed_tools - required - connection_origin additionalProperties: false description: Tools provided by a remote MCP server without stored credentials. ServiceTierResource: type: string enum: - auto - default - flex - priority - fast description: The service-tier policy configured for an agent. MultiAgentConfigCurrentParam: type: object properties: enabled: type: boolean description: Whether subagent tools are enabled. max_concurrent_subagents: type: integer format: int64 minimum: 1 maximum: 4294967295 description: Maximum number of subagents that may run concurrently. Defaults to 6. required: - enabled additionalProperties: false description: Explicit configuration for creating and coordinating subagents. EncryptedContentResource: type: object properties: type: type: string enum: - encrypted_content default: encrypted_content x-stainless-const: true description: The content type. Always `encrypted_content`. encrypted_content: type: string minLength: 0 description: The encrypted content payload. required: - type - encrypted_content additionalProperties: false description: Encrypted content exchanged between agents. AgentToolResourceFunction: type: object properties: type: type: string enum: - function default: function x-stainless-const: true description: The type of the object. Always `function`. name: type: string minLength: 0 description: The name of the function. description: type: string minLength: 0 description: A description of what the function does. parameters: type: object additionalProperties: {} propertyNames: type: string minLength: 0 minProperties: 0 description: A JSON Schema object describing the function's arguments. defer_loading: type: boolean description: Whether the function is deferred and discovered through tool search. required: - type - name - description - parameters - defer_loading additionalProperties: false description: A function defined by the application. HostedEnvironmentFileParam: oneOf: - $ref: '#/components/schemas/HostedEnvironmentFileParamFileId' - $ref: '#/components/schemas/HostedEnvironmentFileParamInline' discriminator: propertyName: type mapping: file_id: '#/components/schemas/HostedEnvironmentFileParamFileId' inline: '#/components/schemas/HostedEnvironmentFileParamInline' x-oai-discriminator-values: - file_id - inline description: A file materialized in an OpenAI-hosted execution environment. ReasoningSummaryParam: type: string enum: - concise - detailed - auto x-enumDescriptions: - Returns a concise reasoning summary when supported. - Returns a detailed reasoning summary when supported. - Automatically selects the most detailed summary supported by the model. description: The reasoning summary format requested from the model. PersistedMcpTransportResourceHttp: type: object properties: type: type: string enum: - http default: http x-stainless-const: true description: The type of the object. Always `http`. server_url: type: string minLength: 0 description: The URL of the MCP server. headers: type: object additionalProperties: type: string minLength: 0 propertyNames: type: string minLength: 0 minProperties: 0 description: Non-secret HTTP headers sent to the MCP server. required: - type - server_url - headers additionalProperties: false description: Connects to an MCP server over HTTP. ReasoningParam: type: object properties: effort: anyOf: - $ref: '#/components/schemas/ReasoningEffortParam' - type: 'null' description: The amount of reasoning effort the model should use. Omission lets the model select it. summary: anyOf: - $ref: '#/components/schemas/ReasoningSummaryParam' - type: 'null' description: Controls whether the response includes a reasoning summary. additionalProperties: false description: Reasoning configuration for the agent. OutputItemStatusResource: type: string enum: - in_progress - completed - incomplete x-enumDescriptions: - The item is in progress. - The item is complete. - The item stopped before completing. description: The status of an agent output item. FunctionCallOutputParam: oneOf: - type: string minLength: 0 maxLength: 1048576 - type: array items: $ref: '#/components/schemas/InputContentParam' minItems: 0 maxItems: 16384 description: A function result represented as text or supported model-input content. WebSearchLocationResource: type: object properties: country: type: - string - 'null' minLength: 0 description: The two-letter ISO country code, such as `US`. region: type: - string - 'null' minLength: 0 description: The region or state name. city: type: - string - 'null' minLength: 0 description: The city name. timezone: type: - string - 'null' minLength: 0 description: The IANA timezone, such as `America/Los_Angeles`. required: - country - region - city - timezone additionalProperties: false description: Approximate user location used to localize web search results. MessageContentResourceOutputText: type: object properties: type: type: string enum: - output_text default: output_text x-stainless-const: true description: The type of the object. Always `output_text`. text: type: string minLength: 0 description: The text produced by the assistant. required: - type - text additionalProperties: false description: Text produced by the assistant. ReasoningResource: type: object properties: effort: anyOf: - $ref: '#/components/schemas/ReasoningEffortResource' - type: 'null' description: The requested reasoning effort, or `null` when the model selects its own default. summary: anyOf: - $ref: '#/components/schemas/ReasoningSummaryResource' - type: 'null' description: The requested reasoning summary format, or `null` when summaries are disabled. required: - effort - summary additionalProperties: false description: The reasoning configuration used by an agent. PersistedAgentToolConfigParamToolSearch: type: object properties: type: type: string enum: - tool_search default: tool_search x-stainless-const: true description: The type of the object. Always `tool_search`. required: - type additionalProperties: false description: Discovers deferred function tools and loads them into the model context. WebSearchContextSizeResource: type: string enum: - low - medium - high description: The amount of web search context made available to the model. WebSearchActionResourceOther: type: object properties: type: type: string enum: - other default: other x-stainless-const: true description: The type of the object. Always `other`. required: - type additionalProperties: false description: Another web search action. WebSearchActionResourceOpenPage: type: object properties: type: type: string enum: - open_page default: open_page x-stainless-const: true description: The type of the object. Always `open_page`. url: type: - string - 'null' minLength: 0 description: The URL of the page that was opened. required: - type - url additionalProperties: false description: Opens a web page. EnvironmentFileListResource: type: object properties: object: $ref: '#/components/schemas/EnvironmentFilePageObjectResource' description: The object type. Always `page`. data: type: array items: $ref: '#/components/schemas/EnvironmentFileResource' minItems: 0 maxItems: 2000 description: Files available on the current page. next: type: - string - 'null' minLength: 0 description: The opaque cursor to use when requesting the next page, if any. has_more: type: boolean description: Whether more files follow this page. required: - object - data - next - has_more additionalProperties: false description: A paginated list of live execution environment files. PersistedAgentToolResourceFunction: type: object properties: type: type: string enum: - function default: function x-stainless-const: true description: The type of the object. Always `function`. name: type: string minLength: 0 description: The name of the function. description: type: string minLength: 0 description: A description of what the function does. parameters: type: object additionalProperties: {} propertyNames: type: string minLength: 0 minProperties: 0 description: A JSON Schema object describing the function's arguments. defer_loading: type: boolean description: Whether the function is deferred and discovered through tool search. required: - type - name - description - parameters - defer_loading additionalProperties: false description: A function defined by the application. CloseSubagentCallItemResource: type: object properties: type: type: string enum: - close_subagent_call default: close_subagent_call x-stainless-const: true x-enumDescriptions: - The current public item type. description: The item type. Always `close_subagent_call`. id: type: string minLength: 0 description: The ID of the tool call item. turn_id: type: string minLength: 0 description: The ID of the turn that contains this item. status: $ref: '#/components/schemas/FunctionCallStatusResource' description: The status of the tool call. sender_agent_id: type: string minLength: 0 description: The ID of the agent requesting the close. recipient_agent_id: type: string minLength: 0 description: The ID of the agent to close. required: - type - id - turn_id - status - sender_agent_id - recipient_agent_id additionalProperties: false description: A request to close a subagent. EnvironmentResource: oneOf: - $ref: '#/components/schemas/EnvironmentResourceNone' - $ref: '#/components/schemas/EnvironmentResourceOpenaiHosted' - $ref: '#/components/schemas/EnvironmentResourceSelfHosted' discriminator: propertyName: type mapping: none: '#/components/schemas/EnvironmentResourceNone' openai_hosted: '#/components/schemas/EnvironmentResourceOpenaiHosted' self_hosted: '#/components/schemas/EnvironmentResourceSelfHosted' x-oai-discriminator-values: - none - openai_hosted - self_hosted description: The execution environment for a session. DeletedEnvironmentTemplateResource: type: object properties: id: type: string minLength: 0 description: The ID of the deleted environment template. object: type: string enum: - agent.environment.template.deleted default: agent.environment.template.deleted x-stainless-const: true description: The object type. Always `agent.environment.template.deleted`. deleted: type: boolean description: Whether the environment template was deleted. Always `true`. required: - id - object - deleted additionalProperties: false description: A deleted reusable environment template. AgentMessageItemResource: type: object properties: id: type: string minLength: 0 description: The ID of the message. turn_id: type: string minLength: 0 description: The ID of the turn that contains this item. type: type: string enum: - agent_message default: agent_message x-stainless-const: true description: The item type. Always `agent_message`. sender_agent_id: type: string minLength: 0 description: The ID or name of the sending agent. recipient_agent_id: type: string minLength: 0 description: The ID or name of the receiving agent. content: type: array items: $ref: '#/components/schemas/AgentContentResource' minItems: 0 maxItems: 2000 description: The content exchanged between the agents. required: - id - turn_id - type - sender_agent_id - recipient_agent_id - content additionalProperties: false description: A message exchanged between agent threads. HostedEnvironmentFileResource: oneOf: - $ref: '#/components/schemas/HostedEnvironmentFileResourceFileId' - $ref: '#/components/schemas/HostedEnvironmentFileResourceInline' discriminator: propertyName: type mapping: file_id: '#/components/schemas/HostedEnvironmentFileResourceFileId' inline: '#/components/schemas/HostedEnvironmentFileResourceInline' x-oai-discriminator-values: - file_id - inline description: Metadata for a file materialized in an OpenAI-hosted execution environment. SessionTurnItemResource: oneOf: - $ref: '#/components/schemas/MessageItemResource' - $ref: '#/components/schemas/ReasoningItemResource' - $ref: '#/components/schemas/FunctionCallItemResource' - $ref: '#/components/schemas/FunctionCallOutputItemResource' - $ref: '#/components/schemas/AgentMessageItemResource' - $ref: '#/components/schemas/McpCallItemResource' - $ref: '#/components/schemas/WebSearchCallItemResource' - $ref: '#/components/schemas/CommandExecutionItemResource' - $ref: '#/components/schemas/CreateSubagentCallItemResource' - $ref: '#/components/schemas/SendSubagentInputCallItemResource' - $ref: '#/components/schemas/ResumeSubagentCallItemResource' - $ref: '#/components/schemas/WaitForSubagentsCallItemResource' - $ref: '#/components/schemas/InterruptSubagentCallItemResource' - $ref: '#/components/schemas/CloseSubagentCallItemResource' discriminator: propertyName: type mapping: message: '#/components/schemas/MessageItemResource' reasoning: '#/components/schemas/ReasoningItemResource' function_call: '#/components/schemas/FunctionCallItemResource' function_call_output: '#/components/schemas/FunctionCallOutputItemResource' agent_message: '#/components/schemas/AgentMessageItemResource' mcp_call: '#/components/schemas/McpCallItemResource' web_search_call: '#/components/schemas/WebSearchCallItemResource' command_execution: '#/components/schemas/CommandExecutionItemResource' interrupt_subagent_call: '#/components/schemas/InterruptSubagentCallItemResource' create_subagent_call: '#/components/schemas/CreateSubagentCallItemResource' send_subagent_input_call: '#/components/schemas/SendSubagentInputCallItemResource' resume_subagent_call: '#/components/schemas/ResumeSubagentCallItemResource' wait_for_subagents_call: '#/components/schemas/WaitForSubagentsCallItemResource' close_subagent_call: '#/components/schemas/CloseSubagentCallItemResource' x-oai-discriminator-values: - message - reasoning - function_call - function_call_output - agent_message - mcp_call - web_search_call - command_execution - create_subagent_call - send_subagent_input_call - resume_subagent_call - wait_for_subagents_call - interrupt_subagent_call - close_subagent_call description: An item associated with a session turn. PersistedMcpTransportResourceStdio: type: object properties: type: type: string enum: - stdio default: stdio x-stainless-const: true description: The type of the object. Always `stdio`. command: type: string minLength: 0 description: The command used to start the MCP server. args: type: array items: type: string minLength: 0 minItems: 0 maxItems: 2000 description: Arguments passed to the MCP server command. cwd: type: string minLength: 0 description: The working directory used to start the MCP server. env_vars: type: array items: type: string minLength: 0 minItems: 0 maxItems: 2000 description: Environment variable names inherited from the execution environment. required: - type - command - args - cwd - env_vars additionalProperties: false description: Starts an MCP server as a local process. SessionEventAgentSessionTurnCompleted: type: object properties: type: type: string enum: - agent.session.turn.completed default: agent.session.turn.completed x-stainless-const: true description: The type of the object. Always `agent.session.turn.completed`. event_id: type: string minLength: 0 description: The unique ID of the event. session_id: type: string minLength: 0 description: The ID of the session associated with the event. turn_id: type: string minLength: 0 description: The ID of the turn associated with the event. turn: $ref: '#/components/schemas/TurnResource' description: The completed turn. usage: anyOf: - $ref: '#/components/schemas/TokenUsageResource' - type: 'null' description: Token usage by the root agent during the turn, when available. required: - type - event_id - session_id - turn_id - turn - usage additionalProperties: false description: Emitted when a turn completes. SetupCommandParam: type: object properties: command: type: string minLength: 0 maxLength: 65536 description: The shell command to execute. cwd: type: - string - 'null' minLength: 0 maxLength: 4096 description: The absolute working directory. Defaults to `/workspace`. required: - command additionalProperties: false description: A confidential setup command executed before the hosted agent starts. securitySchemes: ApiKeyAuth: type: http scheme: bearer AdminApiKeyAuth: type: http scheme: bearer x-oaiMeta: navigationGroups: - id: responses title: Responses API - id: webhooks title: Webhooks - id: endpoints title: Platform APIs - id: vector_stores title: Vector stores - id: chatkit title: ChatKit beta: true - id: containers title: Containers - id: live title: Live (alpha) - id: realtime title: Realtime - id: chat title: Chat Completions - id: assistants title: Assistants deprecated: true - id: administration title: Administration - id: legacy title: Legacy groups: - id: responses-streaming title: Streaming events description: 'When you [create a Response](https://developers.openai.com/api/reference/resources/responses/methods/create) with `stream` set to `true`, the server will emit server-sent events to the client as the Response is generated. This section contains the events that are emitted by the server. When processing a `compaction_trigger`, `response.compaction.compacting` reports newly sampled summary output at most once every 30 seconds. It carries no summary content and does not modify the compaction output item. The existing `response.output_item.added` and `response.output_item.done` events mark that item''s lifecycle; `response.output_item.done` carries its final encrypted content. A short compaction may finish without emitting a progress event. [Learn more about streaming responses](https://developers.openai.com/api/docs/guides/streaming-responses). ' navigationGroup: responses sections: - type: object key: ResponseCreatedEvent path: - type: object key: ResponseInProgressEvent path: - type: object key: ResponseCompletedEvent path: - type: object key: ResponseFailedEvent path: - type: object key: ResponseIncompleteEvent path: - type: object key: ResponseOutputItemAddedEvent path: - type: object key: ResponseOutputItemDoneEvent path: - type: object key: ResponseCompactionCompactingEvent path: - type: object key: ResponseContentPartAddedEvent path: - type: object key: ResponseContentPartDoneEvent path: - type: object key: ResponseTextDeltaEvent path: response/output_text/delta - type: object key: ResponseTextDoneEvent path: response/output_text/done - type: object key: ResponseRefusalDeltaEvent path: - type: object key: ResponseRefusalDoneEvent path: - type: object key: ResponseFunctionCallArgumentsDeltaEvent path: - type: object key: ResponseFunctionCallArgumentsDoneEvent path: - type: object key: ResponseFileSearchCallInProgressEvent path: - type: object key: ResponseFileSearchCallSearchingEvent path: - type: object key: ResponseFileSearchCallCompletedEvent path: - type: object key: ResponseWebSearchCallInProgressEvent path: - type: object key: ResponseWebSearchCallSearchingEvent path: - type: object key: ResponseWebSearchCallCompletedEvent path: - type: object key: ResponseReasoningSummaryPartAddedEvent path: - type: object key: ResponseReasoningSummaryPartDoneEvent path: - type: object key: ResponseReasoningSummaryTextDeltaEvent path: - type: object key: ResponseReasoningSummaryTextDoneEvent path: - type: object key: ResponseReasoningTextDeltaEvent path: - type: object key: ResponseReasoningTextDoneEvent path: - type: object key: ResponseImageGenCallCompletedEvent path: - type: object key: ResponseImageGenCallGeneratingEvent path: - type: object key: ResponseImageGenCallInProgressEvent path: - type: object key: ResponseImageGenCallPartialImageEvent path: - type: object key: ResponseMCPCallArgumentsDeltaEvent path: - type: object key: ResponseMCPCallArgumentsDoneEvent path: - type: object key: ResponseMCPCallCompletedEvent path: - type: object key: ResponseMCPCallFailedEvent path: - type: object key: ResponseMCPCallInProgressEvent path: - type: object key: ResponseMCPListToolsCompletedEvent path: - type: object key: ResponseMCPListToolsFailedEvent path: - type: object key: ResponseMCPListToolsInProgressEvent path: - type: object key: ResponseCodeInterpreterCallInProgressEvent path: - type: object key: ResponseCodeInterpreterCallInterpretingEvent path: - type: object key: ResponseCodeInterpreterCallCompletedEvent path: - type: object key: ResponseCodeInterpreterCallCodeDeltaEvent path: - type: object key: ResponseCodeInterpreterCallCodeDoneEvent path: - type: object key: ResponseOutputTextAnnotationAddedEvent path: - type: object key: ResponseQueuedEvent path: - type: object key: ResponseCustomToolCallInputDeltaEvent path: - type: object key: ResponseCustomToolCallInputDoneEvent path: - type: object key: ResponseErrorEvent path: - id: responses-websocket-client-events title: Client events description: 'Events sent by the client over a Responses API WebSocket connection. ' navigationGroup: responses sections: - type: object key: ResponsesClientEventResponseCreate path: - type: object key: ResponseSteerEvent path: - id: responses-websocket-server-events title: Server events (WebSocket only) description: 'Events emitted only over a Responses API WebSocket connection. ' navigationGroup: responses sections: - type: object key: ResponseSteerAcceptedEvent path: - type: object key: ResponseSteerPendingEvent path: - type: object key: ResponseSteerFailedEvent path: - id: responses-websocket-shared-events title: Server events description: 'These events use the same payloads over WebSocket and [HTTP streaming](https://developers.openai.com/api/reference/resources/responses/streaming-events). Compaction progress follows the same cadence and output-item lifecycle described in HTTP streaming. ' navigationGroup: responses sections: - type: object key: ResponseCreatedEvent path: - type: object key: ResponseInProgressEvent path: - type: object key: ResponseCompletedEvent path: - type: object key: ResponseFailedEvent path: - type: object key: ResponseIncompleteEvent path: - type: object key: ResponseOutputItemAddedEvent path: - type: object key: ResponseOutputItemDoneEvent path: - type: object key: ResponseCompactionCompactingEvent path: - type: object key: ResponseContentPartAddedEvent path: - type: object key: ResponseContentPartDoneEvent path: - type: object key: ResponseTextDeltaEvent path: response/output_text/delta - type: object key: ResponseTextDoneEvent path: response/output_text/done - type: object key: ResponseRefusalDeltaEvent path: - type: object key: ResponseRefusalDoneEvent path: - type: object key: ResponseFunctionCallArgumentsDeltaEvent path: - type: object key: ResponseFunctionCallArgumentsDoneEvent path: - type: object key: ResponseFileSearchCallInProgressEvent path: - type: object key: ResponseFileSearchCallSearchingEvent path: - type: object key: ResponseFileSearchCallCompletedEvent path: - type: object key: ResponseWebSearchCallInProgressEvent path: - type: object key: ResponseWebSearchCallSearchingEvent path: - type: object key: ResponseWebSearchCallCompletedEvent path: - type: object key: ResponseReasoningSummaryPartAddedEvent path: - type: object key: ResponseReasoningSummaryPartDoneEvent path: - type: object key: ResponseReasoningSummaryTextDeltaEvent path: - type: object key: ResponseReasoningSummaryTextDoneEvent path: - type: object key: ResponseReasoningTextDeltaEvent path: - type: object key: ResponseReasoningTextDoneEvent path: - type: object key: ResponseImageGenCallCompletedEvent path: - type: object key: ResponseImageGenCallGeneratingEvent path: - type: object key: ResponseImageGenCallInProgressEvent path: - type: object key: ResponseImageGenCallPartialImageEvent path: - type: object key: ResponseMCPCallArgumentsDeltaEvent path: - type: object key: ResponseMCPCallArgumentsDoneEvent path: - type: object key: ResponseMCPCallCompletedEvent path: - type: object key: ResponseMCPCallFailedEvent path: - type: object key: ResponseMCPCallInProgressEvent path: - type: object key: ResponseMCPListToolsCompletedEvent path: - type: object key: ResponseMCPListToolsFailedEvent path: - type: object key: ResponseMCPListToolsInProgressEvent path: - type: object key: ResponseCodeInterpreterCallInProgressEvent path: - type: object key: ResponseCodeInterpreterCallInterpretingEvent path: - type: object key: ResponseCodeInterpreterCallCompletedEvent path: - type: object key: ResponseCodeInterpreterCallCodeDeltaEvent path: - type: object key: ResponseCodeInterpreterCallCodeDoneEvent path: - type: object key: ResponseOutputTextAnnotationAddedEvent path: - type: object key: ResponseQueuedEvent path: - type: object key: ResponseCustomToolCallInputDeltaEvent path: - type: object key: ResponseCustomToolCallInputDoneEvent path: - type: object key: ResponseErrorEvent path: - id: safety-cases title: Safety Cases description: 'Retrieve details about a safety warning or deactivation using the case ID from a `safety.warning_issued` or `safety.deactivation_issued` webhook event. Cases belong to an organization and require an API key with `api.safety.read`. ' navigationGroup: endpoints sections: - type: endpoint key: Getsafetycase path: retrieve - type: object key: SafetyCaseResource path: object - id: safety-alerts title: Safety Alerts description: 'Retrieve approved safety alerts with an API key. Project keys require `api.safety.alerts.read` and can read alerts from their project. ' navigationGroup: endpoints sections: - type: endpoint key: Getprojectsafetyalert path: retrieve - type: object key: SafetyAlertResource path: object - id: webhook-events title: Webhook Events description: 'Webhooks are HTTP requests sent by OpenAI to a URL you specify when certain events happen during the course of API usage. [Learn more about webhooks](https://developers.openai.com/api/docs/guides/webhooks). ' navigationGroup: webhooks sections: - type: object key: WebhookResponseCompleted path: - type: object key: WebhookResponseCancelled path: - type: object key: WebhookResponseFailed path: - type: object key: WebhookResponseIncomplete path: - type: object key: WebhookBatchCompleted path: - type: object key: WebhookBatchCancelled path: - type: object key: WebhookBatchExpired path: - type: object key: WebhookBatchFailed path: - type: object key: WebhookFineTuningJobSucceeded path: - type: object key: WebhookFineTuningJobFailed path: - type: object key: WebhookFineTuningJobCancelled path: - type: object key: WebhookEvalRunSucceeded path: - type: object key: WebhookEvalRunFailed path: - type: object key: WebhookEvalRunCanceled path: - type: object key: WebhookRealtimeCallIncoming path: - type: object key: WebhookLiveCallIncoming path: - type: object key: WebhookLiveTransportIncoming path: - type: object key: WebhookSafetyWarningIssued path: - type: object key: WebhookSafetyDeactivationIssued path: - type: object key: WebhookSafetyAlertCreated path: - type: object key: WebhookSafetyOrgAlertCreated path: - id: images-streaming title: Image Streaming description: 'Stream image generation and editing in real time with server-sent events. [Learn more about image streaming](https://developers.openai.com/api/docs/guides/image-generation). ' navigationGroup: endpoints sections: - type: object key: ImageGenPartialImageEvent path: - type: object key: ImageGenCompletedEvent path: - type: object key: ImageEditPartialImageEvent path: - type: object key: ImageEditCompletedEvent path: - id: realtime-client-events title: Client events description: 'These are events that the OpenAI Realtime WebSocket server will accept from the client. ' navigationGroup: realtime sections: - type: object key: RealtimeClientEventSessionUpdate path: - type: object key: RealtimeClientEventInputAudioBufferAppend path: - type: object key: RealtimeClientEventInputAudioBufferCommit path: - type: object key: RealtimeClientEventInputAudioBufferClear path: - type: object key: RealtimeClientEventConversationItemCreate path: - type: object key: RealtimeClientEventConversationItemRetrieve path: - type: object key: RealtimeClientEventConversationItemTruncate path: - type: object key: RealtimeClientEventConversationItemDelete path: - type: object key: RealtimeClientEventResponseCreate path: - type: object key: RealtimeClientEventResponseCancel path: - type: object key: RealtimeClientEventOutputAudioBufferClear path: - id: realtime-server-events title: Server events description: 'These are events emitted from the OpenAI Realtime WebSocket server to the client. ' navigationGroup: realtime sections: - type: object key: RealtimeServerEventError path: - type: object key: RealtimeServerEventSessionCreated path: - type: object key: RealtimeServerEventSessionUpdated path: - type: object key: RealtimeServerEventConversationItemAdded path: - type: object key: RealtimeServerEventConversationItemDone path: - type: object key: RealtimeServerEventConversationItemRetrieved path: - type: object key: RealtimeServerEventConversationItemInputAudioTranscriptionCompleted path: - type: object key: RealtimeServerEventConversationItemInputAudioTranscriptionDelta path: - type: object key: RealtimeServerEventConversationItemInputAudioTranscriptionSegment path: - type: object key: RealtimeServerEventConversationItemInputAudioTranscriptionFailed path: - type: object key: RealtimeServerEventConversationItemTruncated path: - type: object key: RealtimeServerEventConversationItemDeleted path: - type: object key: RealtimeServerEventInputAudioBufferCommitted path: - type: object key: RealtimeServerEventInputAudioBufferDtmfEventReceived path: - type: object key: RealtimeServerEventInputAudioBufferCleared path: - type: object key: RealtimeServerEventInputAudioBufferSpeechStarted path: - type: object key: RealtimeServerEventInputAudioBufferSpeechStopped path: - type: object key: RealtimeServerEventInputAudioBufferTimeoutTriggered path: - type: object key: RealtimeServerEventOutputAudioBufferStarted path: - type: object key: RealtimeServerEventOutputAudioBufferStopped path: - type: object key: RealtimeServerEventOutputAudioBufferCleared path: - type: object key: RealtimeServerEventResponseCreated path: - type: object key: RealtimeServerEventResponseDone path: - type: object key: RealtimeServerEventResponseOutputItemAdded path: - type: object key: RealtimeServerEventResponseOutputItemDone path: - type: object key: RealtimeServerEventResponseContentPartAdded path: - type: object key: RealtimeServerEventResponseContentPartDone path: - type: object key: RealtimeServerEventResponseTextDelta path: - type: object key: RealtimeServerEventResponseTextDone path: - type: object key: RealtimeServerEventResponseAudioTranscriptDelta path: - type: object key: RealtimeServerEventResponseAudioTranscriptDone path: - type: object key: RealtimeServerEventResponseAudioDelta path: - type: object key: RealtimeServerEventResponseAudioDone path: - type: object key: RealtimeServerEventResponseFunctionCallArgumentsDelta path: - type: object key: RealtimeServerEventResponseFunctionCallArgumentsDone path: - type: object key: RealtimeServerEventResponseMCPCallArgumentsDelta path: - type: object key: RealtimeServerEventResponseMCPCallArgumentsDone path: - type: object key: RealtimeServerEventResponseMCPCallInProgress path: - type: object key: RealtimeServerEventResponseMCPCallCompleted path: - type: object key: RealtimeServerEventResponseMCPCallFailed path: - type: object key: RealtimeServerEventMCPListToolsInProgress path: - type: object key: RealtimeServerEventMCPListToolsCompleted path: - type: object key: RealtimeServerEventMCPListToolsFailed path: - type: object key: RealtimeServerEventRateLimitsUpdated path: - id: realtime-translation-client-events title: Translation client events description: 'These are events that the OpenAI Realtime Translation WebSocket server will accept from the client. ' navigationGroup: realtime sections: - type: object key: RealtimeTranslationClientEventSessionUpdate path: - type: object key: RealtimeTranslationClientEventInputAudioBufferAppend path: - type: object key: RealtimeTranslationClientEventSessionClose path: - id: realtime-translation-server-events title: Translation server events description: 'These are events emitted from the OpenAI Realtime Translation WebSocket server to the client. ' navigationGroup: realtime sections: - type: object key: RealtimeServerEventError path: - type: object key: RealtimeTranslationServerEventSessionCreated path: - type: object key: RealtimeTranslationServerEventSessionUpdated path: - type: object key: RealtimeTranslationServerEventSessionClosed path: - type: object key: RealtimeTranslationServerEventSessionInputTranscriptDelta path: - type: object key: RealtimeTranslationServerEventSessionOutputTranscriptDelta path: - type: object key: RealtimeTranslationServerEventSessionOutputAudioDelta path: - id: chat-streaming title: Streaming description: 'Stream Chat Completions in real time. Receive chunks of completions returned from the model using server-sent events. [Learn more](https://developers.openai.com/api/docs/guides/streaming-responses). ' navigationGroup: chat sections: - type: object key: CreateChatCompletionStreamResponse path: streaming - id: assistants-streaming title: Streaming beta: true description: 'Stream the result of executing a Run or resuming a Run after submitting tool outputs. You can stream events from the [Create Thread and Run](https://developers.openai.com/api/docs/assistants/migration), [Create Run](https://developers.openai.com/api/docs/assistants/migration), and [Submit Tool Outputs](https://developers.openai.com/api/docs/assistants/migration) endpoints by passing `"stream": true`. The response will be a [Server-Sent events](https://html.spec.whatwg.org/multipage/server-sent-events.html#server-sent-events) stream. Our Node and Python SDKs provide helpful utilities to make streaming easy. Reference the [Assistants API quickstart](https://developers.openai.com/api/docs/assistants/migration) to learn more. ' navigationGroup: assistants sections: - type: object key: AssistantStreamEvent path: events - id: realtime-beta-client-events title: Realtime Beta client events description: 'These are events that the OpenAI Realtime WebSocket server will accept from the client. ' navigationGroup: legacy sections: - type: object key: RealtimeBetaClientEventSessionUpdate path: - type: object key: RealtimeBetaClientEventInputAudioBufferAppend path: - type: object key: RealtimeBetaClientEventInputAudioBufferCommit path: - type: object key: RealtimeBetaClientEventInputAudioBufferClear path: - type: object key: RealtimeBetaClientEventConversationItemCreate path: - type: object key: RealtimeBetaClientEventConversationItemRetrieve path: - type: object key: RealtimeBetaClientEventConversationItemTruncate path: - type: object key: RealtimeBetaClientEventConversationItemDelete path: - type: object key: RealtimeBetaClientEventResponseCreate path: - type: object key: RealtimeBetaClientEventResponseCancel path: - type: object key: RealtimeBetaClientEventTranscriptionSessionUpdate path: - type: object key: RealtimeBetaClientEventOutputAudioBufferClear path: - id: realtime-beta-server-events title: Realtime Beta server events description: 'These are events emitted from the OpenAI Realtime WebSocket server to the client. ' navigationGroup: legacy sections: - type: object key: RealtimeBetaServerEventError path: - type: object key: RealtimeBetaServerEventSessionCreated path: - type: object key: RealtimeBetaServerEventSessionUpdated path: - type: object key: RealtimeBetaServerEventTranscriptionSessionCreated path: - type: object key: RealtimeBetaServerEventTranscriptionSessionUpdated path: - type: object key: RealtimeBetaServerEventConversationItemCreated path: - type: object key: RealtimeBetaServerEventConversationItemRetrieved path: - type: object key: RealtimeBetaServerEventConversationItemInputAudioTranscriptionCompleted path: - type: object key: RealtimeBetaServerEventConversationItemInputAudioTranscriptionDelta path: - type: object key: RealtimeBetaServerEventConversationItemInputAudioTranscriptionSegment path: - type: object key: RealtimeBetaServerEventConversationItemInputAudioTranscriptionFailed path: - type: object key: RealtimeBetaServerEventConversationItemTruncated path: - type: object key: RealtimeBetaServerEventConversationItemDeleted path: - type: object key: RealtimeBetaServerEventInputAudioBufferCommitted path: - type: object key: RealtimeBetaServerEventInputAudioBufferCleared path: - type: object key: RealtimeBetaServerEventInputAudioBufferSpeechStarted path: - type: object key: RealtimeBetaServerEventInputAudioBufferSpeechStopped path: - type: object key: RealtimeServerEventInputAudioBufferTimeoutTriggered path: - type: object key: RealtimeBetaServerEventResponseCreated path: - type: object key: RealtimeBetaServerEventResponseDone path: - type: object key: RealtimeBetaServerEventResponseOutputItemAdded path: - type: object key: RealtimeBetaServerEventResponseOutputItemDone path: - type: object key: RealtimeBetaServerEventResponseContentPartAdded path: - type: object key: RealtimeBetaServerEventResponseContentPartDone path: - type: object key: RealtimeBetaServerEventResponseTextDelta path: - type: object key: RealtimeBetaServerEventResponseTextDone path: - type: object key: RealtimeBetaServerEventResponseAudioTranscriptDelta path: - type: object key: RealtimeBetaServerEventResponseAudioTranscriptDone path: - type: object key: RealtimeBetaServerEventResponseAudioDelta path: - type: object key: RealtimeBetaServerEventResponseAudioDone path: - type: object key: RealtimeBetaServerEventResponseFunctionCallArgumentsDelta path: - type: object key: RealtimeBetaServerEventResponseFunctionCallArgumentsDone path: - type: object key: RealtimeBetaServerEventResponseMCPCallArgumentsDelta path: - type: object key: RealtimeBetaServerEventResponseMCPCallArgumentsDone path: - type: object key: RealtimeBetaServerEventResponseMCPCallInProgress path: - type: object key: RealtimeBetaServerEventResponseMCPCallCompleted path: - type: object key: RealtimeBetaServerEventResponseMCPCallFailed path: - type: object key: RealtimeBetaServerEventMCPListToolsInProgress path: - type: object key: RealtimeBetaServerEventMCPListToolsCompleted path: - type: object key: RealtimeBetaServerEventMCPListToolsFailed path: - type: object key: RealtimeBetaServerEventRateLimitsUpdated path: - id: live-client-events title: Client events description: Initialize a primary WebSocket with session.start and wait for session.started before sending other events. WebRTC creation starts the session for you. Start with the [Live prompting guide](https://developers.openai.com/api/docs/guides/live-prompting) to design frontend instructions and delegation policy; see [backend prompting](https://developers.openai.com/api/docs/guides/live-delegation#start-with-your-existing-backend-prompt) for tools and business rules. navigationGroup: live sections: - type: object key: LiveSessionStartEvent path: - type: object key: LiveForkSessionStartEvent path: - type: object key: LiveSessionUpdateParam path: - type: object key: LiveInputAudioAppendEvent path: - type: object key: LiveInputAudioMuteParam path: - type: object key: LiveInputAudioUnmuteParam path: - type: object key: LiveInstructionsAppendParam path: - type: object key: LiveThinkingAppendParam path: - type: object key: LiveCommentaryAppendParam path: - type: object key: LiveResponseItemCreateParam path: - type: object key: LiveResponseCreateParam path: - type: object key: LiveSessionCloseParam path: - id: live-server-events title: Server events description: Live server events. Responses delegation lifecycle events arrive inside response.event, not as top-level response events. Start with the [Live prompting guide](https://developers.openai.com/api/docs/guides/live-prompting) to design frontend instructions and delegation policy; see [backend prompting](https://developers.openai.com/api/docs/guides/live-delegation#start-with-your-existing-backend-prompt) for tools and business rules. navigationGroup: live sections: - type: object key: LiveSessionStarted path: - type: object key: LiveSessionUpdated path: - type: object key: LiveInputAudioMuted path: - type: object key: LiveInputAudioUnmuted path: - type: object key: LiveInstructionsAppended path: - type: object key: LiveThinkingAppended path: - type: object key: LiveCommentaryAppended path: - type: object key: LiveOutputAudioDelta path: - type: object key: LiveInputTranscriptDelta path: - type: object key: LiveOutputTranscriptDelta path: - type: object key: LiveDelegationCreated path: - type: object key: LiveResponseEvent path: - type: object key: LiveSessionUsageUpdated path: - type: object key: LiveSessionClosed path: - type: object key: LiveErrorEvent path: - type: object key: LiveInfoEvent path: