diff --git a/.castiron.stats.yml b/.castiron.stats.yml index 696dc87..52fc229 100644 --- a/.castiron.stats.yml +++ b/.castiron.stats.yml @@ -1,8 +1,8 @@ schema_version: 1 -generation_id: 3febc428-f82e-4bfa-a3a2-be64927f1e59 -openapi_spec_hash: 06abf78143cc2d777012de4b4bada359 -openapi_transformed_spec_hash: fb78e9baa61748309d4571899a7e3455 -config_hash: e5cd2ea20dc089f47efc81a424eea9bd -codegen_sha: 4b2cf190871d6ed4ac225b5c059ae4ad84d0c8d5 -codegen_hash: dd4e3a7cc6b4311ba6a88d7bfd9ce9f1a34fd23345b2406f243d3756444aa146 -public_codegen_sha: e2629f8ccb85c11b93a1dc5f2688b25d013d4580 +generation_id: 28d9d984-4c2b-424b-98ef-82df6ae038d2 +openapi_spec_hash: 662efe7cf7d92cb2a9e77bef4bfbe722 +openapi_transformed_spec_hash: dcc14f90c5a5568ce21ec02960b21c56 +config_hash: d2fcc283b95b7414c5336bf361e3abc3 +codegen_sha: 8972a3195525ee3a201e801e9a27229938b1787f +codegen_hash: 8a87c1bee991b56b246c24cc7f9ed810d7436bbab0e502821ac67ec20f412f47 +public_codegen_sha: 8850a9ce3d29e36b60d4c571640fd1c89c004f81 diff --git a/api_reference/openapi.transformed.yml b/api_reference/openapi.transformed.yml index ba43beb..6f8b01b 100644 --- a/api_reference/openapi.transformed.yml +++ b/api_reference/openapi.transformed.yml @@ -602,8 +602,37 @@ paths: text/event-stream: schema: $ref: '#/components/schemas/CreateSpeechResponseStreamEvent' + '400': + description: Invalid speech request, input, output format, or voice. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '401': + description: Authentication failed because the API key is missing or revoked, or the client IP is not authorized. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + text/plain: + schema: + type: string + description: JSON-encoded error text containing an error object and the HTTP status. + '403': + description: Access to a personal API organization is blocked by the organization policy. + content: + text/plain: + schema: + type: string + description: JSON-encoded error text containing an error object and the HTTP status. '429': $ref: '#/components/responses/InferenceRateLimited' + '500': + description: The voice or speech audio could not be processed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '503': $ref: '#/components/responses/InferenceServiceUnavailable' x-oaiMeta: @@ -716,8 +745,49 @@ paths: text/event-stream: schema: $ref: '#/components/schemas/CreateTranscriptionResponseStreamEvent' + '400': + description: Invalid audio input or request parameters. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '401': + description: Authentication failed because the API key is missing or revoked, or the client IP is not authorized. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + text/plain: + schema: + type: string + description: JSON-encoded error text containing an error object and the HTTP status. + '403': + description: Access to a personal API organization is blocked by the organization policy. + content: + text/plain: + schema: + type: string + description: JSON-encoded error text containing an error object and the HTTP status. + '413': + description: The audio request exceeds the supported size limit. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/InferenceRateLimited' + '500': + description: The audio could not be processed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '502': + description: The upstream audio service connection failed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '503': $ref: '#/components/responses/InferenceServiceUnavailable' x-oaiMeta: @@ -1269,8 +1339,49 @@ paths: - $ref: '#/components/schemas/CreateTranslationResponseVerboseJson' x-stainless-skip: - go + '400': + description: Invalid audio input or request parameters. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '401': + description: Authentication failed because the API key is missing or revoked, or the client IP is not authorized. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + text/plain: + schema: + type: string + description: JSON-encoded error text containing an error object and the HTTP status. + '403': + description: Access to a personal API organization is blocked by the organization policy. + content: + text/plain: + schema: + type: string + description: JSON-encoded error text containing an error object and the HTTP status. + '413': + description: The audio request exceeds the supported size limit. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/InferenceRateLimited' + '500': + description: The audio could not be processed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '502': + description: The upstream audio service connection failed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '503': $ref: '#/components/responses/InferenceServiceUnavailable' x-oaiMeta: @@ -1346,6 +1457,18 @@ paths: application/json: schema: $ref: '#/components/schemas/VoiceConsentResource' + '400': + description: Invalid consent recording or consent phrase. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The endpoint is unavailable to this caller. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: audio examples: @@ -1386,6 +1509,18 @@ paths: application/json: schema: $ref: '#/components/schemas/VoiceConsentListResource' + '400': + description: Invalid pagination parameters. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The endpoint is unavailable or the pagination cursor was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: audio examples: @@ -1414,6 +1549,18 @@ paths: application/json: schema: $ref: '#/components/schemas/VoiceConsentResource' + '400': + description: Invalid consent recording ID. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The endpoint is unavailable or the consent recording was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: audio examples: @@ -1447,6 +1594,18 @@ paths: application/json: schema: $ref: '#/components/schemas/VoiceConsentResource' + '400': + description: Invalid consent recording ID or update. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The endpoint is unavailable or the consent recording was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: audio examples: @@ -1479,6 +1638,18 @@ paths: application/json: schema: $ref: '#/components/schemas/VoiceConsentDeletedResource' + '400': + description: Invalid consent recording ID. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The endpoint is unavailable or the consent recording was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: audio examples: @@ -1507,6 +1678,24 @@ paths: application/json: schema: $ref: '#/components/schemas/VoiceResource' + '400': + description: Invalid voice request, consent recording, or audio sample. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The endpoint is unavailable or the consent recording was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '500': + description: The audio sample could not be processed or the voice could not be created. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: audio examples: @@ -1538,6 +1727,30 @@ paths: application/json: schema: $ref: '#/components/schemas/Batch' + '400': + description: The request is invalid or the account cannot create a batch. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: The request was rejected because a rate limit was exceeded. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '500': + description: An internal error prevented the batch from being created. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '503': + description: The batch could not be created because the service is temporarily unavailable. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: batch examples: @@ -1635,6 +1848,24 @@ paths: application/json: schema: $ref: '#/components/schemas/ListBatchesResponse' + '400': + description: Invalid pagination parameters. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: No batch was found with the specified pagination cursor. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: The request was rejected because a rate limit was exceeded. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: batch examples: @@ -1722,6 +1953,24 @@ paths: application/json: schema: $ref: '#/components/schemas/Batch' + '400': + description: Invalid batch ID. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: No batch was found with the specified ID. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: The request was rejected because a rate limit was exceeded. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: batch examples: @@ -1798,6 +2047,30 @@ paths: application/json: schema: $ref: '#/components/schemas/Batch' + '400': + description: Invalid batch ID. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: No batch was found with the specified ID. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '409': + description: The batch's current status does not allow cancellation. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: The request was rejected because a rate limit was exceeded. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: batch examples: @@ -1909,6 +2182,20 @@ paths: application/json: schema: $ref: '#/components/schemas/ChatCompletionList' + '400': + description: Invalid pagination or filter parameters. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + $ref: '#/components/responses/TooManyRequests' + '500': + description: An internal error prevented the request from being completed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: chat path: list @@ -2010,8 +2297,43 @@ paths: text/event-stream: schema: $ref: '#/components/schemas/CreateChatCompletionStreamResponse' + '400': + description: Invalid chat completion request or incompatible request parameters. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '401': + description: Authentication failed because the API key is missing or revoked, or the client IP is not authorized. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + text/plain: + schema: + type: string + description: JSON-encoded error text containing an error object and the HTTP status. + '403': + description: Access to a personal API organization is blocked by the organization policy. + content: + text/plain: + schema: + type: string + description: JSON-encoded error text containing an error object and the HTTP status. + '404': + description: The requested model or a referenced resource was not found or is unavailable to this caller. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/InferenceRateLimited' + '500': + description: The chat completion could not be processed due to an internal error. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '503': $ref: '#/components/responses/InferenceServiceUnavailable' x-oaiMeta: @@ -2838,6 +3160,20 @@ paths: application/json: schema: $ref: '#/components/schemas/CreateChatCompletionResponse' + '404': + description: No stored chat completion was found with the specified ID. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + $ref: '#/components/responses/TooManyRequests' + '500': + description: An internal error prevented the request from being completed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: chat examples: @@ -2926,6 +3262,26 @@ paths: application/json: schema: $ref: '#/components/schemas/CreateChatCompletionResponse' + '400': + description: Invalid metadata update. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: No stored chat completion was found with the specified ID. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + $ref: '#/components/responses/TooManyRequests' + '500': + description: An internal error prevented the request from being completed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: chat examples: @@ -3005,6 +3361,20 @@ paths: application/json: schema: $ref: '#/components/schemas/ChatCompletionDeleted' + '404': + description: No stored chat completion was found with the specified ID. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + $ref: '#/components/responses/TooManyRequests' + '500': + description: An internal error prevented the request from being completed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: chat examples: @@ -3074,6 +3444,26 @@ paths: application/json: schema: $ref: '#/components/schemas/ChatCompletionMessageList' + '400': + description: Invalid message pagination parameters. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: No stored chat completion was found with the specified ID. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + $ref: '#/components/responses/TooManyRequests' + '500': + description: An internal error prevented the request from being completed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: chat examples: @@ -3130,8 +3520,43 @@ paths: application/json: schema: $ref: '#/components/schemas/CreateCompletionResponse' + '400': + description: Invalid completion request or incompatible request parameters. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '401': + description: Authentication failed because the API key is missing or revoked, or the client IP is not authorized. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + text/plain: + schema: + type: string + description: JSON-encoded error text containing an error object and the HTTP status. + '403': + description: Access to a personal API organization is blocked by the organization policy. + content: + text/plain: + schema: + type: string + description: JSON-encoded error text containing an error object and the HTTP status. + '404': + description: The requested model was not found, is unavailable, or does not support this endpoint. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/InferenceRateLimited' + '500': + description: The completion could not be processed due to an internal error. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '503': $ref: '#/components/responses/InferenceServiceUnavailable' x-oaiMeta: @@ -3298,6 +3723,12 @@ paths: application/json: schema: $ref: '#/components/schemas/ContainerListResource' + '404': + description: The container specified by `after` was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -3347,6 +3778,12 @@ paths: application/json: schema: $ref: '#/components/schemas/ContainerResource' + '400': + description: The container configuration or supplied skill is invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -3413,6 +3850,12 @@ paths: application/json: schema: $ref: '#/components/schemas/ContainerResource' + '404': + description: The container was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -3451,6 +3894,12 @@ paths: responses: '200': description: OK + '404': + description: The container was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -3497,6 +3946,18 @@ paths: application/json: schema: $ref: '#/components/schemas/ContainerFileResource' + '400': + description: The file input is invalid, or the container file limit would be exceeded. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The container was not found or has expired. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -3559,6 +4020,12 @@ paths: application/json: schema: $ref: '#/components/schemas/ContainerFileListResource' + '404': + description: The container was not found or has expired, or the file specified by `after` was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -3610,6 +4077,12 @@ paths: application/json: schema: $ref: '#/components/schemas/ContainerFileResource' + '404': + description: The container was not found or has expired, or the file was not found in the container. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -3648,6 +4121,12 @@ paths: responses: '200': description: OK + '404': + description: The container was not found or has expired, or the file was not found in the container. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -3683,6 +4162,12 @@ paths: responses: '200': description: Success + '404': + description: The container was not found or has expired, or the file was not found in the container. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -3742,8 +4227,26 @@ paths: application/json: schema: $ref: '#/components/schemas/ConversationItemList' + '400': + description: The items are invalid, are already in the conversation, or the conversation is locked. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The conversation was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' + '500': + description: The conversation update could not be finalized. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: conversations path: create-item @@ -3938,6 +4441,18 @@ paths: application/json: schema: $ref: '#/components/schemas/ConversationItemList' + '400': + description: The stored encrypted item content could not be validated. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The conversation or the item specified by `after` was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -4030,6 +4545,12 @@ paths: application/json: schema: $ref: '#/components/schemas/ConversationItem' + '404': + description: The conversation or the item in that conversation was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -4106,8 +4627,26 @@ paths: application/json: schema: $ref: '#/components/schemas/ConversationResource' + '400': + description: The item cannot be removed while the conversation is locked. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The conversation or the item in that conversation was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' + '500': + description: The conversation update could not be finalized. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: conversations path: delete-item @@ -4171,8 +4710,37 @@ paths: application/json: schema: $ref: '#/components/schemas/CreateEmbeddingResponse' + '400': + description: Invalid embedding input or request parameters. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '401': + description: Authentication failed because the API key is missing or revoked, or the client IP is not authorized. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + text/plain: + schema: + type: string + description: JSON-encoded error text containing an error object and the HTTP status. + '403': + description: Access to a personal API organization is blocked by the organization policy. + content: + text/plain: + schema: + type: string + description: JSON-encoded error text containing an error object and the HTTP status. '429': $ref: '#/components/responses/InferenceRateLimited' + '500': + description: The embedding request could not be processed due to an internal error. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '503': $ref: '#/components/responses/InferenceServiceUnavailable' x-oaiMeta: @@ -4421,6 +4989,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Eval' + '400': + description: The evaluation input or grader configuration is invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -4602,6 +5176,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Eval' + '404': + description: The evaluation was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -4704,6 +5284,18 @@ paths: application/json: schema: $ref: '#/components/schemas/Eval' + '400': + description: The evaluation name or metadata is invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The evaluation was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -4818,12 +5410,18 @@ paths: - object - deleted - eval_id + '400': + description: The evaluation cannot be deleted while it has unfinished runs. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '404': description: Evaluation not found. content: application/json: schema: - $ref: '#/components/schemas/Error' + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -4910,6 +5508,18 @@ paths: application/json: schema: $ref: '#/components/schemas/EvalRunList' + '400': + description: The run list parameters are invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The evaluation or the run specified by `after` was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -5046,9 +5656,21 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/Error' + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The evaluation or a referenced resource was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' + '500': + description: The evaluation run could not be created. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: evals examples: @@ -5230,6 +5852,18 @@ paths: application/json: schema: $ref: '#/components/schemas/EvalRun' + '400': + description: The evaluation run does not belong to the specified evaluation. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The evaluation or evaluation run was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -5643,12 +6277,18 @@ paths: run_id: type: string example: evalrun_677469f564d48190807532a852da3afb + '400': + description: The evaluation run cannot be deleted until it is finished. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '404': description: Run not found content: application/json: schema: - $ref: '#/components/schemas/Error' + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -5748,6 +6388,18 @@ paths: application/json: schema: $ref: '#/components/schemas/EvalRunOutputItemList' + '400': + description: The output item list parameters are invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The evaluation or evaluation run was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -5882,6 +6534,18 @@ paths: application/json: schema: $ref: '#/components/schemas/EvalRunOutputItem' + '400': + description: The output item was not found, its identifier is invalid, or the run does not belong to the evaluation. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The evaluation or evaluation run was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -6023,6 +6687,24 @@ paths: application/json: schema: $ref: '#/components/schemas/ListFilesResponse' + '400': + description: The file listing parameters are invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The file specified by the after cursor was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: Too many file requests. Reduce the request rate and try again later. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: files examples: @@ -6120,6 +6802,24 @@ paths: application/json: schema: $ref: '#/components/schemas/OpenAIFile' + '400': + description: The file upload request is invalid or exceeds a file size or storage quota limit. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: Too many file requests. Reduce the request rate and try again later. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '500': + description: The file could not be uploaded because of a server error. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: files examples: @@ -6194,6 +6894,18 @@ paths: application/json: schema: $ref: '#/components/schemas/DeleteFileResponse' + '404': + description: The file was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: Too many file requests. Reduce the request rate and try again later. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: files examples: @@ -6245,6 +6957,18 @@ paths: application/json: schema: $ref: '#/components/schemas/OpenAIFile' + '404': + description: The file was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: Too many file requests. Reduce the request rate and try again later. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: files examples: @@ -6300,6 +7024,30 @@ paths: application/json: schema: type: string + '400': + description: The file cannot be downloaded for its purpose or the account does not have permission to download it. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The file was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: Too many file requests. Reduce the request rate and try again later. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '500': + description: The file could not be downloaded because of a server error. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: files examples: @@ -6346,6 +7094,18 @@ paths: application/json: schema: $ref: '#/components/schemas/RunGraderResponse' + '400': + description: The grader definition or request is invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: The request rate limit has been exceeded. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: beta: true group: graders @@ -6577,6 +7337,18 @@ paths: application/json: schema: $ref: '#/components/schemas/ValidateGraderResponse' + '400': + description: The grader definition or request is invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: The request rate limit has been exceeded. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: beta: true group: graders @@ -6660,6 +7432,18 @@ paths: application/json: schema: $ref: '#/components/schemas/ListFineTuningCheckpointPermissionResponse' + '400': + description: The query parameters are invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: The request rate limit has been exceeded. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: fine-tuning examples: @@ -6719,6 +7503,24 @@ paths: application/json: schema: $ref: '#/components/schemas/ListFineTuningCheckpointPermissionResponse' + '400': + description: The request is invalid or checkpoint permissions cannot be changed for the requested projects or job state. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The checkpoint or its fine-tuning job was not found, or the checkpoint cannot be shared. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: The request rate limit has been exceeded. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: fine-tuning examples: @@ -6776,6 +7578,24 @@ paths: application/json: schema: $ref: '#/components/schemas/DeleteFineTuningCheckpointPermissionResponse' + '400': + description: The checkpoint permission cannot be removed for the requested project or job state. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The checkpoint, permission, associated project, or fine-tuning job was not found, or the checkpoint cannot be shared. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: The request rate limit has been exceeded. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: fine-tuning examples: @@ -6814,6 +7634,18 @@ paths: application/json: schema: $ref: '#/components/schemas/FineTuningJob' + '400': + description: The request is invalid or the organization does not meet the requirements to create a fine-tuning job. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: A request or fine-tuning job limit has been exceeded. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: fine-tuning examples: @@ -7233,6 +8065,18 @@ paths: application/json: schema: $ref: '#/components/schemas/ListPaginatedFineTuningJobsResponse' + '400': + description: The query parameters are invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: The request rate limit has been exceeded. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: fine-tuning examples: @@ -7308,6 +8152,18 @@ paths: application/json: schema: $ref: '#/components/schemas/FineTuningJob' + '404': + description: The fine-tuning job was not found or is not accessible. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: The request rate limit has been exceeded. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: fine-tuning examples: @@ -7391,6 +8247,24 @@ paths: application/json: schema: $ref: '#/components/schemas/FineTuningJob' + '400': + description: The fine-tuning job cannot be cancelled in its current state. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The fine-tuning job was not found or is not accessible. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: The request rate limit has been exceeded. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: fine-tuning examples: @@ -7464,6 +8338,24 @@ paths: application/json: schema: $ref: '#/components/schemas/ListFineTuningJobCheckpointsResponse' + '400': + description: The query parameters are invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The fine-tuning job was not found or is not accessible. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: The request rate limit has been exceeded. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: fine-tuning examples: @@ -7541,6 +8433,24 @@ paths: application/json: schema: $ref: '#/components/schemas/ListFineTuningJobEventsResponse' + '400': + description: The query parameters are invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The fine-tuning job was not found or is not accessible. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: The request rate limit has been exceeded. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: fine-tuning examples: @@ -7619,6 +8529,24 @@ paths: application/json: schema: $ref: '#/components/schemas/FineTuningJob' + '400': + description: The fine-tuning job cannot be paused in its current state or does not support pausing. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The fine-tuning job was not found or is not accessible, or this operation is unavailable. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: The request rate limit has been exceeded. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: fine-tuning examples: @@ -7679,6 +8607,24 @@ paths: application/json: schema: $ref: '#/components/schemas/FineTuningJob' + '400': + description: The fine-tuning job cannot be resumed in its current state or does not support resuming. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The fine-tuning job was not found or is not accessible, or this operation is unavailable. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: A request or fine-tuning job limit has been exceeded. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: fine-tuning examples: @@ -7738,8 +8684,32 @@ paths: text/event-stream: schema: $ref: '#/components/schemas/ImageEditStreamEvent' + '400': + description: Invalid image request, including invalid DALL-E parameters or input. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The project does not have access to the requested model. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '410': + description: The requested DALL-E image endpoint is unavailable because it has been retired. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/InferenceRateLimited' + '500': + description: The image could not be generated or processed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '503': $ref: '#/components/responses/InferenceServiceUnavailable' x-oaiMeta: @@ -7915,8 +8885,32 @@ paths: text/event-stream: schema: $ref: '#/components/schemas/ImageGenStreamEvent' + '400': + description: Invalid image request, including invalid DALL-E parameters or input. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The project does not have access to the requested model. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '410': + description: The requested DALL-E image endpoint is unavailable because it has been retired. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/InferenceRateLimited' + '500': + description: The image could not be generated or processed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '503': $ref: '#/components/responses/InferenceServiceUnavailable' x-oaiMeta: @@ -8053,6 +9047,50 @@ paths: application/json: schema: $ref: '#/components/schemas/ImagesResponse' + '400': + description: Invalid image or request, or the request cannot be processed for this account. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The project does not have access to the requested model. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '410': + description: The image variations endpoint is no longer available. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: The image rate limit was exceeded. + headers: + X-RateLimit-Limit-Images: + description: The image limit for the rate-limit window. + schema: + type: number + X-RateLimit-Remaining-Images: + description: The number of images remaining in the rate-limit window. + schema: + type: number + minimum: 0 + X-RateLimit-Reset-Images: + description: The number of seconds until the rate-limit window resets. + schema: + type: integer + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '500': + description: The image variation could not be generated or processed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: images examples: @@ -8137,6 +9175,45 @@ paths: transport: type: webrtc sdp: + '400': + description: Invalid Live session request. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + text/plain: + schema: + type: string + '413': + description: The Live session request exceeds the supported size limit. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + text/plain: + schema: + type: string + '429': + description: The session could not start because a rate or quota limit was exceeded. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '500': + description: An internal error occurred. The response body is plain text. + content: + text/plain: + schema: + type: string + '503': + description: The session is temporarily unavailable. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + text/plain: + schema: + type: string x-oaiMeta: group: live returns: Returns 201 Created with the session identifier in session.id and SDP answer in transport.sdp. @@ -8170,6 +9247,42 @@ paths: responses: '200': description: Session accept request accepted. + '400': + description: Invalid request body or headers. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The session or call was not found or is unavailable for this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '409': + description: The session or call can no longer accept this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: The session could not start because a rate or quota limit was exceeded. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '500': + description: An internal error occurred. The response body is plain text. + content: + text/plain: + schema: + type: string + '503': + description: The session is temporarily unavailable. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: live-sessions returns: Returns 200 OK when the control request succeeds. @@ -8200,6 +9313,42 @@ paths: application/json: schema: $ref: '#/components/schemas/LiveCreateResponse' + '400': + description: Invalid Live session request. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: Invalid session ID. + content: + text/plain: + schema: + type: string + '413': + description: The Live session request exceeds the supported size limit. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: The session could not start because a rate or quota limit was exceeded. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '500': + description: An internal error occurred. The response body is plain text. + content: + text/plain: + schema: + type: string + '503': + description: The session is temporarily unavailable. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: live returns: The new session identifier in session.id and SDP answer in transport.sdp. @@ -8227,6 +9376,12 @@ paths: responses: '200': description: Session hangup request accepted. + '404': + description: The session or call was not found or is unavailable for this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: live-sessions returns: Returns 200 OK when the control request succeeds. @@ -8253,6 +9408,24 @@ paths: responses: '200': description: Session refer request accepted. + '400': + description: Invalid request body or headers. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The session or call was not found or is unavailable for this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '500': + description: An internal error occurred. The response body is plain text. + content: + text/plain: + schema: + type: string x-oaiMeta: group: live-sessions returns: Returns 200 OK when the control request succeeds. @@ -8279,6 +9452,30 @@ paths: responses: '200': description: Session reject request accepted. + '400': + description: Invalid request body or headers. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The session or call was not found or is unavailable for this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '409': + description: The session or call can no longer accept this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '500': + description: An internal error occurred. The response body is plain text. + content: + text/plain: + schema: + type: string x-oaiMeta: group: live-sessions returns: Returns 200 OK when the control request succeeds. @@ -8296,6 +9493,12 @@ paths: application/json: schema: $ref: '#/components/schemas/ListModelsResponse' + '403': + description: The API credential does not have permission to list models. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' x-oaiMeta: group: models examples: @@ -8383,6 +9586,18 @@ paths: application/json: schema: $ref: '#/components/schemas/Model' + '403': + description: The API credential does not have permission to retrieve models. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The model was not found or is not accessible. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: models examples: @@ -8448,6 +9663,18 @@ paths: application/json: schema: $ref: '#/components/schemas/DeleteModelResponse' + '403': + description: Insufficient permissions to delete the model. Model deletion requires the Owner role in the organization and a credential that permits deletion. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The model was not found, is not accessible, or cannot be deleted through this endpoint. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: models examples: @@ -8502,8 +9729,26 @@ paths: application/json: schema: $ref: '#/components/schemas/CreateModerationResponse' + '400': + description: Invalid moderation input or unsupported request parameters. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: Access to the requested moderation model was denied. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/InferenceRateLimited' + '500': + description: The moderation request could not be processed due to an internal error. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '503': $ref: '#/components/responses/InferenceServiceUnavailable' x-oaiMeta: @@ -8768,6 +10013,18 @@ paths: application/json: schema: $ref: '#/components/schemas/ApiKeyList' + '400': + description: The API key listing parameters are invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' x-oaiMeta: group: administration examples: @@ -8833,6 +10090,24 @@ paths: application/json: schema: $ref: '#/components/schemas/AdminApiKeyCreateResponse' + '400': + description: The API key creation request is invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The created API key could not be found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -8885,6 +10160,18 @@ paths: application/json: schema: $ref: '#/components/schemas/AdminApiKey' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The API key was not found or is not available to this organization. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -8947,6 +10234,18 @@ paths: - id - object - deleted + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The API key was not found or is not available to this organization. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -9064,6 +10363,18 @@ paths: application/json: schema: $ref: '#/components/schemas/ListAuditLogsResponse' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: No audit log was found with the specified pagination cursor. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -9176,6 +10487,18 @@ paths: application/json: schema: $ref: '#/components/schemas/ListCertificatesResponse' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -9230,6 +10553,18 @@ paths: application/json: schema: $ref: '#/components/schemas/Certificate' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -9281,8 +10616,32 @@ paths: application/json: schema: $ref: '#/components/schemas/OrganizationCertificateActivationResponse' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: A certificate was not found in this organization. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' + '500': + description: The certificate update could not be completed because of a server error. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -9348,8 +10707,32 @@ paths: application/json: schema: $ref: '#/components/schemas/OrganizationCertificateDeactivationResponse' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: A certificate was not found in this organization. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' + '500': + description: The certificate update could not be completed because of a server error. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -9425,6 +10808,24 @@ paths: application/json: schema: $ref: '#/components/schemas/Certificate' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: A certificate was not found in this organization. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -9476,8 +10877,32 @@ paths: application/json: schema: $ref: '#/components/schemas/Certificate' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: A certificate was not found in this organization. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' + '500': + description: The certificate update could not be completed because of a server error. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -9525,6 +10950,24 @@ paths: application/json: schema: $ref: '#/components/schemas/DeleteCertificateResponse' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: A certificate was not found in this organization. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -9626,6 +11069,18 @@ paths: application/json: schema: $ref: '#/components/schemas/UsageResponse' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -9679,6 +11134,18 @@ paths: application/json: schema: $ref: '#/components/schemas/OrganizationDataRetention' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The organization was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -9714,6 +11181,24 @@ paths: application/json: schema: $ref: '#/components/schemas/OrganizationDataRetention' + '400': + description: The requested data retention setting or transition is invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The organization was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -9774,6 +11259,24 @@ paths: application/json: schema: $ref: '#/components/schemas/GroupListResource' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The endpoint is unavailable or a requested group, user, or project was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -9821,8 +11324,38 @@ paths: application/json: schema: $ref: '#/components/schemas/GroupResponse' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The endpoint is unavailable or a requested group, user, or project was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '422': + description: The organization has reached its maximum number of groups. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' + '500': + description: The group operation could not be completed because of a server error. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -9865,8 +11398,32 @@ paths: application/json: schema: $ref: '#/components/schemas/GroupResponse' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The endpoint is unavailable or a requested group, user, or project was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' + '500': + description: The group operation could not be completed because of a server error. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -9912,8 +11469,32 @@ paths: application/json: schema: $ref: '#/components/schemas/GroupResourceWithSuccess' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The endpoint is unavailable or a requested group, user, or project was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' + '500': + description: The group operation could not be completed because of a server error. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -9954,6 +11535,24 @@ paths: application/json: schema: $ref: '#/components/schemas/GroupDeletedResource' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The endpoint is unavailable. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -10016,6 +11615,24 @@ paths: application/json: schema: $ref: '#/components/schemas/RoleListResource' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The endpoint is unavailable or a requested resource was not found in this organization or project. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -10083,6 +11700,24 @@ paths: application/json: schema: $ref: '#/components/schemas/GroupRoleAssignment' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The endpoint is unavailable or a requested resource was not found in this organization or project. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -10148,6 +11783,24 @@ paths: application/json: schema: $ref: '#/components/schemas/AssignedRoleDetails' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The endpoint is unavailable or a requested resource was not found in this organization or project. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -10204,6 +11857,24 @@ paths: application/json: schema: $ref: '#/components/schemas/DeletedRoleAssignmentResource' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The endpoint is unavailable or a requested resource was not found in this organization or project. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -10269,8 +11940,32 @@ paths: application/json: schema: $ref: '#/components/schemas/UserListResource' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The endpoint is unavailable or a requested group, user, or project was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' + '502': + description: The upstream group service returned an invalid pagination cursor. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -10394,6 +12089,24 @@ paths: application/json: schema: $ref: '#/components/schemas/GroupMemberUser' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The endpoint is unavailable or a requested group, user, or project was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -10513,6 +12226,30 @@ paths: application/json: schema: $ref: '#/components/schemas/InviteListResponse' + '400': + description: The invite listing parameters are invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The invite specified by the after cursor was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: Too many management requests. Reduce the request rate and try again later. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -10562,6 +12299,24 @@ paths: application/json: schema: $ref: '#/components/schemas/Invite' + '400': + description: The invite request is invalid or the user has already joined or been invited. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '429': + description: Too many management requests. Reduce the request rate and try again later. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -10628,6 +12383,36 @@ paths: application/json: schema: $ref: '#/components/schemas/Invite' + '400': + description: The invite request is invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The invite was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: Too many management requests. Reduce the request rate and try again later. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '500': + description: The invite could not be retrieved because of a server error. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -10749,6 +12534,30 @@ paths: application/json: schema: $ref: '#/components/schemas/ProjectListResponse' + '400': + description: The project listing parameters are invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The project specified by the after cursor was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: Too many management requests. Reduce the request rate and try again later. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -10796,6 +12605,24 @@ paths: application/json: schema: $ref: '#/components/schemas/Project' + '400': + description: The project creation request is invalid or contains incompatible settings. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '429': + description: Too many management requests. Reduce the request rate and try again later. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -10839,6 +12666,24 @@ paths: application/json: schema: $ref: '#/components/schemas/Project' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The project was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: Too many management requests. Reduce the request rate and try again later. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -10891,6 +12736,24 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: A requested project, user, service account, or API key was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: Too many management requests. Reduce the request rate and try again later. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -10951,6 +12814,30 @@ paths: application/json: schema: $ref: '#/components/schemas/ProjectApiKeyListResponse' + '400': + description: The listing parameters are invalid or the project is archived. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The project was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: Too many management requests. Reduce the request rate and try again later. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -11016,6 +12903,30 @@ paths: application/json: schema: $ref: '#/components/schemas/ProjectApiKey' + '400': + description: The project is archived. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The project or API key was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: Too many management requests. Reduce the request rate and try again later. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -11082,6 +12993,24 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: A requested project, user, service account, or API key was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: Too many management requests. Reduce the request rate and try again later. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -11119,6 +13048,30 @@ paths: application/json: schema: $ref: '#/components/schemas/Project' + '400': + description: The project is already archived or is the default project and cannot be archived. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The project was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: Too many management requests. Reduce the request rate and try again later. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -11184,6 +13137,18 @@ paths: application/json: schema: $ref: '#/components/schemas/ListProjectCertificatesResponse' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -11246,8 +13211,32 @@ paths: application/json: schema: $ref: '#/components/schemas/OrganizationProjectCertificateActivationResponse' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: A certificate was not found in this organization. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' + '500': + description: The certificate update could not be completed because of a server error. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -11317,8 +13306,32 @@ paths: application/json: schema: $ref: '#/components/schemas/OrganizationProjectCertificateDeactivationResponse' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: A certificate was not found in this organization. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' + '500': + description: The certificate update could not be completed because of a server error. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -11381,6 +13394,24 @@ paths: application/json: schema: $ref: '#/components/schemas/ProjectDataRetention' + '400': + description: The project ID is invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The organization or project was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -11423,6 +13454,24 @@ paths: application/json: schema: $ref: '#/components/schemas/ProjectDataRetention' + '400': + description: The requested data retention setting or transition is invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The organization or project was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -11487,6 +13536,24 @@ paths: application/json: schema: $ref: '#/components/schemas/ProjectGroupListResource' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The endpoint is unavailable or a requested group, user, or project was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -11541,8 +13608,32 @@ paths: application/json: schema: $ref: '#/components/schemas/ProjectGroup' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The endpoint is unavailable or a requested group, user, or project was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' + '500': + description: The group operation could not be completed because of a server error. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -11602,6 +13693,24 @@ paths: application/json: schema: $ref: '#/components/schemas/ProjectGroup' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The endpoint is unavailable or a requested group, user, or project was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -11649,6 +13758,24 @@ paths: application/json: schema: $ref: '#/components/schemas/ProjectGroupDeletedResource' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The endpoint is unavailable or a requested group, user, or project was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -11687,6 +13814,30 @@ paths: application/json: schema: $ref: '#/components/schemas/ProjectHostedToolPermissions' + '400': + description: The project ID is invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The project was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: Too many management requests. Reduce the request rate and try again later. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -11742,6 +13893,36 @@ paths: application/json: schema: $ref: '#/components/schemas/ProjectHostedToolPermissions' + '400': + description: The hosted tool permission request is invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The project was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '409': + description: The requested project setting conflicts with the organization policy. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: Too many management requests. Reduce the request rate and try again later. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -11799,6 +13980,30 @@ paths: application/json: schema: $ref: '#/components/schemas/ProjectModelPermissions' + '400': + description: The project is archived. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The project or model permission settings were not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: Too many management requests. Reduce the request rate and try again later. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -11845,6 +14050,30 @@ paths: application/json: schema: $ref: '#/components/schemas/ProjectModelPermissions' + '400': + description: The model permission request is invalid or the project is archived. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The project was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: Too many management requests. Reduce the request rate and try again later. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -11889,6 +14118,30 @@ paths: application/json: schema: $ref: '#/components/schemas/ProjectModelPermissionsDeleteResponse' + '400': + description: The project is archived. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The project or model permission settings were not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: Too many management requests. Reduce the request rate and try again later. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -11947,6 +14200,24 @@ paths: application/json: schema: $ref: '#/components/schemas/ProjectRateLimitListResponse' + '400': + description: The rate limit listing parameters are invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The project or pagination cursor was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -12019,6 +14290,18 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The project was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -12088,6 +14371,24 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: A requested project, user, service account, or API key was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: Too many management requests. Reduce the request rate and try again later. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -12147,6 +14448,24 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: A requested project, user, service account, or API key was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: Too many management requests. Reduce the request rate and try again later. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -12202,6 +14521,30 @@ paths: application/json: schema: $ref: '#/components/schemas/ProjectServiceAccount' + '400': + description: The project is archived. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The project or service account was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: Too many management requests. Reduce the request rate and try again later. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -12253,6 +14596,30 @@ paths: application/json: schema: $ref: '#/components/schemas/ProjectServiceAccount' + '400': + description: The service account update is invalid or the project is archived. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The project or service account was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: Too many management requests. Reduce the request rate and try again later. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -12400,6 +14767,24 @@ paths: application/json: schema: $ref: '#/components/schemas/ProjectSpendAlertListResource' + '400': + description: The spend alert listing parameters are invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The project or spend alert pagination cursor was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -12458,6 +14843,24 @@ paths: application/json: schema: $ref: '#/components/schemas/ProjectSpendAlert' + '400': + description: The spend alert request is invalid or conflicts with the hard spend limit. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The project was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -12518,6 +14921,24 @@ paths: application/json: schema: $ref: '#/components/schemas/ProjectSpendAlert' + '400': + description: The project ID is invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The project or spend alert was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -12574,6 +14995,24 @@ paths: application/json: schema: $ref: '#/components/schemas/ProjectSpendAlert' + '400': + description: The spend alert update is invalid or conflicts with the hard spend limit. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The project or spend alert was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -12633,6 +15072,24 @@ paths: application/json: schema: $ref: '#/components/schemas/ProjectSpendAlertDeletedResource' + '400': + description: The project ID is invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The project or spend alert was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -12691,6 +15148,24 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: A requested project, user, service account, or API key was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: Too many management requests. Reduce the request rate and try again later. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -12827,6 +15302,30 @@ paths: application/json: schema: $ref: '#/components/schemas/ProjectUser' + '400': + description: The project is archived. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The project or user was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: Too many management requests. Reduce the request rate and try again later. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -12885,6 +15384,24 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: A requested project, user, service account, or API key was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: Too many management requests. Reduce the request rate and try again later. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -12943,6 +15460,24 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: A requested project, user, service account, or API key was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: Too many management requests. Reduce the request rate and try again later. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -12999,6 +15534,24 @@ paths: application/json: schema: $ref: '#/components/schemas/PublicRoleListResource' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The endpoint is unavailable or a requested resource was not found in this organization or project. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -13051,6 +15604,24 @@ paths: application/json: schema: $ref: '#/components/schemas/Role' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The endpoint is unavailable or a requested resource was not found in this organization or project. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -13105,6 +15676,18 @@ paths: application/json: schema: $ref: '#/components/schemas/Role' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The endpoint is unavailable or a requested resource was not found in this organization or project. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -13157,6 +15740,24 @@ paths: application/json: schema: $ref: '#/components/schemas/Role' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The endpoint is unavailable or a requested resource was not found in this organization or project. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -13210,6 +15811,24 @@ paths: application/json: schema: $ref: '#/components/schemas/RoleDeletedResource' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The endpoint is unavailable or a requested resource was not found in this organization or project. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -13273,6 +15892,24 @@ paths: application/json: schema: $ref: '#/components/schemas/OrganizationSpendAlertListResource' + '400': + description: The spend alert listing parameters are invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The spend alert specified by the after cursor was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -13324,6 +15961,18 @@ paths: application/json: schema: $ref: '#/components/schemas/OrganizationSpendAlert' + '400': + description: The spend alert request is invalid or conflicts with the hard spend limit. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' x-oaiMeta: group: administration examples: @@ -13378,6 +16027,18 @@ paths: application/json: schema: $ref: '#/components/schemas/OrganizationSpendAlert' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The spend alert was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -13428,6 +16089,24 @@ paths: application/json: schema: $ref: '#/components/schemas/OrganizationSpendAlert' + '400': + description: The spend alert update is invalid or conflicts with the hard spend limit. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The spend alert was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -13481,6 +16160,18 @@ paths: application/json: schema: $ref: '#/components/schemas/OrganizationSpendAlertDeletedResource' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The spend alert was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -13595,6 +16286,18 @@ paths: application/json: schema: $ref: '#/components/schemas/UsageResponse' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -13729,6 +16432,18 @@ paths: application/json: schema: $ref: '#/components/schemas/UsageResponse' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -13836,6 +16551,18 @@ paths: application/json: schema: $ref: '#/components/schemas/UsageResponse' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -13975,6 +16702,18 @@ paths: application/json: schema: $ref: '#/components/schemas/UsageResponse' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -14124,6 +16863,18 @@ paths: application/json: schema: $ref: '#/components/schemas/UsageResponse' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -14258,6 +17009,18 @@ paths: application/json: schema: $ref: '#/components/schemas/UsageResponse' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -14419,6 +17182,18 @@ paths: application/json: schema: $ref: '#/components/schemas/UsageResponse' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -14555,6 +17330,18 @@ paths: application/json: schema: $ref: '#/components/schemas/UsageResponse' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -14662,6 +17449,18 @@ paths: application/json: schema: $ref: '#/components/schemas/UsageResponse' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -14805,6 +17604,18 @@ paths: application/json: schema: $ref: '#/components/schemas/UsageResponse' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -14880,6 +17691,24 @@ paths: application/json: schema: $ref: '#/components/schemas/UserListResponse' + '400': + description: The user listing parameters are invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '429': + description: Too many management requests. Reduce the request rate and try again later. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -14928,6 +17757,24 @@ paths: application/json: schema: $ref: '#/components/schemas/User' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The user was not found in this organization. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: Too many management requests. Reduce the request rate and try again later. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -14974,6 +17821,30 @@ paths: application/json: schema: $ref: '#/components/schemas/User' + '400': + description: The requested user role is invalid or the update is not permitted. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The user was not found in this organization. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: Too many management requests. Reduce the request rate and try again later. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -15104,6 +17975,24 @@ paths: application/json: schema: $ref: '#/components/schemas/RoleListResource' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The endpoint is unavailable or a requested resource was not found in this organization or project. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -15171,6 +18060,24 @@ paths: application/json: schema: $ref: '#/components/schemas/UserRoleAssignment' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The endpoint is unavailable or a requested resource was not found in this organization or project. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -15237,6 +18144,24 @@ paths: application/json: schema: $ref: '#/components/schemas/AssignedRoleDetails' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The endpoint is unavailable or a requested resource was not found in this organization or project. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -15293,6 +18218,24 @@ paths: application/json: schema: $ref: '#/components/schemas/DeletedRoleAssignmentResource' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The endpoint is unavailable or a requested resource was not found in this organization or project. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -15360,6 +18303,24 @@ paths: application/json: schema: $ref: '#/components/schemas/RoleListResource' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The endpoint is unavailable or a requested resource was not found in this organization or project. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -15433,6 +18394,24 @@ paths: application/json: schema: $ref: '#/components/schemas/GroupRoleAssignment' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The endpoint is unavailable or a requested resource was not found in this organization or project. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -15504,6 +18483,24 @@ paths: application/json: schema: $ref: '#/components/schemas/AssignedRoleDetails' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The endpoint is unavailable or a requested resource was not found in this organization or project. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -15566,6 +18563,24 @@ paths: application/json: schema: $ref: '#/components/schemas/DeletedRoleAssignmentResource' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The endpoint is unavailable or a requested resource was not found in this organization or project. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -15629,6 +18644,24 @@ paths: application/json: schema: $ref: '#/components/schemas/PublicRoleListResource' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The endpoint is unavailable or a requested resource was not found in this organization or project. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -15688,6 +18721,24 @@ paths: application/json: schema: $ref: '#/components/schemas/Role' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The endpoint is unavailable or a requested resource was not found in this organization or project. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -15748,6 +18799,18 @@ paths: application/json: schema: $ref: '#/components/schemas/Role' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The endpoint is unavailable or a requested resource was not found in this organization or project. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -15806,6 +18869,24 @@ paths: application/json: schema: $ref: '#/components/schemas/Role' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The endpoint is unavailable or a requested resource was not found in this organization or project. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -15865,6 +18946,24 @@ paths: application/json: schema: $ref: '#/components/schemas/RoleDeletedResource' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The endpoint is unavailable or a requested resource was not found in this organization or project. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -15933,6 +19032,24 @@ paths: application/json: schema: $ref: '#/components/schemas/RoleListResource' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The endpoint is unavailable or a requested resource was not found in this organization or project. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -16006,6 +19123,24 @@ paths: application/json: schema: $ref: '#/components/schemas/UserRoleAssignment' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The endpoint is unavailable or a requested resource was not found in this organization or project. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -16078,6 +19213,24 @@ paths: application/json: schema: $ref: '#/components/schemas/AssignedRoleDetails' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The endpoint is unavailable or a requested resource was not found in this organization or project. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -16140,6 +19293,24 @@ paths: application/json: schema: $ref: '#/components/schemas/DeletedRoleAssignmentResource' + '400': + description: The request parameters are invalid or the requested operation cannot be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The endpoint is unavailable or a requested resource was not found in this organization or project. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -16258,6 +19429,24 @@ paths: responses: '200': description: Call accepted successfully. + '404': + description: The session or call was not found or is unavailable for this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '409': + description: The session or call can no longer accept this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '500': + description: An internal error occurred. The response body is plain text. + content: + text/plain: + schema: + type: string x-oaiMeta: group: realtime-calls returns: |- @@ -16298,6 +19487,12 @@ paths: responses: '200': description: Call hangup initiated successfully. + '404': + description: The session or call was not found or is unavailable for this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: realtime-calls returns: Returns `200 OK` when OpenAI begins terminating the realtime call. @@ -16333,6 +19528,18 @@ paths: responses: '200': description: Call referred successfully. + '404': + description: The session or call was not found or is unavailable for this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '500': + description: An internal error occurred. The response body is plain text. + content: + text/plain: + schema: + type: string x-oaiMeta: group: realtime-calls returns: Returns `200 OK` once the REFER is handed off to your SIP provider. @@ -16372,6 +19579,24 @@ paths: responses: '200': description: Call rejected successfully. + '404': + description: The session or call was not found or is unavailable for this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '409': + description: The session or call can no longer accept this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '500': + description: An internal error occurred. The response body is plain text. + content: + text/plain: + schema: + type: string x-oaiMeta: group: realtime-calls returns: Returns `200 OK` after OpenAI sends the SIP status code to the caller. @@ -16416,6 +19641,24 @@ paths: application/json: schema: $ref: '#/components/schemas/RealtimeCreateClientSecretResponse' + '400': + description: Invalid session configuration or model. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The requested model was not found or is unavailable to this caller. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '500': + description: The requested model's availability could not be determined. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: realtime examples: @@ -16602,6 +19845,24 @@ paths: application/json: schema: $ref: '#/components/schemas/RealtimeTranslationClientSecretCreateResponse' + '400': + description: Invalid session configuration or model. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The requested model was not found or is unavailable to this caller. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '500': + description: The requested model's availability could not be determined. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: realtime examples: @@ -16682,6 +19943,18 @@ paths: text/event-stream: schema: $ref: '#/components/schemas/ResponseStreamEvent' + '400': + description: Invalid response request or incompatible request parameters. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The requested model or a referenced resource was not found or is unavailable to this caller. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/InferenceRateLimited' '503': @@ -17924,6 +21197,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Response' + '404': + description: The response was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -18028,7 +21307,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/Error' + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -18087,7 +21366,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/Error' + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -18215,6 +21494,12 @@ paths: application/json: schema: $ref: '#/components/schemas/ResponseItemList' + '404': + description: The response or the item specified by `after` was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -20851,6 +24136,18 @@ paths: application/json: schema: $ref: '#/components/schemas/Upload' + '400': + description: The upload request is invalid or exceeds a file size or storage quota limit. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: Too many upload requests. Reduce the request rate and try again later. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: uploads examples: @@ -20905,6 +24202,30 @@ paths: application/json: schema: $ref: '#/components/schemas/Upload' + '400': + description: The upload is no longer pending or is already being completed and cannot be cancelled. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The upload was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '410': + description: The upload has expired. Create a new upload before adding parts or completing it. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: Too many upload requests. Reduce the request rate and try again later. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: uploads examples: @@ -20959,6 +24280,36 @@ paths: application/json: schema: $ref: '#/components/schemas/Upload' + '400': + description: The upload cannot be completed in its current state, the parts are invalid, or the uploaded size does not match the specified size. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The upload was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '410': + description: The upload has expired. Create a new upload before adding parts or completing it. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: Too many upload requests. Reduce the request rate and try again later. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '500': + description: The upload could not be completed. Retry the same request, preserving the part order and MD5 value. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: uploads examples: @@ -21022,6 +24373,36 @@ paths: application/json: schema: $ref: '#/components/schemas/UploadPart' + '400': + description: The upload cannot accept more parts, or the part exceeds an upload size limit. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The upload was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '410': + description: The upload has expired. Create a new upload before adding parts or completing it. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: Too many upload requests. Reduce the request rate and try again later. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '500': + description: The part could not be uploaded. Try the request again. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: uploads examples: @@ -21083,6 +24464,12 @@ paths: $ref: '#/components/schemas/ListVectorStoresResponse' '429': $ref: '#/components/responses/TooManyRequests' + '503': + description: The vector store list is temporarily unavailable. Retry the request. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: vector_stores examples: @@ -21166,6 +24553,18 @@ paths: application/json: schema: $ref: '#/components/schemas/VectorStoreObject' + '400': + description: The vector store input, files or chunking configuration are invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: A referenced input file was not found or is not accessible. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -21237,6 +24636,12 @@ paths: application/json: schema: $ref: '#/components/schemas/VectorStoreObject' + '404': + description: The vector store was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -21300,6 +24705,24 @@ paths: application/json: schema: $ref: '#/components/schemas/VectorStoreObject' + '400': + description: The vector store input is invalid, the store has expired, or the store cannot be modified. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller is not authorized to update the vector store. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The vector store was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -21374,6 +24797,24 @@ paths: application/json: schema: $ref: '#/components/schemas/DeleteVectorStoreResponse' + '404': + description: The vector store was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '409': + description: The vector store is temporarily unavailable for this change or was modified concurrently. + headers: + Retry-After: + description: When this change is blocked by a vector store migration, the number of seconds to wait before retrying. Other conflicts may omit this header. + schema: + type: integer + minimum: 1 + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -21441,8 +24882,38 @@ paths: application/json: schema: $ref: '#/components/schemas/VectorStoreFileBatchObject' + '400': + description: The file batch input is invalid, the store has expired, or a file limit would be exceeded. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The vector store was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '409': + description: The vector store is temporarily unavailable for this change or was modified concurrently. + headers: + Retry-After: + description: When this change is blocked by a vector store migration, the number of seconds to wait before retrying. Other conflicts may omit this header. + schema: + type: integer + minimum: 1 + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' + '500': + description: The files could not be attached to the vector store. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: vector_stores examples: @@ -21562,6 +25033,18 @@ paths: application/json: schema: $ref: '#/components/schemas/VectorStoreFileBatchObject' + '400': + description: The file batch identifier is invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The vector store or file batch was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -21637,6 +25120,30 @@ paths: application/json: schema: $ref: '#/components/schemas/VectorStoreFileBatchObject' + '400': + description: The file batch identifier is invalid or the vector store has expired. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The vector store or file batch was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '409': + description: The vector store is temporarily unavailable for this change or was modified concurrently. + headers: + Retry-After: + description: When this change is blocked by a vector store migration, the number of seconds to wait before retrying. Other conflicts may omit this header. + schema: + type: integer + minimum: 1 + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -21753,6 +25260,18 @@ paths: application/json: schema: $ref: '#/components/schemas/ListVectorStoreFilesResponse' + '400': + description: The file batch identifier or file filter is invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The vector store or file batch was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -21868,6 +25387,18 @@ paths: application/json: schema: $ref: '#/components/schemas/ListVectorStoreFilesResponse' + '400': + description: The requested file filter is invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The vector store was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -21948,8 +25479,38 @@ paths: application/json: schema: $ref: '#/components/schemas/VectorStoreFileObject' + '400': + description: The file input is invalid, the store has expired, or a file limit would be exceeded. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The vector store was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '409': + description: The vector store is temporarily unavailable for this change or was modified concurrently. + headers: + Retry-After: + description: When this change is blocked by a vector store migration, the number of seconds to wait before retrying. Other conflicts may omit this header. + schema: + type: integer + minimum: 1 + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' + '500': + description: The file could not be attached to the vector store. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: vector_stores examples: @@ -22025,8 +25586,20 @@ paths: application/json: schema: $ref: '#/components/schemas/VectorStoreFileObject' + '404': + description: The vector store or file was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' + '500': + description: The vector store file could not be retrieved. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: vector_stores examples: @@ -22093,8 +25666,38 @@ paths: application/json: schema: $ref: '#/components/schemas/DeleteVectorStoreFileResponse' + '400': + description: The vector store has expired. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The vector store or file was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '409': + description: The vector store is temporarily unavailable for this change or was modified concurrently. + headers: + Retry-After: + description: When this change is blocked by a vector store migration, the number of seconds to wait before retrying. Other conflicts may omit this header. + schema: + type: integer + minimum: 1 + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' + '500': + description: The vector store file could not be deleted. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: vector_stores examples: @@ -22167,8 +25770,38 @@ paths: application/json: schema: $ref: '#/components/schemas/VectorStoreFileObject' + '400': + description: The file attributes are invalid or the vector store has expired. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The vector store or file was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '409': + description: The vector store is temporarily unavailable for this change or was modified concurrently. + headers: + Retry-After: + description: When this change is blocked by a vector store migration, the number of seconds to wait before retrying. Other conflicts may omit this header. + schema: + type: integer + minimum: 1 + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' + '500': + description: The vector store file attributes could not be updated. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: vector_stores examples: @@ -22219,8 +25852,26 @@ paths: application/json: schema: $ref: '#/components/schemas/VectorStoreFileContentResponse' + '400': + description: The vector store has expired or the file content is not ready. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The vector store or file was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' + '500': + description: The vector store file content could not be retrieved. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: vector_stores examples: @@ -22267,6 +25918,18 @@ paths: application/json: schema: $ref: '#/components/schemas/VectorStoreSearchResultsPage' + '400': + description: The search input or filters are invalid, or the vector store has expired. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The vector store was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -22338,8 +26001,20 @@ paths: application/json: schema: $ref: '#/components/schemas/ConversationResource' + '400': + description: The conversation input is invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' + '500': + description: The conversation update could not be finalized. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: conversations path: create @@ -22437,6 +26112,12 @@ paths: application/json: schema: $ref: '#/components/schemas/ConversationResource' + '404': + description: The conversation was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -22497,6 +26178,12 @@ paths: application/json: schema: $ref: '#/components/schemas/DeletedConversationResource' + '404': + description: The conversation was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -22561,8 +26248,26 @@ paths: application/json: schema: $ref: '#/components/schemas/ConversationResource' + '400': + description: The conversation metadata is invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The conversation was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' + '500': + description: The conversation update could not be finalized. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: conversations path: update @@ -22620,6 +26325,121 @@ paths: "created_at": 1741900000, "metadata": {"topic": "project-x"} } + /responses/{response_id}/cancel?beta=true: + post: + operationId: beta_cancelResponse + tags: + - Responses + summary: Cancel a response + description: | + Cancels a model response with the given ID. Only responses created with + the `background` parameter set to `true` can be cancelled. + [Learn more](https://developers.openai.com/api/docs/guides/background). + parameters: + - in: path + name: response_id + required: true + schema: + type: string + example: resp_677efb5139a88190b512bc3fef8e535d + description: The ID of the response to cancel. + - name: openai-beta + in: header + required: false + description: Optional beta features to enable for this request. + style: simple + explode: false + schema: + type: array + x-stainless-param: betas + items: + type: string + enum: + - responses_multi_agent=v1 + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/BetaResponse' + '404': + description: Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/BetaErrorResponse' + '429': + $ref: '#/components/responses/TooManyRequests' + x-oaiMeta: + group: responses + examples: + request: + curl: | + curl -X POST https://api.openai.com/v1/responses/resp_123/cancel \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" + javascript: | + import OpenAI from "openai"; + const client = new OpenAI(); + + const response = await client.responses.cancel("resp_123"); + console.log(response); + python: | + from openai import OpenAI + client = OpenAI() + + response = client.responses.cancel("resp_123") + print(response) + response: | + { + "id": "resp_67cb71b351908190a308f3859487620d06981a8637e6bc44", + "object": "response", + "created_at": 1741386163, + "status": "cancelled", + "background": true, + "completed_at": null, + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-6-astra", + "output": [ + { + "type": "message", + "id": "msg_67cb71b3c2b0819084d481baaaf148f206981a8637e6bc44", + "status": "in_progress", + "role": "assistant", + "content": [ + { + "type": "output_text", + "text": "Silent circuits hum, \nThoughts emerge in data streams— \nDigital dawn breaks.", + "annotations": [] + } + ] + } + ], + "parallel_tool_calls": true, + "previous_response_id": null, + "reasoning": { + "effort": null, + "summary": null + }, + "store": true, + "temperature": 1.0, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [], + "top_p": 1.0, + "truncation": "disabled", + "usage": null, + "user": null, + "metadata": {} + } /safety/alerts/{id}: get: summary: Get project safety alert @@ -22641,6 +26461,26 @@ paths: application/json: schema: $ref: '#/components/schemas/SafetyAlertResource' + '400': + description: The safety alert ID is too long. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The safety alert was not found or is not accessible to the caller. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + $ref: '#/components/responses/TooManyRequests' + '503': + description: The safety alert lookup is temporarily unavailable. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: safety-alerts path: retrieve @@ -22686,9 +26526,466 @@ paths: description: The Live session recording as a stereo WAV file, with input audio in the left channel and output audio in the right channel. type: string format: binary + '400': + description: Invalid Live session ID. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The endpoint is unavailable or the stored session recording was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + $ref: '#/components/responses/TooManyRequests' + '500': + description: The stored session audio could not be exported. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '503': + description: The audio export is temporarily unavailable. + headers: + Retry-After: + description: The minimum number of seconds to wait before retrying. + schema: + type: integer + minimum: 1 + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: live returns: The stored session recording as binary stereo WAV audio. + /responses/input_tokens?beta=true: + post: + x-oaiMeta: + group: responses + examples: + request: + curl: | + curl -X POST https://api.openai.com/v1/responses/input_tokens \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-6-astra", + "input": "Tell me a joke." + }' + javascript: | + import OpenAI from "openai"; + + const client = new OpenAI(); + + const response = await client.responses.inputTokens.count({ + model: "gpt-6-astra", + input: "Tell me a joke.", + }); + + console.log(response.input_tokens); + python: | + from openai import OpenAI + + client = OpenAI() + + response = client.responses.input_tokens.count( + model="gpt-6-astra", + input="Tell me a joke." + ) + print(response.input_tokens) + go: | + package main + + import ( + "context" + "fmt" + + "github.com/openai/openai-go" + "github.com/openai/openai-go/responses" + ) + + func main() { + client := openai.NewClient() + response, err := client.Responses.InputTokens.Count(context.TODO(), responses.InputTokenCountParams{ + Model: "gpt-6-astra", + Input: "Tell me a joke.", + }) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", response.InputTokens) + } + ruby: | + require "openai" + + openai = OpenAI::Client.new + + response = openai.responses.input_tokens.count(model: "gpt-6-astra", input: "Tell me a joke.") + + puts(response) + java: | + package com.openai.example; + + import com.openai.client.OpenAIClient; + import com.openai.client.okhttp.OpenAIOkHttpClient; + import com.openai.models.responses.inputtokens.InputTokenCountParams; + import com.openai.models.responses.inputtokens.InputTokenCountResponse; + + public final class Main { + private Main() {} + + public static void main(String[] args) { + OpenAIClient client = OpenAIOkHttpClient.fromEnv(); + + InputTokenCountParams params = InputTokenCountParams.builder() + .model("gpt-6-astra") + .input("Tell me a joke.") + .build(); + + InputTokenCountResponse response = client.responses().inputTokens().count(params); + } + } + response: | + { + "object": "response.input_tokens", + "input_tokens": 11 + } + summary: Get input token counts + description: |- + Returns input token counts of the request. + + Returns an object with `object` set to `response.input_tokens` and an `input_tokens` count. + operationId: beta_Getinputtokencounts + parameters: + - name: openai-beta + in: header + required: false + description: Optional beta features to enable for this request. + style: simple + explode: false + schema: + type: array + x-stainless-param: betas + items: + type: string + enum: + - responses_multi_agent=v1 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/BetaTokenCountsBody' + responses: + '200': + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/BetaTokenCountsResource' + '400': + description: The request to count input tokens is invalid or contains incompatible parameters. + content: + application/json: + schema: + $ref: '#/components/schemas/BetaErrorResponse' + '429': + $ref: '#/components/responses/TooManyRequests' + /responses/{response_id}/input_items?beta=true: + get: + operationId: beta_listInputItems + tags: + - Responses + summary: List input items + description: Returns a list of input items for a given response. + parameters: + - in: path + name: response_id + required: true + schema: + type: string + description: The ID of the response to retrieve input items for. + - name: limit + in: query + description: | + A limit on the number of objects to be returned. Limit can range between + 1 and 100, and the default is 20. + required: false + schema: + type: integer + default: 20 + - in: query + name: order + schema: + type: string + enum: + - asc + - desc + description: | + The order to return the input items in. Default is `desc`. + - `asc`: Return the input items in ascending order. + - `desc`: Return the input items in descending order. + - in: query + name: after + schema: + type: string + description: | + An item ID to list items after, used in pagination. + - in: query + name: include + schema: + type: array + items: + $ref: '#/components/schemas/BetaIncludeEnum' + description: | + Additional fields to include in the response. See the `include` + parameter for Response creation above for more information. + - name: openai-beta + in: header + required: false + description: Optional beta features to enable for this request. + style: simple + explode: false + schema: + type: array + x-stainless-param: betas + items: + type: string + enum: + - responses_multi_agent=v1 + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/BetaResponseItemList' + '404': + description: The response or the item specified by `after` was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/BetaErrorResponse' + '429': + $ref: '#/components/responses/TooManyRequests' + x-oaiMeta: + group: responses + examples: + request: + curl: | + curl https://api.openai.com/v1/responses/resp_abc123/input_items \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" + javascript: | + import OpenAI from "openai"; + const client = new OpenAI(); + + const response = await client.responses.inputItems.list("resp_123"); + console.log(response.data); + python: | + from openai import OpenAI + client = OpenAI() + + response = client.responses.input_items.list("resp_123") + print(response.data) + response: | + { + "object": "list", + "data": [ + { + "id": "msg_abc123", + "type": "message", + "role": "user", + "content": [ + { + "type": "input_text", + "text": "Tell me a three sentence bedtime story about a unicorn." + } + ] + } + ], + "first_id": "msg_abc123", + "last_id": "msg_abc123", + "has_more": false + } + /responses/compact?beta=true: + post: + x-oaiMeta: + group: responses + examples: + request: + curl: | + curl -X POST https://api.openai.com/v1/responses/compact \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-6-astra", + "input": [ + { + "role": "user", + "content": "Create a simple landing page for a dog petting café." + }, + { + "id": "msg_001", + "type": "message", + "status": "completed", + "content": [ + { + "type": "output_text", + "annotations": [], + "logprobs": [], + "text": "Below is a single file, ready-to-use landing page for a dog petting café:..." + } + ], + "role": "assistant" + } + ] + }' + javascript: | + import OpenAI from "openai"; + + const openai = new OpenAI(); + + // Compact the previous response if you are running out of tokens + const compactedResponse = await openai.responses.compact({ + model: "gpt-6-astra", + input: [ + { + role: "user", + content: "Create a simple landing page for a dog petting café.", + }, + // All items returned from previous requests are included here, like reasoning, message, function call, etc. + { + id: "msg_030d085c0b53e67e0069332e3a72d4819c96c6f2c4adc15d33", + type: "message", + status: "completed", + content: [ + { + type: "output_text", + annotations: [], + logprobs: [], + text: "Below is a single file, ready-to-use landing page for a dog petting café:...", + }, + ], + role: "assistant", + }, + ], + }); + + // Pass the compactedResponse.output as input to the next request + console.log(compactedResponse); + python: | + from openai import OpenAI + + client = OpenAI() + + compacted_response = client.responses.compact( + model="gpt-6-astra", + input=[ + { + "role": "user", + "content": "Create a simple landing page for a dog petting cafe.", + }, + # All items returned from previous requests are included here, like reasoning, message, function call, etc. + { + "id": "msg_001", + "type": "message", + "status": "completed", + "content": [ + { + "type": "output_text", + "annotations": [], + "logprobs": [], + "text": "Below is a single file, ready-to-use landing page for a dog petting café:...", + }, + ], + "role": "assistant", + }, + ] + ) + # Pass the compacted_response.output as input to the next request + print(compacted_response) + response: | + { + "id": "resp_001", + "object": "response.compaction", + "created_at": 1764967971, + "output": [ + { + "id": "msg_000", + "type": "message", + "status": "completed", + "content": [ + { + "type": "input_text", + "text": "Create a simple landing page for a dog petting cafe." + } + ], + "role": "user" + }, + { + "id": "cmp_001", + "type": "compaction", + "encrypted_content": "gAAAAABpM0Yj-...=" + } + ], + "usage": { + "input_tokens": 139, + "input_tokens_details": { + "cached_tokens": 0, + "cache_write_tokens": 0 + }, + "output_tokens": 438, + "output_tokens_details": { + "reasoning_tokens": 64 + }, + "total_tokens": 577 + } + } + summary: Compact conversation + description: |- + Compact a conversation. Returns a compacted response object. + + Learn when and how to compact long-running conversations in the [conversation state guide](https://developers.openai.com/api/docs/guides/conversation-state#managing-the-context-window). For ZDR-compatible compaction details, see [Compaction (advanced)](https://developers.openai.com/api/docs/guides/conversation-state#compaction-advanced). + operationId: beta_Compactconversation + parameters: + - name: openai-beta + in: header + required: false + description: Optional beta features to enable for this request. + style: simple + explode: false + schema: + type: array + x-stainless-param: betas + items: + type: string + enum: + - responses_multi_agent=v1 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/BetaCompactResponseMethodPublicBody' + responses: + '200': + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/BetaCompactResource' + '400': + description: Invalid compaction request or incompatible input parameters. + content: + application/json: + schema: + $ref: '#/components/schemas/BetaErrorResponse' + '429': + $ref: '#/components/responses/InferenceRateLimited' + '503': + $ref: '#/components/responses/InferenceServiceUnavailable' /organization/spend_limit: get: summary: Get organization spend limit @@ -22702,6 +26999,18 @@ paths: application/json: schema: $ref: '#/components/schemas/OrganizationSpendLimitResource' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The organization does not have a hard spend limit. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -22741,6 +27050,18 @@ paths: application/json: schema: $ref: '#/components/schemas/OrganizationSpendLimitResource' + '400': + description: The requested spend limit is invalid or cannot be applied. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' x-oaiMeta: group: administration examples: @@ -22778,6 +27099,18 @@ paths: application/json: schema: $ref: '#/components/schemas/OrganizationSpendLimitDeletedResource' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The organization does not have a hard spend limit. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -22813,6 +27146,24 @@ paths: application/json: schema: $ref: '#/components/schemas/ProjectSpendLimitResource' + '400': + description: The project ID is invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The project was not found or does not have a hard spend limit. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -22852,6 +27203,24 @@ paths: application/json: schema: $ref: '#/components/schemas/ProjectSpendLimitDeletedResource' + '400': + description: The project ID is invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The project was not found or does not have a hard spend limit. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -22893,13 +27262,31 @@ paths: application/json: schema: $ref: '#/components/schemas/ProjectSpendLimitResource' - x-oaiMeta: - group: administration - examples: - request: - curl: | - curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/spend_limit \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + '400': + description: The requested spend limit is invalid or cannot be applied. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The project was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + x-oaiMeta: + group: administration + examples: + request: + curl: | + curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/spend_limit \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "threshold_amount": 10000, @@ -22951,6 +27338,36 @@ paths: application/json: schema: $ref: '#/components/schemas/ServiceAccountApiKeyBody' + '400': + description: The API key request is invalid or the project is archived. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: The caller does not have permission to perform this operation. + content: + application/json: + schema: + $ref: '#/components/schemas/PermissionErrorResponse' + '404': + description: The project or service account was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '409': + description: The service account already has an API key and cannot create another. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: Too many management requests. Reduce the request rate and try again later. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: administration examples: @@ -22994,8 +27411,32 @@ paths: application/json: schema: $ref: '#/components/schemas/ProvenanceResource' + '400': + description: The file is missing, invalid, unsupported, too large, or rejected by safety checks. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: Content provenance checks are unavailable to this caller. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' + '500': + description: The content provenance check could not be completed. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '503': + description: Content provenance inspection is temporarily unavailable. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: content_provenance_checks /videos: @@ -23018,8 +27459,26 @@ paths: application/json: schema: $ref: '#/components/schemas/VideoResource' + '400': + description: The video request is invalid, or the organization does not support video generation. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: A referenced character was not found or is not accessible, or the Videos API is unavailable. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/InferenceRateLimited' + '500': + description: The video generation task could not be created. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '503': $ref: '#/components/responses/InferenceServiceUnavailable' deprecated: true @@ -23144,6 +27603,18 @@ paths: application/json: schema: $ref: '#/components/schemas/VideoListResource' + '400': + description: The query parameters are invalid, or the organization does not support video generation. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The video specified by after was not found or is not accessible, or the Videos API is unavailable. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' deprecated: true x-oaiMeta: group: videos @@ -23246,6 +27717,30 @@ paths: application/json: schema: $ref: '#/components/schemas/VideoCharacterResource' + '400': + description: The character request or video upload is invalid, or the organization does not support video generation. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The video character endpoint is unavailable. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '500': + description: The character could not be created. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '504': + description: The character creation request timed out. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' deprecated: true /videos/characters/{character_id}: get: @@ -23269,6 +27764,18 @@ paths: application/json: schema: $ref: '#/components/schemas/VideoCharacterResource' + '400': + description: The character ID is invalid, or the organization does not support video generation. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The character was not found or is not accessible, or the video character endpoint is unavailable. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' deprecated: true /videos/edits: post: @@ -23290,8 +27797,26 @@ paths: application/json: schema: $ref: '#/components/schemas/VideoResource' + '400': + description: The edit request or source video is invalid, or the organization does not support video generation. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The source video or a referenced character was not found or is not accessible, the source video is not ready, or the Videos API is unavailable. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/InferenceRateLimited' + '500': + description: The source video media is unavailable or the edit task could not be created. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '503': $ref: '#/components/responses/InferenceServiceUnavailable' deprecated: true @@ -23315,8 +27840,26 @@ paths: application/json: schema: $ref: '#/components/schemas/VideoResource' + '400': + description: The extension request or source video is invalid, or the organization does not support video generation. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The source video was not found or is not accessible, the source video is not ready, or the Videos API is unavailable. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/InferenceRateLimited' + '500': + description: The source video media is unavailable or the extension task could not be created. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '503': $ref: '#/components/responses/InferenceServiceUnavailable' deprecated: true @@ -23342,6 +27885,18 @@ paths: application/json: schema: $ref: '#/components/schemas/VideoResource' + '400': + description: The request is invalid, or the organization does not support video generation. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The video was not found or is not accessible, or the Videos API is unavailable. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' deprecated: true x-oaiMeta: group: videos @@ -23429,6 +27984,24 @@ paths: application/json: schema: $ref: '#/components/schemas/DeletedVideoResource' + '400': + description: The video is still being processed, the request is invalid, or the organization does not support video generation. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The video was not found or is not accessible, or the Videos API is unavailable. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '500': + description: The video or its stored media could not be deleted. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' deprecated: true x-oaiMeta: group: videos @@ -23534,6 +28107,24 @@ paths: application/json: schema: type: string + '400': + description: The request or content variant is invalid, or the organization does not support video generation. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The video was not found or is not ready, its download is unavailable or expired, or the Videos API is unavailable. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '500': + description: The requested video media is unavailable. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' deprecated: true x-oaiMeta: group: videos @@ -23641,8 +28232,26 @@ paths: application/json: schema: $ref: '#/components/schemas/VideoResource' + '400': + description: The request or source video is not supported for remixing, or the organization does not support video generation. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The source video or a referenced character was not found or is not accessible, the source video is not ready, or the Videos API is unavailable. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/InferenceRateLimited' + '500': + description: The source generation is unavailable or the remix task could not be created. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '503': $ref: '#/components/responses/InferenceServiceUnavailable' deprecated: true @@ -23742,27 +28351,6 @@ paths: } /responses/input_tokens: post: - summary: Get input token counts - description: |- - Returns input token counts of the request. - - Returns an object with `object` set to `response.input_tokens` and an `input_tokens` count. - operationId: Getinputtokencounts - parameters: [] - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/TokenCountsBody' - responses: - '200': - description: Success - content: - application/json: - schema: - $ref: '#/components/schemas/TokenCountsResource' - '429': - $ref: '#/components/responses/TooManyRequests' x-oaiMeta: group: responses examples: @@ -23853,31 +28441,35 @@ paths: "object": "response.input_tokens", "input_tokens": 11 } - /responses/compact: - post: - summary: Compact conversation + summary: Get input token counts description: |- - Compact a conversation. Returns a compacted response object. + Returns input token counts of the request. - Learn when and how to compact long-running conversations in the [conversation state guide](https://developers.openai.com/api/docs/guides/conversation-state#managing-the-context-window). For ZDR-compatible compaction details, see [Compaction (advanced)](https://developers.openai.com/api/docs/guides/conversation-state#compaction-advanced). - operationId: Compactconversation + Returns an object with `object` set to `response.input_tokens` and an `input_tokens` count. + operationId: Getinputtokencounts parameters: [] requestBody: content: application/json: schema: - $ref: '#/components/schemas/CompactResponseMethodPublicBody' + $ref: '#/components/schemas/TokenCountsBody' responses: '200': description: Success content: application/json: schema: - $ref: '#/components/schemas/CompactResource' + $ref: '#/components/schemas/TokenCountsResource' + '400': + description: The request to count input tokens is invalid or contains incompatible parameters. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': - $ref: '#/components/responses/InferenceRateLimited' - '503': - $ref: '#/components/responses/InferenceServiceUnavailable' + $ref: '#/components/responses/TooManyRequests' + /responses/compact: + post: x-oaiMeta: group: responses examples: @@ -24010,6 +28602,35 @@ paths: "total_tokens": 577 } } + summary: Compact conversation + description: |- + Compact a conversation. Returns a compacted response object. + + Learn when and how to compact long-running conversations in the [conversation state guide](https://developers.openai.com/api/docs/guides/conversation-state#managing-the-context-window). For ZDR-compatible compaction details, see [Compaction (advanced)](https://developers.openai.com/api/docs/guides/conversation-state#compaction-advanced). + operationId: Compactconversation + parameters: [] + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CompactResponseMethodPublicBody' + responses: + '200': + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/CompactResource' + '400': + description: Invalid compaction request or incompatible input parameters. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + $ref: '#/components/responses/InferenceRateLimited' + '503': + $ref: '#/components/responses/InferenceServiceUnavailable' /skills: post: tags: @@ -24033,8 +28654,20 @@ paths: application/json: schema: $ref: '#/components/schemas/SkillResource' + '400': + description: The uploaded skill files or archive are invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' + '500': + description: The skill could not be saved. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' get: tags: - Skills @@ -24070,6 +28703,12 @@ paths: application/json: schema: $ref: '#/components/schemas/SkillListResource' + '404': + description: The skill specified by `after` was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' /skills/{skill_id}: @@ -24094,6 +28733,12 @@ paths: application/json: schema: $ref: '#/components/schemas/DeletedSkillResource' + '404': + description: The skill was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' get: @@ -24117,6 +28762,12 @@ paths: application/json: schema: $ref: '#/components/schemas/SkillResource' + '404': + description: The skill was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' post: @@ -24145,6 +28796,18 @@ paths: application/json: schema: $ref: '#/components/schemas/SkillResource' + '400': + description: The requested version is invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The skill or requested skill version was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' /skills/{skill_id}/content: @@ -24173,6 +28836,12 @@ paths: application/json: schema: type: string + '404': + description: The skill was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' /skills/{skill_id}/versions: @@ -24205,8 +28874,26 @@ paths: application/json: schema: $ref: '#/components/schemas/SkillVersionResource' + '400': + description: The uploaded skill files or archive are invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The skill was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' + '500': + description: The skill version could not be saved. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' get: tags: - Skills @@ -24249,6 +28936,18 @@ paths: application/json: schema: $ref: '#/components/schemas/SkillVersionListResource' + '400': + description: The version specified by `after` does not belong to this skill. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The skill or the version specified by `after` was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' /skills/{skill_id}/versions/{version}: @@ -24280,6 +28979,18 @@ paths: application/json: schema: $ref: '#/components/schemas/SkillVersionResource' + '400': + description: The requested version is invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The skill or requested skill version was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' delete: @@ -24310,6 +29021,18 @@ paths: application/json: schema: $ref: '#/components/schemas/DeletedSkillVersionResource' + '400': + description: The requested version is invalid, or it is the default version and other versions remain. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The skill or requested skill version was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' /skills/{skill_id}/versions/{version}/content: @@ -24345,6 +29068,18 @@ paths: application/json: schema: type: string + '400': + description: The requested version is invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The skill or requested skill version was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' /chatkit/sessions/{session_id}/cancel: @@ -24370,6 +29105,24 @@ paths: application/json: schema: $ref: '#/components/schemas/ChatSessionResource' + '400': + description: The request is invalid or the required ChatKit beta header is missing or invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The session was not found or is not accessible. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: The request rate limit has been exceeded. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: chatkit beta: true @@ -24475,6 +29228,24 @@ paths: application/json: schema: $ref: '#/components/schemas/ChatSessionResource' + '400': + description: The request is invalid or the required ChatKit beta header is missing or invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The requested workflow or workflow version was not found or is not accessible. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: The request rate limit has been exceeded. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: chatkit beta: true @@ -24638,6 +29409,24 @@ paths: application/json: schema: $ref: '#/components/schemas/ThreadItemListResource' + '400': + description: The request is invalid or the required ChatKit beta header is missing or invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The thread was not found or is not accessible. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: The request rate limit has been exceeded. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: chatkit beta: true @@ -24766,6 +29555,24 @@ paths: application/json: schema: $ref: '#/components/schemas/ThreadResource' + '400': + description: The request is invalid or the required ChatKit beta header is missing or invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The thread was not found or is not accessible. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: The request rate limit has been exceeded. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: chatkit beta: true @@ -24888,6 +29695,24 @@ paths: application/json: schema: $ref: '#/components/schemas/DeletedThreadResource' + '400': + description: The request is invalid or the required ChatKit beta header is missing or invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The thread was not found or is not accessible. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: The request rate limit has been exceeded. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: beta: true examples: @@ -25004,6 +29829,24 @@ paths: application/json: schema: $ref: '#/components/schemas/ThreadListResource' + '400': + description: The request is invalid or the required ChatKit beta header is missing or invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The thread specified by after was not found or is not accessible. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '429': + description: The request rate limit has been exceeded. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: group: chatkit beta: true @@ -25127,6 +29970,12 @@ paths: 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: @@ -25221,6 +30070,12 @@ paths: 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: @@ -25284,6 +30139,12 @@ paths: 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: @@ -25946,6 +30807,12 @@ paths: 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: @@ -26000,6 +30867,12 @@ paths: 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: @@ -26059,6 +30932,12 @@ paths: 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: @@ -26122,6 +31001,12 @@ paths: 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: @@ -26180,6 +31065,12 @@ paths: 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: @@ -27496,6 +32387,12 @@ paths: 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: @@ -27563,6 +32460,12 @@ paths: 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: @@ -28283,6 +33186,18 @@ paths: application/json: schema: $ref: '#/components/schemas/WebhookEndpointListResource' + '400': + description: The request parameters are invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The pagination cursor does not identify a webhook endpoint in the authenticated project. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: beta: true post: @@ -28302,6 +33217,12 @@ paths: application/json: schema: $ref: '#/components/schemas/WebhookEndpointWithSecretResource' + '400': + description: The webhook endpoint parameters are invalid or the endpoint cannot be created with the requested URL or event types. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: beta: true /webhook_endpoints/{webhook_endpoint_id}: @@ -28324,6 +33245,18 @@ paths: application/json: schema: $ref: '#/components/schemas/WebhookEndpointBody' + '400': + description: The request parameters are invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The webhook endpoint was not found in the authenticated project. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: beta: true post: @@ -28350,6 +33283,18 @@ paths: application/json: schema: $ref: '#/components/schemas/WebhookEndpointBody' + '400': + description: The webhook endpoint parameters are invalid or the requested URL or event types are not permitted. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The webhook endpoint was not found in the authenticated project. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: beta: true delete: @@ -28371,6 +33316,18 @@ paths: application/json: schema: $ref: '#/components/schemas/DeletedWebhookEndpointResource' + '400': + description: The request parameters are invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The webhook endpoint was not found in the authenticated project. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: beta: true /webhook_endpoints/{webhook_endpoint_id}/rotate_secret: @@ -28398,6 +33355,18 @@ paths: application/json: schema: $ref: '#/components/schemas/WebhookEndpointWithSecretResource' + '400': + description: The request parameters are invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The webhook endpoint was not found in the authenticated project. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: beta: true /webhook_endpoints/{webhook_endpoint_id}/test: @@ -28425,6 +33394,24 @@ paths: application/json: schema: $ref: '#/components/schemas/WebhookEndpointTestResultResource' + '400': + description: The request parameters are invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The webhook endpoint was not found in the authenticated project. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '500': + description: The sample event could not be sent to the webhook endpoint. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: beta: true /webhook_event_types: @@ -28440,6 +33427,18 @@ paths: application/json: schema: $ref: '#/components/schemas/WebhookEventTypeListResource' + '401': + description: The request does not contain authentication credentials. + headers: + WWW-Authenticate: + description: The bearer authentication challenge returned by the service. + schema: + type: string + example: Bearer realm="OpenAI API" + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' x-oaiMeta: beta: true /responses?beta=true: @@ -28472,6 +33471,18 @@ paths: text/event-stream: schema: $ref: '#/components/schemas/BetaResponseStreamEvent' + '400': + description: Invalid response request or incompatible request parameters. + content: + application/json: + schema: + $ref: '#/components/schemas/BetaErrorResponse' + '404': + description: The requested model or a referenced resource was not found or is unavailable to this caller. + content: + application/json: + schema: + $ref: '#/components/schemas/BetaErrorResponse' '429': $ref: '#/components/responses/InferenceRateLimited' '503': @@ -29741,6 +34752,12 @@ paths: application/json: schema: $ref: '#/components/schemas/BetaResponse' + '404': + description: The response was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/BetaErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -29858,7 +34875,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/BetaError' + $ref: '#/components/schemas/BetaErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -29887,578 +34904,56 @@ paths: "object": "response", "deleted": true } - /responses/{response_id}/cancel?beta=true: +webhooks: + batch_cancelled: post: - operationId: beta_cancelResponse - tags: - - Responses - summary: Cancel a response description: | - Cancels a model response with the given ID. Only responses created with - the `background` parameter set to `true` can be cancelled. - [Learn more](https://developers.openai.com/api/docs/guides/background). - parameters: - - in: path - name: response_id - required: true - schema: - type: string - example: resp_677efb5139a88190b512bc3fef8e535d - description: The ID of the response to cancel. - - name: openai-beta - in: header - required: false - description: Optional beta features to enable for this request. - style: simple - explode: false - schema: - type: array - x-stainless-param: betas - items: - type: string - enum: - - responses_multi_agent=v1 + Sent when a batch has been cancelled. + requestBody: + description: The event payload sent by the API. + content: + application/json: + schema: + $ref: '#/components/schemas/WebhookBatchCancelled' responses: '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/BetaResponse' - '404': - description: Not Found - content: - application/json: - schema: - $ref: '#/components/schemas/BetaError' - '429': - $ref: '#/components/responses/TooManyRequests' - x-oaiMeta: - group: responses - examples: - request: - curl: | - curl -X POST https://api.openai.com/v1/responses/resp_123/cancel \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" - javascript: | - import OpenAI from "openai"; - const client = new OpenAI(); - - const response = await client.responses.cancel("resp_123"); - console.log(response); - python: | - from openai import OpenAI - client = OpenAI() - - response = client.responses.cancel("resp_123") - print(response) - response: | - { - "id": "resp_67cb71b351908190a308f3859487620d06981a8637e6bc44", - "object": "response", - "created_at": 1741386163, - "status": "cancelled", - "background": true, - "completed_at": null, - "error": null, - "incomplete_details": null, - "instructions": null, - "max_output_tokens": null, - "model": "gpt-6-astra", - "output": [ - { - "type": "message", - "id": "msg_67cb71b3c2b0819084d481baaaf148f206981a8637e6bc44", - "status": "in_progress", - "role": "assistant", - "content": [ - { - "type": "output_text", - "text": "Silent circuits hum, \nThoughts emerge in data streams— \nDigital dawn breaks.", - "annotations": [] - } - ] - } - ], - "parallel_tool_calls": true, - "previous_response_id": null, - "reasoning": { - "effort": null, - "summary": null - }, - "store": true, - "temperature": 1.0, - "text": { - "format": { - "type": "text" - } - }, - "tool_choice": "auto", - "tools": [], - "top_p": 1.0, - "truncation": "disabled", - "usage": null, - "user": null, - "metadata": {} - } - /responses/compact?beta=true: + description: "Return a 200 status code to acknowledge receipt of the event. Non-200 \nstatus codes will be retried.\n" + batch_completed: post: - summary: Compact conversation - description: |- - Compact a conversation. Returns a compacted response object. - - Learn when and how to compact long-running conversations in the [conversation state guide](https://developers.openai.com/api/docs/guides/conversation-state#managing-the-context-window). For ZDR-compatible compaction details, see [Compaction (advanced)](https://developers.openai.com/api/docs/guides/conversation-state#compaction-advanced). - operationId: beta_Compactconversation - parameters: - - name: openai-beta - in: header - required: false - description: Optional beta features to enable for this request. - style: simple - explode: false - schema: - type: array - x-stainless-param: betas - items: - type: string - enum: - - responses_multi_agent=v1 + description: | + Sent when a batch has completed processing. requestBody: + description: The event payload sent by the API. content: application/json: schema: - $ref: '#/components/schemas/BetaCompactResponseMethodPublicBody' + $ref: '#/components/schemas/WebhookBatchCompleted' responses: '200': - description: Success - content: - application/json: - schema: - $ref: '#/components/schemas/BetaCompactResource' - '429': - $ref: '#/components/responses/InferenceRateLimited' - '503': - $ref: '#/components/responses/InferenceServiceUnavailable' - x-oaiMeta: - group: responses - examples: - request: - curl: | - curl -X POST https://api.openai.com/v1/responses/compact \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -d '{ - "model": "gpt-6-astra", - "input": [ - { - "role": "user", - "content": "Create a simple landing page for a dog petting café." - }, - { - "id": "msg_001", - "type": "message", - "status": "completed", - "content": [ - { - "type": "output_text", - "annotations": [], - "logprobs": [], - "text": "Below is a single file, ready-to-use landing page for a dog petting café:..." - } - ], - "role": "assistant" - } - ] - }' - javascript: | - import OpenAI from "openai"; - - const openai = new OpenAI(); - - // Compact the previous response if you are running out of tokens - const compactedResponse = await openai.responses.compact({ - model: "gpt-6-astra", - input: [ - { - role: "user", - content: "Create a simple landing page for a dog petting café.", - }, - // All items returned from previous requests are included here, like reasoning, message, function call, etc. - { - id: "msg_030d085c0b53e67e0069332e3a72d4819c96c6f2c4adc15d33", - type: "message", - status: "completed", - content: [ - { - type: "output_text", - annotations: [], - logprobs: [], - text: "Below is a single file, ready-to-use landing page for a dog petting café:...", - }, - ], - role: "assistant", - }, - ], - }); - - // Pass the compactedResponse.output as input to the next request - console.log(compactedResponse); - python: | - from openai import OpenAI - - client = OpenAI() - - compacted_response = client.responses.compact( - model="gpt-6-astra", - input=[ - { - "role": "user", - "content": "Create a simple landing page for a dog petting cafe.", - }, - # All items returned from previous requests are included here, like reasoning, message, function call, etc. - { - "id": "msg_001", - "type": "message", - "status": "completed", - "content": [ - { - "type": "output_text", - "annotations": [], - "logprobs": [], - "text": "Below is a single file, ready-to-use landing page for a dog petting café:...", - }, - ], - "role": "assistant", - }, - ] - ) - # Pass the compacted_response.output as input to the next request - print(compacted_response) - response: | - { - "id": "resp_001", - "object": "response.compaction", - "created_at": 1764967971, - "output": [ - { - "id": "msg_000", - "type": "message", - "status": "completed", - "content": [ - { - "type": "input_text", - "text": "Create a simple landing page for a dog petting cafe." - } - ], - "role": "user" - }, - { - "id": "cmp_001", - "type": "compaction", - "encrypted_content": "gAAAAABpM0Yj-...=" - } - ], - "usage": { - "input_tokens": 139, - "input_tokens_details": { - "cached_tokens": 0, - "cache_write_tokens": 0 - }, - "output_tokens": 438, - "output_tokens_details": { - "reasoning_tokens": 64 - }, - "total_tokens": 577 - } - } - /responses/{response_id}/input_items?beta=true: - get: - operationId: beta_listInputItems - tags: - - Responses - summary: List input items - description: Returns a list of input items for a given response. - parameters: - - in: path - name: response_id - required: true - schema: - type: string - description: The ID of the response to retrieve input items for. - - name: limit - in: query - description: | - A limit on the number of objects to be returned. Limit can range between - 1 and 100, and the default is 20. - required: false - schema: - type: integer - default: 20 - - in: query - name: order - schema: - type: string - enum: - - asc - - desc - description: | - The order to return the input items in. Default is `desc`. - - `asc`: Return the input items in ascending order. - - `desc`: Return the input items in descending order. - - in: query - name: after - schema: - type: string - description: | - An item ID to list items after, used in pagination. - - in: query - name: include - schema: - type: array - items: - $ref: '#/components/schemas/BetaIncludeEnum' - description: | - Additional fields to include in the response. See the `include` - parameter for Response creation above for more information. - - name: openai-beta - in: header - required: false - description: Optional beta features to enable for this request. - style: simple - explode: false - schema: - type: array - x-stainless-param: betas - items: - type: string - enum: - - responses_multi_agent=v1 + description: "Return a 200 status code to acknowledge receipt of the event. Non-200 \nstatus codes will be retried.\n" + batch_expired: + post: + description: | + Sent when a batch has expired before completion. + requestBody: + description: The event payload sent by the API. + content: + application/json: + schema: + $ref: '#/components/schemas/WebhookBatchExpired' responses: '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/BetaResponseItemList' - '429': - $ref: '#/components/responses/TooManyRequests' - x-oaiMeta: - group: responses - examples: - request: - curl: | - curl https://api.openai.com/v1/responses/resp_abc123/input_items \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" - javascript: | - import OpenAI from "openai"; - const client = new OpenAI(); - - const response = await client.responses.inputItems.list("resp_123"); - console.log(response.data); - python: | - from openai import OpenAI - client = OpenAI() - - response = client.responses.input_items.list("resp_123") - print(response.data) - response: | - { - "object": "list", - "data": [ - { - "id": "msg_abc123", - "type": "message", - "role": "user", - "content": [ - { - "type": "input_text", - "text": "Tell me a three sentence bedtime story about a unicorn." - } - ] - } - ], - "first_id": "msg_abc123", - "last_id": "msg_abc123", - "has_more": false - } - /responses/input_tokens?beta=true: + description: "Return a 200 status code to acknowledge receipt of the event. Non-200 \nstatus codes will be retried.\n" + batch_failed: post: - summary: Get input token counts - description: |- - Returns input token counts of the request. - - Returns an object with `object` set to `response.input_tokens` and an `input_tokens` count. - operationId: beta_Getinputtokencounts - parameters: - - name: openai-beta - in: header - required: false - description: Optional beta features to enable for this request. - style: simple - explode: false - schema: - type: array - x-stainless-param: betas - items: - type: string - enum: - - responses_multi_agent=v1 + description: | + Sent when a batch has failed. requestBody: + description: The event payload sent by the API. content: application/json: schema: - $ref: '#/components/schemas/BetaTokenCountsBody' - responses: - '200': - description: Success - content: - application/json: - schema: - $ref: '#/components/schemas/BetaTokenCountsResource' - '429': - $ref: '#/components/responses/TooManyRequests' - x-oaiMeta: - group: responses - examples: - request: - curl: | - curl -X POST https://api.openai.com/v1/responses/input_tokens \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -d '{ - "model": "gpt-6-astra", - "input": "Tell me a joke." - }' - javascript: | - import OpenAI from "openai"; - - const client = new OpenAI(); - - const response = await client.responses.inputTokens.count({ - model: "gpt-6-astra", - input: "Tell me a joke.", - }); - - console.log(response.input_tokens); - python: | - from openai import OpenAI - - client = OpenAI() - - response = client.responses.input_tokens.count( - model="gpt-6-astra", - input="Tell me a joke." - ) - print(response.input_tokens) - go: | - package main - - import ( - "context" - "fmt" - - "github.com/openai/openai-go" - "github.com/openai/openai-go/responses" - ) - - func main() { - client := openai.NewClient() - response, err := client.Responses.InputTokens.Count(context.TODO(), responses.InputTokenCountParams{ - Model: "gpt-6-astra", - Input: "Tell me a joke.", - }) - if err != nil { - panic(err.Error()) - } - fmt.Printf("%+v\n", response.InputTokens) - } - ruby: | - require "openai" - - openai = OpenAI::Client.new - - response = openai.responses.input_tokens.count(model: "gpt-6-astra", input: "Tell me a joke.") - - puts(response) - java: | - package com.openai.example; - - import com.openai.client.OpenAIClient; - import com.openai.client.okhttp.OpenAIOkHttpClient; - import com.openai.models.responses.inputtokens.InputTokenCountParams; - import com.openai.models.responses.inputtokens.InputTokenCountResponse; - - public final class Main { - private Main() {} - - public static void main(String[] args) { - OpenAIClient client = OpenAIOkHttpClient.fromEnv(); - - InputTokenCountParams params = InputTokenCountParams.builder() - .model("gpt-6-astra") - .input("Tell me a joke.") - .build(); - - InputTokenCountResponse response = client.responses().inputTokens().count(params); - } - } - response: | - { - "object": "response.input_tokens", - "input_tokens": 11 - } -webhooks: - batch_cancelled: - post: - description: | - Sent when a batch has been cancelled. - requestBody: - description: The event payload sent by the API. - content: - application/json: - schema: - $ref: '#/components/schemas/WebhookBatchCancelled' - responses: - '200': - description: "Return a 200 status code to acknowledge receipt of the event. Non-200 \nstatus codes will be retried.\n" - batch_completed: - post: - description: | - Sent when a batch has completed processing. - requestBody: - description: The event payload sent by the API. - content: - application/json: - schema: - $ref: '#/components/schemas/WebhookBatchCompleted' - responses: - '200': - description: "Return a 200 status code to acknowledge receipt of the event. Non-200 \nstatus codes will be retried.\n" - batch_expired: - post: - description: | - Sent when a batch has expired before completion. - requestBody: - description: The event payload sent by the API. - content: - application/json: - schema: - $ref: '#/components/schemas/WebhookBatchExpired' - responses: - '200': - description: "Return a 200 status code to acknowledge receipt of the event. Non-200 \nstatus codes will be retried.\n" - batch_failed: - post: - description: | - Sent when a batch has failed. - requestBody: - description: The event payload sent by the API. - content: - application/json: - schema: - $ref: '#/components/schemas/WebhookBatchFailed' + $ref: '#/components/schemas/WebhookBatchFailed' responses: '200': description: "Return a 200 status code to acknowledge receipt of the event. Non-200 \nstatus codes will be retried.\n" @@ -31452,6 +35947,36 @@ components: id: type: string description: The ID of the external key configuration. + certificates.deactivated: + type: object + description: The details for events with this `type`. + properties: + certificates: + type: array + items: + type: object + properties: + id: + type: string + description: The certificate ID. + name: + type: string + description: The name of the certificate. + certificates.activated: + type: object + description: The details for events with this `type`. + properties: + certificates: + type: array + items: + type: object + properties: + id: + type: string + description: The certificate ID. + name: + type: string + description: The name of the certificate. group.created: type: object description: The details for events with this `type`. @@ -32106,36 +36631,6 @@ components: certificate: type: string description: The certificate content in PEM format. - certificates.activated: - type: object - description: The details for events with this `type`. - properties: - certificates: - type: array - items: - type: object - properties: - id: - type: string - description: The certificate ID. - name: - type: string - description: The name of the certificate. - certificates.deactivated: - type: object - description: The details for events with this `type`. - properties: - certificates: - type: array - items: - type: object - properties: - id: - type: string - description: The certificate ID. - name: - type: string - description: The name of the certificate. required: - id - type @@ -66130,6 +70625,40 @@ components: "type": "safety.alert.created", "data": {"id": "alert_0123456789abcdef0123456789abcdef"} } + BetaInputAudio: + type: object + title: Input audio + description: | + An audio input to the model. + properties: + type: + type: string + description: | + The type of the input item. Always `input_audio`. + enum: + - input_audio + x-stainless-const: true + input_audio: + type: object + properties: + data: + type: string + description: | + Base64-encoded audio data. + format: + type: string + description: | + The format of the audio data. Currently supported formats are `mp3` and + `wav`. + enum: + - mp3 + - wav + required: + - data + - format + required: + - type + - input_audio WebhookSafetyOrgAlertCreated: type: object title: safety.org_alert.created @@ -66181,6 +70710,61 @@ components: "type": "safety.org_alert.created", "data": {"id": "alert_0123456789abcdef0123456789abcdef"} } + BetaOutputAudio: + type: object + title: Output audio + description: | + An audio output from the model. + properties: + type: + type: string + description: | + The type of the output audio. Always `output_audio`. + enum: + - output_audio + x-stainless-const: true + data: + type: string + description: | + Base64-encoded audio data from the model. + transcript: + type: string + description: | + The transcript of the audio data from the model. + required: + - type + - data + - transcript + _MisalignmentErrorType: + anyOf: + - type: string + - type: string + enum: + - potentially_unintended_data_transfer + - potentially_unintended_data_access + - potentially_unintended_destructive_activity + - other + _MisalignmentSteer: + properties: + message: + type: string + description: The public continuation instruction. + type: object + required: + - message + MisalignmentErrorDetailsResource: + properties: + error_type: + $ref: '#/components/schemas/_MisalignmentErrorType' + description: An optional classification; clients must accept additional values. + detailed_explanation: + type: string + description: The public explanation for this block. + steer: + $ref: '#/components/schemas/_MisalignmentSteer' + description: An optional public continuation instruction. + type: object + required: [] ModerationInputType: type: string enum: @@ -69657,36 +74241,6 @@ components: - object - metadata - created_at - _MisalignmentErrorType: - anyOf: - - type: string - - type: string - enum: - - potentially_unintended_data_transfer - - potentially_unintended_data_access - - potentially_unintended_destructive_activity - - other - _MisalignmentSteer: - properties: - message: - type: string - description: The public continuation instruction. - type: object - required: - - message - MisalignmentErrorDetailsResource: - properties: - error_type: - $ref: '#/components/schemas/_MisalignmentErrorType' - description: An optional classification; clients must accept additional values. - detailed_explanation: - type: string - description: The public explanation for this block. - steer: - $ref: '#/components/schemas/_MisalignmentSteer' - description: An optional public continuation instruction. - type: object - required: [] ImageGenOutputTokensDetails: properties: image_tokens: @@ -70339,22942 +74893,16786 @@ components: URI that should appear in the SIP Refer-To header. Supports values like `tel:+14155550123` or `sip:agent@example.com`. example: tel:+14155550123 - PublicProjectResidency: - type: string - enum: - - GLOBAL - - US_STORAGE_PROCESSING - - EU_STORAGE_PROCESSING - - JP_STORAGE - - KR_STORAGE - - CA_STORAGE - - SG_STORAGE - - IN_STORAGE - - AU_STORAGE - - GB_STORAGE - - AE_STORAGE - - AE_STORAGE_PROCESSING - SpecificProgrammaticToolCallingParam: - properties: - type: - type: string - enum: - - programmatic_tool_calling - description: The tool to call. Always `programmatic_tool_calling`. - default: programmatic_tool_calling - x-stainless-const: true - type: object - required: - - type - SpecificApplyPatchParam: - properties: - type: - type: string - enum: - - apply_patch - description: The tool to call. Always `apply_patch`. - default: apply_patch - x-stainless-const: true - type: object - required: - - type - title: Specific apply patch tool choice - description: Forces the model to call the apply_patch tool when executing a tool call. - SpecificFunctionShellParam: - properties: - type: - type: string - enum: - - shell - description: The tool to call. Always `shell`. - default: shell - x-stainless-const: true - type: object - required: - - type - title: Specific shell tool choice - description: Forces the model to call the shell tool when a tool call is required. - ResponsePromptCacheOptionsParam: - properties: - ttl: - $ref: '#/components/schemas/PromptCacheTTLEnum' - description: The minimum lifetime applied to every implicit and explicit cache breakpoint written by the request. Defaults to `30m`, which is currently the only supported value. The backend may retain cache entries for longer. - mode: - $ref: '#/components/schemas/PromptCacheModeEnum' - description: Controls whether OpenAI automatically creates an implicit cache breakpoint. Defaults to `implicit`. With `implicit`, OpenAI creates one implicit breakpoint and writes up to the latest three explicit breakpoints in the request. With `explicit`, OpenAI does not create an implicit breakpoint and writes up to the latest four explicit breakpoints. If there are no explicit breakpoints, the request does not use prompt caching. - prewarm: - type: boolean - description: Prepares the prompt cache without generating output. Defaults to `false`. When set to `true`, overrides the `generate` field to `false`. - comparison_response_id: - anyOf: - - type: string - description: The ID of a response to compare when diagnosing prompt cache reuse. Supplying this field requests prompt cache diagnostics when the feature is enabled. - example: resp_123 - - type: 'null' - type: object - required: [] - title: Prompt cache options - description: Options for prompt caching. Supported for `gpt-5.6` and later models. By default, OpenAI automatically chooses one implicit cache breakpoint. You can add explicit breakpoints to content blocks with `prompt_cache_breakpoint`. Each request can write up to four breakpoints. For cache matching, OpenAI considers up to the latest 80 breakpoints in the conversation, without a content-block lookback limit. Set `mode` to `explicit` to disable the implicit breakpoint. The `ttl` defaults to `30m`, which is currently the only supported value. See the [prompt caching guide](https://developers.openai.com/api/docs/guides/prompt-caching) for current details. - ReasoningModeEnum: - anyOf: - - type: string - - type: string - enum: - - standard - - pro - ConversationParam-2: - properties: - id: - type: string - description: The unique ID of the conversation. - example: conv_123 - type: object - required: - - id - title: Conversation object - description: The conversation that this response belongs to. - ContextManagementParam: - properties: - type: - type: string - description: The context management entry type. Currently only 'compaction' is supported. - compact_threshold: - anyOf: - - type: integer - minimum: 1000 - description: Token threshold at which compaction should be triggered for this entry. - - type: 'null' - type: object - required: - - type - PromptCacheOptions: - properties: - ttl: - $ref: '#/components/schemas/PromptCacheTTLEnum' - description: The minimum lifetime applied to each cache breakpoint. - mode: - $ref: '#/components/schemas/PromptCacheModeEnum' - description: Whether implicit prompt-cache breakpoints were enabled. - comparison_response_id: - anyOf: - - type: string - description: The response ID supplied as the prompt cache diagnostics comparison. - - type: 'null' - type: object - required: - - ttl - - mode - title: Prompt cache options - description: The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - CacheMissReasonTypeEnum: - type: string - enum: - - model_changed - - prompt_cache_key_changed - - tools_changed - - text_format_changed - - reasoning_effort_changed - - verbosity_changed - - context_compacted - - input_changed - - service_tier_changed - PromptCacheMissDiagnosticsBody: - properties: - type: - type: string - enum: - - cache_miss - default: cache_miss - x-stainless-const: true - reason: - $ref: '#/components/schemas/CacheMissReasonTypeEnum' - description: The reason prompt cache reuse did not occur. - cache_missed_tokens: - type: integer - description: The estimated number of input tokens affected after the first detected divergence. - comparison_reusable_tokens: - type: integer - description: The raw token count of the reusable prefix in the compared response. - type: object - required: - - type - - reason - - cache_missed_tokens - PromptCacheHitDiagnosticsBody: - properties: - type: - type: string - enum: - - cache_hit - default: cache_hit - x-stainless-const: true + BetaCreateResponse: + allOf: + - $ref: '#/components/schemas/BetaCreateModelResponseProperties' + - $ref: '#/components/schemas/BetaResponseProperties' + - type: object + properties: + prompt_cache_options: + $ref: '#/components/schemas/BetaResponsePromptCacheOptionsParam' + service_tier: + $ref: '#/components/schemas/BetaServiceTierResponses' + truncation: + deprecated: true + anyOf: + - type: string + description: | + The truncation strategy to use for the model response. + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. + enum: + - auto + - disabled + default: disabled + - type: 'null' + reasoning: + anyOf: + - $ref: '#/components/schemas/BetaReasoning' + - type: 'null' + input: + $ref: '#/components/schemas/BetaInputParam' + include: + anyOf: + - type: array + description: |- + Specify additional output data to include in the model response. Currently supported values are: + - `web_search_call.action.sources`: Include the sources of the web search tool call. + - `code_interpreter_call.outputs`: Includes the outputs of python code execution in code interpreter tool call items. + - `computer_call_output.output.image_url`: Include image urls from the computer call output. + - `file_search_call.results`: Include the search results of the file search tool call. + - `message.input_image.image_url`: Include image urls from the input message. + - `message.output_text.logprobs`: Include logprobs with assistant messages. + - `reasoning.encrypted_content`: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the `store` parameter is set to `false`, or when an organization is enrolled in the zero data retention program). + items: + $ref: '#/components/schemas/BetaIncludeEnum' + - type: 'null' + parallel_tool_calls: + anyOf: + - type: boolean + description: | + Whether to allow the model to run tool calls in parallel. + default: true + - type: 'null' + store: + anyOf: + - type: boolean + description: | + Whether to store the generated model response for later retrieval via + API. + Defaults to true when omitted. + If set to true, response data will be stored for at least 30 days, subject to the [data retention exceptions](https://developers.openai.com/api/docs/guides/your-data#v1responses). + default: true + - type: 'null' + instructions: + anyOf: + - type: string + description: | + A system (or developer) message inserted into the model's context. + + When using along with `previous_response_id`, the instructions from a previous + response will not be carried over to the next response. This makes it simple + to swap out system (or developer) messages in new responses. + - type: 'null' + moderation: + anyOf: + - $ref: '#/components/schemas/BetaModerationParam' + description: | + Configuration for running moderation on the input and output of this response. + - type: 'null' + stream: + anyOf: + - description: | + If set to true, the model response data will be streamed to the client + as it is generated using [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format). + See the [Streaming section below](https://developers.openai.com/api/reference/resources/responses/streaming-events) + for more information. + type: boolean + default: false + - type: 'null' + stream_options: + $ref: '#/components/schemas/BetaResponseStreamOptions' + conversation: + anyOf: + - $ref: '#/components/schemas/BetaConversationParam' + - type: 'null' + context_management: + anyOf: + - type: array + example: + - type: compaction + compact_threshold: 1000 + description: | + Context management configuration for this request. + minItems: 1 + items: + $ref: '#/components/schemas/BetaContextManagementParam' + - type: 'null' + max_output_tokens: + anyOf: + - description: | + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://developers.openai.com/api/docs/guides/reasoning). + type: integer + minimum: 16 + - type: 'null' + multi_agent: + anyOf: + - $ref: '#/components/schemas/BetaMultiAgentParam' + description: Configuration for server-hosted multi-agent execution. + - type: 'null' + BetaResponseInjectEvent: type: object - required: - - type - PromptCacheComparisonResponseNotFoundDiagnosticsBody: + title: ResponseInjectEvent + description: | + Injects input items into an active response over a WebSocket connection. + The items are validated and committed atomically. Currently, the server + accepts client-owned tool outputs that resume a waiting agent. properties: type: type: string enum: - - comparison_response_not_found - default: comparison_response_not_found + - response.inject + description: The event discriminator. Always `response.inject`. x-stainless-const: true - type: object - required: - - type - PromptCacheUnavailableDiagnosticsBody: - properties: - type: + response_id: type: string - enum: - - unavailable - default: unavailable - x-stainless-const: true - type: object + description: The ID of the active response that should receive the input. + input: + type: array + maxItems: 16384 + description: Input items to inject into the active response. + items: + $ref: '#/components/schemas/BetaInputItem' required: - type - PromptCacheDiagnostics: + - response_id + - input + x-oai-beta: responses_multi_agent=v1 + x-oaiMeta: + example: | + { + "type": "response.inject", + "response_id": "resp_123", + "input": [ + { + "type": "function_call_output", + "call_id": "call_123", + "output": "{\"temperature\":72}" + } + ] + } + BetaResponsesServerEvent: discriminator: propertyName: type - description: Prompt cache diagnostics requested for this response. + description: | + Server events emitted by the Responses WebSocket server. anyOf: - - $ref: '#/components/schemas/PromptCacheMissDiagnosticsBody' - - $ref: '#/components/schemas/PromptCacheHitDiagnosticsBody' - - $ref: '#/components/schemas/PromptCacheComparisonResponseNotFoundDiagnosticsBody' - - $ref: '#/components/schemas/PromptCacheUnavailableDiagnosticsBody' - ModerationErrorBody: - properties: - type: - type: string - enum: - - error - description: The object type, which was always `error` for moderation failures. - default: error - x-stainless-const: true - code: - type: string - description: The error code. - message: - type: string - description: The error message. - type: object - required: - - type - - code - - message - title: Moderation error - description: An error produced while attempting moderation for the response input or output. - Moderation: - properties: - input: - discriminator: - propertyName: type - description: Moderation for the response input. - anyOf: - - $ref: '#/components/schemas/ModerationResultBody' - - $ref: '#/components/schemas/ModerationErrorBody' - output: - discriminator: - propertyName: type - description: Moderation for the response output. - anyOf: - - $ref: '#/components/schemas/ModerationResultBody' - - $ref: '#/components/schemas/ModerationErrorBody' - type: object - required: - - input - - output - title: Moderation - description: Moderation results or errors for the response input and output. - ResponseConversation: - properties: - id: - type: string - description: The unique ID of the conversation that this response was associated with. - type: object - required: - - id - title: Conversation - description: The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - ResponseCompactionCompactingStreamingEvent: - properties: - type: - type: string - enum: - - response.compaction.compacting - description: The type of the event, always `response.compaction.compacting`. - default: response.compaction.compacting - x-stainless-const: true - sequence_number: - type: integer - description: The sequence number of the event that was emitted. - output_index: - type: integer - description: The index of the compaction output item. - item_id: - type: string - description: The ID of the compaction output item. - type: object - required: - - type - - sequence_number - - output_index - - item_id - title: Response compaction compacting event - description: Emitted when new summary content is sampled for a compaction trigger. Contains no summary content. - ResponseShellCallCommandAddedStreamingEvent: - properties: - type: - type: string - enum: - - response.shell_call_command.added - description: The type of the event, always `response.shell_call_command.added`. - default: response.shell_call_command.added - x-stainless-const: true - sequence_number: - type: integer - description: The sequence number of the event that was emitted. - output_index: - type: integer - description: The index of the output item that was updated. - command_index: - type: integer - description: The index of the shell command that was added. - command: - type: string - description: The shell command that was added. - type: object - required: - - type - - sequence_number - - output_index - - command_index - - command - title: Response shell command added event - description: A streaming event that indicated a shell command was added to a tool call. - ResponseShellCallCommandDeltaStreamingEvent: - properties: - type: - type: string - enum: - - response.shell_call_command.delta - description: The type of the event, always `response.shell_call_command.delta`. - default: response.shell_call_command.delta - x-stainless-const: true - sequence_number: - type: integer - description: The sequence number of the event that was emitted. - output_index: - type: integer - description: The index of the output item that was updated. - command_index: - type: integer - description: The index of the shell command that was updated. - delta: - type: string - description: The shell command delta that was appended. - obfuscation: - type: string - description: An obfuscation string that was added to pad the event payload. - type: object - required: - - type - - sequence_number - - output_index - - command_index - - delta - title: Response shell command delta event - description: A streaming event that indicated a shell command was incrementally updated. - ResponseShellCallCommandDoneStreamingEvent: - properties: - type: - type: string - enum: - - response.shell_call_command.done - description: The type of the event, always `response.shell_call_command.done`. - default: response.shell_call_command.done - x-stainless-const: true - sequence_number: - type: integer - description: The sequence number of the event that was emitted. - output_index: - type: integer - description: The index of the output item that was updated. - command_index: - type: integer - description: The index of the shell command that was completed. - command: - type: string - description: The final shell command that was emitted. - type: object - required: - - type - - sequence_number - - output_index - - command_index - - command - title: Response shell command done event - description: A streaming event that indicated a shell command was completed. - ShellCallOutputDelta: - properties: - stdout: - type: string - description: The stdout delta that was emitted. - stderr: - type: string - description: The stderr delta that was emitted. - type: object - required: [] - title: Shell call output delta - description: A delta of stdout/stderr emitted while a shell call was running. - ResponseShellCallOutputContentDeltaStreamingEvent: - properties: - type: - type: string - enum: - - response.shell_call_output_content.delta - description: The type of the event, always `response.shell_call_output_content.delta`. - default: response.shell_call_output_content.delta - x-stainless-const: true - sequence_number: - type: integer - description: The sequence number of the event that was emitted. - item_id: - type: string - description: The ID of the output item that was updated. - output_index: - type: integer - description: The index of the output item that was updated. - command_index: - type: integer - description: The index of the shell command that produced output. - delta: - $ref: '#/components/schemas/ShellCallOutputDelta' - description: The stdout/stderr delta that was emitted. - type: object - required: - - type - - sequence_number - - item_id - - output_index - - command_index - - delta - title: Response shell call output content delta event - description: A streaming event that indicated shell call output was incrementally added. - ResponseShellCallOutputContentDoneStreamingEvent: - properties: - type: - type: string - enum: - - response.shell_call_output_content.done - description: The type of the event, always `response.shell_call_output_content.done`. - default: response.shell_call_output_content.done - x-stainless-const: true - sequence_number: - type: integer - description: The sequence number of the event that was emitted. - item_id: - type: string - description: The ID of the output item that was updated. - output_index: - type: integer - description: The index of the output item that was updated. - command_index: - type: integer - description: The index of the shell command that produced output. - output: - items: - $ref: '#/components/schemas/FunctionShellCallOutputContent' - type: array - description: The output contents emitted for the shell command. - type: object - required: - - type - - sequence_number - - item_id - - output_index - - command_index - - output - title: Response shell call output content done event - description: A streaming event that indicated shell call output was completed. - CreateConversationBody: - properties: - metadata: - anyOf: - - $ref: '#/components/schemas/Metadata' - description: |- - Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. - Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. - - type: 'null' - items: - anyOf: - - items: - $ref: '#/components/schemas/InputItem' - type: array - maxItems: 20 - description: Initial items to include in the conversation context. You may add up to 20 items at a time. - - type: 'null' - type: object - required: [] - UpdateConversationBody: - properties: - metadata: - $ref: '#/components/schemas/Metadata' - description: |- - Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. - Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. - type: object - required: - - metadata - DeletedConversationResource: - properties: - object: - type: string - enum: - - conversation.deleted - default: conversation.deleted - x-stainless-const: true - deleted: - type: boolean - id: - type: string - type: object - required: - - object - - deleted - - id - SafetyAlertErrorType: - type: string - enum: - - potentially_unintended_data_transfer - - potentially_unintended_data_access - - potentially_unintended_destructive_activity - - other - SafetyAlertResource: - properties: - id: - type: string - object: - type: string - enum: - - safety.alert - default: safety.alert - x-stainless-const: true - created_at: - type: integer - format: unixtime - request_id: - type: string - response_id: - type: string - model: - type: string - request_paused: - type: boolean - description: Whether block registration succeeded for this request. This does not confirm that response execution stopped. - error_type: - $ref: '#/components/schemas/SafetyAlertErrorType' - reason: - anyOf: - - type: string - description: A customer-safe description derived from error_type, or null for zero data retention requests. - - type: 'null' - type: object - required: - - id - - object - - created_at - - request_id - - response_id - - model - - request_paused - - error_type - - reason - SpendLimitCurrency: - anyOf: - - type: string - - type: string - enum: - - USD - SpendLimitInterval: - anyOf: - - type: string - - type: string - enum: - - month - SpendLimitEnforcementStatus: - anyOf: - - type: string - - type: string - enum: - - inactive - - enforcing - SpendLimitEnforcement: - properties: - status: - $ref: '#/components/schemas/SpendLimitEnforcementStatus' - description: Whether the hard spend limit is currently enforcing. - type: object - required: - - status - description: The current enforcement state of a hard spend limit. - OrganizationSpendLimitResource: - properties: - object: - type: string - enum: - - organization.spend_limit - description: The object type, which is always `organization.spend_limit`. - default: organization.spend_limit - x-stainless-const: true - threshold_amount: - type: integer - description: The hard spend limit amount, in cents. - currency: - $ref: '#/components/schemas/SpendLimitCurrency' - description: The currency for the threshold amount. Currently, only `USD` is supported. - interval: - $ref: '#/components/schemas/SpendLimitInterval' - description: The time interval for evaluating spend against the threshold. Currently, only `month` is supported. - enforcement: - $ref: '#/components/schemas/SpendLimitEnforcement' - description: The current enforcement state of the hard spend limit. - type: object - required: - - object - - threshold_amount - - currency - - interval - - enforcement - description: Represents a hard spend limit configured at the organization level. - UpdateOrganizationSpendLimitBody: - properties: - threshold_amount: - type: integer - minimum: 1 - description: The hard spend limit amount, in cents. - currency: - type: string - enum: - - USD - description: The currency for the threshold amount. Currently, only `USD` is supported. - interval: - type: string - enum: - - month - description: The time interval for evaluating spend against the threshold. Currently, only `month` is supported. - type: object - required: - - threshold_amount - - currency - - interval - description: Parameters for the hard spend limit you want to create or replace. - OrganizationSpendLimitDeletedResource: - properties: - object: - type: string - enum: - - organization.spend_limit.deleted - description: The object type, which is always `organization.spend_limit.deleted`. - default: organization.spend_limit.deleted - x-stainless-const: true - deleted: - type: boolean - description: Whether the hard spend limit was deleted. - type: object - required: - - object - - deleted - description: Confirmation payload returned after deleting an organization hard spend limit. - ProjectSpendLimitResource: - properties: - object: - type: string - enum: - - project.spend_limit - description: The object type, which is always `project.spend_limit`. - default: project.spend_limit - x-stainless-const: true - threshold_amount: - type: integer - description: The hard spend limit amount, in cents. - currency: - $ref: '#/components/schemas/SpendLimitCurrency' - description: The currency for the threshold amount. Currently, only `USD` is supported. - interval: - $ref: '#/components/schemas/SpendLimitInterval' - description: The time interval for evaluating spend against the threshold. Currently, only `month` is supported. - enforcement: - $ref: '#/components/schemas/SpendLimitEnforcement' - description: The current enforcement state of the hard spend limit. - type: object - required: - - object - - threshold_amount - - currency - - interval - - enforcement - description: Represents a hard spend limit configured at the project level. - UpdateProjectSpendLimitBody: - properties: - threshold_amount: - type: integer - minimum: 1 - description: The hard spend limit amount, in cents. - currency: - type: string - enum: - - USD - description: The currency for the threshold amount. Currently, only `USD` is supported. - interval: - type: string - enum: - - month - description: The time interval for evaluating spend against the threshold. Currently, only `month` is supported. - type: object - required: - - threshold_amount - - currency - - interval - description: Parameters for the hard spend limit you want to create or replace. - ProjectSpendLimitDeletedResource: - properties: - object: - type: string - enum: - - project.spend_limit.deleted - description: The object type, which is always `project.spend_limit.deleted`. - default: project.spend_limit.deleted - x-stainless-const: true - deleted: - type: boolean - description: Whether the hard spend limit was deleted. - type: object - required: - - object - - deleted - description: Confirmation payload returned after deleting a project hard spend limit. - CreateProjectServiceAccountApiKeyBody: - properties: - name: - type: string - description: API key name. - scopes: - items: - type: string - description: API key scope. - type: array - description: API key scopes. - expires_in_seconds: - anyOf: - - type: integer - maximum: 31536000 - minimum: 1 - description: Number of seconds until the API key expires. - - type: 'null' - type: object - required: [] - description: The service account API key create request payload. - ServiceAccountApiKeyBody: - properties: - object: - type: string - enum: - - organization.project.service_account.api_key - description: The object type, which is always `organization.project.service_account.api_key` - default: organization.project.service_account.api_key - x-stainless-const: true - value: - type: string - description: The unredacted API key value. - name: - type: string - description: The name of the API key. - created_at: - type: integer - format: unixtime - description: The Unix timestamp (in seconds) when the API key was created. - expires_at: - anyOf: - - type: integer - format: unixtime - description: The Unix timestamp (in seconds) when the API key expires, or null if it does not expire. - - type: 'null' - id: - type: string - description: The identifier of the API key. - type: object - required: - - object - - value - - name - - created_at - - id - CreateContentProvenanceBody: - properties: - file: - type: string - format: binary - description: The image or audio file to check for supported OpenAI provenance signals. - type: object - required: - - file - ProvenanceCheckObject: - type: string - enum: - - content_provenance_check - ProvenanceDetectionResultApi: - type: string - enum: - - detected - - not_detected - C2PAValidationStateApi: - type: string - enum: - - trusted - - valid - - invalid - - not_present - C2PAProvenanceResult: - properties: - type: - type: string - enum: - - c2pa - description: The provenance signal type. Always `c2pa`. - default: c2pa - x-stainless-const: true - outcome: - $ref: '#/components/schemas/ProvenanceDetectionResultApi' - description: |- - Whether a supported OpenAI C2PA provenance signal was detected. - If `not_detected`, it means the tool did not find supported signals in the uploaded file. The content could still have been generated by OpenAI if the metadata was stripped or has evidence of tampering, the watermark was degraded, it comes from a legacy generation model, or it was created before provenance signals were available. Content could also still be AI-generated by another company's model, which the tool currently does not detect. - validation_state: - $ref: '#/components/schemas/C2PAValidationStateApi' - description: The validation status of the C2PA manifest in the uploaded image. - issuer: - anyOf: - - type: string - description: The C2PA manifest issuer, when available. - - type: 'null' - model: - anyOf: - - type: string - description: The OpenAI model recorded by the provenance signal, when available. - - type: 'null' - generated_at: - anyOf: - - type: string - description: The UTC RFC 3339 timestamp recorded by the provenance signal for when the asset was generated, when available. - - type: 'null' - type: object - required: - - type - - outcome - - validation_state - - issuer - - model - - generated_at - SynthIDProvenanceResult: - properties: - type: - type: string - enum: - - synthid - description: The provenance signal type. Always `synthid`. - default: synthid - x-stainless-const: true - outcome: - $ref: '#/components/schemas/ProvenanceDetectionResultApi' - description: |- - Whether a supported OpenAI SynthID watermark was detected. - If `not_detected`, it means the tool did not find supported signals in the uploaded file. The content could still have been generated by OpenAI if the metadata was stripped or has evidence of tampering, the watermark was degraded, it comes from a legacy generation model, or it was created before provenance signals were available. Content could also still be AI-generated by another company's model, which the tool currently does not detect. - model: - anyOf: - - type: string - description: The OpenAI model recorded by the provenance signal, when available. - - type: 'null' - generated_at: - anyOf: - - type: string - description: The UTC RFC 3339 timestamp recorded by the provenance signal for when the asset was generated, when available. - - type: 'null' - type: object - required: - - type - - outcome - - model - - generated_at - ProvenanceResource: - properties: - object: - $ref: '#/components/schemas/ProvenanceCheckObject' - description: The object type. Always `content_provenance_check` for this endpoint. - created_at: - type: integer - format: unixtime - description: The Unix timestamp, in seconds, when the provenance check was created. - results: - items: - discriminator: - propertyName: type - anyOf: - - $ref: '#/components/schemas/C2PAProvenanceResult' - - $ref: '#/components/schemas/SynthIDProvenanceResult' - type: array - description: The provenance results that apply to the uploaded file. Image results include C2PA and SynthID; audio results include SynthID. - type: object - required: - - object - - created_at - - results - OrderEnum: - type: string - enum: - - asc - - desc - VideoModel: - anyOf: - - type: string - - type: string - enum: - - sora-2 - - sora-2-pro - - sora-2-2025-10-06 - - sora-2-pro-2025-10-06 - - sora-2-2025-12-08 - VideoStatus: - type: string - enum: - - queued - - in_progress - - completed - - failed - VideoSize: - type: string - enum: - - 720x1280 - - 1280x720 - - 1024x1792 - - 1792x1024 - Error-2: - properties: - code: - type: string - description: A machine-readable error code that was returned. - message: - type: string - description: A human-readable description of the error that was returned. - misalignment: - $ref: '#/components/schemas/MisalignmentErrorDetailsResource' - type: object - required: - - code - - message - title: Error - description: An error that occurred while generating the response. - VideoResource: - properties: - id: - type: string - description: Unique identifier for the video job. - object: - type: string - enum: - - video - description: The object type, which is always `video`. - default: video - x-stainless-const: true - model: - $ref: '#/components/schemas/VideoModel' - description: The video generation model that produced the job. - status: - $ref: '#/components/schemas/VideoStatus' - description: Current lifecycle status of the video job. - progress: - type: integer - description: Approximate completion percentage for the generation task. - created_at: - type: integer - format: unixtime - description: Unix timestamp (seconds) for when the job was created. - completed_at: - anyOf: - - type: integer - format: unixtime - description: Unix timestamp (seconds) for when the job completed, if finished. - - type: 'null' - expires_at: - anyOf: - - type: integer - format: unixtime - description: Unix timestamp (seconds) for when the downloadable assets expire, if set. - - type: 'null' - prompt: - anyOf: - - type: string - description: The prompt that was used to generate the video. - - type: 'null' - size: - $ref: '#/components/schemas/VideoSize' - description: The resolution of the generated video. - seconds: - anyOf: - - type: string - - $ref: '#/components/schemas/VideoSeconds' - description: Duration of the generated clip in seconds. For extensions, this is the stitched total duration. - remixed_from_video_id: - anyOf: - - type: string - description: Identifier of the source video if this video is a remix. - - type: 'null' - error: - anyOf: - - $ref: '#/components/schemas/Error-2' - description: Error payload that explains why generation failed, if applicable. - - type: 'null' - type: object - required: - - id - - object - - model - - status - - progress - - created_at - - completed_at - - expires_at - - prompt - - size - - seconds - - remixed_from_video_id - - error - title: Video job - description: Structured information describing a generated video job. - VideoListResource: - properties: - object: - x-stainless-const: true - default: list - description: The type of object returned, must be `list`. - const: list - data: - items: - $ref: '#/components/schemas/VideoResource' - type: array - description: A list of items - first_id: - anyOf: - - type: string - description: The ID of the first item in the list. - - type: 'null' - last_id: - anyOf: - - type: string - description: The ID of the last item in the list. - - type: 'null' - has_more: - type: boolean - description: Whether there are more items available. - type: object - required: - - object - - data - - first_id - - last_id - - has_more - ImageRefParam-2: - properties: - image_url: - type: string - maxLength: 20971520 - format: uri - description: A fully qualified URL or base64-encoded data URL. - file_id: - type: string - example: file-123 - type: object - required: [] - VideoSeconds: - type: string - enum: - - '4' - - '8' - - '12' - CreateVideoMultipartBody: - properties: - model: - $ref: '#/components/schemas/VideoModel' - description: 'The video generation model to use (allowed values: sora-2, sora-2-pro). Defaults to `sora-2`.' - prompt: - type: string - maxLength: 32000 - minLength: 1 - description: Text prompt that describes the video to generate. - input_reference: - anyOf: - - type: string - format: binary - description: Optional reference asset upload or reference object that guides generation. - - $ref: '#/components/schemas/ImageRefParam-2' - description: Optional reference asset upload or reference object that guides generation. Provide exactly one of `image_url` or `file_id` when using an object. - seconds: - $ref: '#/components/schemas/VideoSeconds' - description: 'Clip duration in seconds (allowed values: 4, 8, 12). Defaults to 4 seconds.' - size: - $ref: '#/components/schemas/VideoSize' - description: 'Output resolution formatted as width x height (allowed values: 720x1280, 1280x720, 1024x1792, 1792x1024). Defaults to 720x1280.' - type: object - required: - - prompt - title: Create video multipart request - description: Multipart parameters for creating a new video generation job. - CreateVideoJsonBody: - properties: - model: - $ref: '#/components/schemas/VideoModel' - description: 'The video generation model to use (allowed values: sora-2, sora-2-pro). Defaults to `sora-2`.' - prompt: - type: string - maxLength: 32000 - minLength: 1 - description: Text prompt that describes the video to generate. - input_reference: - $ref: '#/components/schemas/ImageRefParam-2' - description: Optional reference object that guides generation. Provide exactly one of `image_url` or `file_id`. - seconds: - $ref: '#/components/schemas/VideoSeconds' - description: 'Clip duration in seconds (allowed values: 4, 8, 12). Defaults to 4 seconds.' - size: - $ref: '#/components/schemas/VideoSize' - description: 'Output resolution formatted as width x height (allowed values: 720x1280, 1280x720, 1024x1792, 1792x1024). Defaults to 720x1280.' - type: object - required: - - prompt - title: Create video JSON request - description: JSON parameters for creating a new video generation job. - CreateVideoCharacterBody: - properties: - video: - type: string - format: binary - description: Video file used to create a character. - name: - type: string - maxLength: 80 - minLength: 1 - description: Display name for this API character. - type: object - required: - - video - - name - title: Create character request - description: Parameters for creating a character from an uploaded video. - VideoCharacterResource: - properties: - id: - anyOf: - - type: string - description: Identifier for the character creation cameo. - - type: 'null' - name: - anyOf: - - type: string - description: Display name for the character. - - type: 'null' - created_at: - type: integer - format: unixtime - description: Unix timestamp (in seconds) when the character was created. - type: object - required: - - id - - name - - created_at - VideoReferenceInputParam: - properties: - id: - type: string - description: The identifier of the completed video. - example: video_123 - type: object - required: - - id - description: Reference to the completed video. - CreateVideoEditMultipartBody: - properties: - video: - anyOf: - - type: string - format: binary - description: Reference to the completed video to edit. - - $ref: '#/components/schemas/VideoReferenceInputParam' - description: Reference to the completed video to edit. - prompt: - type: string - maxLength: 32000 - minLength: 1 - description: Text prompt that describes how to edit the source video. - type: object - required: - - video - - prompt - title: Create video edit multipart request - description: Parameters for editing an existing generated video. - CreateVideoEditJsonBody: - properties: - video: - $ref: '#/components/schemas/VideoReferenceInputParam' - description: Reference to the completed video to edit. - prompt: - type: string - maxLength: 32000 - minLength: 1 - description: Text prompt that describes how to edit the source video. - type: object - required: - - video - - prompt - title: Create video edit JSON request - description: JSON parameters for editing an existing generated video. - CreateVideoExtendMultipartBody: - properties: - video: - oneOf: - - type: string - format: binary - description: Reference to the completed video to extend. - - $ref: '#/components/schemas/VideoReferenceInputParam' - description: Reference to the completed video to extend. - prompt: - type: string - maxLength: 32000 - minLength: 1 - description: Updated text prompt that directs the extension generation. - seconds: - $ref: '#/components/schemas/VideoSeconds' - description: 'Length of the newly generated extension segment in seconds (allowed values: 4, 8, 12, 16, 20).' - type: object - required: - - video - - prompt - - seconds - title: Create video extension multipart request - description: Multipart parameters for extending an existing generated video. - CreateVideoExtendJsonBody: - properties: - video: - $ref: '#/components/schemas/VideoReferenceInputParam' - description: Reference to the completed video to extend. - prompt: - type: string - maxLength: 32000 - minLength: 1 - description: Updated text prompt that directs the extension generation. - seconds: - $ref: '#/components/schemas/VideoSeconds' - description: 'Length of the newly generated extension segment in seconds (allowed values: 4, 8, 12, 16, 20).' - type: object - required: - - video - - prompt - - seconds - title: Create video extension JSON request - description: JSON parameters for extending an existing generated video. - DeletedVideoResource: - properties: - object: - type: string - enum: - - video.deleted - description: The object type that signals the deletion response. - default: video.deleted - x-stainless-const: true - deleted: - type: boolean - description: Indicates that the video resource was deleted. - id: - type: string - description: Identifier of the deleted video. - type: object - required: - - object - - deleted - - id - title: Deleted video response - description: Confirmation payload returned after deleting a video. - VideoContentVariant: - type: string - enum: - - video - - thumbnail - - spritesheet - CreateVideoRemixBody: - properties: - prompt: - type: string - maxLength: 32000 - minLength: 1 - description: Updated text prompt that directs the remix generation. - type: object - required: - - prompt - title: Create video remix request - description: Parameters for remixing an existing generated video. - TruncationEnum: - type: string - enum: - - auto - - disabled - PersonalityEnum: - anyOf: - - type: string - - type: string - enum: - - friendly - - pragmatic - TokenCountsBody: - properties: - model: - anyOf: - - type: string - description: Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](https://developers.openai.com/api/docs/models) to browse and compare available models. - - type: 'null' - input: - anyOf: - - description: Text, image, or file inputs to the model, used to generate a response - anyOf: - - type: string - maxLength: 10485760 - description: A text input to the model, equivalent to a text input with the `user` role. - - items: - $ref: '#/components/schemas/InputItem' - type: array - maxItems: 131072 - description: A list of one or many input items to the model, containing different content types. - - type: 'null' - previous_response_id: - anyOf: - - type: string - description: The unique ID of the previous response to the model. Use this to create multi-turn conversations. Learn more about [conversation state](https://developers.openai.com/api/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. - example: resp_123 - - type: 'null' - tools: - anyOf: - - items: - $ref: '#/components/schemas/Tool' - type: array - description: An array of tools the model may call while generating a response. You can specify which tool to use by setting the `tool_choice` parameter. - - type: 'null' - text: - anyOf: - - $ref: '#/components/schemas/ResponseTextParam' - - type: 'null' - reasoning: - anyOf: - - $ref: '#/components/schemas/Reasoning' - description: '**gpt-5 and o-series models only** Configuration options for [reasoning models](https://developers.openai.com/api/docs/guides/reasoning).' - - type: 'null' - truncation: - $ref: '#/components/schemas/TruncationEnum' - description: 'The truncation strategy to use for the model response. - `auto`: If the input to this Response exceeds the model''s context window size, the model will truncate the response to fit the context window by dropping items from the beginning of the conversation. - `disabled` (default): If the input size will exceed the context window size for a model, the request will fail with a 400 error.' - deprecated: true - instructions: - anyOf: - - type: string - description: |- - A system (or developer) message inserted into the model's context. - When used along with `previous_response_id`, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses. - - type: 'null' - personality: - $ref: '#/components/schemas/PersonalityEnum' - description: A model-owned style preset to apply to this request. Omit this parameter to use the model's default style. Supported values may expand over time. Values must be at most 64 characters. - conversation: - anyOf: - - $ref: '#/components/schemas/ConversationParam' - - type: 'null' - tool_choice: - anyOf: - - $ref: '#/components/schemas/ToolChoiceParam' - description: Controls which tool the model should use, if any. - - type: 'null' - parallel_tool_calls: - anyOf: - - type: boolean - description: Whether to allow the model to run tool calls in parallel. - - type: 'null' - type: object - required: [] - TokenCountsResource: - properties: - object: - type: string - enum: - - response.input_tokens - default: response.input_tokens - x-stainless-const: true - input_tokens: - type: integer - type: object - required: - - object - - input_tokens - title: Token counts - example: - object: response.input_tokens - input_tokens: 123 - PromptCacheRetentionEnum: - type: string - enum: - - in_memory - - 24h - ServiceTierEnum: - type: string - enum: - - auto - - default - - fast - - flex - - priority - CompactResponseMethodPublicBody: - properties: - model: - $ref: '#/components/schemas/ModelIdsCompaction' - input: - anyOf: - - description: Text, image, or file inputs to the model, used to generate a response - anyOf: - - type: string - maxLength: 10485760 - description: A text input to the model, equivalent to a text input with the `user` role. - - items: - $ref: '#/components/schemas/InputItem' - type: array - maxItems: 131072 - description: A list of one or many input items to the model, containing different content types. - - type: 'null' - previous_response_id: - anyOf: - - type: string - description: The unique ID of the previous response to the model. Use this to create multi-turn conversations. Learn more about [conversation state](https://developers.openai.com/api/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. - example: resp_123 - - type: 'null' - instructions: - anyOf: - - type: string - description: |- - A system (or developer) message inserted into the model's context. - When used along with `previous_response_id`, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses. - - type: 'null' - prompt_cache_key: - anyOf: - - type: string - maxLength: 64 - description: A key to use when reading from or writing to the prompt cache. - - type: 'null' - prompt_cache_retention: - anyOf: - - $ref: '#/components/schemas/PromptCacheRetentionEnum' - description: How long to retain a prompt cache entry created by this request. - deprecated: true - - type: 'null' - prompt_cache_options: - anyOf: - - $ref: '#/components/schemas/PromptCacheOptionsParam' - - type: 'null' - service_tier: - anyOf: - - $ref: '#/components/schemas/ServiceTierEnum' - description: |- - Specifies the processing type used for serving the request. - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - If set to '[flex](https://developers.openai.com/api/docs/guides/flex-processing)', then the request will be processed with the Flex Processing service tier. - To opt-in to [Fast mode](https://developers.openai.com/api/docs/guides/fast-mode) at the request level, include the `service_tier=fast` or `service_tier=priority` parameter for Responses or Chat Completions. For models with a dedicated Fast tier, either value resolves to `service_tier=fast`; for other models, either value resolves to `service_tier=priority`. - When not set, the default behavior is 'auto'. - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - - type: 'null' - type: object - required: - - model - ItemField: - discriminator: - propertyName: type - description: An item representing a message, tool call, tool output, reasoning, or other response element. - anyOf: - - $ref: '#/components/schemas/Message' - - $ref: '#/components/schemas/Program' - - $ref: '#/components/schemas/ProgramOutput' - - $ref: '#/components/schemas/FunctionToolCall' - - $ref: '#/components/schemas/ToolSearchCall' - - $ref: '#/components/schemas/ToolSearchOutput' - - $ref: '#/components/schemas/AdditionalTools' - - $ref: '#/components/schemas/FunctionToolCallOutput' - - $ref: '#/components/schemas/FileSearchToolCall' - - $ref: '#/components/schemas/WebSearchToolCall' - - $ref: '#/components/schemas/ImageGenToolCall' - - $ref: '#/components/schemas/ComputerToolCall' - - $ref: '#/components/schemas/ComputerToolCallOutputResource' - - $ref: '#/components/schemas/ReasoningItem' - - $ref: '#/components/schemas/CompactionBody' - - $ref: '#/components/schemas/CodeInterpreterToolCall' - - $ref: '#/components/schemas/LocalShellToolCall' - deprecated: true - - $ref: '#/components/schemas/LocalShellToolCallOutput' - deprecated: true - - $ref: '#/components/schemas/FunctionShellCall' - - $ref: '#/components/schemas/FunctionShellCallOutput' - - $ref: '#/components/schemas/ApplyPatchToolCall' - - $ref: '#/components/schemas/ApplyPatchToolCallOutput' - - $ref: '#/components/schemas/MCPListTools' - - $ref: '#/components/schemas/MCPApprovalRequest' - - $ref: '#/components/schemas/MCPApprovalResponseResource' - - $ref: '#/components/schemas/MCPToolCall' - - $ref: '#/components/schemas/CustomToolCall' - - $ref: '#/components/schemas/CustomToolCallOutput' - CompactResource: - properties: - id: - type: string - description: The unique identifier for the compacted response. - object: - type: string - enum: - - response.compaction - description: The object type. Always `response.compaction`. - default: response.compaction - x-stainless-const: true - output: - type: array - description: The compacted list of output items. This is a list of all user messages, followed by a single compaction item. - items: - $ref: '#/components/schemas/OutputItem' - created_at: - type: integer - format: unixtime - description: Unix timestamp (in seconds) when the compacted conversation was created. - usage: - $ref: '#/components/schemas/ResponseUsage' - description: Token accounting for the compaction pass, including cached, reasoning, and total tokens. - type: object - required: - - id - - object - - output - - created_at - - usage - title: The compacted response object - SkillResource: - properties: - id: - type: string - description: Unique identifier for the skill. - object: - type: string - enum: - - skill - description: The object type, which is `skill`. - default: skill - x-stainless-const: true - name: - type: string - description: Name of the skill. - description: - type: string - description: Description of the skill. - created_at: - type: integer - format: unixtime - description: Unix timestamp (seconds) for when the skill was created. - default_version: - type: string - description: Default version for the skill. - latest_version: - type: string - description: Latest version for the skill. - type: object - required: - - id - - object - - name - - description - - created_at - - default_version - - latest_version - SkillListResource: - properties: - object: - x-stainless-const: true - default: list - description: The type of object returned, must be `list`. - const: list - data: - items: - $ref: '#/components/schemas/SkillResource' - type: array - description: A list of items - first_id: - anyOf: - - type: string - description: The ID of the first item in the list. - - type: 'null' - last_id: - anyOf: - - type: string - description: The ID of the last item in the list. - - type: 'null' - has_more: - type: boolean - description: Whether there are more items available. - type: object - required: - - object - - data - - first_id - - last_id - - has_more - CreateSkillBody: - properties: - files: - anyOf: - - items: - type: string - format: binary - type: array - maxItems: 500 - description: Skill files to upload (directory upload) or a single zip file. - - type: string - format: binary - description: Skill zip file to upload. - type: object - description: Uploads a skill either as a directory (multipart `files[]`) or as a single zip file. - title: Create skill request - SetDefaultSkillVersionBody: - properties: - default_version: - type: string - description: The skill version number to set as default. - type: object - required: - - default_version - title: Update skill request - description: Updates the default version pointer for a skill. - DeletedSkillResource: - properties: - object: - type: string - enum: - - skill.deleted - default: skill.deleted - x-stainless-const: true - deleted: - type: boolean - id: - type: string - type: object - required: - - object - - deleted - - id - SkillVersionResource: - properties: - object: - type: string - enum: - - skill.version - description: The object type, which is `skill.version`. - default: skill.version - x-stainless-const: true - id: - type: string - description: Unique identifier for the skill version. - skill_id: - type: string - description: Identifier of the skill for this version. - version: - type: string - description: Version number for this skill. - created_at: - type: integer - format: unixtime - description: Unix timestamp (seconds) for when the version was created. - name: - type: string - description: Name of the skill version. - description: - type: string - description: Description of the skill version. - type: object - required: - - object - - id - - skill_id - - version - - created_at - - name - - description - SkillVersionListResource: - properties: - object: - x-stainless-const: true - default: list - description: The type of object returned, must be `list`. - const: list - data: - items: - $ref: '#/components/schemas/SkillVersionResource' - type: array - description: A list of items - first_id: - anyOf: - - type: string - description: The ID of the first item in the list. - - type: 'null' - last_id: - anyOf: - - type: string - description: The ID of the last item in the list. - - type: 'null' - has_more: - type: boolean - description: Whether there are more items available. - type: object - required: - - object - - data - - first_id - - last_id - - has_more - CreateSkillVersionBody: - properties: - files: - anyOf: - - items: - type: string - format: binary - type: array - maxItems: 500 - description: Skill files to upload (directory upload) or a single zip file. - - type: string - format: binary - description: Skill zip file to upload. - default: - type: boolean - description: Whether to set this version as the default. - type: object - description: Uploads a new immutable version of a skill. - title: Create skill version request - DeletedSkillVersionResource: - properties: - object: - type: string - enum: - - skill.version.deleted - default: skill.version.deleted - x-stainless-const: true - deleted: - type: boolean - id: - type: string - version: - type: string - description: The deleted skill version. - type: object - required: - - object - - deleted - - id - - version - ChatkitWorkflowTracing: - properties: - enabled: - type: boolean - description: Indicates whether tracing is enabled. - type: object - required: - - enabled - title: Tracing Configuration - description: Controls diagnostic tracing during the session. - ChatkitWorkflow: - properties: - id: - type: string - description: Identifier of the workflow backing the session. - version: - anyOf: - - type: string - description: Specific workflow version used for the session. Defaults to null when using the latest deployment. - - type: 'null' - state_variables: - anyOf: - - additionalProperties: - anyOf: - - type: string - - type: integer - - type: boolean - - type: number - type: object - description: State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. - x-oaiTypeLabel: map - - type: 'null' - tracing: - $ref: '#/components/schemas/ChatkitWorkflowTracing' - description: Tracing settings applied to the workflow. - type: object - required: - - id - - version - - state_variables - - tracing - title: Workflow - description: Workflow metadata and state returned for the session. - ChatSessionRateLimits: - properties: - max_requests_per_1_minute: - type: integer - description: Maximum allowed requests per one-minute window. - type: object - required: - - max_requests_per_1_minute - title: Rate limits - description: Active per-minute request limit for the session. - ChatSessionStatus: - type: string - enum: - - active - - expired - - cancelled - ChatSessionAutomaticThreadTitling: - properties: - enabled: - type: boolean - description: Whether automatic thread titling is enabled. - type: object - required: - - enabled - title: Automatic thread titling - description: Automatic thread title preferences for the session. - ChatSessionFileUpload: - properties: - enabled: - type: boolean - description: Indicates if uploads are enabled for the session. - max_file_size: - anyOf: - - type: integer - description: Maximum upload size in megabytes. - - type: 'null' - max_files: - anyOf: - - type: integer - description: Maximum number of uploads allowed during the session. - - type: 'null' - type: object - required: - - enabled - - max_file_size - - max_files - title: File upload settings - description: Upload permissions and limits applied to the session. - ChatSessionHistory: - properties: - enabled: - type: boolean - description: Indicates if chat history is persisted for the session. - recent_threads: - anyOf: - - type: integer - description: Number of prior threads surfaced in history views. Defaults to null when all history is retained. - - type: 'null' - type: object - required: - - enabled - - recent_threads - title: History settings - description: History retention preferences returned for the session. - ChatSessionChatkitConfiguration: - properties: - automatic_thread_titling: - $ref: '#/components/schemas/ChatSessionAutomaticThreadTitling' - description: Automatic thread titling preferences. - file_upload: - $ref: '#/components/schemas/ChatSessionFileUpload' - description: Upload settings for the session. - history: - $ref: '#/components/schemas/ChatSessionHistory' - description: History retention configuration. - type: object - required: - - automatic_thread_titling - - file_upload - - history - title: ChatKit configuration - description: ChatKit configuration for the session. - ChatSessionResource: - properties: - id: - type: string - description: Identifier for the ChatKit session. - object: - type: string - enum: - - chatkit.session - description: Type discriminator that is always `chatkit.session`. - default: chatkit.session - x-stainless-const: true - expires_at: - type: integer - format: unixtime - description: Unix timestamp (in seconds) for when the session expires. - client_secret: - type: string - description: Ephemeral client secret that authenticates session requests. - workflow: - $ref: '#/components/schemas/ChatkitWorkflow' - description: Workflow metadata for the session. - user: - type: string - description: User identifier associated with the session. - rate_limits: - $ref: '#/components/schemas/ChatSessionRateLimits' - description: Resolved rate limit values. - max_requests_per_1_minute: - type: integer - description: Convenience copy of the per-minute request limit. - status: - $ref: '#/components/schemas/ChatSessionStatus' - description: Current lifecycle state of the session. - chatkit_configuration: - $ref: '#/components/schemas/ChatSessionChatkitConfiguration' - description: Resolved ChatKit feature configuration for the session. - type: object - required: - - id - - object - - expires_at - - client_secret - - workflow - - user - - rate_limits - - max_requests_per_1_minute - - status - - chatkit_configuration - title: The chat session object - description: Represents a ChatKit session and its resolved configuration. - WorkflowTracingParam: - properties: - enabled: - type: boolean - description: Whether tracing is enabled during the session. Defaults to true. - type: object - required: [] - title: Tracing Configuration - description: Controls diagnostic tracing during the session. - WorkflowParam: - properties: - id: - type: string - description: Identifier for the workflow invoked by the session. - version: - type: string - description: Specific workflow version to run. Defaults to the latest deployed version. - state_variables: - additionalProperties: - anyOf: - - type: string - maxLength: 10485760 - - type: integer - - type: boolean - - type: number - type: object - maxProperties: 64 - description: State variables forwarded to the workflow. Keys may be up to 64 characters, values must be primitive types, and the map defaults to an empty object. - x-oaiTypeLabel: map - tracing: - $ref: '#/components/schemas/WorkflowTracingParam' - description: Optional tracing overrides for the workflow invocation. When omitted, tracing is enabled by default. - type: object - required: - - id - title: Workflow settings - description: Workflow reference and overrides applied to the chat session. - ExpiresAfterParam: - properties: - anchor: - type: string - enum: - - created_at - description: Base timestamp used to calculate expiration. Currently fixed to `created_at`. - default: created_at - x-stainless-const: true - seconds: - type: integer - maximum: 600 - minimum: 1 - format: int64 - description: Number of seconds after the anchor when the session expires. - type: object - required: - - anchor - - seconds - title: Expiration overrides - description: Controls when the session expires relative to an anchor timestamp. - RateLimitsParam: - properties: - max_requests_per_1_minute: - type: integer - minimum: 1 - description: Maximum number of requests allowed per minute for the session. Defaults to 10. - type: object - required: [] - title: Rate limit overrides - description: Controls request rate limits for the session. - AutomaticThreadTitlingParam: - properties: - enabled: - type: boolean - description: Enable automatic thread title generation. Defaults to true. - type: object - required: [] - title: Automatic thread titling configuration - description: Controls whether ChatKit automatically generates thread titles. - FileUploadParam: - properties: - enabled: - type: boolean - description: Enable uploads for this session. Defaults to false. - max_file_size: - type: integer - maximum: 512 - minimum: 1 - description: Maximum size in megabytes for each uploaded file. Defaults to 512 MB, which is the maximum allowable size. - max_files: - type: integer - minimum: 1 - description: Maximum number of files that can be uploaded to the session. Defaults to 10. - type: object - required: [] - title: File upload configuration - description: Controls whether users can upload files. - HistoryParam: - properties: - enabled: - type: boolean - description: Enables chat users to access previous ChatKit threads. Defaults to true. - recent_threads: - type: integer - minimum: 1 - description: Number of recent ChatKit threads users have access to. Defaults to unlimited when unset. - type: object - required: [] - title: Chat history configuration - description: Controls how much historical context is retained for the session. - ChatkitConfigurationParam: - properties: - automatic_thread_titling: - $ref: '#/components/schemas/AutomaticThreadTitlingParam' - description: Configuration for automatic thread titling. When omitted, automatic thread titling is enabled by default. - file_upload: - $ref: '#/components/schemas/FileUploadParam' - description: Configuration for upload enablement and limits. When omitted, uploads are disabled by default (max_files 10, max_file_size 512 MB). - history: - $ref: '#/components/schemas/HistoryParam' - description: Configuration for chat history retention. When omitted, history is enabled by default with no limit on recent_threads (null). - type: object - required: [] - title: ChatKit configuration overrides - description: Optional per-session configuration settings for ChatKit behavior. - CreateChatSessionBody: - properties: - workflow: - $ref: '#/components/schemas/WorkflowParam' - description: Workflow that powers the session. - user: - type: string - minLength: 1 - description: A free-form string that identifies your end user; ensures this Session can access other objects that have the same `user` scope. - expires_after: - $ref: '#/components/schemas/ExpiresAfterParam' - description: Optional override for session expiration timing in seconds from creation. Defaults to 10 minutes. - rate_limits: - $ref: '#/components/schemas/RateLimitsParam' - description: Optional override for per-minute request limits. When omitted, defaults to 10. - chatkit_configuration: - $ref: '#/components/schemas/ChatkitConfigurationParam' - description: Optional overrides for ChatKit runtime configuration features - type: object - required: - - workflow - - user - title: Create chat session request - description: Parameters for provisioning a new ChatKit session. - UserMessageInputText: - properties: - type: - type: string - enum: - - input_text - description: Type discriminator that is always `input_text`. - default: input_text - x-stainless-const: true - text: - type: string - description: Plain-text content supplied by the user. - type: object - required: - - type - - text - title: User message input - description: Text block that a user contributed to the thread. - UserMessageQuotedText: - properties: - type: - type: string - enum: - - quoted_text - description: Type discriminator that is always `quoted_text`. - default: quoted_text - x-stainless-const: true - text: - type: string - description: Quoted text content. - type: object - required: - - type - - text - title: User message quoted text - description: Quoted snippet that the user referenced in their message. - AttachmentType: - type: string - enum: - - image - - file - Attachment: - properties: - type: - $ref: '#/components/schemas/AttachmentType' - description: Attachment discriminator. - id: - type: string - description: Identifier for the attachment. - name: - type: string - description: Original display name for the attachment. - mime_type: - type: string - description: MIME type of the attachment. - preview_url: - anyOf: - - type: string - format: uri - description: Preview URL for rendering the attachment inline. - - type: 'null' - type: object - required: - - type - - id - - name - - mime_type - - preview_url - title: Attachment - description: Attachment metadata included on thread items. - ToolChoice: - properties: - id: - type: string - description: Identifier of the requested tool. - type: object - required: - - id - title: Tool choice - description: Tool selection that the assistant should honor when executing the item. - InferenceOptions: - properties: - tool_choice: - anyOf: - - $ref: '#/components/schemas/ToolChoice' - description: Preferred tool to invoke. Defaults to null when ChatKit should auto-select. - - type: 'null' - model: - anyOf: - - type: string - description: Model name that generated the response. Defaults to null when using the session default. - - type: 'null' - type: object - required: - - tool_choice - - model - title: Inference options - description: Model and tool overrides applied when generating the assistant response. - UserMessageItem: - properties: - id: - type: string - description: Identifier of the thread item. - object: - type: string - enum: - - chatkit.thread_item - description: Type discriminator that is always `chatkit.thread_item`. - default: chatkit.thread_item - x-stainless-const: true - created_at: - type: integer - format: unixtime - description: Unix timestamp (in seconds) for when the item was created. - thread_id: - type: string - description: Identifier of the parent thread. - type: - type: string - enum: - - chatkit.user_message - default: chatkit.user_message - x-stainless-const: true - content: - items: - discriminator: - propertyName: type - description: Content blocks that comprise a user message. - anyOf: - - $ref: '#/components/schemas/UserMessageInputText' - - $ref: '#/components/schemas/UserMessageQuotedText' - type: array - description: Ordered content elements supplied by the user. - attachments: - items: - $ref: '#/components/schemas/Attachment' - type: array - description: Attachments associated with the user message. Defaults to an empty list. - inference_options: - anyOf: - - $ref: '#/components/schemas/InferenceOptions' - description: Inference overrides applied to the message. Defaults to null when unset. - - type: 'null' - type: object - required: - - id - - object - - created_at - - thread_id - - type - - content - - attachments - - inference_options - title: User Message Item - description: User-authored messages within a thread. - FileAnnotationSource: - properties: - type: - type: string - enum: - - file - description: Type discriminator that is always `file`. - default: file - x-stainless-const: true - filename: - type: string - description: Filename referenced by the annotation. - type: object - required: - - type - - filename - title: File annotation source - description: Attachment source referenced by an annotation. - FileAnnotation: - properties: - type: - type: string - enum: - - file - description: Type discriminator that is always `file` for this annotation. - default: file - x-stainless-const: true - source: - $ref: '#/components/schemas/FileAnnotationSource' - description: File attachment referenced by the annotation. - type: object - required: - - type - - source - title: File annotation - description: Annotation that references an uploaded file. - UrlAnnotationSource: - properties: - type: - type: string - enum: - - url - description: Type discriminator that is always `url`. - default: url - x-stainless-const: true - url: - type: string - format: uri - description: URL referenced by the annotation. - type: object - required: - - type - - url - title: URL annotation source - description: URL backing an annotation entry. - UrlAnnotation: - properties: - type: - type: string - enum: - - url - description: Type discriminator that is always `url` for this annotation. - default: url - x-stainless-const: true - source: - $ref: '#/components/schemas/UrlAnnotationSource' - description: URL referenced by the annotation. - type: object - required: - - type - - source - title: URL annotation - description: Annotation that references a URL. - ResponseOutputText: - properties: - type: - type: string - enum: - - output_text - description: Type discriminator that is always `output_text`. - default: output_text - x-stainless-const: true - text: - type: string - description: Assistant generated text. - annotations: - items: - discriminator: - propertyName: type - description: Annotation object describing a cited source. - anyOf: - - $ref: '#/components/schemas/FileAnnotation' - - $ref: '#/components/schemas/UrlAnnotation' - type: array - description: Ordered list of annotations attached to the response text. - type: object - required: - - type - - text - - annotations - title: Assistant message content - description: Assistant response text accompanied by optional annotations. - AssistantMessageItem: - properties: - id: - type: string - description: Identifier of the thread item. - object: - type: string - enum: - - chatkit.thread_item - description: Type discriminator that is always `chatkit.thread_item`. - default: chatkit.thread_item - x-stainless-const: true - created_at: - type: integer - format: unixtime - description: Unix timestamp (in seconds) for when the item was created. - thread_id: - type: string - description: Identifier of the parent thread. - type: - type: string - enum: - - chatkit.assistant_message - description: Type discriminator that is always `chatkit.assistant_message`. - default: chatkit.assistant_message - x-stainless-const: true - content: - items: - $ref: '#/components/schemas/ResponseOutputText' - type: array - description: Ordered assistant response segments. - type: object - required: - - id - - object - - created_at - - thread_id - - type - - content - title: Assistant message - description: Assistant-authored message within a thread. - WidgetMessageItem: - properties: - id: - type: string - description: Identifier of the thread item. - object: - type: string - enum: - - chatkit.thread_item - description: Type discriminator that is always `chatkit.thread_item`. - default: chatkit.thread_item - x-stainless-const: true - created_at: - type: integer - format: unixtime - description: Unix timestamp (in seconds) for when the item was created. - thread_id: - type: string - description: Identifier of the parent thread. - type: - type: string - enum: - - chatkit.widget - description: Type discriminator that is always `chatkit.widget`. - default: chatkit.widget - x-stainless-const: true - widget: - type: string - description: Serialized widget payload rendered in the UI. - type: object - required: - - id - - object - - created_at - - thread_id - - type - - widget - title: Widget message - description: Thread item that renders a widget payload. - ClientToolCallStatus: - type: string - enum: - - in_progress - - completed - ClientToolCallItem: - properties: - id: - type: string - description: Identifier of the thread item. - object: - type: string - enum: - - chatkit.thread_item - description: Type discriminator that is always `chatkit.thread_item`. - default: chatkit.thread_item - x-stainless-const: true - created_at: - type: integer - format: unixtime - description: Unix timestamp (in seconds) for when the item was created. - thread_id: - type: string - description: Identifier of the parent thread. - type: - type: string - enum: - - chatkit.client_tool_call - description: Type discriminator that is always `chatkit.client_tool_call`. - default: chatkit.client_tool_call - x-stainless-const: true - status: - $ref: '#/components/schemas/ClientToolCallStatus' - description: Execution status for the tool call. - call_id: - type: string - description: Identifier for the client tool call. - name: - type: string - description: Tool name that was invoked. - arguments: - type: string - description: JSON-encoded arguments that were sent to the tool. - output: - anyOf: - - type: string - description: JSON-encoded output captured from the tool. Defaults to null while execution is in progress. - - type: 'null' - type: object - required: - - id - - object - - created_at - - thread_id - - type - - status - - call_id - - name - - arguments - - output - title: Client tool call - description: Record of a client side tool invocation initiated by the assistant. - TaskType: - type: string - enum: - - custom - - thought - TaskItem: - properties: - id: - type: string - description: Identifier of the thread item. - object: - type: string - enum: - - chatkit.thread_item - description: Type discriminator that is always `chatkit.thread_item`. - default: chatkit.thread_item - x-stainless-const: true - created_at: - type: integer - format: unixtime - description: Unix timestamp (in seconds) for when the item was created. - thread_id: - type: string - description: Identifier of the parent thread. - type: - type: string - enum: - - chatkit.task - description: Type discriminator that is always `chatkit.task`. - default: chatkit.task - x-stainless-const: true - task_type: - $ref: '#/components/schemas/TaskType' - description: Subtype for the task. - heading: - anyOf: - - type: string - description: Optional heading for the task. Defaults to null when not provided. - - type: 'null' - summary: - anyOf: - - type: string - description: Optional summary that describes the task. Defaults to null when omitted. - - type: 'null' - type: object - required: - - id - - object - - created_at - - thread_id - - type - - task_type - - heading - - summary - title: Task item - description: Task emitted by the workflow to show progress and status updates. - TaskGroupTask: - properties: - type: - $ref: '#/components/schemas/TaskType' - description: Subtype for the grouped task. - heading: - anyOf: - - type: string - description: Optional heading for the grouped task. Defaults to null when not provided. - - type: 'null' - summary: - anyOf: - - type: string - description: Optional summary that describes the grouped task. Defaults to null when omitted. - - type: 'null' - type: object - required: - - type - - heading - - summary - title: Task group task - description: Task entry that appears within a TaskGroup. - TaskGroupItem: - properties: - id: - type: string - description: Identifier of the thread item. - object: - type: string - enum: - - chatkit.thread_item - description: Type discriminator that is always `chatkit.thread_item`. - default: chatkit.thread_item - x-stainless-const: true - created_at: - type: integer - format: unixtime - description: Unix timestamp (in seconds) for when the item was created. - thread_id: - type: string - description: Identifier of the parent thread. - type: - type: string - enum: - - chatkit.task_group - description: Type discriminator that is always `chatkit.task_group`. - default: chatkit.task_group - x-stainless-const: true - tasks: - items: - $ref: '#/components/schemas/TaskGroupTask' - type: array - description: Tasks included in the group. - type: object - required: - - id - - object - - created_at - - thread_id - - type - - tasks - title: Task group - description: Collection of workflow tasks grouped together in the thread. - ThreadItem: - discriminator: - propertyName: type - title: The thread item - anyOf: - - $ref: '#/components/schemas/UserMessageItem' - - $ref: '#/components/schemas/AssistantMessageItem' - - $ref: '#/components/schemas/WidgetMessageItem' - - $ref: '#/components/schemas/ClientToolCallItem' - - $ref: '#/components/schemas/TaskItem' - - $ref: '#/components/schemas/TaskGroupItem' - ThreadItemListResource: - properties: - object: - x-stainless-const: true - default: list - description: The type of object returned, must be `list`. - const: list - data: - items: - $ref: '#/components/schemas/ThreadItem' - type: array - description: A list of items - first_id: - anyOf: - - type: string - description: The ID of the first item in the list. - - type: 'null' - last_id: - anyOf: - - type: string - description: The ID of the last item in the list. - - type: 'null' - has_more: - type: boolean - description: Whether there are more items available. - type: object - required: - - object - - data - - first_id - - last_id - - has_more - title: Thread Items - description: A paginated list of thread items rendered for the ChatKit API. - ActiveStatus: - properties: - type: - type: string - enum: - - active - description: Status discriminator that is always `active`. - default: active - x-stainless-const: true - type: object - required: - - type - title: Active thread status - description: Indicates that a thread is active. - LockedStatus: - properties: - type: - type: string - enum: - - locked - description: Status discriminator that is always `locked`. - default: locked - x-stainless-const: true - reason: - anyOf: - - type: string - description: Reason that the thread was locked. Defaults to null when no reason is recorded. - - type: 'null' - type: object - required: - - type - - reason - title: Locked thread status - description: Indicates that a thread is locked and cannot accept new input. - ClosedStatus: - properties: - type: - type: string - enum: - - closed - description: Status discriminator that is always `closed`. - default: closed - x-stainless-const: true - reason: - anyOf: - - type: string - description: Reason that the thread was closed. Defaults to null when no reason is recorded. - - type: 'null' - type: object - required: - - type - - reason - title: Closed thread status - description: Indicates that a thread has been closed. - ThreadResource: - properties: - id: - type: string - description: Identifier of the thread. - object: - type: string - enum: - - chatkit.thread - description: Type discriminator that is always `chatkit.thread`. - default: chatkit.thread - x-stainless-const: true - created_at: - type: integer - format: unixtime - description: Unix timestamp (in seconds) for when the thread was created. - title: - anyOf: - - type: string - description: Optional human-readable title for the thread. Defaults to null when no title has been generated. - - type: 'null' - status: - discriminator: - propertyName: type - description: Current status for the thread. Defaults to `active` for newly created threads. - anyOf: - - $ref: '#/components/schemas/ActiveStatus' - - $ref: '#/components/schemas/LockedStatus' - - $ref: '#/components/schemas/ClosedStatus' - user: - type: string - description: Free-form string that identifies your end user who owns the thread. - type: object - required: - - id - - object - - created_at - - title - - status - - user - title: The thread object - description: Represents a ChatKit thread and its current status. - example: - id: cthr_def456 - object: chatkit.thread - created_at: 1712345600 - title: Demo feedback - status: - type: active - user: user_456 - DeletedThreadResource: - properties: - id: - type: string - description: Identifier of the deleted thread. - object: - type: string - enum: - - chatkit.thread.deleted - description: Type discriminator that is always `chatkit.thread.deleted`. - default: chatkit.thread.deleted - x-stainless-const: true - deleted: - type: boolean - description: Indicates that the thread has been deleted. - type: object - required: - - id - - object - - deleted - title: Deleted thread - description: Confirmation payload returned after deleting a thread. - ThreadListResource: - properties: - object: - x-stainless-const: true - default: list - description: The type of object returned, must be `list`. - const: list - data: - items: - $ref: '#/components/schemas/ThreadResource' - type: array - description: A list of items - first_id: - anyOf: - - type: string - description: The ID of the first item in the list. - - type: 'null' - last_id: - anyOf: - - type: string - description: The ID of the last item in the list. - - type: 'null' - has_more: - type: boolean - description: Whether there are more items available. - type: object - required: - - object - - data - - first_id - - last_id - - has_more - title: Threads - description: A paginated list of ChatKit threads. - EnvironmentTypeResource: - type: string - enum: - - openai_hosted - - self_hosted - description: The kind of execution environment. - EnvironmentStatusResource: - type: string - enum: - - pending - - connected - - disconnected - - expired - - failed - description: The public lifecycle status of an execution environment. - 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. - 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. - HostedEnvironmentFileResource: - description: Metadata for a file materialized in an OpenAI-hosted execution environment. - discriminator: - propertyName: type - mapping: - file_id: '#/components/schemas/HostedEnvironmentFileResourceFileId' - inline: '#/components/schemas/HostedEnvironmentFileResourceInline' - x-oai-discriminator-values: - - file_id - - inline - anyOf: - - $ref: '#/components/schemas/HostedEnvironmentFileResourceFileId' - - $ref: '#/components/schemas/HostedEnvironmentFileResourceInline' - 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. - 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. - HostedSkillResource: - description: A skill installed in an OpenAI-hosted environment. - discriminator: - propertyName: type - mapping: - skill_reference: '#/components/schemas/HostedSkillResourceSkillReference' - inline: '#/components/schemas/HostedSkillResourceInline' - x-oai-discriminator-values: - - skill_reference - - inline - anyOf: - - $ref: '#/components/schemas/HostedSkillResourceSkillReference' - - $ref: '#/components/schemas/HostedSkillResourceInline' - 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. - HostedPluginResource: - description: A plugin installed in an OpenAI-hosted environment. - discriminator: - propertyName: type - mapping: - inline: '#/components/schemas/HostedPluginResourceInline' - x-oai-discriminator-values: - - inline - anyOf: - - $ref: '#/components/schemas/HostedPluginResourceInline' - 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. - files: - type: array - items: - $ref: '#/components/schemas/HostedEnvironmentFileResource' - minItems: 0 - maxItems: 2000 - description: Files installed in the environment, without their contents. - skills: - type: array - items: - $ref: '#/components/schemas/HostedSkillResource' - minItems: 0 - maxItems: 2000 - description: Skills installed in the environment, without their archive contents. - plugins: - type: array - items: - $ref: '#/components/schemas/HostedPluginResource' - minItems: 0 - maxItems: 2000 - description: Plugins installed in the environment, without their archive contents. - required: - - id - - object - - type - - status - - files - - skills - - plugins - additionalProperties: false - description: Safe metadata for a first-class 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. - 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. - 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. - EnvironmentFilePageObjectResource: - type: string - enum: - - page - default: page - x-stainless-const: true - description: The object type for a page of files in an execution environment. - 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. - 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. - 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. - 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. - HostedEnvironmentFileParam: - description: A file materialized in an OpenAI-hosted execution environment. - discriminator: - propertyName: type - mapping: - file_id: '#/components/schemas/HostedEnvironmentFileParamFileId' - inline: '#/components/schemas/HostedEnvironmentFileParamInline' - x-oai-discriminator-values: - - file_id - - inline - anyOf: - - $ref: '#/components/schemas/HostedEnvironmentFileParamFileId' - - $ref: '#/components/schemas/HostedEnvironmentFileParamInline' - SubagentObjectResource: - type: string - enum: - - agent.session.subagent - default: agent.session.subagent - x-stainless-const: true - description: The object type for a subagent. - 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. - 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. - AgentContentResource: - description: A plaintext or encrypted content part exchanged between agents. - discriminator: - propertyName: type - mapping: - output_text: '#/components/schemas/OutputTextResource' - encrypted_content: '#/components/schemas/EncryptedContentResource' - x-oai-discriminator-values: - - output_text - - encrypted_content - anyOf: - - $ref: '#/components/schemas/OutputTextResource' - - $ref: '#/components/schemas/EncryptedContentResource' - 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. - 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. - SessionMessageRoleResource: - type: string - enum: - - user - - assistant - description: The author of a session message. - 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. - 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. - 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. - MessageContentResource: - description: A content part in a session message. - 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 - anyOf: - - $ref: '#/components/schemas/MessageContentResourceInputText' - - $ref: '#/components/schemas/MessageContentResourceInputImage' - - $ref: '#/components/schemas/MessageContentResourceOutputText' - 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. - 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. - 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. - 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. - 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. - 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. - 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. - 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. - 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. - InputContentResource: - description: User-provided content recorded in a session item. - discriminator: - propertyName: type - mapping: - input_text: '#/components/schemas/InputContentResourceInputText' - input_image: '#/components/schemas/InputContentResourceInputImage' - x-oai-discriminator-values: - - input_text - - input_image - anyOf: - - $ref: '#/components/schemas/InputContentResourceInputText' - - $ref: '#/components/schemas/InputContentResourceInputImage' - FunctionCallOutputResource: - description: The text or model-input content supplied as a function result. - anyOf: - - type: string - minLength: 0 - - type: array - items: - $ref: '#/components/schemas/InputContentResource' - minItems: 0 - maxItems: 2000 - 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. - 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. - 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. - 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. - 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. - 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. - 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. - WebSearchActionResource: - description: An action performed by the web search tool. - 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 - anyOf: - - $ref: '#/components/schemas/WebSearchActionResourceSearch' - - $ref: '#/components/schemas/WebSearchActionResourceOpenPage' - - $ref: '#/components/schemas/WebSearchActionResourceFindInPage' - - $ref: '#/components/schemas/WebSearchActionResourceOther' - 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. - 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. - 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. - 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. - 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. - 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. - 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. - 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. - SessionTurnItemResource: - description: An item associated with a session turn. - 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 - anyOf: - - $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' - 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. - TurnObjectResource: - type: string - enum: - - agent.session.turn - default: agent.session.turn - x-stainless-const: true - description: The object type for a turn. - 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. - 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. - 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. - 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. - 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. - 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. - 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. - 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. - ReasoningEffortResource: - type: string - enum: - - none - - minimal - - low - - medium - - high - - xhigh - - max - description: The amount of reasoning effort used by an agent. - 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. - 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. - 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. - 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. - TextFormatResource: - description: The effective output format for generated text. - discriminator: - propertyName: type - mapping: - text: '#/components/schemas/TextFormatResourceText' - json_schema: '#/components/schemas/TextFormatResourceJsonSchema' - x-oai-discriminator-values: - - text - - json_schema - anyOf: - - $ref: '#/components/schemas/TextFormatResourceText' - - $ref: '#/components/schemas/TextFormatResourceJsonSchema' - VerbosityResource: - type: string - enum: - - low - - medium - - high - description: The amount of text produced by an agent. - 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. - ServiceTierResource: - type: string - enum: - - auto - - default - - flex - - priority - - fast - description: The service-tier policy configured for an agent. - 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. - 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. - 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. - 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. - 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. - PersistedMcpTransportResource: - description: A credential-free transport used to connect to an MCP server. - discriminator: - propertyName: type - mapping: - http: '#/components/schemas/PersistedMcpTransportResourceHttp' - stdio: '#/components/schemas/PersistedMcpTransportResourceStdio' - x-oai-discriminator-values: - - http - - stdio - anyOf: - - $ref: '#/components/schemas/PersistedMcpTransportResourceHttp' - - $ref: '#/components/schemas/PersistedMcpTransportResourceStdio' - McpConnectionOriginResource: - type: string - enum: - - service - - environment - description: Where outbound MCP HTTP connections originate. - 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. - WebSearchModeResource: - type: string - enum: - - disabled - - cached - - live - description: The source used for web search results. - WebSearchContextSizeResource: - type: string - enum: - - low - - medium - - high - description: The amount of web search context made available to the model. - 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. - 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. - PersistedAgentToolResource: - description: A credential-free tool available to a reusable agent. - 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 - anyOf: - - $ref: '#/components/schemas/PersistedAgentToolResourceFunction' - - $ref: '#/components/schemas/PersistedAgentToolResourceToolSearch' - - $ref: '#/components/schemas/PersistedAgentToolResourceProgrammaticToolCalling' - - $ref: '#/components/schemas/PersistedAgentToolResourceMcp' - - $ref: '#/components/schemas/PersistedAgentToolResourceWebSearch' - 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. - 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. - 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. - ReasoningEffortParam: - type: string - enum: - - none - - minimal - - low - - medium - - high - - xhigh - - max - description: The amount of reasoning effort the model should use. - 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. - 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. - 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. - 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. - TextFormatParam: - description: The output format for generated text. - discriminator: - propertyName: type - mapping: - text: '#/components/schemas/TextFormatParamText' - json_schema: '#/components/schemas/TextFormatParamJsonSchema' - x-oai-discriminator-values: - - text - - json_schema - anyOf: - - $ref: '#/components/schemas/TextFormatParamText' - - $ref: '#/components/schemas/TextFormatParamJsonSchema' - 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. - 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. - 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. - 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. - 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. - PersistedAgentToolConfigParamProgrammaticToolCalling: - type: object + - title: BetaResponseAudioWsDelta + description: Emitted when there is a partial audio response. + allOf: + - $ref: '#/components/schemas/BetaResponseAudioDeltaEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseAudioWsDone + description: Emitted when the audio response is complete. + allOf: + - $ref: '#/components/schemas/BetaResponseAudioDoneEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseAudioTranscriptWsDelta + description: Emitted when there is a partial transcript of audio. + allOf: + - $ref: '#/components/schemas/BetaResponseAudioTranscriptDeltaEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseAudioTranscriptWsDone + description: Emitted when the full audio transcript is completed. + allOf: + - $ref: '#/components/schemas/BetaResponseAudioTranscriptDoneEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseCodeInterpreterCallCodeWsDelta + description: Emitted when a partial code snippet is streamed by the code interpreter. + allOf: + - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallCodeDeltaEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseCodeInterpreterCallCodeWsDone + description: Emitted when the code snippet is finalized by the code interpreter. + allOf: + - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallCodeDoneEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseCodeInterpreterCallWsCompleted + description: Emitted when the code interpreter call is completed. + allOf: + - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallCompletedEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseCodeInterpreterCallInWsProgress + description: Emitted when a code interpreter call is in progress. + allOf: + - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallInProgressEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseCodeInterpreterCallWsInterpreting + description: Emitted when the code interpreter is actively interpreting the code snippet. + allOf: + - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallInterpretingEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseCompactionWsCompacting + description: Emitted when new summary content is sampled for a compaction trigger. Contains no summary content. + allOf: + - $ref: '#/components/schemas/BetaResponseCompactionCompactingStreamingEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseWsCompleted + description: Emitted when the model response is complete. + allOf: + - $ref: '#/components/schemas/BetaResponseCompletedEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseContentPartWsAdded + description: Emitted when a new content part is added. + allOf: + - $ref: '#/components/schemas/BetaResponseContentPartAddedEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseContentPartWsDone + description: Emitted when a content part is done. + allOf: + - $ref: '#/components/schemas/BetaResponseContentPartDoneEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseWsCreated + description: | + An event that is emitted when a response is created. + allOf: + - $ref: '#/components/schemas/BetaResponseCreatedEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseFileSearchCallWsCompleted + description: Emitted when a file search call is completed (results found). + allOf: + - $ref: '#/components/schemas/BetaResponseFileSearchCallCompletedEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseFileSearchCallInWsProgress + description: Emitted when a file search call is initiated. + allOf: + - $ref: '#/components/schemas/BetaResponseFileSearchCallInProgressEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseFileSearchCallWsSearching + description: Emitted when a file search is currently searching. + allOf: + - $ref: '#/components/schemas/BetaResponseFileSearchCallSearchingEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseFunctionCallArgumentsWsDelta + description: Emitted when there is a partial function-call arguments delta. + allOf: + - $ref: '#/components/schemas/BetaResponseFunctionCallArgumentsDeltaEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseFunctionCallArgumentsWsDone + description: Emitted when function-call arguments are finalized. + allOf: + - $ref: '#/components/schemas/BetaResponseFunctionCallArgumentsDoneEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseShellCallCommandWsAdded + description: A streaming event that indicated a shell command was added to a tool call. + allOf: + - $ref: '#/components/schemas/BetaResponseShellCallCommandAddedStreamingEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseShellCallCommandWsDelta + description: A streaming event that indicated a shell command was incrementally updated. + allOf: + - $ref: '#/components/schemas/BetaResponseShellCallCommandDeltaStreamingEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseShellCallCommandWsDone + description: A streaming event that indicated a shell command was completed. + allOf: + - $ref: '#/components/schemas/BetaResponseShellCallCommandDoneStreamingEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseShellCallOutputContentWsDelta + description: A streaming event that indicated shell call output was incrementally added. + allOf: + - $ref: '#/components/schemas/BetaResponseShellCallOutputContentDeltaStreamingEvent' + x-stainless-skip: + - go + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseShellCallOutputContentWsDone + description: A streaming event that indicated shell call output was completed. + allOf: + - $ref: '#/components/schemas/BetaResponseShellCallOutputContentDoneStreamingEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseInWsProgress + description: Emitted when the response is in progress. + allOf: + - $ref: '#/components/schemas/BetaResponseInProgressEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseWsFailed + description: | + An event that is emitted when a response fails. + allOf: + - $ref: '#/components/schemas/BetaResponseFailedEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseWsIncomplete + description: | + An event that is emitted when a response finishes as incomplete. + + Over WebSocket, steering can finish a response with + `response.incomplete_details.reason` set to `steered`, followed automatically + by a successor `response.created` that commits the queued steering input. + allOf: + - $ref: '#/components/schemas/BetaResponseIncompleteEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseOutputItemWsAdded + description: Emitted when a new output item is added. + allOf: + - $ref: '#/components/schemas/BetaResponseOutputItemAddedEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseOutputItemWsDone + description: Emitted when an output item is marked done. + allOf: + - $ref: '#/components/schemas/BetaResponseOutputItemDoneEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseReasoningSummaryPartWsAdded + description: Emitted when a new reasoning summary part is added. + allOf: + - $ref: '#/components/schemas/BetaResponseReasoningSummaryPartAddedEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseReasoningSummaryPartWsDone + description: Emitted when a reasoning summary part is completed. + allOf: + - $ref: '#/components/schemas/BetaResponseReasoningSummaryPartDoneEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseReasoningSummaryTextWsDelta + description: Emitted when a delta is added to a reasoning summary text. + allOf: + - $ref: '#/components/schemas/BetaResponseReasoningSummaryTextDeltaEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseReasoningSummaryTextWsDone + description: Emitted when a reasoning summary text is completed. + allOf: + - $ref: '#/components/schemas/BetaResponseReasoningSummaryTextDoneEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseReasoningTextWsDelta + description: Emitted when a delta is added to a reasoning text. + allOf: + - $ref: '#/components/schemas/BetaResponseReasoningTextDeltaEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseReasoningTextWsDone + description: Emitted when a reasoning text is completed. + allOf: + - $ref: '#/components/schemas/BetaResponseReasoningTextDoneEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseRefusalWsDelta + description: Emitted when there is a partial refusal text. + allOf: + - $ref: '#/components/schemas/BetaResponseRefusalDeltaEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseRefusalWsDone + description: Emitted when refusal text is finalized. + allOf: + - $ref: '#/components/schemas/BetaResponseRefusalDoneEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseTextWsDelta + description: Emitted when there is an additional text delta. + allOf: + - $ref: '#/components/schemas/BetaResponseTextDeltaEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseTextWsDone + description: Emitted when text content is finalized. + allOf: + - $ref: '#/components/schemas/BetaResponseTextDoneEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseWebSearchCallWsCompleted + description: Emitted when a web search call is completed. + allOf: + - $ref: '#/components/schemas/BetaResponseWebSearchCallCompletedEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseWebSearchCallInWsProgress + description: Emitted when a web search call is initiated. + allOf: + - $ref: '#/components/schemas/BetaResponseWebSearchCallInProgressEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseWebSearchCallWsSearching + description: Emitted when a web search call is executing. + allOf: + - $ref: '#/components/schemas/BetaResponseWebSearchCallSearchingEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseImageGenCallWsCompleted + description: | + Emitted when an image generation tool call has completed and the final image is available. + allOf: + - $ref: '#/components/schemas/BetaResponseImageGenCallCompletedEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseImageGenCallWsGenerating + description: | + Emitted when an image generation tool call is actively generating an image (intermediate state). + allOf: + - $ref: '#/components/schemas/BetaResponseImageGenCallGeneratingEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseImageGenCallInWsProgress + description: | + Emitted when an image generation tool call is in progress. + allOf: + - $ref: '#/components/schemas/BetaResponseImageGenCallInProgressEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseImageGenCallPartialWsImage + description: | + Emitted when a partial image is available during image generation streaming. + allOf: + - $ref: '#/components/schemas/BetaResponseImageGenCallPartialImageEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseMcpCallArgumentsWsDelta + description: | + Emitted when there is a delta (partial update) to the arguments of an MCP tool call. + allOf: + - $ref: '#/components/schemas/BetaResponseMCPCallArgumentsDeltaEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseMcpCallArgumentsWsDone + description: | + Emitted when the arguments for an MCP tool call are finalized. + allOf: + - $ref: '#/components/schemas/BetaResponseMCPCallArgumentsDoneEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseMcpCallWsCompleted + description: | + Emitted when an MCP tool call has completed successfully. + allOf: + - $ref: '#/components/schemas/BetaResponseMCPCallCompletedEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseMcpCallWsFailed + description: | + Emitted when an MCP tool call has failed. + allOf: + - $ref: '#/components/schemas/BetaResponseMCPCallFailedEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseMcpCallInWsProgress + description: | + Emitted when an MCP tool call is in progress. + allOf: + - $ref: '#/components/schemas/BetaResponseMCPCallInProgressEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseMcpListToolsWsCompleted + description: | + Emitted when the list of available MCP tools has been successfully retrieved. + allOf: + - $ref: '#/components/schemas/BetaResponseMCPListToolsCompletedEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseMcpListToolsWsFailed + description: | + Emitted when the attempt to list available MCP tools has failed. + allOf: + - $ref: '#/components/schemas/BetaResponseMCPListToolsFailedEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseMcpListToolsInWsProgress + description: | + Emitted when the system is in the process of retrieving the list of available MCP tools. + allOf: + - $ref: '#/components/schemas/BetaResponseMCPListToolsInProgressEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseOutputTextAnnotationWsAdded + description: | + Emitted when an annotation is added to output text content. + allOf: + - $ref: '#/components/schemas/BetaResponseOutputTextAnnotationAddedEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseWsQueued + description: | + Emitted when a response is queued and waiting to be processed. + allOf: + - $ref: '#/components/schemas/BetaResponseQueuedEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseCustomToolCallInputWsDelta + description: | + Event representing a delta (partial update) to the input of a custom tool call. + allOf: + - $ref: '#/components/schemas/BetaResponseCustomToolCallInputDeltaEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseCustomToolCallInputWsDone + description: | + Event indicating that input for a custom tool call is complete. + allOf: + - $ref: '#/components/schemas/BetaResponseCustomToolCallInputDoneEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - $ref: '#/components/schemas/BetaResponseWsError' + - $ref: '#/components/schemas/BetaResponseSteerAcceptedEvent' + - $ref: '#/components/schemas/BetaResponseSteerPendingEvent' + - $ref: '#/components/schemas/BetaResponseSteerFailedEvent' + - $ref: '#/components/schemas/BetaResponseInjectCreatedEvent' + - $ref: '#/components/schemas/BetaResponseInjectFailedEvent' + PublicProjectResidency: + type: string + enum: + - GLOBAL + - US_STORAGE_PROCESSING + - EU_STORAGE_PROCESSING + - JP_STORAGE + - KR_STORAGE + - CA_STORAGE + - SG_STORAGE + - IN_STORAGE + - AU_STORAGE + - GB_STORAGE + - AE_STORAGE + - AE_STORAGE_PROCESSING + SpecificProgrammaticToolCallingParam: properties: type: type: string enum: - programmatic_tool_calling + description: The tool to call. Always `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. - 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. - PersistedMcpTransportConfigParamStdio: - type: object + SpecificApplyPatchParam: properties: type: type: string enum: - - stdio - default: stdio + - apply_patch + description: The tool to call. Always `apply_patch`. + default: apply_patch 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. - PersistedMcpTransportConfigParam: - description: A credential-free transport used to connect to an MCP server. - discriminator: - propertyName: type - mapping: - http: '#/components/schemas/PersistedMcpTransportConfigParamHttp' - stdio: '#/components/schemas/PersistedMcpTransportConfigParamStdio' - x-oai-discriminator-values: - - http - - stdio - anyOf: - - $ref: '#/components/schemas/PersistedMcpTransportConfigParamHttp' - - $ref: '#/components/schemas/PersistedMcpTransportConfigParamStdio' - 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. - 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. - 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. - WebSearchContextSizeParam: - type: string - enum: - - low - - medium - - high - description: The amount of web search context made available to the model. - 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. - PersistedAgentToolConfigParamWebSearch: - type: object + title: Specific apply patch tool choice + description: Forces the model to call the apply_patch tool when executing a tool call. + SpecificFunctionShellParam: properties: type: type: string enum: - - web_search - default: web_search + - shell + description: The tool to call. Always `shell`. + default: shell 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. + type: object required: - type - additionalProperties: false - description: Web search. - PersistedAgentToolConfigParam: - description: A tool that can be stored on a reusable agent without session credentials. - 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 - anyOf: - - $ref: '#/components/schemas/PersistedAgentToolConfigParamFunction' - - $ref: '#/components/schemas/PersistedAgentToolConfigParamToolSearch' - - $ref: '#/components/schemas/PersistedAgentToolConfigParamProgrammaticToolCalling' - - $ref: '#/components/schemas/PersistedAgentToolConfigParamMcp' - - $ref: '#/components/schemas/PersistedAgentToolConfigParamWebSearch' - MultiAgentConfigCurrentParam: - type: object + title: Specific shell tool choice + description: Forces the model to call the shell tool when a tool call is required. + ResponsePromptCacheOptionsParam: properties: - enabled: + ttl: + $ref: '#/components/schemas/PromptCacheTTLEnum' + description: The minimum lifetime applied to every implicit and explicit cache breakpoint written by the request. Defaults to `30m`, which is currently the only supported value. The backend may retain cache entries for longer. + mode: + $ref: '#/components/schemas/PromptCacheModeEnum' + description: Controls whether OpenAI automatically creates an implicit cache breakpoint. Defaults to `implicit`. With `implicit`, OpenAI creates one implicit breakpoint and writes up to the latest three explicit breakpoints in the request. With `explicit`, OpenAI does not create an implicit breakpoint and writes up to the latest four explicit breakpoints. If there are no explicit breakpoints, the request does not use prompt caching. + prewarm: 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. - 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. - 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: + description: Prepares the prompt cache without generating output. Defaults to `false`. When set to `true`, overrides the `generate` field to `false`. + comparison_response_id: anyOf: - - $ref: '#/components/schemas/MultiAgentConfigCurrentParam' + - type: string + description: The ID of a response to compare when diagnosing prompt cache reuse. Supplying this field requests prompt cache diagnostics when the feature is enabled. + example: resp_123 - 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. - DeletedAgentResource: type: object + required: [] + title: Prompt cache options + description: Options for prompt caching. Supported for `gpt-5.6` and later models. By default, OpenAI automatically chooses one implicit cache breakpoint. You can add explicit breakpoints to content blocks with `prompt_cache_breakpoint`. Each request can write up to four breakpoints. For cache matching, OpenAI considers up to the latest 80 breakpoints in the conversation, without a content-block lookback limit. Set `mode` to `explicit` to disable the implicit breakpoint. The `ttl` defaults to `30m`, which is currently the only supported value. See the [prompt caching guide](https://developers.openai.com/api/docs/guides/prompt-caching) for current details. + ReasoningModeEnum: + anyOf: + - type: string + - type: string + enum: + - standard + - pro + ConversationParam-2: 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`. + description: The unique ID of the conversation. + example: conv_123 + type: object required: - id - - object - - deleted - additionalProperties: false - description: A deleted reusable agent. - EnvironmentPackagesResource: + title: Conversation object + description: The conversation that this response belongs to. + ContextManagementParam: + properties: + type: + type: string + description: The context management entry type. Currently only 'compaction' is supported. + compact_threshold: + anyOf: + - type: integer + minimum: 1000 + description: Token threshold at which compaction should be triggered for this entry. + - type: 'null' type: object + required: + - type + PromptCacheOptions: 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. + ttl: + $ref: '#/components/schemas/PromptCacheTTLEnum' + description: The minimum lifetime applied to each cache breakpoint. + mode: + $ref: '#/components/schemas/PromptCacheModeEnum' + description: Whether implicit prompt-cache breakpoints were enabled. + comparison_response_id: + anyOf: + - type: string + description: The response ID supplied as the prompt cache diagnostics comparison. + - type: 'null' + type: object required: - - python - - system - - npm - additionalProperties: false - description: Packages installed in an OpenAI-hosted environment. - NetworkAccessResource: + - ttl + - mode + title: Prompt cache options + description: The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + CacheMissReasonTypeEnum: 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. - 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. - HostedTemplateSkillResourceSkillReference: - type: object + - model_changed + - prompt_cache_key_changed + - tools_changed + - text_format_changed + - reasoning_effort_changed + - verbosity_changed + - context_compacted + - input_changed + - service_tier_changed + PromptCacheMissDiagnosticsBody: properties: type: type: string enum: - - skill_reference - default: skill_reference + - cache_miss + default: cache_miss 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`. + reason: + $ref: '#/components/schemas/CacheMissReasonTypeEnum' + description: The reason prompt cache reuse did not occur. + cache_missed_tokens: + type: integer + description: The estimated number of input tokens affected after the first detected divergence. + comparison_reusable_tokens: + type: integer + description: The raw token count of the reusable prefix in the compared response. + type: object required: - type - - skill_id - - version - additionalProperties: false - description: A skill resolved afresh from the Skills API whenever a session starts. - HostedTemplateSkillResourceInline: - type: object + - reason + - cache_missed_tokens + PromptCacheHitDiagnosticsBody: properties: type: type: string enum: - - inline - default: inline + - cache_hit + default: cache_hit 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`. + type: object required: - type - - name - - description - additionalProperties: false - description: Safe metadata for an inline skill archive. - HostedTemplateSkillResource: - description: Safe metadata for a skill configured by an environment template. - discriminator: - propertyName: type - mapping: - skill_reference: '#/components/schemas/HostedTemplateSkillResourceSkillReference' - inline: '#/components/schemas/HostedTemplateSkillResourceInline' - x-oai-discriminator-values: - - skill_reference - - inline - anyOf: - - $ref: '#/components/schemas/HostedTemplateSkillResourceSkillReference' - - $ref: '#/components/schemas/HostedTemplateSkillResourceInline' - HostedTemplateFileResourceFileId: - type: object + PromptCacheComparisonResponseNotFoundDiagnosticsBody: properties: type: type: string enum: - - file_id - default: file_id + - comparison_response_not_found + default: comparison_response_not_found 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. + type: object required: - type - - file_id - - path - additionalProperties: false - description: A project-scoped Files API reference resolved separately for each session. - HostedTemplateFileResourceInline: - type: object + PromptCacheUnavailableDiagnosticsBody: properties: type: type: string enum: - - inline - default: inline + - unavailable + default: unavailable 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. + type: object required: - type - - path - - size_bytes - additionalProperties: false - description: Metadata for confidential inline file contents. - HostedTemplateFileResource: - description: Safe metadata for a file configured by an environment template. + PromptCacheDiagnostics: discriminator: propertyName: type - mapping: - file_id: '#/components/schemas/HostedTemplateFileResourceFileId' - inline: '#/components/schemas/HostedTemplateFileResourceInline' - x-oai-discriminator-values: - - file_id - - inline + description: Prompt cache diagnostics requested for this response. anyOf: - - $ref: '#/components/schemas/HostedTemplateFileResourceFileId' - - $ref: '#/components/schemas/HostedTemplateFileResourceInline' - EnvironmentTemplateResource: - type: object + - $ref: '#/components/schemas/PromptCacheMissDiagnosticsBody' + - $ref: '#/components/schemas/PromptCacheHitDiagnosticsBody' + - $ref: '#/components/schemas/PromptCacheComparisonResponseNotFoundDiagnosticsBody' + - $ref: '#/components/schemas/PromptCacheUnavailableDiagnosticsBody' + ModerationErrorBody: 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: type: string enum: - - agent.environment.template - default: agent.environment.template + - error + description: The object type, which was always `error` for moderation failures. + default: error 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. - EnvironmentTemplateListResource: - type: object - properties: - object: + code: 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. - EnvironmentPackagesParam: + description: The error code. + message: + type: string + description: The error message. type: object + required: + - type + - code + - message + title: Moderation error + description: An error produced while attempting moderation for the response input or output. + Moderation: 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. - SetupCommandParam: + input: + discriminator: + propertyName: type + description: Moderation for the response input. + anyOf: + - $ref: '#/components/schemas/ModerationResultBody' + - $ref: '#/components/schemas/ModerationErrorBody' + output: + discriminator: + propertyName: type + description: Moderation for the response output. + anyOf: + - $ref: '#/components/schemas/ModerationResultBody' + - $ref: '#/components/schemas/ModerationErrorBody' type: object + required: + - input + - output + title: Moderation + description: Moderation results or errors for the response input and output. + ResponseConversation: properties: - command: + id: 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. - 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. - NetworkPolicyParam: + description: The unique ID of the conversation that this response was associated with. 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. - HostedSkillParamSkillReference: + - id + title: Conversation + description: The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + ResponseCompactionCompactingStreamingEvent: + properties: + type: + type: string + enum: + - response.compaction.compacting + description: The type of the event, always `response.compaction.compacting`. + default: response.compaction.compacting + x-stainless-const: true + sequence_number: + type: integer + description: The sequence number of the event that was emitted. + output_index: + type: integer + description: The index of the compaction output item. + item_id: + type: string + description: The ID of the compaction output item. type: object + required: + - type + - sequence_number + - output_index + - item_id + title: Response compaction compacting event + description: Emitted when new summary content is sampled for a compaction trigger. Contains no summary content. + ResponseShellCallCommandAddedStreamingEvent: properties: type: type: string enum: - - skill_reference - default: skill_reference + - response.shell_call_command.added + description: The type of the event, always `response.shell_call_command.added`. + default: response.shell_call_command.added x-stainless-const: true - description: The type of the object. Always `skill_reference`. - skill_id: + sequence_number: + type: integer + description: The sequence number of the event that was emitted. + output_index: + type: integer + description: The index of the output item that was updated. + command_index: + type: integer + description: The index of the shell command that was added. + command: 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. + description: The shell command that was added. + type: object required: - type - - skill_id - additionalProperties: false - description: References a skill uploaded through the Skills API. - InlineCapabilitySourceParamBase64: - type: object + - sequence_number + - output_index + - command_index + - command + title: Response shell command added event + description: A streaming event that indicated a shell command was added to a tool call. + ResponseShellCallCommandDeltaStreamingEvent: properties: type: type: string enum: - - base64 - default: base64 + - response.shell_call_command.delta + description: The type of the event, always `response.shell_call_command.delta`. + default: response.shell_call_command.delta x-stainless-const: true - description: The type of the object. Always `base64`. - media_type: + sequence_number: + type: integer + description: The sequence number of the event that was emitted. + output_index: + type: integer + description: The index of the output item that was updated. + command_index: + type: integer + description: The index of the shell command that was updated. + delta: + type: string + description: The shell command delta that was appended. + obfuscation: + type: string + description: An obfuscation string that was added to pad the event payload. + type: object + required: + - type + - sequence_number + - output_index + - command_index + - delta + title: Response shell command delta event + description: A streaming event that indicated a shell command was incrementally updated. + ResponseShellCallCommandDoneStreamingEvent: + properties: + type: type: string enum: - - application/zip - default: application/zip + - response.shell_call_command.done + description: The type of the event, always `response.shell_call_command.done`. + default: response.shell_call_command.done x-stainless-const: true - x-enumDescriptions: - - A ZIP archive. - description: The archive media type, always `application/zip`. - data: + sequence_number: + type: integer + description: The sequence number of the event that was emitted. + output_index: + type: integer + description: The index of the output item that was updated. + command_index: + type: integer + description: The index of the shell command that was completed. + command: type: string - minLength: 1 - maxLength: 70254592 - description: Standard-base64 encoded ZIP archive bytes. + description: The final shell command that was emitted. + type: object required: - type - - media_type - - data - additionalProperties: false - description: Provides ZIP bytes encoded with standard base64. - InlineCapabilitySourceParam: - description: The encoded ZIP archive for an inline skill or plugin. - discriminator: - propertyName: type - mapping: - base64: '#/components/schemas/InlineCapabilitySourceParamBase64' - x-oai-discriminator-values: - - base64 - anyOf: - - $ref: '#/components/schemas/InlineCapabilitySourceParamBase64' - HostedSkillParamInline: + - sequence_number + - output_index + - command_index + - command + title: Response shell command done event + description: A streaming event that indicated a shell command was completed. + ShellCallOutputDelta: + properties: + stdout: + type: string + description: The stdout delta that was emitted. + stderr: + type: string + description: The stderr delta that was emitted. type: object + required: [] + title: Shell call output delta + description: A delta of stdout/stderr emitted while a shell call was running. + ResponseShellCallOutputContentDeltaStreamingEvent: properties: type: type: string enum: - - inline - default: inline + - response.shell_call_output_content.delta + description: The type of the event, always `response.shell_call_output_content.delta`. + default: response.shell_call_output_content.delta 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: + sequence_number: + type: integer + description: The sequence number of the event that was emitted. + item_id: type: string - minLength: 0 - maxLength: 1048576 - description: The skill description declared in `SKILL.md`. - source: - $ref: '#/components/schemas/InlineCapabilitySourceParam' - description: The inline ZIP archive. + description: The ID of the output item that was updated. + output_index: + type: integer + description: The index of the output item that was updated. + command_index: + type: integer + description: The index of the shell command that produced output. + delta: + $ref: '#/components/schemas/ShellCallOutputDelta' + description: The stdout/stderr delta that was emitted. + type: object required: - type - - name - - description - - source - additionalProperties: false - description: Supplies a skill ZIP directly in the session request. - HostedSkillParam: - description: A skill installed in an OpenAI-hosted environment. - discriminator: - propertyName: type - mapping: - skill_reference: '#/components/schemas/HostedSkillParamSkillReference' - inline: '#/components/schemas/HostedSkillParamInline' - x-oai-discriminator-values: - - skill_reference - - inline - anyOf: - - $ref: '#/components/schemas/HostedSkillParamSkillReference' - - $ref: '#/components/schemas/HostedSkillParamInline' - HostedPluginParamInline: - type: object + - sequence_number + - item_id + - output_index + - command_index + - delta + title: Response shell call output content delta event + description: A streaming event that indicated shell call output was incrementally added. + ResponseShellCallOutputContentDoneStreamingEvent: properties: type: type: string enum: - - inline - default: inline + - response.shell_call_output_content.done + description: The type of the event, always `response.shell_call_output_content.done`. + default: response.shell_call_output_content.done 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: + sequence_number: + type: integer + description: The sequence number of the event that was emitted. + item_id: 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. + description: The ID of the output item that was updated. + output_index: + type: integer + description: The index of the output item that was updated. + command_index: + type: integer + description: The index of the shell command that produced output. + output: + items: + $ref: '#/components/schemas/FunctionShellCallOutputContent' + type: array + description: The output contents emitted for the shell command. + type: object required: - type - - name - - description - - source - additionalProperties: false - description: Supplies a plugin ZIP directly in the session request. - HostedPluginParam: - description: A plugin installed in an OpenAI-hosted environment. - discriminator: - propertyName: type - mapping: - inline: '#/components/schemas/HostedPluginParamInline' - x-oai-discriminator-values: - - inline - anyOf: - - $ref: '#/components/schemas/HostedPluginParamInline' - CreateEnvironmentTemplateParams: - type: object + - sequence_number + - item_id + - output_index + - command_index + - output + title: Response shell call output content done event + description: A streaming event that indicated shell call output was completed. + CreateConversationBody: properties: - packages: + metadata: anyOf: - - $ref: '#/components/schemas/EnvironmentPackagesParam' + - $ref: '#/components/schemas/Metadata' + description: |- + Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. + Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. - 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: + items: anyOf: - - $ref: '#/components/schemas/NetworkPolicyParam' + - items: + $ref: '#/components/schemas/InputItem' + type: array + maxItems: 20 + description: Initial items to include in the conversation context. You may add up to 20 items at a time. - 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. - UpdateEnvironmentTemplateParams: type: object + required: [] + UpdateConversationBody: 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. - DeletedEnvironmentTemplateResource: + metadata: + $ref: '#/components/schemas/Metadata' + description: |- + Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. + Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. + type: object + required: + - metadata + DeletedConversationResource: + properties: + object: + type: string + enum: + - conversation.deleted + default: conversation.deleted + x-stainless-const: true + deleted: + type: boolean + id: + type: string type: object + required: + - object + - deleted + - id + BetaContent: + description: | + Multi-modal input and output contents. + anyOf: + - title: Input content types + $ref: '#/components/schemas/BetaInputContent' + - title: Output content types + $ref: '#/components/schemas/BetaOutputContent' + BetaIncludeEnum: + type: string + enum: + - file_search_call.results + - web_search_call.results + - web_search_call.action.sources + - message.input_image.image_url + - computer_call_output.output.image_url + - code_interpreter_call.outputs + - reasoning.encrypted_content + - message.output_text.logprobs + description: |- + Specify additional output data to include in the model response. Currently supported values are: + - `web_search_call.results`: Include the search results of the web search tool call. + - `web_search_call.action.sources`: Include the sources of the web search tool call. + - `code_interpreter_call.outputs`: Includes the outputs of python code execution in code interpreter tool call items. + - `computer_call_output.output.image_url`: Include image urls from the computer call output. + - `file_search_call.results`: Include the search results of the file search tool call. + - `message.input_image.image_url`: Include image urls from the input message. + - `message.output_text.logprobs`: Include logprobs with assistant messages. + - `reasoning.encrypted_content`: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the `store` parameter is set to `false`, or when an organization is enrolled in the zero data retention program). + BetaInputParam: + description: | + Text, image, or file inputs to the model, used to generate a response. + + Learn more: + - [Text inputs and outputs](https://developers.openai.com/api/docs/guides/text) + - [Image inputs](https://developers.openai.com/api/docs/guides/images-vision) + - [File inputs](https://developers.openai.com/api/docs/guides/file-inputs) + - [Conversation state](https://developers.openai.com/api/docs/guides/conversation-state) + - [Function calling](https://developers.openai.com/api/docs/guides/function-calling) + anyOf: + - type: string + title: Text input + description: | + A text input to the model, equivalent to a text input with the + `user` role. + - type: array + title: Input item list + description: | + A list of one or many input items to the model, containing + different content types. + items: + $ref: '#/components/schemas/BetaInputItem' + SafetyAlertErrorType: + type: string + enum: + - potentially_unintended_data_transfer + - potentially_unintended_data_access + - potentially_unintended_destructive_activity + - other + SafetyAlertResource: 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 + - safety.alert + default: safety.alert x-stainless-const: true - description: The object type. Always `agent.environment.template.deleted`. - deleted: + created_at: + type: integer + format: unixtime + request_id: + type: string + response_id: + type: string + model: + type: string + request_paused: type: boolean - description: Whether the environment template was deleted. Always `true`. + description: Whether block registration succeeded for this request. This does not confirm that response execution stopped. + error_type: + $ref: '#/components/schemas/SafetyAlertErrorType' + reason: + anyOf: + - type: string + description: A customer-safe description derived from error_type, or null for zero data retention requests. + - type: 'null' + type: object required: - id - object - - deleted - additionalProperties: false - description: A deleted reusable 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. - SessionRequiredActionResourceFunctionCall: + - created_at + - request_id + - response_id + - model + - request_paused + - error_type + - reason + BetaResponseWsError: type: object + title: ResponseWsError + description: Emitted when an error occurs while processing a Responses WebSocket request. properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. type: type: string + description: The type of the event. Always `error`. enum: - - function_call - default: function_call + - error 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: + status: + type: integer + description: The HTTP status code associated with a WebSocket protocol error. + sequence_number: + type: integer + description: The sequence number of an error emitted by the response stream. + error: + $ref: '#/components/schemas/BetaErrorPayload' + description: Details about the error. + stream_id: type: string - minLength: 0 - description: The function name. - arguments: - description: The arguments supplied by the model. + description: | + The WebSocket lane that emitted this event. This field is present when the + originating `response.create` event supplied a `stream_id`. required: - type - - turn_id - - call_id - - name - - arguments - additionalProperties: false - description: Run a function tool and submit its result. - SessionRequiredActionResourceEnvironmentConnection: + - error + x-oaiMeta: + name: error + group: responses + example: | + { + "type": "error", + "status": 400, + "stream_id": "agent_1", + "error": { + "type": "invalid_request_error", + "code": "websocket_stream_limit_reached", + "message": "This WebSocket connection has reached its stream limit.", + "param": "stream_id" + } + } + BetaResponseInjectFailedEvent: type: object + title: ResponseInjectFailedEvent + description: | + Emitted when injected input could not be committed to a response. The event + returns the uncommitted raw input so the client can retry it in another + response when appropriate. properties: type: type: string enum: - - environment_connection - default: environment_connection + - response.inject.failed + description: The event discriminator. Always `response.inject.failed`. x-stainless-const: true - description: The type of the object. Always `environment_connection`. - environment_id: + response_id: type: string - minLength: 0 - description: The ID of the environment to reconnect. + description: The ID of the response that rejected the input. + input: + type: array + description: The raw input items that were not committed. + items: + $ref: '#/components/schemas/BetaInputItem' + error: + type: object + description: Information about why the input was not committed. + properties: + code: + type: string + enum: + - response_already_completed + - response_not_found + description: A machine-readable error code. + message: + type: string + description: A human-readable description of the error. + required: + - code + - message + sequence_number: + type: integer + description: The sequence number for this event. + stream_id: + type: string + description: | + The multiplexed WebSocket stream that emitted the event. This field is + present only when WebSocket multiplexing is enabled separately. required: - type - - environment_id - additionalProperties: false - description: Reconnect a session environment. - SessionRequiredActionResource: - description: An action that must be completed before a session can continue. - discriminator: - propertyName: type - mapping: - function_call: '#/components/schemas/SessionRequiredActionResourceFunctionCall' - environment_connection: '#/components/schemas/SessionRequiredActionResourceEnvironmentConnection' - x-oai-discriminator-values: - - function_call - - environment_connection - anyOf: - - $ref: '#/components/schemas/SessionRequiredActionResourceFunctionCall' - - $ref: '#/components/schemas/SessionRequiredActionResourceEnvironmentConnection' - AgentToolResourceFunction: + - response_id + - input + - error + - sequence_number + x-oai-beta: responses_multi_agent=v1 + x-oaiMeta: + example: | + { + "type": "response.inject.failed", + "response_id": "resp_123", + "input": [ + { + "type": "function_call_output", + "call_id": "call_123", + "output": "{\"temperature\":72}" + } + ], + "error": { + "code": "response_already_completed", + "message": "Response 'resp_123' has already completed." + }, + "sequence_number": 9 + } + BetaResponseInjectCreatedEvent: type: object + title: ResponseInjectCreatedEvent + description: | + Emitted when all injected input items were validated and committed to the + active response. properties: type: type: string enum: - - function - default: function + - response.inject.created + description: The event discriminator. Always `response.inject.created`. x-stainless-const: true - description: The type of the object. Always `function`. - name: + response_id: type: string - minLength: 0 - description: The name of the function. - description: + description: The ID of the response that accepted the input. + sequence_number: + type: integer + description: The sequence number for this event. + stream_id: 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. + description: | + The multiplexed WebSocket stream that emitted the event. This field is + present only when WebSocket multiplexing is enabled separately. required: - type - - name - - description - - parameters - - defer_loading - additionalProperties: false - description: A function defined by the application. - AgentToolResourceProgrammaticToolCalling: - type: object + - response_id + - sequence_number + x-oai-beta: responses_multi_agent=v1 + x-oaiMeta: + example: | + { + "type": "response.inject.created", + "response_id": "resp_123", + "sequence_number": 8 + } + BetaErrorPayload: 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`. + description: The error type that was emitted. + code: + anyOf: + - type: string + description: The error code that was emitted, if any. + - type: 'null' + message: + type: string + description: The human-readable error message that was emitted. + param: + anyOf: + - type: string + description: The parameter name that was associated with the error, if any. + - type: 'null' + headers: + additionalProperties: + type: string + description: The header value that was emitted. + type: object + description: The response headers that were emitted with the error, if any. + x-oaiTypeLabel: map + misalignment: + $ref: '#/components/schemas/BetaMisalignmentErrorDetailsResource' + type: object + required: + - type + - code + - message + - param + title: Error payload + description: An error payload that was emitted for a streaming error event. + BetaMultiAgentParam: + properties: enabled: type: boolean - description: Whether tools can be called from model-generated code. + description: Whether to enable server-hosted multi-agent execution for this response. + max_concurrent_subagents: + type: integer + minimum: 1 + description: |- + `max_concurrent_subagents` sets the maximum number of subagents that can be active simultaneously across the entire agent tree. It includes all descendants—children, grandchildren, and deeper subagents—but excludes the root agent. + The API does not impose a fixed upper bound on this setting. The default is `3`, which is recommended for most workloads. Multi-agent runs also have no fixed limit on tree depth or the total number of subagents created during a run. + type: object required: - - type - enabled - additionalProperties: false - description: Enables calling tools from model-generated code. - McpTransportResourceHttp: + description: Configuration for server-hosted multi-agent execution. + x-oai-beta: responses_multi_agent=v1 + BetaResponsesClientEventResponseCreate: + allOf: + - type: object + properties: + type: + type: string + enum: + - response.create + description: | + The type of the client event. Always `response.create`. + x-stainless-const: true + stream_id: + type: string + minLength: 1 + maxLength: 256 + pattern: ^[A-Za-z0-9_.-]+$ + description: | + The WebSocket lane for this response. Requests with the same + `stream_id` are processed FIFO, and events for the response echo the + same `stream_id`. + + `stream_id` controls routing; `previous_response_id` controls + conversation lineage, so a new lane can fork from a response created + on another lane. + required: + - type + - $ref: '#/components/schemas/BetaCreateResponse' + description: | + Client event for creating a response over a persistent WebSocket connection. + This payload uses the same top-level fields as `POST /v1/responses`, plus + WebSocket-only envelope metadata. + + Notes: + - `stream` is implicit over WebSocket and should not be sent. + - `background` is not supported over WebSocket. + - `stream_id` is WebSocket-only and is not part of `POST /v1/responses`. + x-oaiMeta: + example: | + { + "type": "response.create", + "stream_id": "agent_1", + "model": "gpt-6-astra", + "input": "Say hello." + } + BetaResponsesClientEvent: + discriminator: + propertyName: type + description: | + Client events accepted by the Responses WebSocket server. + anyOf: + - $ref: '#/components/schemas/BetaResponsesClientEventResponseCreate' + - $ref: '#/components/schemas/BetaResponseSteerEvent' + - $ref: '#/components/schemas/BetaResponseInjectEvent' + BetaResponsesWebSocketStreamEvent: + allOf: + - anyOf: + - $ref: '#/components/schemas/BetaResponseAudioDeltaEvent' + - $ref: '#/components/schemas/BetaResponseAudioDoneEvent' + - $ref: '#/components/schemas/BetaResponseAudioTranscriptDeltaEvent' + - $ref: '#/components/schemas/BetaResponseAudioTranscriptDoneEvent' + - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallCodeDeltaEvent' + - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallCodeDoneEvent' + - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallCompletedEvent' + - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallInProgressEvent' + - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallInterpretingEvent' + - $ref: '#/components/schemas/BetaResponseCompactionCompactingStreamingEvent' + - $ref: '#/components/schemas/BetaResponseCompletedEvent' + - $ref: '#/components/schemas/BetaResponseContentPartAddedEvent' + - $ref: '#/components/schemas/BetaResponseContentPartDoneEvent' + - $ref: '#/components/schemas/BetaResponseCreatedEvent' + - $ref: '#/components/schemas/BetaResponseFileSearchCallCompletedEvent' + - $ref: '#/components/schemas/BetaResponseFileSearchCallInProgressEvent' + - $ref: '#/components/schemas/BetaResponseFileSearchCallSearchingEvent' + - $ref: '#/components/schemas/BetaResponseFunctionCallArgumentsDeltaEvent' + - $ref: '#/components/schemas/BetaResponseFunctionCallArgumentsDoneEvent' + - $ref: '#/components/schemas/BetaResponseShellCallCommandAddedStreamingEvent' + - $ref: '#/components/schemas/BetaResponseShellCallCommandDeltaStreamingEvent' + - $ref: '#/components/schemas/BetaResponseShellCallCommandDoneStreamingEvent' + - $ref: '#/components/schemas/BetaResponseShellCallOutputContentDeltaStreamingEvent' + x-stainless-skip: + - go + - $ref: '#/components/schemas/BetaResponseShellCallOutputContentDoneStreamingEvent' + - $ref: '#/components/schemas/BetaResponseInProgressEvent' + - $ref: '#/components/schemas/BetaResponseFailedEvent' + - $ref: '#/components/schemas/BetaResponseIncompleteEvent' + - $ref: '#/components/schemas/BetaResponseOutputItemAddedEvent' + - $ref: '#/components/schemas/BetaResponseOutputItemDoneEvent' + - $ref: '#/components/schemas/BetaResponseReasoningSummaryPartAddedEvent' + - $ref: '#/components/schemas/BetaResponseReasoningSummaryPartDoneEvent' + - $ref: '#/components/schemas/BetaResponseReasoningSummaryTextDeltaEvent' + - $ref: '#/components/schemas/BetaResponseReasoningSummaryTextDoneEvent' + - $ref: '#/components/schemas/BetaResponseReasoningTextDeltaEvent' + - $ref: '#/components/schemas/BetaResponseReasoningTextDoneEvent' + - $ref: '#/components/schemas/BetaResponseRefusalDeltaEvent' + - $ref: '#/components/schemas/BetaResponseRefusalDoneEvent' + - $ref: '#/components/schemas/BetaResponseTextDeltaEvent' + - $ref: '#/components/schemas/BetaResponseTextDoneEvent' + - $ref: '#/components/schemas/BetaResponseWebSearchCallCompletedEvent' + - $ref: '#/components/schemas/BetaResponseWebSearchCallInProgressEvent' + - $ref: '#/components/schemas/BetaResponseWebSearchCallSearchingEvent' + - $ref: '#/components/schemas/BetaResponseImageGenCallCompletedEvent' + - $ref: '#/components/schemas/BetaResponseImageGenCallGeneratingEvent' + - $ref: '#/components/schemas/BetaResponseImageGenCallInProgressEvent' + - $ref: '#/components/schemas/BetaResponseImageGenCallPartialImageEvent' + - $ref: '#/components/schemas/BetaResponseMCPCallArgumentsDeltaEvent' + - $ref: '#/components/schemas/BetaResponseMCPCallArgumentsDoneEvent' + - $ref: '#/components/schemas/BetaResponseMCPCallCompletedEvent' + - $ref: '#/components/schemas/BetaResponseMCPCallFailedEvent' + - $ref: '#/components/schemas/BetaResponseMCPCallInProgressEvent' + - $ref: '#/components/schemas/BetaResponseMCPListToolsCompletedEvent' + - $ref: '#/components/schemas/BetaResponseMCPListToolsFailedEvent' + - $ref: '#/components/schemas/BetaResponseMCPListToolsInProgressEvent' + - $ref: '#/components/schemas/BetaResponseOutputTextAnnotationAddedEvent' + - $ref: '#/components/schemas/BetaResponseQueuedEvent' + - $ref: '#/components/schemas/BetaResponseCustomToolCallInputDeltaEvent' + - $ref: '#/components/schemas/BetaResponseCustomToolCallInputDoneEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + SpendLimitCurrency: + anyOf: + - type: string + - type: string + enum: + - USD + SpendLimitInterval: + anyOf: + - type: string + - type: string + enum: + - month + SpendLimitEnforcementStatus: + anyOf: + - type: string + - type: string + enum: + - inactive + - enforcing + SpendLimitEnforcement: + properties: + status: + $ref: '#/components/schemas/SpendLimitEnforcementStatus' + description: Whether the hard spend limit is currently enforcing. + type: object + required: + - status + description: The current enforcement state of a hard spend limit. + OrganizationSpendLimitResource: + properties: + object: + type: string + enum: + - organization.spend_limit + description: The object type, which is always `organization.spend_limit`. + default: organization.spend_limit + x-stainless-const: true + threshold_amount: + type: integer + description: The hard spend limit amount, in cents. + currency: + $ref: '#/components/schemas/SpendLimitCurrency' + description: The currency for the threshold amount. Currently, only `USD` is supported. + interval: + $ref: '#/components/schemas/SpendLimitInterval' + description: The time interval for evaluating spend against the threshold. Currently, only `month` is supported. + enforcement: + $ref: '#/components/schemas/SpendLimitEnforcement' + description: The current enforcement state of the hard spend limit. + type: object + required: + - object + - threshold_amount + - currency + - interval + - enforcement + description: Represents a hard spend limit configured at the organization level. + UpdateOrganizationSpendLimitBody: + properties: + threshold_amount: + type: integer + minimum: 1 + description: The hard spend limit amount, in cents. + currency: + type: string + enum: + - USD + description: The currency for the threshold amount. Currently, only `USD` is supported. + interval: + type: string + enum: + - month + description: The time interval for evaluating spend against the threshold. Currently, only `month` is supported. type: object + required: + - threshold_amount + - currency + - interval + description: Parameters for the hard spend limit you want to create or replace. + OrganizationSpendLimitDeletedResource: properties: - type: + object: type: string enum: - - http - default: http + - organization.spend_limit.deleted + description: The object type, which is always `organization.spend_limit.deleted`. + default: organization.spend_limit.deleted 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. - McpTransportResourceStdio: + deleted: + type: boolean + description: Whether the hard spend limit was deleted. type: object + required: + - object + - deleted + description: Confirmation payload returned after deleting an organization hard spend limit. + ProjectSpendLimitResource: properties: - type: + object: type: string enum: - - stdio - default: stdio + - project.spend_limit + description: The object type, which is always `project.spend_limit`. + default: project.spend_limit x-stainless-const: true - description: The type of the object. Always `stdio`. - command: + threshold_amount: + type: integer + description: The hard spend limit amount, in cents. + currency: + $ref: '#/components/schemas/SpendLimitCurrency' + description: The currency for the threshold amount. Currently, only `USD` is supported. + interval: + $ref: '#/components/schemas/SpendLimitInterval' + description: The time interval for evaluating spend against the threshold. Currently, only `month` is supported. + enforcement: + $ref: '#/components/schemas/SpendLimitEnforcement' + description: The current enforcement state of the hard spend limit. + type: object + required: + - object + - threshold_amount + - currency + - interval + - enforcement + description: Represents a hard spend limit configured at the project level. + UpdateProjectSpendLimitBody: + properties: + threshold_amount: + type: integer + minimum: 1 + description: The hard spend limit amount, in cents. + currency: 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: + enum: + - USD + description: The currency for the threshold amount. Currently, only `USD` is supported. + interval: 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. - McpTransportResource: - description: The transport used to connect to an MCP server. - discriminator: - propertyName: type - mapping: - http: '#/components/schemas/McpTransportResourceHttp' - stdio: '#/components/schemas/McpTransportResourceStdio' - x-oai-discriminator-values: - - http - - stdio - anyOf: - - $ref: '#/components/schemas/McpTransportResourceHttp' - - $ref: '#/components/schemas/McpTransportResourceStdio' - AgentToolResourceMcp: + enum: + - month + description: The time interval for evaluating spend against the threshold. Currently, only `month` is supported. type: object + required: + - threshold_amount + - currency + - interval + description: Parameters for the hard spend limit you want to create or replace. + ProjectSpendLimitDeletedResource: properties: - type: + object: type: string enum: - - mcp - default: mcp + - project.spend_limit.deleted + description: The object type, which is always `project.spend_limit.deleted`. + default: project.spend_limit.deleted 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: + deleted: 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. - AgentToolResourceWebSearch: + description: Whether the hard spend limit was deleted. type: object + required: + - object + - deleted + description: Confirmation payload returned after deleting a project hard spend limit. + CreateProjectServiceAccountApiKeyBody: properties: - type: + name: 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' + description: API key name. + scopes: items: type: string - minLength: 0 - minItems: 0 - maxItems: 2000 - description: Allowed search domains, or `null` when the search is unrestricted. - location: + description: API key scope. + type: array + description: API key scopes. + expires_in_seconds: anyOf: - - $ref: '#/components/schemas/WebSearchLocationResource' + - type: integer + maximum: 31536000 + minimum: 1 + description: Number of seconds until the API key expires. - 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. - AgentToolResource: - description: A tool available to the agent. - 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 - anyOf: - - $ref: '#/components/schemas/AgentToolResourceFunction' - - $ref: '#/components/schemas/AgentToolResourceProgrammaticToolCalling' - - $ref: '#/components/schemas/AgentToolResourceMcp' - - $ref: '#/components/schemas/AgentToolResourceWebSearch' - SessionAgentResource: type: object + required: [] + description: The service account API key create request payload. + ServiceAccountApiKeyBody: properties: - id: + object: type: string - minLength: 0 - description: The ID of the agent. + enum: + - organization.project.service_account.api_key + description: The object type, which is always `organization.project.service_account.api_key` + default: organization.project.service_account.api_key + x-stainless-const: true + value: + type: string + description: The unredacted API key value. 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. + description: The name of the API key. + created_at: + type: integer + format: unixtime + description: The Unix timestamp (in seconds) when the API key was created. + expires_at: + anyOf: + - type: integer + format: unixtime + description: The Unix timestamp (in seconds) when the API key expires, or null if it does not expire. + - type: 'null' + id: + type: string + description: The identifier of the API key. + type: object required: - - id + - object + - value - name - - model - - reasoning - - text - - service_tier - - instructions - - tools - - multi_agent - additionalProperties: false - description: The effective agent configuration for a session. - EnvironmentResourceNone: + - created_at + - id + CreateContentProvenanceBody: + properties: + file: + type: string + format: binary + description: The image or audio file to check for supported OpenAI provenance signals. type: object + required: + - file + ProvenanceCheckObject: + type: string + enum: + - content_provenance_check + ProvenanceDetectionResultApi: + type: string + enum: + - detected + - not_detected + C2PAValidationStateApi: + type: string + enum: + - trusted + - valid + - invalid + - not_present + C2PAProvenanceResult: properties: type: type: string enum: - - none - default: none + - c2pa + description: The provenance signal type. Always `c2pa`. + default: c2pa x-stainless-const: true - description: The type of the object. Always `none`. + outcome: + $ref: '#/components/schemas/ProvenanceDetectionResultApi' + description: |- + Whether a supported OpenAI C2PA provenance signal was detected. + If `not_detected`, it means the tool did not find supported signals in the uploaded file. The content could still have been generated by OpenAI if the metadata was stripped or has evidence of tampering, the watermark was degraded, it comes from a legacy generation model, or it was created before provenance signals were available. Content could also still be AI-generated by another company's model, which the tool currently does not detect. + validation_state: + $ref: '#/components/schemas/C2PAValidationStateApi' + description: The validation status of the C2PA manifest in the uploaded image. + issuer: + anyOf: + - type: string + description: The C2PA manifest issuer, when available. + - type: 'null' + model: + anyOf: + - type: string + description: The OpenAI model recorded by the provenance signal, when available. + - type: 'null' + generated_at: + anyOf: + - type: string + description: The UTC RFC 3339 timestamp recorded by the provenance signal for when the asset was generated, when available. + - type: 'null' + type: object required: - type - additionalProperties: false - description: The session talks to CCA without selecting or provisioning an execution environment. - EnvironmentResourceOpenaiHosted: - type: object + - outcome + - validation_state + - issuer + - model + - generated_at + SynthIDProvenanceResult: properties: type: type: string enum: - - openai_hosted - default: openai_hosted + - synthid + description: The provenance signal type. Always `synthid`. + default: synthid 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. + outcome: + $ref: '#/components/schemas/ProvenanceDetectionResultApi' + description: |- + Whether a supported OpenAI SynthID watermark was detected. + If `not_detected`, it means the tool did not find supported signals in the uploaded file. The content could still have been generated by OpenAI if the metadata was stripped or has evidence of tampering, the watermark was degraded, it comes from a legacy generation model, or it was created before provenance signals were available. Content could also still be AI-generated by another company's model, which the tool currently does not detect. + model: + anyOf: + - type: string + description: The OpenAI model recorded by the provenance signal, when available. + - type: 'null' + generated_at: + anyOf: + - type: string + description: The UTC RFC 3339 timestamp recorded by the provenance signal for when the asset was generated, when available. + - type: 'null' + type: object required: - type - - id - - packages - - network - - capability_directories - - skills - - plugins - - files - additionalProperties: false - description: An environment hosted by OpenAI. - EnvironmentResourceSelfHosted: + - outcome + - model + - generated_at + ProvenanceResource: + properties: + object: + $ref: '#/components/schemas/ProvenanceCheckObject' + description: The object type. Always `content_provenance_check` for this endpoint. + created_at: + type: integer + format: unixtime + description: The Unix timestamp, in seconds, when the provenance check was created. + results: + items: + discriminator: + propertyName: type + anyOf: + - $ref: '#/components/schemas/C2PAProvenanceResult' + - $ref: '#/components/schemas/SynthIDProvenanceResult' + type: array + description: The provenance results that apply to the uploaded file. Image results include C2PA and SynthID; audio results include SynthID. type: object + required: + - object + - created_at + - results + OrderEnum: + type: string + enum: + - asc + - desc + VideoModel: + anyOf: + - type: string + - type: string + enum: + - sora-2 + - sora-2-pro + - sora-2-2025-10-06 + - sora-2-pro-2025-10-06 + - sora-2-2025-12-08 + VideoStatus: + type: string + enum: + - queued + - in_progress + - completed + - failed + VideoSize: + type: string + enum: + - 720x1280 + - 1280x720 + - 1024x1792 + - 1792x1024 + Error-2: 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: + code: type: string - minLength: 0 - description: The public ID of the environment. - workspace_directory: + description: A machine-readable error code that was returned. + message: 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. - EnvironmentResource: - description: The execution environment for a session. - 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 - anyOf: - - $ref: '#/components/schemas/EnvironmentResourceNone' - - $ref: '#/components/schemas/EnvironmentResourceOpenaiHosted' - - $ref: '#/components/schemas/EnvironmentResourceSelfHosted' - SessionResource: + description: A human-readable description of the error that was returned. + misalignment: + $ref: '#/components/schemas/MisalignmentErrorDetailsResource' type: object + required: + - code + - message + title: Error + description: An error that occurred while generating the response. + VideoResource: 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. + description: Unique identifier for the video job. object: type: string enum: - - agent.session - default: agent.session + - video + description: The object type, which is always `video`. + default: video x-stainless-const: true - description: The object type. Always `agent.session`. - created_at: + model: + $ref: '#/components/schemas/VideoModel' + description: The video generation model that produced the job. + status: + $ref: '#/components/schemas/VideoStatus' + description: Current lifecycle status of the video job. + progress: type: integer - format: int64 - description: The Unix timestamp, in seconds, when the session was created. - last_active_at: + description: Approximate completion percentage for the generation task. + created_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. + format: unixtime + description: Unix timestamp (seconds) for when the job was created. + completed_at: + anyOf: + - type: integer + format: unixtime + description: Unix timestamp (seconds) for when the job completed, if finished. + - type: 'null' + expires_at: + anyOf: + - type: integer + format: unixtime + description: Unix timestamp (seconds) for when the downloadable assets expire, if set. + - type: 'null' + prompt: + anyOf: + - type: string + description: The prompt that was used to generate the video. + - type: 'null' + size: + $ref: '#/components/schemas/VideoSize' + description: The resolution of the generated video. + seconds: + anyOf: + - type: string + - $ref: '#/components/schemas/VideoSeconds' + description: Duration of the generated clip in seconds. For extensions, this is the stitched total duration. + remixed_from_video_id: + anyOf: + - type: string + description: Identifier of the source video if this video is a remix. + - type: 'null' error: - type: - - string - - 'null' - minLength: 0 - description: The error that caused the session to fail, if any. - 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' + - $ref: '#/components/schemas/Error-2' + description: Error payload that explains why generation failed, if applicable. - type: 'null' - description: Best-effort token usage for the session, or null if unknown. Recorded usage may change. + type: object required: - - metadata - id - object - - created_at - - last_active_at + - model - status - - required_actions + - progress + - created_at + - completed_at + - expires_at + - prompt + - size + - seconds + - remixed_from_video_id - error - - agent - - environment - - vault_ids - - usage - additionalProperties: false - description: A Managed Agents session. - SessionListResource: - type: object + title: Video job + description: Structured information describing a generated video job. + VideoListResource: properties: object: - type: string - enum: - - list - default: list x-stainless-const: true - description: The object type, which is always `list`. + default: list + description: The type of object returned, must be `list`. + const: 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. + $ref: '#/components/schemas/VideoResource' + type: array + description: A list of items first_id: - type: - - string - - 'null' - minLength: 0 - description: The ID of the first resource in `data`, or `null` if the page is empty. + anyOf: + - type: string + description: The ID of the first item in the list. + - type: 'null' 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. + anyOf: + - type: string + description: The ID of the last item in the list. + - type: 'null' has_more: type: boolean - description: Whether there are more resources to retrieve after this page. + description: Whether there are more items available. + type: object required: - object - data - first_id - last_id - has_more - additionalProperties: false - description: A page of Agents API resources, with IDs for retrieving additional pages. - AgentToolConfigParamFunction: - type: object + ImageRefParam-2: properties: - type: - type: string - enum: - - function - default: function - x-stainless-const: true - description: The type of the object. Always `function`. - name: + image_url: type: string - minLength: 0 - maxLength: 1048576 - description: The name of the function. - description: + maxLength: 20971520 + format: uri + description: A fully qualified URL or base64-encoded data URL. + file_id: 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. - AgentToolConfigParamToolSearch: + example: file-123 type: object + required: [] + VideoSeconds: + type: string + enum: + - '4' + - '8' + - '12' + CreateVideoMultipartBody: properties: - type: + model: + $ref: '#/components/schemas/VideoModel' + description: 'The video generation model to use (allowed values: sora-2, sora-2-pro). Defaults to `sora-2`.' + prompt: 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. - AgentToolConfigParamProgrammaticToolCalling: + maxLength: 32000 + minLength: 1 + description: Text prompt that describes the video to generate. + input_reference: + anyOf: + - type: string + format: binary + description: Optional reference asset upload or reference object that guides generation. + - $ref: '#/components/schemas/ImageRefParam-2' + description: Optional reference asset upload or reference object that guides generation. Provide exactly one of `image_url` or `file_id` when using an object. + seconds: + $ref: '#/components/schemas/VideoSeconds' + description: 'Clip duration in seconds (allowed values: 4, 8, 12). Defaults to 4 seconds.' + size: + $ref: '#/components/schemas/VideoSize' + description: 'Output resolution formatted as width x height (allowed values: 720x1280, 1280x720, 1024x1792, 1792x1024). Defaults to 720x1280.' type: object + required: + - prompt + title: Create video multipart request + description: Multipart parameters for creating a new video generation job. + CreateVideoJsonBody: properties: - type: + model: + $ref: '#/components/schemas/VideoModel' + description: 'The video generation model to use (allowed values: sora-2, sora-2-pro). Defaults to `sora-2`.' + prompt: 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. - McpTransportConfigParamHttp: + maxLength: 32000 + minLength: 1 + description: Text prompt that describes the video to generate. + input_reference: + $ref: '#/components/schemas/ImageRefParam-2' + description: Optional reference object that guides generation. Provide exactly one of `image_url` or `file_id`. + seconds: + $ref: '#/components/schemas/VideoSeconds' + description: 'Clip duration in seconds (allowed values: 4, 8, 12). Defaults to 4 seconds.' + size: + $ref: '#/components/schemas/VideoSize' + description: 'Output resolution formatted as width x height (allowed values: 720x1280, 1280x720, 1024x1792, 1792x1024). Defaults to 720x1280.' type: object + required: + - prompt + title: Create video JSON request + description: JSON parameters for creating a new video generation job. + CreateVideoCharacterBody: properties: - type: + video: type: string - enum: - - http - default: http - x-stainless-const: true - description: The type of the object. Always `http`. - server_url: + format: binary + description: Video file used to create a character. + name: 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. + maxLength: 80 + minLength: 1 + description: Display name for this API character. + type: object required: - - type - - server_url - additionalProperties: false - description: Connects to an MCP server over HTTP. - McpTransportConfigParamStdio: + - video + - name + title: Create character request + description: Parameters for creating a character from an uploaded video. + VideoCharacterResource: + properties: + id: + anyOf: + - type: string + description: Identifier for the character creation cameo. + - type: 'null' + name: + anyOf: + - type: string + description: Display name for the character. + - type: 'null' + created_at: + type: integer + format: unixtime + description: Unix timestamp (in seconds) when the character was created. type: object + required: + - id + - name + - created_at + VideoReferenceInputParam: 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: + id: 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. + description: The identifier of the completed video. + example: video_123 + type: object required: - - type - - command - - cwd - additionalProperties: false - description: Starts an MCP server as a local process. - McpTransportConfigParam: - description: The transport used to connect to an MCP server. - discriminator: - propertyName: type - mapping: - http: '#/components/schemas/McpTransportConfigParamHttp' - stdio: '#/components/schemas/McpTransportConfigParamStdio' - x-oai-discriminator-values: - - http - - stdio - anyOf: - - $ref: '#/components/schemas/McpTransportConfigParamHttp' - - $ref: '#/components/schemas/McpTransportConfigParamStdio' - AgentToolConfigParamMcp: + - id + description: Reference to the completed video. + CreateVideoEditMultipartBody: + properties: + video: + anyOf: + - type: string + format: binary + description: Reference to the completed video to edit. + - $ref: '#/components/schemas/VideoReferenceInputParam' + description: Reference to the completed video to edit. + prompt: + type: string + maxLength: 32000 + minLength: 1 + description: Text prompt that describes how to edit the source video. type: object + required: + - video + - prompt + title: Create video edit multipart request + description: Parameters for editing an existing generated video. + CreateVideoEditJsonBody: properties: - type: + video: + $ref: '#/components/schemas/VideoReferenceInputParam' + description: Reference to the completed video to edit. + prompt: type: string - enum: - - mcp - default: mcp - x-stainless-const: true - description: The type of the object. Always `mcp`. - server_label: + maxLength: 32000 + minLength: 1 + description: Text prompt that describes how to edit the source video. + type: object + required: + - video + - prompt + title: Create video edit JSON request + description: JSON parameters for editing an existing generated video. + CreateVideoExtendMultipartBody: + properties: + video: + oneOf: + - type: string + format: binary + description: Reference to the completed video to extend. + - $ref: '#/components/schemas/VideoReferenceInputParam' + description: Reference to the completed video to extend. + prompt: 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. + maxLength: 32000 + minLength: 1 + description: Updated text prompt that directs the extension generation. + seconds: + $ref: '#/components/schemas/VideoSeconds' + description: 'Length of the newly generated extension segment in seconds (allowed values: 4, 8, 12, 16, 20).' + type: object required: - - type - - server_label - - transport - additionalProperties: false - description: Tools provided by a remote MCP server. - AgentToolConfigParamWebSearch: + - video + - prompt + - seconds + title: Create video extension multipart request + description: Multipart parameters for extending an existing generated video. + CreateVideoExtendJsonBody: + properties: + video: + $ref: '#/components/schemas/VideoReferenceInputParam' + description: Reference to the completed video to extend. + prompt: + type: string + maxLength: 32000 + minLength: 1 + description: Updated text prompt that directs the extension generation. + seconds: + $ref: '#/components/schemas/VideoSeconds' + description: 'Length of the newly generated extension segment in seconds (allowed values: 4, 8, 12, 16, 20).' type: object + required: + - video + - prompt + - seconds + title: Create video extension JSON request + description: JSON parameters for extending an existing generated video. + DeletedVideoResource: properties: - type: + object: type: string enum: - - web_search - default: web_search + - video.deleted + description: The object type that signals the deletion response. + default: video.deleted x-stainless-const: true - description: The type of the object. Always `web_search`. - mode: + deleted: + type: boolean + description: Indicates that the video resource was deleted. + id: + type: string + description: Identifier of the deleted video. + type: object + required: + - object + - deleted + - id + title: Deleted video response + description: Confirmation payload returned after deleting a video. + VideoContentVariant: + type: string + enum: + - video + - thumbnail + - spritesheet + CreateVideoRemixBody: + properties: + prompt: + type: string + maxLength: 32000 + minLength: 1 + description: Updated text prompt that directs the remix generation. + type: object + required: + - prompt + title: Create video remix request + description: Parameters for remixing an existing generated video. + TruncationEnum: + type: string + enum: + - auto + - disabled + PersonalityEnum: + anyOf: + - type: string + - type: string + enum: + - friendly + - pragmatic + TokenCountsBody: + properties: + model: anyOf: - - $ref: '#/components/schemas/WebSearchModeParam' + - type: string + description: Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](https://developers.openai.com/api/docs/models) to browse and compare available models. - type: 'null' - description: The source used for web search results. Defaults to `live`. - context_size: + input: anyOf: - - $ref: '#/components/schemas/WebSearchContextSizeParam' + - description: Text, image, or file inputs to the model, used to generate a response + anyOf: + - type: string + maxLength: 10485760 + description: A text input to the model, equivalent to a text input with the `user` role. + - items: + $ref: '#/components/schemas/InputItem' + type: array + maxItems: 131072 + description: A list of one or many input items to the model, containing different content types. - 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: + previous_response_id: anyOf: - - $ref: '#/components/schemas/WebSearchLocationParam' + - type: string + description: The unique ID of the previous response to the model. Use this to create multi-turn conversations. Learn more about [conversation state](https://developers.openai.com/api/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + example: resp_123 - type: 'null' - description: Approximate location used to localize search results. - required: - - type - additionalProperties: false - description: Web search. - AgentToolConfigParam: - description: A tool available to the agent. - 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 - anyOf: - - $ref: '#/components/schemas/AgentToolConfigParamFunction' - - $ref: '#/components/schemas/AgentToolConfigParamToolSearch' - - $ref: '#/components/schemas/AgentToolConfigParamProgrammaticToolCalling' - - $ref: '#/components/schemas/AgentToolConfigParamMcp' - - $ref: '#/components/schemas/AgentToolConfigParamWebSearch' - 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: + tools: anyOf: - - $ref: '#/components/schemas/ReasoningParam' + - items: + $ref: '#/components/schemas/Tool' + type: array + description: An array of tools the model may call while generating a response. You can specify which tool to use by setting the `tool_choice` parameter. - 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' + - $ref: '#/components/schemas/ResponseTextParam' - type: 'null' - description: Configuration for text generated by the agent. - service_tier: + reasoning: anyOf: - - $ref: '#/components/schemas/ServiceTierParam' + - $ref: '#/components/schemas/Reasoning' + description: '**gpt-5 and o-series models only** Configuration options for [reasoning models](https://developers.openai.com/api/docs/guides/reasoning).' - type: 'null' - description: The service tier used for model requests. + truncation: + $ref: '#/components/schemas/TruncationEnum' + description: 'The truncation strategy to use for the model response. - `auto`: If the input to this Response exceeds the model''s context window size, the model will truncate the response to fit the context window by dropping items from the beginning of the conversation. - `disabled` (default): If the input size will exceed the context window size for a model, the request will fail with a 400 error.' + deprecated: true 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: string + description: |- + A system (or developer) message inserted into the model's context. + When used along with `previous_response_id`, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses. + - type: 'null' + personality: + $ref: '#/components/schemas/PersonalityEnum' + description: A model-owned style preset to apply to this request. Omit this parameter to use the model's default style. Supported values may expand over time. Values must be at most 64 characters. + conversation: + anyOf: + - $ref: '#/components/schemas/ConversationParam' + - type: 'null' + tool_choice: + anyOf: + - $ref: '#/components/schemas/ToolChoiceParam' + description: Controls which tool the model should use, if any. + - type: 'null' + parallel_tool_calls: + anyOf: + - type: boolean + description: Whether to allow the model to run tool calls in parallel. - 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. - EnvironmentParamNone: type: object + required: [] + TokenCountsResource: properties: - type: + object: type: string enum: - - none - default: none + - response.input_tokens + default: response.input_tokens x-stainless-const: true - description: The type of the object. Always `none`. - required: - - type - additionalProperties: false - description: Runs the agent without an execution environment. - EnvironmentParamOpenaiHosted: + input_tokens: + type: integer type: object + required: + - object + - input_tokens + title: Token counts + example: + object: response.input_tokens + input_tokens: 123 + PromptCacheRetentionEnum: + type: string + enum: + - in_memory + - 24h + ServiceTierEnum: + type: string + enum: + - auto + - default + - fast + - flex + - priority + CompactResponseMethodPublicBody: properties: - type: - type: string - enum: - - openai_hosted - default: openai_hosted - x-stainless-const: true - description: The type of the object. Always `openai_hosted`. - packages: + model: + $ref: '#/components/schemas/ModelIdsCompaction' + input: anyOf: - - $ref: '#/components/schemas/EnvironmentPackagesParam' + - description: Text, image, or file inputs to the model, used to generate a response + anyOf: + - type: string + maxLength: 10485760 + description: A text input to the model, equivalent to a text input with the `user` role. + - items: + $ref: '#/components/schemas/InputItem' + type: array + maxItems: 131072 + description: A list of one or many input items to the model, containing different content types. - 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: + previous_response_id: anyOf: - - $ref: '#/components/schemas/NetworkPolicyParam' + - type: string + description: The unique ID of the previous response to the model. Use this to create multi-turn conversations. Learn more about [conversation state](https://developers.openai.com/api/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + example: resp_123 + - type: 'null' + instructions: + anyOf: + - type: string + description: |- + A system (or developer) message inserted into the model's context. + When used along with `previous_response_id`, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses. + - type: 'null' + prompt_cache_key: + anyOf: + - type: string + maxLength: 64 + description: A key to use when reading from or writing to the prompt cache. + - type: 'null' + prompt_cache_retention: + anyOf: + - $ref: '#/components/schemas/PromptCacheRetentionEnum' + description: How long to retain a prompt cache entry created by this request. + deprecated: true + - type: 'null' + prompt_cache_options: + anyOf: + - $ref: '#/components/schemas/PromptCacheOptionsParam' + - type: 'null' + service_tier: + anyOf: + - $ref: '#/components/schemas/ServiceTierEnum' + description: |- + Specifies the processing type used for serving the request. - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - If set to '[flex](https://developers.openai.com/api/docs/guides/flex-processing)', then the request will be processed with the Flex Processing service tier. - To opt-in to [Fast mode](https://developers.openai.com/api/docs/guides/fast-mode) at the request level, include the `service_tier=fast` or `service_tier=priority` parameter for Responses or Chat Completions. For models with a dedicated Fast tier, either value resolves to `service_tier=fast`; for other models, either value resolves to `service_tier=priority`. - When not set, the default behavior is 'auto'. + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - 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 OpenAI-hosted environment, optionally based on a reusable template. - EnvironmentParamSelfHosted: type: object + required: + - model + ItemField: + discriminator: + propertyName: type + description: An item representing a message, tool call, tool output, reasoning, or other response element. + anyOf: + - $ref: '#/components/schemas/Message' + - $ref: '#/components/schemas/Program' + - $ref: '#/components/schemas/ProgramOutput' + - $ref: '#/components/schemas/FunctionToolCall' + - $ref: '#/components/schemas/ToolSearchCall' + - $ref: '#/components/schemas/ToolSearchOutput' + - $ref: '#/components/schemas/AdditionalTools' + - $ref: '#/components/schemas/FunctionToolCallOutput' + - $ref: '#/components/schemas/FileSearchToolCall' + - $ref: '#/components/schemas/WebSearchToolCall' + - $ref: '#/components/schemas/ImageGenToolCall' + - $ref: '#/components/schemas/ComputerToolCall' + - $ref: '#/components/schemas/ComputerToolCallOutputResource' + - $ref: '#/components/schemas/ReasoningItem' + - $ref: '#/components/schemas/CompactionBody' + - $ref: '#/components/schemas/CodeInterpreterToolCall' + - $ref: '#/components/schemas/LocalShellToolCall' + deprecated: true + - $ref: '#/components/schemas/LocalShellToolCallOutput' + deprecated: true + - $ref: '#/components/schemas/FunctionShellCall' + - $ref: '#/components/schemas/FunctionShellCallOutput' + - $ref: '#/components/schemas/ApplyPatchToolCall' + - $ref: '#/components/schemas/ApplyPatchToolCallOutput' + - $ref: '#/components/schemas/MCPListTools' + - $ref: '#/components/schemas/MCPApprovalRequest' + - $ref: '#/components/schemas/MCPApprovalResponseResource' + - $ref: '#/components/schemas/MCPToolCall' + - $ref: '#/components/schemas/CustomToolCall' + - $ref: '#/components/schemas/CustomToolCallOutput' + CompactResource: properties: - type: + id: + type: string + description: The unique identifier for the compacted response. + object: type: string enum: - - self_hosted - default: self_hosted + - response.compaction + description: The object type. Always `response.compaction`. + default: response.compaction 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' + output: + type: array + description: The compacted list of output items. This is a list of all user messages, followed by a single compaction item. 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. - EnvironmentParam: - description: The execution environment and optional reusable template for a session. - 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 - anyOf: - - $ref: '#/components/schemas/EnvironmentParamNone' - - $ref: '#/components/schemas/EnvironmentParamOpenaiHosted' - - $ref: '#/components/schemas/EnvironmentParamSelfHosted' - InputContentParamInputText: + $ref: '#/components/schemas/OutputItem' + created_at: + type: integer + format: unixtime + description: Unix timestamp (in seconds) when the compacted conversation was created. + usage: + $ref: '#/components/schemas/ResponseUsage' + description: Token accounting for the compaction pass, including cached, reasoning, and total tokens. type: object + required: + - id + - object + - output + - created_at + - usage + title: The compacted response object + SkillResource: properties: - type: + id: + type: string + description: Unique identifier for the skill. + object: type: string enum: - - input_text - default: input_text + - skill + description: The object type, which is `skill`. + default: skill x-stainless-const: true - description: The type of the object. Always `input_text`. - text: + name: type: string - minLength: 0 - maxLength: 1048576 - description: The text sent to the model. + description: Name of the skill. + description: + type: string + description: Description of the skill. + created_at: + type: integer + format: unixtime + description: Unix timestamp (seconds) for when the skill was created. + default_version: + type: string + description: Default version for the skill. + latest_version: + type: string + description: Latest version for the skill. + type: object required: - - type - - text - additionalProperties: false - description: Text input to the model. - InputContentParamInputImage: + - id + - object + - name + - description + - created_at + - default_version + - latest_version + SkillListResource: + properties: + object: + x-stainless-const: true + default: list + description: The type of object returned, must be `list`. + const: list + data: + items: + $ref: '#/components/schemas/SkillResource' + type: array + description: A list of items + first_id: + anyOf: + - type: string + description: The ID of the first item in the list. + - type: 'null' + last_id: + anyOf: + - type: string + description: The ID of the last item in the list. + - type: 'null' + has_more: + type: boolean + description: Whether there are more items available. type: object + required: + - object + - data + - first_id + - last_id + - has_more + CreateSkillBody: properties: - type: + files: + anyOf: + - items: + type: string + format: binary + type: array + maxItems: 500 + description: Skill files to upload (directory upload) or a single zip file. + - type: string + format: binary + description: Skill zip file to upload. + type: object + description: Uploads a skill either as a directory (multipart `files[]`) or as a single zip file. + title: Create skill request + SetDefaultSkillVersionBody: + properties: + default_version: + type: string + description: The skill version number to set as default. + type: object + required: + - default_version + title: Update skill request + description: Updates the default version pointer for a skill. + DeletedSkillResource: + properties: + object: type: string enum: - - input_image - default: input_image + - skill.deleted + default: skill.deleted x-stainless-const: true - description: The type of the object. Always `input_image`. - image_url: + deleted: + type: boolean + id: 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. - InputContentParam: - description: Content included in an input message. - discriminator: - propertyName: type - mapping: - input_text: '#/components/schemas/InputContentParamInputText' - input_image: '#/components/schemas/InputContentParamInputImage' - x-oai-discriminator-values: - - input_text - - input_image - anyOf: - - $ref: '#/components/schemas/InputContentParamInputText' - - $ref: '#/components/schemas/InputContentParamInputImage' - InputMessageParam: type: object + required: + - object + - deleted + - id + SkillVersionResource: properties: - type: + object: type: string enum: - - message - default: message + - skill.version + description: The object type, which is `skill.version`. + default: skill.version x-stainless-const: true - description: The type of the input item. Always `message`. - role: + id: 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. - CreateSessionInputParam: - description: Initial input submitted when creating a session. - anyOf: - - type: string - minLength: 1 - maxLength: 1048576 - - type: array - items: - $ref: '#/components/schemas/InputMessageParam' - minItems: 0 - maxItems: 16384 - CreateAgentSessionParams: + description: Unique identifier for the skill version. + skill_id: + type: string + description: Identifier of the skill for this version. + version: + type: string + description: Version number for this skill. + created_at: + type: integer + format: unixtime + description: Unix timestamp (seconds) for when the version was created. + name: + type: string + description: Name of the skill version. + description: + type: string + description: Description of the skill version. type: object + required: + - object + - id + - skill_id + - version + - created_at + - name + - description + SkillVersionListResource: 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' + object: + x-stainless-const: true + default: list + description: The type of object returned, must be `list`. + const: list + data: items: - type: string - minLength: 0 - maxLength: 1048576 - minItems: 0 - maxItems: 16384 - description: The IDs of vaults made available to the session. - input: + $ref: '#/components/schemas/SkillVersionResource' + type: array + description: A list of items + first_id: anyOf: - - $ref: '#/components/schemas/CreateSessionInputParam' + - type: string + description: The ID of the first item in the list. - 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: + last_id: + anyOf: + - type: string + description: The ID of the last item in the list. + - type: 'null' + has_more: 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. - SessionErrorResource: + description: Whether there are more items available. 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. - SessionEventError: + - object + - data + - first_id + - last_id + - has_more + CreateSkillVersionBody: + properties: + files: + anyOf: + - items: + type: string + format: binary + type: array + maxItems: 500 + description: Skill files to upload (directory upload) or a single zip file. + - type: string + format: binary + description: Skill zip file to upload. + default: + type: boolean + description: Whether to set this version as the default. type: object + description: Uploads a new immutable version of a skill. + title: Create skill version request + DeletedSkillVersionResource: properties: - type: + object: type: string enum: - - error - default: error + - skill.version.deleted + default: skill.version.deleted x-stainless-const: true - description: The type of the object. Always `error`. - event_id: + deleted: + type: boolean + id: type: string - minLength: 0 - description: The unique ID of the event. - session_id: + version: type: string - minLength: 0 - description: The ID of the session associated with the event. - error: - $ref: '#/components/schemas/SessionErrorResource' - description: The error that occurred. + description: The deleted skill version. + type: object 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 - SessionEnvironmentStatusResource: + - object + - deleted + - id + - version + ChatkitWorkflowTracing: + properties: + enabled: + type: boolean + description: Indicates whether tracing is enabled. + type: object + required: + - enabled + title: Tracing Configuration + description: Controls diagnostic tracing during the session. + ChatkitWorkflow: + properties: + id: + type: string + description: Identifier of the workflow backing the session. + version: + anyOf: + - type: string + description: Specific workflow version used for the session. Defaults to null when using the latest deployment. + - type: 'null' + state_variables: + anyOf: + - additionalProperties: + anyOf: + - type: string + - type: integer + - type: boolean + - type: number + type: object + description: State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. + x-oaiTypeLabel: map + - type: 'null' + tracing: + $ref: '#/components/schemas/ChatkitWorkflowTracing' + description: Tracing settings applied to the workflow. + type: object + required: + - id + - version + - state_variables + - tracing + title: Workflow + description: Workflow metadata and state returned for the session. + ChatSessionRateLimits: + properties: + max_requests_per_1_minute: + type: integer + description: Maximum allowed requests per one-minute window. + type: object + required: + - max_requests_per_1_minute + title: Rate limits + description: Active per-minute request limit for the session. + ChatSessionStatus: 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. - SessionEnvironmentErrorResource: + - active + - expired + - cancelled + ChatSessionAutomaticThreadTitling: + properties: + enabled: + type: boolean + description: Whether automatic thread titling is enabled. + type: object + required: + - enabled + title: Automatic thread titling + description: Automatic thread title preferences for the session. + ChatSessionFileUpload: + properties: + enabled: + type: boolean + description: Indicates if uploads are enabled for the session. + max_file_size: + anyOf: + - type: integer + description: Maximum upload size in megabytes. + - type: 'null' + max_files: + anyOf: + - type: integer + description: Maximum number of uploads allowed during the session. + - type: 'null' type: object + required: + - enabled + - max_file_size + - max_files + title: File upload settings + description: Upload permissions and limits applied to the session. + ChatSessionHistory: 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. + enabled: + type: boolean + description: Indicates if chat history is persisted for the session. + recent_threads: + anyOf: + - type: integer + description: Number of prior threads surfaced in history views. Defaults to null when all history is retained. + - type: 'null' + type: object required: - - type - - code - - message - additionalProperties: false - description: An error reported while preparing a session environment. - SessionEnvironmentStateResource: + - enabled + - recent_threads + title: History settings + description: History retention preferences returned for the session. + ChatSessionChatkitConfiguration: + properties: + automatic_thread_titling: + $ref: '#/components/schemas/ChatSessionAutomaticThreadTitling' + description: Automatic thread titling preferences. + file_upload: + $ref: '#/components/schemas/ChatSessionFileUpload' + description: Upload settings for the session. + history: + $ref: '#/components/schemas/ChatSessionHistory' + description: History retention configuration. type: object + required: + - automatic_thread_titling + - file_upload + - history + title: ChatKit configuration + description: ChatKit configuration for the session. + ChatSessionResource: properties: id: type: string - minLength: 0 - description: The public ID of the environment. - type: + description: Identifier for the ChatKit session. + object: type: string - minLength: 0 - description: The environment type. + enum: + - chatkit.session + description: Type discriminator that is always `chatkit.session`. + default: chatkit.session + x-stainless-const: true + expires_at: + type: integer + format: unixtime + description: Unix timestamp (in seconds) for when the session expires. + client_secret: + type: string + description: Ephemeral client secret that authenticates session requests. + workflow: + $ref: '#/components/schemas/ChatkitWorkflow' + description: Workflow metadata for the session. + user: + type: string + description: User identifier associated with the session. + rate_limits: + $ref: '#/components/schemas/ChatSessionRateLimits' + description: Resolved rate limit values. + max_requests_per_1_minute: + type: integer + description: Convenience copy of the per-minute request limit. 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. + $ref: '#/components/schemas/ChatSessionStatus' + description: Current lifecycle state of the session. + chatkit_configuration: + $ref: '#/components/schemas/ChatSessionChatkitConfiguration' + description: Resolved ChatKit feature configuration for the session. + type: object required: - id - - type + - object + - expires_at + - client_secret + - workflow + - user + - rate_limits + - max_requests_per_1_minute - status - - error - additionalProperties: false - description: The current state of a session environment. - SessionEventAgentSessionEnvironmentReady: + - chatkit_configuration + title: The chat session object + description: Represents a ChatKit session and its resolved configuration. + WorkflowTracingParam: + properties: + enabled: + type: boolean + description: Whether tracing is enabled during the session. Defaults to true. type: object + required: [] + title: Tracing Configuration + description: Controls diagnostic tracing during the session. + WorkflowParam: 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: + id: type: string - minLength: 0 - description: The unique ID of the event. - session_id: + description: Identifier for the workflow invoked by the session. + version: 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. - SessionEventAgentOutputCommandExecutionOutputDelta: + description: Specific workflow version to run. Defaults to the latest deployed version. + state_variables: + additionalProperties: + anyOf: + - type: string + maxLength: 10485760 + - type: integer + - type: boolean + - type: number + type: object + maxProperties: 64 + description: State variables forwarded to the workflow. Keys may be up to 64 characters, values must be primitive types, and the map defaults to an empty object. + x-oaiTypeLabel: map + tracing: + $ref: '#/components/schemas/WorkflowTracingParam' + description: Optional tracing overrides for the workflow invocation. When omitted, tracing is enabled by default. type: object + required: + - id + title: Workflow settings + description: Workflow reference and overrides applied to the chat session. + ExpiresAfterParam: properties: - type: + anchor: type: string enum: - - agent.output.command_execution_output.delta - default: agent.output.command_execution_output.delta + - created_at + description: Base timestamp used to calculate expiration. Currently fixed to `created_at`. + default: created_at 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: + seconds: type: integer + maximum: 600 + minimum: 1 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. + description: Number of seconds after the anchor when the session expires. + type: object required: - - type - - event_id - - session_id - - turn_id - - item_id - - output_index - - delta - additionalProperties: false - description: Emitted when command execution produces an output delta. - SessionEventAgentSessionCreated: + - anchor + - seconds + title: Expiration overrides + description: Controls when the session expires relative to an anchor timestamp. + RateLimitsParam: + properties: + max_requests_per_1_minute: + type: integer + minimum: 1 + description: Maximum number of requests allowed per minute for the session. Defaults to 10. type: object + required: [] + title: Rate limit overrides + description: Controls request rate limits for the session. + AutomaticThreadTitlingParam: 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: + enabled: + type: boolean + description: Enable automatic thread title generation. Defaults to true. + type: object + required: [] + title: Automatic thread titling configuration + description: Controls whether ChatKit automatically generates thread titles. + FileUploadParam: + properties: + enabled: + type: boolean + description: Enable uploads for this session. Defaults to false. + max_file_size: + type: integer + maximum: 512 + minimum: 1 + description: Maximum size in megabytes for each uploaded file. Defaults to 512 MB, which is the maximum allowable size. + max_files: + type: integer + minimum: 1 + description: Maximum number of files that can be uploaded to the session. Defaults to 10. + type: object + required: [] + title: File upload configuration + description: Controls whether users can upload files. + HistoryParam: + properties: + enabled: + type: boolean + description: Enables chat users to access previous ChatKit threads. Defaults to true. + recent_threads: + type: integer + minimum: 1 + description: Number of recent ChatKit threads users have access to. Defaults to unlimited when unset. + type: object + required: [] + title: Chat history configuration + description: Controls how much historical context is retained for the session. + ChatkitConfigurationParam: + properties: + automatic_thread_titling: + $ref: '#/components/schemas/AutomaticThreadTitlingParam' + description: Configuration for automatic thread titling. When omitted, automatic thread titling is enabled by default. + file_upload: + $ref: '#/components/schemas/FileUploadParam' + description: Configuration for upload enablement and limits. When omitted, uploads are disabled by default (max_files 10, max_file_size 512 MB). + history: + $ref: '#/components/schemas/HistoryParam' + description: Configuration for chat history retention. When omitted, history is enabled by default with no limit on recent_threads (null). + type: object + required: [] + title: ChatKit configuration overrides + description: Optional per-session configuration settings for ChatKit behavior. + CreateChatSessionBody: + properties: + workflow: + $ref: '#/components/schemas/WorkflowParam' + description: Workflow that powers the session. + user: 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. - SessionEventAgentSessionTurnCreated: + minLength: 1 + description: A free-form string that identifies your end user; ensures this Session can access other objects that have the same `user` scope. + expires_after: + $ref: '#/components/schemas/ExpiresAfterParam' + description: Optional override for session expiration timing in seconds from creation. Defaults to 10 minutes. + rate_limits: + $ref: '#/components/schemas/RateLimitsParam' + description: Optional override for per-minute request limits. When omitted, defaults to 10. + chatkit_configuration: + $ref: '#/components/schemas/ChatkitConfigurationParam' + description: Optional overrides for ChatKit runtime configuration features type: object + required: + - workflow + - user + title: Create chat session request + description: Parameters for provisioning a new ChatKit session. + UserMessageInputText: properties: type: type: string enum: - - agent.session.turn.created - default: agent.session.turn.created + - input_text + description: Type discriminator that is always `input_text`. + default: input_text 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: + text: 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. + description: Plain-text content supplied by the user. + type: object required: - type - - event_id - - session_id - - turn_id - - turn - additionalProperties: false - description: Emitted when a turn is created. - SessionEventAgentSessionTurnInProgress: - type: object + - text + title: User message input + description: Text block that a user contributed to the thread. + UserMessageQuotedText: properties: type: type: string enum: - - agent.session.turn.in_progress - default: agent.session.turn.in_progress + - quoted_text + description: Type discriminator that is always `quoted_text`. + default: quoted_text 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: + text: 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. + description: Quoted text content. + type: object required: - type - - event_id - - session_id - - turn_id - - turn - additionalProperties: false - description: Emitted when a turn starts running. - SessionEventAgentSessionTurnCompleted: - type: object + - text + title: User message quoted text + description: Quoted snippet that the user referenced in their message. + AttachmentType: + type: string + enum: + - image + - file + Attachment: properties: type: + $ref: '#/components/schemas/AttachmentType' + description: Attachment discriminator. + id: 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: + description: Identifier for the attachment. + name: type: string - minLength: 0 - description: The ID of the session associated with the event. - turn_id: + description: Original display name for the attachment. + mime_type: type: string - minLength: 0 - description: The ID of the turn associated with the event. - turn: - $ref: '#/components/schemas/TurnResource' - description: The completed turn. - usage: + description: MIME type of the attachment. + preview_url: anyOf: - - $ref: '#/components/schemas/TokenUsageResource' + - type: string + format: uri + description: Preview URL for rendering the attachment inline. - type: 'null' - description: Token usage by the root agent during the turn, when available. + type: object required: - type - - event_id - - session_id - - turn_id - - turn - - usage - additionalProperties: false - description: Emitted when a turn completes. - SessionEventAgentSessionTurnFailed: - type: object + - id + - name + - mime_type + - preview_url + title: Attachment + description: Attachment metadata included on thread items. + ToolChoice: 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: + 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: + description: Identifier of the requested tool. + type: object + required: + - id + title: Tool choice + description: Tool selection that the assistant should honor when executing the item. + InferenceOptions: + properties: + tool_choice: anyOf: - - $ref: '#/components/schemas/TokenUsageResource' + - $ref: '#/components/schemas/ToolChoice' + description: Preferred tool to invoke. Defaults to null when ChatKit should auto-select. + - type: 'null' + model: + anyOf: + - type: string + description: Model name that generated the response. Defaults to null when using the session default. - 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. - SessionEventAgentSessionTurnCancelled: type: object + required: + - tool_choice + - model + title: Inference options + description: Model and tool overrides applied when generating the assistant response. + UserMessageItem: properties: - type: + id: + type: string + description: Identifier of the thread item. + object: type: string enum: - - agent.session.turn.cancelled - default: agent.session.turn.cancelled + - chatkit.thread_item + description: Type discriminator that is always `chatkit.thread_item`. + default: chatkit.thread_item 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: + created_at: + type: integer + format: unixtime + description: Unix timestamp (in seconds) for when the item was created. + thread_id: type: string - minLength: 0 - description: The ID of the session associated with the event. - turn_id: + description: Identifier of the parent thread. + type: type: string - minLength: 0 - description: The ID of the turn associated with the event. - turn: - $ref: '#/components/schemas/TurnResource' - description: The cancelled turn. - usage: + enum: + - chatkit.user_message + default: chatkit.user_message + x-stainless-const: true + content: + items: + discriminator: + propertyName: type + description: Content blocks that comprise a user message. + anyOf: + - $ref: '#/components/schemas/UserMessageInputText' + - $ref: '#/components/schemas/UserMessageQuotedText' + type: array + description: Ordered content elements supplied by the user. + attachments: + items: + $ref: '#/components/schemas/Attachment' + type: array + description: Attachments associated with the user message. Defaults to an empty list. + inference_options: anyOf: - - $ref: '#/components/schemas/TokenUsageResource' + - $ref: '#/components/schemas/InferenceOptions' + description: Inference overrides applied to the message. Defaults to null when unset. - type: 'null' - description: Token usage by the root agent during the turn, when available. + type: object required: + - id + - object + - created_at + - thread_id - type - - event_id - - session_id - - turn_id - - turn - - usage - additionalProperties: false - description: Emitted when a turn is cancelled. - SessionEventAgentSessionTurnItemAdded: - type: object + - content + - attachments + - inference_options + title: User Message Item + description: User-authored messages within a thread. + FileAnnotationSource: properties: type: type: string enum: - - agent.session.turn.item.added - default: agent.session.turn.item.added + - file + description: Type discriminator that is always `file`. + default: file 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: + filename: 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. + description: Filename referenced by the annotation. + type: object required: - type - - event_id - - session_id - - turn_id - - output_index - - item - additionalProperties: false - description: Emitted when an item is added to a turn. - SessionEventAgentSessionIdle: - type: object + - filename + title: File annotation source + description: Attachment source referenced by an annotation. + FileAnnotation: properties: type: type: string enum: - - agent.session.idle - default: agent.session.idle + - file + description: Type discriminator that is always `file` for this annotation. + default: file 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. + source: + $ref: '#/components/schemas/FileAnnotationSource' + description: File attachment referenced by the annotation. + type: object required: - type - - event_id - - session - additionalProperties: false - description: Emitted when a session becomes idle. - SessionEventAgentSessionInProgress: - type: object + - source + title: File annotation + description: Annotation that references an uploaded file. + UrlAnnotationSource: properties: type: type: string enum: - - agent.session.in_progress - default: agent.session.in_progress + - url + description: Type discriminator that is always `url`. + default: url x-stainless-const: true - description: The type of the object. Always `agent.session.in_progress`. - event_id: + url: type: string - minLength: 0 - description: The unique ID of the event. - session: - $ref: '#/components/schemas/SessionResource' - description: The session that started processing. + format: uri + description: URL referenced by the annotation. + type: object required: - type - - event_id - - session - additionalProperties: false - description: Emitted when a session starts processing a turn. - SessionEventAgentSessionRequiresAction: - type: object + - url + title: URL annotation source + description: URL backing an annotation entry. + UrlAnnotation: properties: type: type: string enum: - - agent.session.requires_action - default: agent.session.requires_action + - url + description: Type discriminator that is always `url` for this annotation. + default: url 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. + source: + $ref: '#/components/schemas/UrlAnnotationSource' + description: URL referenced by the annotation. + type: object required: - type - - event_id - - session - additionalProperties: false - description: Emitted when a session is waiting for one or more required actions. - SessionEventAgentSessionFailed: - type: object + - source + title: URL annotation + description: Annotation that references a URL. + ResponseOutputText: properties: type: type: string enum: - - agent.session.failed - default: agent.session.failed + - output_text + description: Type discriminator that is always `output_text`. + default: output_text x-stainless-const: true - description: The type of the object. Always `agent.session.failed`. - event_id: + text: type: string - minLength: 0 - description: The unique ID of the event. - session: - $ref: '#/components/schemas/SessionResource' - description: The failed session. + description: Assistant generated text. + annotations: + items: + discriminator: + propertyName: type + description: Annotation object describing a cited source. + anyOf: + - $ref: '#/components/schemas/FileAnnotation' + - $ref: '#/components/schemas/UrlAnnotation' + type: array + description: Ordered list of annotations attached to the response text. + type: object required: - type - - event_id - - session - additionalProperties: false - description: Emitted when a session fails. - SessionEventAgentSessionEnvironmentPending: - type: object + - text + - annotations + title: Assistant message content + description: Assistant response text accompanied by optional annotations. + AssistantMessageItem: properties: - type: + id: + type: string + description: Identifier of the thread item. + object: type: string enum: - - agent.session.environment.pending - default: agent.session.environment.pending + - chatkit.thread_item + description: Type discriminator that is always `chatkit.thread_item`. + default: chatkit.thread_item x-stainless-const: true - description: The type of the object. Always `agent.session.environment.pending`. - event_id: + created_at: + type: integer + format: unixtime + description: Unix timestamp (in seconds) for when the item was created. + thread_id: type: string - minLength: 0 - description: The unique ID of the event. - session_id: + description: Identifier of the parent thread. + type: 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. + enum: + - chatkit.assistant_message + description: Type discriminator that is always `chatkit.assistant_message`. + default: chatkit.assistant_message + x-stainless-const: true + content: + items: + $ref: '#/components/schemas/ResponseOutputText' + type: array + description: Ordered assistant response segments. + type: object required: + - id + - object + - created_at + - thread_id - type - - event_id - - session_id - - turn_id - - environment - additionalProperties: false - description: Emitted while a session environment is being prepared. - SessionEventAgentSessionEnvironmentConnected: - type: object + - content + title: Assistant message + description: Assistant-authored message within a thread. + WidgetMessageItem: properties: - type: + id: + type: string + description: Identifier of the thread item. + object: type: string enum: - - agent.session.environment.connected - default: agent.session.environment.connected + - chatkit.thread_item + description: Type discriminator that is always `chatkit.thread_item`. + default: chatkit.thread_item 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: + created_at: + type: integer + format: unixtime + description: Unix timestamp (in seconds) for when the item was created. + thread_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. - SessionEventAgentSessionEnvironmentDisconnected: - type: object - properties: + description: Identifier of the parent thread. type: type: string enum: - - agent.session.environment.disconnected - default: agent.session.environment.disconnected + - chatkit.widget + description: Type discriminator that is always `chatkit.widget`. + default: chatkit.widget 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: + widget: 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. + description: Serialized widget payload rendered in the UI. + type: object required: + - id + - object + - created_at + - thread_id - type - - event_id - - session_id - - turn_id - - environment - additionalProperties: false - description: Emitted when a session environment disconnects. - SessionEventAgentSessionEnvironmentFailed: - type: object + - widget + title: Widget message + description: Thread item that renders a widget payload. + ClientToolCallStatus: + type: string + enum: + - in_progress + - completed + ClientToolCallItem: properties: - type: + id: + type: string + description: Identifier of the thread item. + object: type: string enum: - - agent.session.environment.failed - default: agent.session.environment.failed + - chatkit.thread_item + description: Type discriminator that is always `chatkit.thread_item`. + default: chatkit.thread_item 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: + created_at: + type: integer + format: unixtime + description: Unix timestamp (in seconds) for when the item was created. + thread_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. - SessionEventAgentSessionSubagentCreated: - type: object - properties: + description: Identifier of the parent thread. type: type: string enum: - - agent.session.subagent.created - default: agent.session.subagent.created + - chatkit.client_tool_call + description: Type discriminator that is always `chatkit.client_tool_call`. + default: chatkit.client_tool_call x-stainless-const: true - description: The type of the object. Always `agent.session.subagent.created`. - event_id: + status: + $ref: '#/components/schemas/ClientToolCallStatus' + description: Execution status for the tool call. + call_id: type: string - minLength: 0 - description: The unique ID of the event. - subagent: - $ref: '#/components/schemas/SubagentResource' - description: The subagent that was created. + description: Identifier for the client tool call. + name: + type: string + description: Tool name that was invoked. + arguments: + type: string + description: JSON-encoded arguments that were sent to the tool. + output: + anyOf: + - type: string + description: JSON-encoded output captured from the tool. Defaults to null while execution is in progress. + - type: 'null' + type: object required: + - id + - object + - created_at + - thread_id - type - - event_id - - subagent - additionalProperties: false - description: Emitted when a subagent is created. - SessionEventAgentSessionSubagentActive: - type: object + - status + - call_id + - name + - arguments + - output + title: Client tool call + description: Record of a client side tool invocation initiated by the assistant. + TaskType: + type: string + enum: + - custom + - thought + TaskItem: properties: - type: + id: + type: string + description: Identifier of the thread item. + object: type: string enum: - - agent.session.subagent.active - default: agent.session.subagent.active + - chatkit.thread_item + description: Type discriminator that is always `chatkit.thread_item`. + default: chatkit.thread_item x-stainless-const: true - description: The type of the object. Always `agent.session.subagent.active`. - event_id: + created_at: + type: integer + format: unixtime + description: Unix timestamp (in seconds) for when the item was created. + thread_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. - SessionEventAgentSessionSubagentClosed: - type: object - properties: + description: Identifier of the parent thread. type: type: string enum: - - agent.session.subagent.closed - default: agent.session.subagent.closed + - chatkit.task + description: Type discriminator that is always `chatkit.task`. + default: chatkit.task 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. + task_type: + $ref: '#/components/schemas/TaskType' + description: Subtype for the task. + heading: + anyOf: + - type: string + description: Optional heading for the task. Defaults to null when not provided. + - type: 'null' + summary: + anyOf: + - type: string + description: Optional summary that describes the task. Defaults to null when omitted. + - type: 'null' + type: object required: + - id + - object + - created_at + - thread_id - type - - event_id - - subagent - additionalProperties: false - description: Emitted when a subagent is closed. - AssistantMessageItemResource: - type: object + - task_type + - heading + - summary + title: Task item + description: Task emitted by the workflow to show progress and status updates. + TaskGroupTask: properties: type: + $ref: '#/components/schemas/TaskType' + description: Subtype for the grouped task. + heading: + anyOf: + - type: string + description: Optional heading for the grouped task. Defaults to null when not provided. + - type: 'null' + summary: + anyOf: + - type: string + description: Optional summary that describes the grouped task. Defaults to null when omitted. + - type: 'null' + type: object + required: + - type + - heading + - summary + title: Task group task + description: Task entry that appears within a TaskGroup. + TaskGroupItem: + properties: + id: + type: string + description: Identifier of the thread item. + object: type: string enum: - - message - default: message + - chatkit.thread_item + description: Type discriminator that is always `chatkit.thread_item`. + default: chatkit.thread_item x-stainless-const: true - description: The item type. Always `message`. - id: - type: string - minLength: 0 - description: The ID of the message. - turn_id: + created_at: + type: integer + format: unixtime + description: Unix timestamp (in seconds) for when the item was created. + thread_id: type: string - minLength: 0 - description: The ID of the turn that contains this item. - role: + description: Identifier of the parent thread. + type: type: string enum: - - assistant - default: assistant + - chatkit.task_group + description: Type discriminator that is always `chatkit.task_group`. + default: chatkit.task_group 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 + tasks: 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. + $ref: '#/components/schemas/TaskGroupTask' + type: array + description: Tasks included in the group. + type: object required: - - type - id - - turn_id - - role - - status - - content - - phase - additionalProperties: false - description: An assistant message produced by the agent. - AgentOutputItemResource: - description: An output item produced by an agent. + - object + - created_at + - thread_id + - type + - tasks + title: Task group + description: Collection of workflow tasks grouped together in the thread. + ThreadItem: 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 + title: The thread item anyOf: - - $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' - SessionEventAgentSessionTurnItemDone: + - $ref: '#/components/schemas/UserMessageItem' + - $ref: '#/components/schemas/AssistantMessageItem' + - $ref: '#/components/schemas/WidgetMessageItem' + - $ref: '#/components/schemas/ClientToolCallItem' + - $ref: '#/components/schemas/TaskItem' + - $ref: '#/components/schemas/TaskGroupItem' + ThreadItemListResource: + properties: + object: + x-stainless-const: true + default: list + description: The type of object returned, must be `list`. + const: list + data: + items: + $ref: '#/components/schemas/ThreadItem' + type: array + description: A list of items + first_id: + anyOf: + - type: string + description: The ID of the first item in the list. + - type: 'null' + last_id: + anyOf: + - type: string + description: The ID of the last item in the list. + - type: 'null' + has_more: + type: boolean + description: Whether there are more items available. type: object + required: + - object + - data + - first_id + - last_id + - has_more + title: Thread Items + description: A paginated list of thread items rendered for the ChatKit API. + ActiveStatus: properties: type: type: string enum: - - agent.session.turn.item.done - default: agent.session.turn.item.done + - active + description: Status discriminator that is always `active`. + default: active 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. + type: object required: - type - - event_id - - session_id - - turn_id - - output_index - - item - additionalProperties: false - description: Emitted when an output item is complete. - SessionEventAgentSessionTurnContentPartAdded: - type: object + title: Active thread status + description: Indicates that a thread is active. + LockedStatus: properties: type: type: string enum: - - agent.session.turn.content_part.added - default: agent.session.turn.content_part.added + - locked + description: Status discriminator that is always `locked`. + default: locked 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. + reason: + anyOf: + - type: string + description: Reason that the thread was locked. Defaults to null when no reason is recorded. + - type: 'null' + type: object 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. - SessionEventAgentSessionTurnContentPartDone: - type: object + - reason + title: Locked thread status + description: Indicates that a thread is locked and cannot accept new input. + ClosedStatus: properties: type: type: string enum: - - agent.session.turn.content_part.done - default: agent.session.turn.content_part.done + - closed + description: Status discriminator that is always `closed`. + default: closed 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. + reason: + anyOf: + - type: string + description: Reason that the thread was closed. Defaults to null when no reason is recorded. + - type: 'null' + type: object 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. - SessionEventAgentSessionTurnOutputTextDelta: - type: object + - reason + title: Closed thread status + description: Indicates that a thread has been closed. + ThreadResource: properties: - type: + id: + type: string + description: Identifier of the thread. + object: type: string enum: - - agent.session.turn.output_text.delta - default: agent.session.turn.output_text.delta + - chatkit.thread + description: Type discriminator that is always `chatkit.thread`. + default: chatkit.thread 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: + created_at: + type: integer + format: unixtime + description: Unix timestamp (in seconds) for when the thread was created. + title: + anyOf: + - type: string + description: Optional human-readable title for the thread. Defaults to null when no title has been generated. + - type: 'null' + status: + discriminator: + propertyName: type + description: Current status for the thread. Defaults to `active` for newly created threads. + anyOf: + - $ref: '#/components/schemas/ActiveStatus' + - $ref: '#/components/schemas/LockedStatus' + - $ref: '#/components/schemas/ClosedStatus' + user: 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: + description: Free-form string that identifies your end user who owns the thread. + type: object + required: + - id + - object + - created_at + - title + - status + - user + title: The thread object + description: Represents a ChatKit thread and its current status. + example: + id: cthr_def456 + object: chatkit.thread + created_at: 1712345600 + title: Demo feedback + status: + type: active + user: user_456 + DeletedThreadResource: + properties: + 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: + description: Identifier of the deleted thread. + object: type: string - minLength: 0 - description: The text that was appended. + enum: + - chatkit.thread.deleted + description: Type discriminator that is always `chatkit.thread.deleted`. + default: chatkit.thread.deleted + x-stainless-const: true + deleted: + type: boolean + description: Indicates that the thread has been deleted. + type: object + required: + - id + - object + - deleted + title: Deleted thread + description: Confirmation payload returned after deleting a thread. + ThreadListResource: + properties: + object: + x-stainless-const: true + default: list + description: The type of object returned, must be `list`. + const: list + data: + items: + $ref: '#/components/schemas/ThreadResource' + type: array + description: A list of items + first_id: + anyOf: + - type: string + description: The ID of the first item in the list. + - type: 'null' + last_id: + anyOf: + - type: string + description: The ID of the last item in the list. + - type: 'null' + has_more: + type: boolean + description: Whether there are more items available. + type: object 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. - SessionEventAgentSessionTurnOutputTextDone: + - object + - data + - first_id + - last_id + - has_more + title: Threads + description: A paginated list of ChatKit threads. + EnvironmentTypeResource: + type: string + enum: + - openai_hosted + - self_hosted + description: The kind of execution environment. + EnvironmentStatusResource: + type: string + enum: + - pending + - connected + - disconnected + - expired + - failed + description: The public lifecycle status of an execution environment. + HostedEnvironmentFileResourceFileId: type: object properties: type: type: string enum: - - agent.session.turn.output_text.done - default: agent.session.turn.output_text.done + - file_id + default: file_id x-stainless-const: true - description: The type of the object. Always `agent.session.turn.output_text.done`. - event_id: + description: The type of the object. Always `file_id`. + id: type: string minLength: 0 - description: The unique ID of the event. - session_id: + description: The session-scoped ID of the file in the execution environment. + file_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: + description: The ID of the uploaded file. + path: 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: + description: The file's absolute path inside the environment. + size_bytes: 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. + description: The decoded file size in bytes. required: - type - - event_id - - session_id - - turn_id - - item_id - - output_index - - content_index - - text + - id + - file_id + - path + - size_bytes additionalProperties: false - description: Emitted when an output text content part is complete. - SessionEventAgentSessionTurnReasoningSummaryPartAdded: + description: A file copied from the OpenAI Files API. + HostedEnvironmentFileResourceInline: type: object properties: type: type: string enum: - - agent.session.turn.reasoning_summary_part.added - default: agent.session.turn.reasoning_summary_part.added + - inline + default: inline 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: + description: The type of the object. Always `inline`. + 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: + description: The session-scoped ID of the file in the execution environment. + path: 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: + description: The file's absolute path inside the environment. + size_bytes: 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. + description: The decoded file size in bytes. required: - type - - event_id - - session_id - - turn_id - - item_id - - output_index - - summary_index - - part + - id + - path + - size_bytes additionalProperties: false - description: Emitted when a reasoning summary content part is added. - SessionEventAgentSessionTurnReasoningSummaryPartDone: + description: A file supplied inline when the session was created. + HostedEnvironmentFileResource: + description: Metadata for a file materialized in an OpenAI-hosted execution environment. + discriminator: + propertyName: type + mapping: + file_id: '#/components/schemas/HostedEnvironmentFileResourceFileId' + inline: '#/components/schemas/HostedEnvironmentFileResourceInline' + x-oai-discriminator-values: + - file_id + - inline + anyOf: + - $ref: '#/components/schemas/HostedEnvironmentFileResourceFileId' + - $ref: '#/components/schemas/HostedEnvironmentFileResourceInline' + HostedSkillResourceSkillReference: type: object properties: type: type: string enum: - - agent.session.turn.reasoning_summary_part.done - default: agent.session.turn.reasoning_summary_part.done + - skill_reference + default: skill_reference x-stainless-const: true - description: The type of the object. Always `agent.session.turn.reasoning_summary_part.done`. - event_id: + description: The type of the object. Always `skill_reference`. + skill_id: type: string minLength: 0 - description: The unique ID of the event. - session_id: + description: The referenced skill ID. + version: type: string minLength: 0 - description: The ID of the session associated with the event. - turn_id: - type: - - string - - 'null' + description: The concrete skill version installed for this session. + name: + type: string minLength: 0 - description: The ID of the turn associated with the event, when applicable. - item_id: + description: The installed skill name. + description: 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 + description: The installed skill description. required: - type - - event_id - - session_id - - turn_id - - item_id - - output_index - - summary_index - - part - - status + - skill_id + - version + - name + - description additionalProperties: false - description: Emitted when a reasoning summary part is complete. - SessionEventAgentSessionTurnReasoningSummaryTextDelta: + description: A skill installed from the Skills API. + HostedSkillResourceInline: type: object properties: type: type: string enum: - - agent.session.turn.reasoning_summary_text.delta - default: agent.session.turn.reasoning_summary_text.delta + - inline + default: inline 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: + description: The type of the object. Always `inline`. + name: 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: + description: The installed skill name. + description: type: string minLength: 0 - description: The summary text that was appended. + description: The installed skill description. required: - type - - event_id - - session_id - - turn_id - - item_id - - output_index - - summary_index - - delta + - name + - description additionalProperties: false - description: Emitted when text is appended to a reasoning summary. - SessionEventAgentSessionTurnReasoningSummaryTextDone: + description: A skill installed from an inline ZIP archive. + HostedSkillResource: + description: A skill installed in an OpenAI-hosted environment. + discriminator: + propertyName: type + mapping: + skill_reference: '#/components/schemas/HostedSkillResourceSkillReference' + inline: '#/components/schemas/HostedSkillResourceInline' + x-oai-discriminator-values: + - skill_reference + - inline + anyOf: + - $ref: '#/components/schemas/HostedSkillResourceSkillReference' + - $ref: '#/components/schemas/HostedSkillResourceInline' + HostedPluginResourceInline: type: object properties: type: type: string enum: - - agent.session.turn.reasoning_summary_text.done - default: agent.session.turn.reasoning_summary_text.done + - inline + default: inline 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: + description: The type of the object. Always `inline`. + name: 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: + description: The installed plugin name. + description: type: string minLength: 0 - description: The complete reasoning summary text. + description: The installed plugin description. required: - type - - event_id - - session_id - - turn_id - - item_id - - output_index - - summary_index - - text + - name + - description additionalProperties: false - description: Emitted when a reasoning summary content part is complete. - SessionEvent: - description: An event emitted by a Managed Agents session. + description: A plugin installed from an inline ZIP archive. + HostedPluginResource: + description: A plugin installed in an OpenAI-hosted environment. discriminator: propertyName: type mapping: - error: '#/components/schemas/SessionEventError' - agent.session.environment.ready: '#/components/schemas/SessionEventAgentSessionEnvironmentReady' - 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' + inline: '#/components/schemas/HostedPluginResourceInline' x-oai-discriminator-values: - - error - - agent.session.environment.ready - - 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 + - inline anyOf: - - $ref: '#/components/schemas/SessionEventError' - - $ref: '#/components/schemas/SessionEventAgentSessionEnvironmentReady' - - $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' - 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. - UpdateSessionAgentParam: + - $ref: '#/components/schemas/HostedPluginResourceInline' + PublicEnvironmentResource: type: object properties: - model: + id: 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. + 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. + files: + type: array + items: + $ref: '#/components/schemas/HostedEnvironmentFileResource' + minItems: 0 + maxItems: 2000 + description: Files installed in the environment, without their contents. + skills: + type: array + items: + $ref: '#/components/schemas/HostedSkillResource' + minItems: 0 + maxItems: 2000 + description: Skills installed in the environment, without their archive contents. + plugins: + type: array + items: + $ref: '#/components/schemas/HostedPluginResource' + minItems: 0 + maxItems: 2000 + description: Plugins installed in the environment, without their archive contents. + required: + - id + - object + - type + - status + - files + - skills + - plugins additionalProperties: false - description: Model settings that can change after session creation. - UpdateAgentSessionParams: + description: Safe metadata for a first-class execution environment. + ErrorBodyResource: type: object properties: - agent: - $ref: '#/components/schemas/UpdateSessionAgentParam' - description: Model settings for subsequent turns. Omitted fields stay unchanged. - metadata: + 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: - - object + - string - '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. + 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: Fields to update on an existing session. - DeletedSessionResource: + description: Details about an API error. + ErrorResponse-2: 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. + error: + $ref: '#/components/schemas/ErrorBodyResource' + description: The error returned by the API. required: - - id - - object - - deleted + - error additionalProperties: false - description: A Managed Agents session removed from the public API. Physical cleanup may continue asynchronously. - SessionArtifactResource: + description: An API error response. + 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. + EnvironmentFilePageObjectResource: + type: string + enum: + - page + default: page + x-stainless-const: true + description: The object type for a page of files in an execution environment. + EnvironmentFileResource: type: object properties: - id: - type: string - minLength: 0 - description: The immutable artifact ID. object: type: string enum: - - agent.session.artifact - default: agent.session.artifact + - agent.environment.file + default: agent.environment.file 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. + description: The object type. Always `agent.environment.file`. 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. + description: The ID of the environment containing this file. path: type: string minLength: 0 - description: The original absolute file path in the execution environment. + description: The absolute file path inside the environment's workspace. 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. + description: The file size in bytes. 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. - SessionArtifactListResource: + description: A live file in an execution environment. + EnvironmentFileListResource: type: object properties: object: - type: string - enum: - - list - default: list - x-stainless-const: true - description: The object type, which is always `list`. + $ref: '#/components/schemas/EnvironmentFilePageObjectResource' + description: The object type. Always `page`. data: type: array items: - $ref: '#/components/schemas/SessionArtifactResource' + $ref: '#/components/schemas/EnvironmentFileResource' 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: + description: Files available on the current page. + next: 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. + description: The opaque cursor to use when requesting the next page, if any. has_more: type: boolean - description: Whether there are more resources to retrieve after this page. + description: Whether more files follow this page. required: - object - data - - first_id - - last_id + - next - has_more additionalProperties: false - description: A page of Agents API resources, with IDs for retrieving additional pages. - DeletedSessionArtifactResource: + description: A paginated list of live execution environment files. + HostedEnvironmentFileParamFileId: type: object properties: - id: - type: string - minLength: 0 - description: The ID of the deleted session artifact. - object: + type: type: string enum: - - agent.session.artifact.deleted - default: agent.session.artifact.deleted + - file_id + default: file_id 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`. + 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: - - id - - object - - deleted + - type + - file_id + - path additionalProperties: false - description: Confirmation that an immutable session artifact was deleted. - SessionInputParamAgentSessionInputMessage: + description: A file previously uploaded through the OpenAI Files API. + HostedEnvironmentFileParamInline: type: object properties: type: type: string enum: - - agent.session.input.message - default: agent.session.input.message + - inline + default: inline 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. + 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 - - input + - data + - path additionalProperties: false - description: Adds one or more user messages and starts a turn. - SessionInputParamAgentSessionInputCancel: + description: A file supplied directly as standard-base64 data. + HostedEnvironmentFileParam: + description: A file materialized in an OpenAI-hosted execution environment. + discriminator: + propertyName: type + mapping: + file_id: '#/components/schemas/HostedEnvironmentFileParamFileId' + inline: '#/components/schemas/HostedEnvironmentFileParamInline' + x-oai-discriminator-values: + - file_id + - inline + anyOf: + - $ref: '#/components/schemas/HostedEnvironmentFileParamFileId' + - $ref: '#/components/schemas/HostedEnvironmentFileParamInline' + SubagentObjectResource: + type: string + enum: + - agent.session.subagent + default: agent.session.subagent + x-stainless-const: true + description: The object type for a subagent. + OutputTextResource: type: object properties: type: type: string enum: - - agent.session.input.cancel - default: agent.session.input.cancel + - output_text + default: output_text x-stainless-const: true - description: The type of the object. Always `agent.session.input.cancel`. + 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: Cancels the session's active turn. - FunctionCallOutputParam: - description: A function result represented as text or supported model-input content. - anyOf: - - type: string - minLength: 0 - maxLength: 1048576 - - type: array - items: - $ref: '#/components/schemas/InputContentParam' - minItems: 0 - maxItems: 16384 - SessionInputParamAgentSessionInputToolResult: + description: A text content part produced by the agent. + EncryptedContentResource: type: object properties: type: type: string enum: - - agent.session.input.tool_result - default: agent.session.input.tool_result + - encrypted_content + default: encrypted_content 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: + description: The content type. Always `encrypted_content`. + encrypted_content: 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. + description: The encrypted content payload. required: - type - - turn_id - - call_id - - success + - encrypted_content additionalProperties: false - description: Submits the result of a function call. - SessionInputParam: - description: Input submitted to an existing session. + description: Encrypted content exchanged between agents. + AgentContentResource: + description: A plaintext or encrypted content part exchanged between agents. 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' + output_text: '#/components/schemas/OutputTextResource' + encrypted_content: '#/components/schemas/EncryptedContentResource' x-oai-discriminator-values: - - agent.session.input.message - - agent.session.input.cancel - - agent.session.input.tool_result + - output_text + - encrypted_content anyOf: - - $ref: '#/components/schemas/SessionInputParamAgentSessionInputMessage' - - $ref: '#/components/schemas/SessionInputParamAgentSessionInputCancel' - - $ref: '#/components/schemas/SessionInputParamAgentSessionInputToolResult' - 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. - VaultStatusParam: + - $ref: '#/components/schemas/OutputTextResource' + - $ref: '#/components/schemas/EncryptedContentResource' + SubagentStatusResource: type: string enum: - active - - archived - description: Whether a vault or credential is active or archived. - VaultStatusFilterParam: - description: One or more lifecycle statuses to include when listing vaults or credentials. - anyOf: - - $ref: '#/components/schemas/VaultStatusParam' - - type: array - items: - $ref: '#/components/schemas/VaultStatusParam' - minItems: 0 - maxItems: 16384 - VaultResource: + - closed + x-enumDescriptions: + - The subagent remains available, including while idle between turns. + - The subagent is closed. + description: The current status of a subagent. + SubagentResource: type: object properties: id: type: string minLength: 0 - description: The ID of the vault. + description: The ID of the subagent. object: + $ref: '#/components/schemas/SubagentObjectResource' + description: The object type. Always `agent.session.subagent`. + session_id: type: string - enum: - - vault - default: vault - x-stainless-const: true - description: The object type. Always `vault`. + minLength: 0 + description: The ID of the session that owns the subagent. name: type: - string - 'null' minLength: 0 - description: The human-readable name of the vault, if set. - metadata: - type: object - additionalProperties: - type: string - minLength: 0 - propertyNames: - type: string - minLength: 0 - minProperties: 0 - description: Key-value pairs associated with the vault, such as an application or team identifier. - created_at: - type: integer - format: int64 - description: The Unix timestamp, in seconds, when the vault was created. - required: - - id - - object - - name - - metadata - - created_at - additionalProperties: false - description: A collection of credentials that agent tools can use to authenticate to MCP servers. - VaultListResource: - 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 + description: The runner-assigned nickname, or null when unavailable. + instructions: + type: + - array + - 'null' items: - $ref: '#/components/schemas/VaultResource' + $ref: '#/components/schemas/AgentContentResource' 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. - CreateVaultParams: - type: object - properties: - name: + 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: 1 - maxLength: 1048576 - description: The name is trimmed before storage. It must contain 1 to 256 UTF-8 bytes after trimming. - metadata: + 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: - - object + - integer - 'null' - additionalProperties: - type: string - minLength: 0 - maxLength: 1048576 - propertyNames: - type: string - minLength: 1 - maxLength: 256 - minProperties: 0 - maxProperties: 1024 - description: Key-value pairs to associate with the vault, such as an application or team identifier. - additionalProperties: false - description: Parameters for creating a vault to store credentials used by agent tools. - DeletedVaultResource: - type: object - properties: - id: - type: string - minLength: 0 - description: The ID of the deleted vault. - object: - type: string - enum: - - vault.deleted - default: vault.deleted - x-stainless-const: true - description: The object type. Always `vault.deleted`. - deleted: - type: boolean - description: Whether the resource was deleted. Always `true`. + format: int64 + description: The Unix timestamp, in seconds, when the subagent was closed. Null while active, including after resume. required: - id - object - - deleted + - session_id + - name + - instructions + - parent_agent_id + - status + - opened_at + - closed_at additionalProperties: false - description: Confirmation that a vault was deleted. - McpOauthTokenEndpointAuthResourceNone: + description: A subagent created within a session. + SessionMessageRoleResource: + type: string + enum: + - user + - assistant + description: The author of a session message. + MessageContentResourceInputText: type: object properties: type: type: string enum: - - none - default: none + - input_text + default: input_text x-stainless-const: true - description: The type of the object. Always `none`. + 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: Sends the client ID without a client secret. - McpOauthTokenEndpointAuthResourceClientSecretBasic: + description: Text supplied by the user. + MessageContentResourceInputImage: type: object properties: type: type: string enum: - - client_secret_basic - default: client_secret_basic + - input_image + default: input_image x-stainless-const: true - description: The type of the object. Always `client_secret_basic`. + 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: Sends the client ID and secret using HTTP Basic authentication. - McpOauthTokenEndpointAuthResourceClientSecretPost: + description: An image supplied by the user. + MessageContentResourceOutputText: type: object properties: type: type: string enum: - - client_secret_post - default: client_secret_post + - output_text + default: output_text x-stainless-const: true - description: The type of the object. Always `client_secret_post`. + 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: Sends the client ID and secret in the token request body. - McpOauthTokenEndpointAuthResource: - description: The client authentication method used for OAuth token refresh. + description: Text produced by the assistant. + MessageContentResource: + description: A content part in a session message. discriminator: propertyName: type mapping: - none: '#/components/schemas/McpOauthTokenEndpointAuthResourceNone' - client_secret_basic: '#/components/schemas/McpOauthTokenEndpointAuthResourceClientSecretBasic' - client_secret_post: '#/components/schemas/McpOauthTokenEndpointAuthResourceClientSecretPost' + input_text: '#/components/schemas/MessageContentResourceInputText' + input_image: '#/components/schemas/MessageContentResourceInputImage' + output_text: '#/components/schemas/MessageContentResourceOutputText' x-oai-discriminator-values: - - none - - client_secret_basic - - client_secret_post + - input_text + - input_image + - output_text anyOf: - - $ref: '#/components/schemas/McpOauthTokenEndpointAuthResourceNone' - - $ref: '#/components/schemas/McpOauthTokenEndpointAuthResourceClientSecretBasic' - - $ref: '#/components/schemas/McpOauthTokenEndpointAuthResourceClientSecretPost' - McpOauthRefreshResource: - type: object - properties: - token_endpoint: - type: string - minLength: 0 - description: The HTTPS OAuth token endpoint used for refresh. - client_id: - type: string - minLength: 0 - description: The OAuth client ID used when requesting a new access token. - resource: - type: - - string - - 'null' - minLength: 0 - description: The resource URI sent to the OAuth token endpoint during refresh, if configured. - scope: - type: - - string - - 'null' - minLength: 0 - description: Space-separated OAuth scopes requested during refresh, if configured. - token_endpoint_auth: - $ref: '#/components/schemas/McpOauthTokenEndpointAuthResource' - description: How the OAuth client authenticates to the token endpoint, excluding its client secret. - required: - - token_endpoint - - client_id - - resource - - scope - - token_endpoint_auth - additionalProperties: false - description: Configuration used to refresh an MCP OAuth access token, excluding secret values. - VaultCredentialAuthResourceMcpOauth: + - $ref: '#/components/schemas/MessageContentResourceInputText' + - $ref: '#/components/schemas/MessageContentResourceInputImage' + - $ref: '#/components/schemas/MessageContentResourceOutputText' + 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. + 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. + MessageItemResource: type: object properties: type: type: string enum: - - mcp_oauth - default: mcp_oauth + - message + default: message x-stainless-const: true - description: The type of the object. Always `mcp_oauth`. - mcp_server_url: - type: string - minLength: 0 - description: The HTTPS MCP server URL authorized by this credential. - expires_at: + description: The item type. Always `message`. + id: type: - string - 'null' minLength: 0 - description: When the OAuth access token expires, as an RFC 3339 timestamp, if known. - refresh: + 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/McpOauthRefreshResource' + - $ref: '#/components/schemas/MessagePhaseResource' - type: 'null' - description: Public refresh metadata without refresh tokens or OAuth client secrets. + description: The phase of an assistant message. Null for user messages. required: - type - - mcp_server_url - - expires_at - - refresh + - id + - turn_id + - role + - content + - status + - phase additionalProperties: false - description: Public metadata for an OAuth credential; tokens and client secrets are never returned. - VaultCredentialAuthResourceStaticBearer: + description: A user or assistant message recorded in a session. + SummaryTextResource: type: object properties: type: type: string enum: - - static_bearer - default: static_bearer + - summary_text + default: summary_text x-stainless-const: true - description: The type of the object. Always `static_bearer`. - mcp_server_url: + description: The content type. Always `summary_text`. + text: type: string minLength: 0 - description: The HTTPS MCP server URL authorized by this credential. + description: The reasoning summary text. required: - type - - mcp_server_url + - text additionalProperties: false - description: Metadata for a bearer-token credential, without automatic OAuth refresh. - VaultCredentialAuthResource: - description: The MCP server and authentication configuration of a vault credential, excluding secrets. - discriminator: - propertyName: type - mapping: - mcp_oauth: '#/components/schemas/VaultCredentialAuthResourceMcpOauth' - static_bearer: '#/components/schemas/VaultCredentialAuthResourceStaticBearer' - x-oai-discriminator-values: - - mcp_oauth - - static_bearer - anyOf: - - $ref: '#/components/schemas/VaultCredentialAuthResourceMcpOauth' - - $ref: '#/components/schemas/VaultCredentialAuthResourceStaticBearer' - VaultCredentialResource: + description: A reasoning summary content part. + ReasoningItemResource: type: object properties: - id: - type: string - minLength: 0 - description: The ID of the credential. - object: + type: type: string enum: - - vault.credential - default: vault.credential + - reasoning + default: reasoning x-stainless-const: true - description: The object type. Always `vault.credential`. - vault_id: + description: The item type. Always `reasoning`. + id: type: string minLength: 0 - description: The ID of the vault containing this credential. - name: + description: The ID of the reasoning item. + turn_id: type: string minLength: 0 - description: The human-readable name of the credential. - auth: - $ref: '#/components/schemas/VaultCredentialAuthResource' - description: The authentication method and non-secret configuration for the MCP server. - created_at: - type: integer - format: int64 - description: The Unix timestamp, in seconds, when the credential was created. - updated_at: - type: integer - format: int64 - description: The Unix timestamp, in seconds, when the credential was last updated. - required: - - id - - object - - vault_id - - name - - auth - - created_at - - updated_at - additionalProperties: false - description: Metadata for a stored MCP server credential. Secret values are never returned. - VaultCredentialListResource: - type: object - properties: - object: - type: string - enum: - - list - default: list - x-stainless-const: true - description: The object type, which is always `list`. - data: + description: The ID of the turn that contains this item. + summary: type: array items: - $ref: '#/components/schemas/VaultCredentialResource' + $ref: '#/components/schemas/SummaryTextResource' 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. + description: The reasoning summaries produced by the agent. + status: + anyOf: + - $ref: '#/components/schemas/OutputItemStatusResource' + - type: 'null' + description: The status of the reasoning item. required: - - object - - data - - first_id - - last_id - - has_more + - type + - id + - turn_id + - summary + - status additionalProperties: false - description: A page of Agents API resources, with IDs for retrieving additional pages. - CreateMcpOauthTokenEndpointAuthParamNone: + description: A reasoning item produced by the agent. + 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. + FunctionCallItemResource: type: object properties: type: type: string enum: - - none - default: none + - function_call + default: function_call x-stainless-const: true - description: The type of the object. Always `none`. + 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: Sends the client ID without a client secret. - CreateMcpOauthTokenEndpointAuthParamClientSecretBasic: + description: A function call produced by the agent. + InputContentResourceInputText: type: object properties: type: type: string enum: - - client_secret_basic - default: client_secret_basic + - input_text + default: input_text x-stainless-const: true - description: The type of the object. Always `client_secret_basic`. - client_secret: + description: The type of the object. Always `input_text`. + text: type: string minLength: 0 - maxLength: 1048576 - description: The OAuth client secret to store. Never returned in credential resources. + description: The text supplied to the agent. required: - type - - client_secret + - text additionalProperties: false - description: Sends the client ID and secret using HTTP Basic authentication. - CreateMcpOauthTokenEndpointAuthParamClientSecretPost: + description: Text input recorded in a session item. + InputContentResourceInputImage: type: object properties: type: type: string enum: - - client_secret_post - default: client_secret_post + - input_image + default: input_image x-stainless-const: true - description: The type of the object. Always `client_secret_post`. - client_secret: + description: The type of the object. Always `input_image`. + image_url: type: string minLength: 0 - maxLength: 1048576 - description: The OAuth client secret to store. Never returned in credential resources. + description: The URL of the image supplied to the agent, which may be a base64-encoded data URL. required: - type - - client_secret + - image_url additionalProperties: false - description: Sends the client ID and secret in the token request body. - CreateMcpOauthTokenEndpointAuthParam: - description: Client authentication credentials for OAuth token refresh. + description: Image input recorded in a session item. + InputContentResource: + description: User-provided content recorded in a session item. discriminator: propertyName: type mapping: - none: '#/components/schemas/CreateMcpOauthTokenEndpointAuthParamNone' - client_secret_basic: '#/components/schemas/CreateMcpOauthTokenEndpointAuthParamClientSecretBasic' - client_secret_post: '#/components/schemas/CreateMcpOauthTokenEndpointAuthParamClientSecretPost' + input_text: '#/components/schemas/InputContentResourceInputText' + input_image: '#/components/schemas/InputContentResourceInputImage' x-oai-discriminator-values: - - none - - client_secret_basic - - client_secret_post + - input_text + - input_image anyOf: - - $ref: '#/components/schemas/CreateMcpOauthTokenEndpointAuthParamNone' - - $ref: '#/components/schemas/CreateMcpOauthTokenEndpointAuthParamClientSecretBasic' - - $ref: '#/components/schemas/CreateMcpOauthTokenEndpointAuthParamClientSecretPost' - CreateMcpOauthRefreshParam: + - $ref: '#/components/schemas/InputContentResourceInputText' + - $ref: '#/components/schemas/InputContentResourceInputImage' + FunctionCallOutputResource: + description: The text or model-input content supplied as a function result. + anyOf: + - type: string + minLength: 0 + - type: array + items: + $ref: '#/components/schemas/InputContentResource' + minItems: 0 + maxItems: 2000 + FunctionCallOutputItemResource: type: object properties: - token_endpoint: + id: type: string minLength: 0 - maxLength: 1048576 - description: The HTTPS OAuth token endpoint used to exchange the refresh token for a new access token. - client_id: + description: The ID of the function call output item. + turn_id: type: string minLength: 0 - maxLength: 1048576 - description: The OAuth client ID used when requesting a new access token. - resource: - type: - - string - - 'null' + 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 - maxLength: 1048576 - description: The resource URI to send to the OAuth token endpoint during refresh, if required. - scope: + 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 - maxLength: 1048576 - description: Space-separated OAuth scopes to request during refresh, if required. - refresh_token: - type: string - minLength: 0 - maxLength: 1048576 - description: The refresh token to store. This secret is never returned in credential resources. - token_endpoint_auth: - $ref: '#/components/schemas/CreateMcpOauthTokenEndpointAuthParam' - description: How the OAuth client authenticates to the token endpoint. + description: The error message, if the call failed. required: - - token_endpoint - - client_id - - refresh_token - - token_endpoint_auth + - id + - turn_id + - type + - call_id + - status + - output + - error additionalProperties: false - description: Configuration for refreshing the access token of an MCP OAuth credential. - CreateVaultCredentialAuthParamMcpOauth: + description: The result supplied for a function call. + 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: - - mcp_oauth - default: mcp_oauth + - agent_message + default: agent_message x-stainless-const: true - description: The type of the object. Always `mcp_oauth`. - mcp_server_url: + description: The item type. Always `agent_message`. + sender_agent_id: type: string minLength: 0 - maxLength: 1048576 - description: The HTTPS MCP server URL authorized by this credential. - access_token: + description: The ID or name of the sending agent. + recipient_agent_id: type: string minLength: 0 - maxLength: 1048576 - description: A write-only OAuth access token; never returned by credential resources. - expires_at: - type: - - string - - 'null' - minLength: 0 - maxLength: 1048576 - description: When the OAuth access token expires, as an RFC 3339 timestamp, if known. - refresh: - anyOf: - - $ref: '#/components/schemas/CreateMcpOauthRefreshParam' - - type: 'null' - description: Optional refresh configuration for an HTTPS OAuth token endpoint. + 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: - - type - - mcp_server_url - - access_token + - id + - turn_id + - type + - sender_agent_id + - recipient_agent_id + - content additionalProperties: false - description: An OAuth credential for an HTTPS MCP destination. - CreateVaultCredentialAuthParamStaticBearer: + description: A message exchanged between agent threads. + McpCallItemResource: type: object properties: type: type: string enum: - - static_bearer - default: static_bearer + - mcp_call + default: mcp_call x-stainless-const: true - description: The type of the object. Always `static_bearer`. - mcp_server_url: + description: The item type. Always `mcp_call`. + id: type: string minLength: 0 - maxLength: 1048576 - description: The HTTPS MCP server URL authorized by this credential. - token: + description: The ID of the MCP call item. + turn_id: type: string minLength: 0 - maxLength: 1048576 - description: The bearer token to store. This secret is never returned in credential resources. - required: - - type - - mcp_server_url - - token - additionalProperties: false - description: A bearer token for an MCP server, without automatic OAuth refresh. - CreateVaultCredentialAuthParam: - description: Authentication credentials for an MCP server used by agent tools. - discriminator: - propertyName: type - mapping: - mcp_oauth: '#/components/schemas/CreateVaultCredentialAuthParamMcpOauth' - static_bearer: '#/components/schemas/CreateVaultCredentialAuthParamStaticBearer' - x-oai-discriminator-values: - - mcp_oauth - - static_bearer - anyOf: - - $ref: '#/components/schemas/CreateVaultCredentialAuthParamMcpOauth' - - $ref: '#/components/schemas/CreateVaultCredentialAuthParamStaticBearer' - CreateVaultCredentialParams: - type: object - properties: + 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: 1 - maxLength: 1048576 - description: The name is trimmed before storage. It must contain 1 to 256 UTF-8 bytes after trimming. - auth: - $ref: '#/components/schemas/CreateVaultCredentialAuthParam' - description: The authentication method and secret values to store for the MCP server. + 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: - - auth + - type + - id + - turn_id + - server_label - name + - arguments + - status + - output + - error additionalProperties: false - description: Parameters for storing a credential that authorizes access to an MCP server. - RotateMcpOauthTokenEndpointAuthParamClientSecretBasic: + description: A call to a tool on an MCP server. + WebSearchActionResourceSearch: type: object properties: type: type: string enum: - - client_secret_basic - default: client_secret_basic + - search + default: search x-stainless-const: true - description: The type of the object. Always `client_secret_basic`. - client_secret: + description: The type of the object. Always `search`. + query: type: - string - 'null' minLength: 0 - maxLength: 1048576 - description: The replacement OAuth client secret. Omit or pass `null` to keep the stored secret. This secret is never returned in resources. + 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: Updates credentials sent using HTTP Basic authentication. - RotateMcpOauthTokenEndpointAuthParamClientSecretPost: + description: A search query or group of search queries. + WebSearchActionResourceOpenPage: type: object properties: type: type: string enum: - - client_secret_post - default: client_secret_post + - open_page + default: open_page x-stainless-const: true - description: The type of the object. Always `client_secret_post`. - client_secret: + description: The type of the object. Always `open_page`. + url: type: - string - 'null' minLength: 0 - maxLength: 1048576 - description: The replacement OAuth client secret. Omit or pass `null` to keep the stored secret. This secret is never returned in resources. + description: The URL of the page that was opened. required: - type + - url additionalProperties: false - description: Updates credentials sent in the token request body. - RotateMcpOauthTokenEndpointAuthParam: - description: Client-secret updates that preserve the credential's OAuth authentication method. - discriminator: - propertyName: type - mapping: - client_secret_basic: '#/components/schemas/RotateMcpOauthTokenEndpointAuthParamClientSecretBasic' - client_secret_post: '#/components/schemas/RotateMcpOauthTokenEndpointAuthParamClientSecretPost' - x-oai-discriminator-values: - - client_secret_basic - - client_secret_post - anyOf: - - $ref: '#/components/schemas/RotateMcpOauthTokenEndpointAuthParamClientSecretBasic' - - $ref: '#/components/schemas/RotateMcpOauthTokenEndpointAuthParamClientSecretPost' - RotateMcpOauthRefreshParam: - type: object - properties: - refresh_token: - type: - - string - - 'null' - minLength: 0 - maxLength: 1048576 - description: The replacement refresh token. Omit or pass `null` to keep the stored token. This secret is never returned in resources. - scope: - type: - - string - - 'null' - minLength: 0 - maxLength: 1048576 - description: Replacement space-separated OAuth scopes for refresh requests. Omit to keep the scopes, or pass `null` to stop sending a scope parameter. - token_endpoint_auth: - anyOf: - - $ref: '#/components/schemas/RotateMcpOauthTokenEndpointAuthParam' - - type: 'null' - description: Client-secret updates for the existing token endpoint authentication method. - additionalProperties: false - description: Updates to an MCP credential's existing OAuth refresh configuration. - RotateVaultCredentialAuthParamMcpOauth: + description: Opens a web page. + WebSearchActionResourceFindInPage: type: object properties: type: type: string enum: - - mcp_oauth - default: mcp_oauth + - find_in_page + default: find_in_page x-stainless-const: true - description: The type of the object. Always `mcp_oauth`. - access_token: + description: The type of the object. Always `find_in_page`. + url: type: - string - 'null' minLength: 0 - maxLength: 1048576 - description: A write-only replacement OAuth access token. - expires_at: + description: The URL of the page that was searched. + pattern: type: - string - 'null' minLength: 0 - maxLength: 1048576 - description: The replacement expiry as an RFC 3339 timestamp, or `null` to clear it. Omitting this field preserves the expiry unless a new access token is supplied, in which case the expiry is cleared. - refresh: - anyOf: - - $ref: '#/components/schemas/RotateMcpOauthRefreshParam' - - type: 'null' - description: Optional write-only refresh-token and client-secret updates. + description: The text pattern that was searched for. required: - type + - url + - pattern additionalProperties: false - description: Rotate an OAuth credential for an HTTPS MCP destination. - RotateVaultCredentialAuthParamStaticBearer: + description: Finds text within a web page. + WebSearchActionResourceOther: type: object properties: type: type: string enum: - - static_bearer - default: static_bearer + - other + default: other x-stainless-const: true - description: The type of the object. Always `static_bearer`. - token: - type: string - minLength: 0 - maxLength: 1048576 - description: The replacement bearer token. This secret is never returned in credential resources. + description: The type of the object. Always `other`. required: - type - - token additionalProperties: false - description: Replace the bearer token for the credential's MCP server. - RotateVaultCredentialAuthParam: - description: Updates to a vault credential without changing its authentication method or MCP server. + description: Another web search action. + WebSearchActionResource: + description: An action performed by the web search tool. discriminator: propertyName: type mapping: - mcp_oauth: '#/components/schemas/RotateVaultCredentialAuthParamMcpOauth' - static_bearer: '#/components/schemas/RotateVaultCredentialAuthParamStaticBearer' + search: '#/components/schemas/WebSearchActionResourceSearch' + open_page: '#/components/schemas/WebSearchActionResourceOpenPage' + find_in_page: '#/components/schemas/WebSearchActionResourceFindInPage' + other: '#/components/schemas/WebSearchActionResourceOther' x-oai-discriminator-values: - - mcp_oauth - - static_bearer + - search + - open_page + - find_in_page + - other anyOf: - - $ref: '#/components/schemas/RotateVaultCredentialAuthParamMcpOauth' - - $ref: '#/components/schemas/RotateVaultCredentialAuthParamStaticBearer' - RotateVaultCredentialParams: - type: object - properties: - auth: - $ref: '#/components/schemas/RotateVaultCredentialAuthParam' - description: Replacement values for the credential's existing authentication method. - required: - - auth - additionalProperties: false - description: Secret, expiry, and OAuth refresh scope updates for an existing vault credential. - DeletedVaultCredentialResource: + - $ref: '#/components/schemas/WebSearchActionResourceSearch' + - $ref: '#/components/schemas/WebSearchActionResourceOpenPage' + - $ref: '#/components/schemas/WebSearchActionResourceFindInPage' + - $ref: '#/components/schemas/WebSearchActionResourceOther' + WebSearchCallItemResource: type: object properties: - id: - type: string - minLength: 0 - description: The ID of the deleted credential. - object: + type: type: string enum: - - vault.credential.deleted - default: vault.credential.deleted + - web_search_call + default: web_search_call x-stainless-const: true - description: The object type. Always `vault.credential.deleted`. - deleted: - type: boolean - description: Whether the resource was deleted. Always `true`. - required: - - id - - object - - deleted - additionalProperties: false - description: Confirmation that a vault credential was deleted. - WebhookEndpointBody: - properties: + description: The item type. Always `web_search_call`. id: type: string - description: The unique ID of the webhook endpoint. - object: - type: string - enum: - - webhook_endpoint - description: The object type, which is always webhook_endpoint. - default: webhook_endpoint - x-stainless-const: true - created_at: - type: integer - format: unixtime - description: The Unix timestamp when the endpoint was created. - updated_at: - type: integer - format: unixtime - description: The Unix timestamp of the last endpoint configuration or signing-secret change. Initialized at creation; tests and unchanged updates do not advance it. - name: - type: string - description: The human-readable name of the endpoint. - url: + minLength: 0 + description: The ID of the web search call. + turn_id: type: string - description: The HTTPS URL that receives webhook deliveries. - event_types: - items: - type: string - type: array - description: The event types that trigger deliveries to this endpoint. - signing_secret_hint: + 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: - - type: string - description: A masked hint for the endpoint's signing secret. + - $ref: '#/components/schemas/WebSearchActionResource' - type: 'null' - type: object + description: The action performed by the web search tool. required: + - type - id - - object - - created_at - - name - - url - - event_types - - signing_secret_hint - WebhookEndpointListResource: - properties: - object: - type: string - enum: - - list - description: The object type, which is always list. - default: list - x-stainless-const: true - data: - items: - $ref: '#/components/schemas/WebhookEndpointBody' - type: array - description: The webhook endpoints in this page. - first_id: - anyOf: - - type: string - description: The ID of the first endpoint in this page. - - type: 'null' - last_id: - anyOf: - - type: string - description: The ID of the last endpoint in this page. - - type: 'null' - has_more: - type: boolean - description: Whether more webhook endpoints are available. - type: object - required: - - object - - data - - first_id - - last_id - - has_more - ProjectEventTypeEnum: - type: string - enum: - - batch.completed - - batch.failed - - batch.expired - - batch.cancelled - - response.completed - - response.failed - - response.cancelled - - response.incomplete - - eval.run.succeeded - - eval.run.failed - - eval.run.canceled - - fine_tuning.job.succeeded - - fine_tuning.job.failed - - fine_tuning.job.cancelled - - realtime.call.incoming - - video.completed - - video.failed - - safety.alert.created - PublicCreateEndpointBody: - properties: - name: - type: string - maxLength: 256 - minLength: 1 - description: A human-readable name for the webhook endpoint. - url: - type: string - maxLength: 2048 - pattern: ^https:// - description: The HTTPS URL that receives webhook deliveries. - event_types: - items: - $ref: '#/components/schemas/ProjectEventTypeEnum' - type: array - minItems: 1 - description: The event types that trigger deliveries to this endpoint. + - turn_id + - status + - action + additionalProperties: false + description: A web search call produced by the agent. + CommandExecutionItemResource: type: object - required: - - name - - url - - event_types - WebhookEndpointWithSecretResource: properties: - id: - type: string - description: The unique ID of the webhook endpoint. - object: + type: type: string enum: - - webhook_endpoint - description: The object type, which is always webhook_endpoint. - default: webhook_endpoint + - command_execution + default: command_execution x-stainless-const: true - created_at: - type: integer - format: unixtime - description: The Unix timestamp when the endpoint was created. - updated_at: - type: integer - format: unixtime - description: The Unix timestamp of the last endpoint configuration or signing-secret change. Initialized at creation; tests and unchanged updates do not advance it. - name: + description: The item type. Always `command_execution`. + id: type: string - description: The human-readable name of the endpoint. - url: + minLength: 0 + description: The ID of the command execution item. + turn_id: type: string - description: The HTTPS URL that receives webhook deliveries. - event_types: - items: - type: string - type: array - description: The event types that trigger deliveries to this endpoint. - signing_secret_hint: - anyOf: - - type: string - description: A masked hint for the endpoint's signing secret. - - type: 'null' - signing_secret: + minLength: 0 + description: The ID of the turn that contains this item. + command: type: string - description: The endpoint's signing secret. This is returned only when the endpoint is created or the secret is rotated. - type: object + 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 - - object - - created_at - - name - - url - - event_types - - signing_secret_hint - - signing_secret - PublicUpdateEndpointBody: - properties: - name: - type: string - maxLength: 256 - minLength: 1 - description: A new human-readable name for the webhook endpoint. - url: - type: string - maxLength: 2048 - pattern: ^https:// - description: A new HTTPS URL that receives webhook deliveries. - event_types: - items: - $ref: '#/components/schemas/ProjectEventTypeEnum' - type: array - minItems: 1 - description: The complete set of event types that should trigger deliveries. + - turn_id + - command + - cwd + - status + - output + - exit_code + - duration_ms + additionalProperties: false + description: A command execution produced by the agent. + InterruptSubagentCallItemResource: type: object - required: [] - DeletedWebhookEndpointResource: 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 - description: The ID of the deleted webhook endpoint. - object: + minLength: 0 + description: The ID of the tool call item. + turn_id: type: string - enum: - - webhook_endpoint.deleted - description: The object type, which is always webhook_endpoint.deleted. - default: webhook_endpoint.deleted - x-stainless-const: true - deleted: - type: boolean - description: Whether the endpoint was deleted. - type: object + 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 - - object - - deleted - PublicRotateSecretBody: - properties: - keep_old_secret_active_for_24_hours: - type: boolean - description: Whether to keep the previous signing secret valid for 24 hours after rotation. Defaults to false, which invalidates the previous secret immediately. - type: object - required: [] - PublicTestEndpointBody: - properties: - event_type: - $ref: '#/components/schemas/ProjectEventTypeEnum' - description: The event type to send as a sample delivery. + - 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. + CreateSubagentCallItemResource: type: object - required: - - event_type - WebhookEndpointTestResultResource: properties: - object: + type: type: string enum: - - webhook_endpoint.test - description: The object type, which is always webhook_endpoint.test. - default: webhook_endpoint.test + - create_subagent_call + default: create_subagent_call x-stainless-const: true - webhook_endpoint_id: + x-enumDescriptions: + - The current public item type. + description: The item type. Always `create_subagent_call`. + id: type: string - description: The ID of the webhook endpoint that received the test. - event_type: + minLength: 0 + description: The ID of the tool call item. + turn_id: type: string - description: The event type sent in the test. - status_code: - type: integer - description: The HTTP status code returned by the endpoint. - success: - type: boolean - enum: - - true - description: Whether the test request completed. Always true for returned results; use status_code to determine the endpoint response. - default: true - x-stainless-const: true - type: object - required: - - object - - webhook_endpoint_id - - event_type - - status_code - - success - WebhookEventTypeListResource: - properties: - object: + 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 - enum: - - list - description: The object type, which is always list. - default: list - x-stainless-const: true - data: - items: - type: string + minLength: 0 + description: The ID of the agent that requested the subagent. + content: type: array - description: The webhook event types available to the authenticated project. - type: object - required: - - object - - data - DragPoint: - properties: - x: - type: integer - description: The x-coordinate. - y: - type: integer - description: The y-coordinate. - type: object + 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: - - x - - y - title: Coordinate - description: 'An x/y coordinate pair, e.g. `{ x: 100, y: 200 }`.' - LiveSessionAudioFormatPCMParam: - description: Raw, mono 16-bit little-endian PCM audio for a Live WebSocket connection. + - type + - id + - turn_id + - status + - agent_id + - content + - model + - reasoning_effort + additionalProperties: false + description: A request to spawn a subagent. + SendSubagentInputCallItemResource: type: object properties: type: - description: The audio encoding. Always `audio/pcm`. - default: audio/pcm - x-stainless-const: true type: string enum: - - audio/pcm - rate: - description: Audio sample rate in hertz. Live WebSocket PCM audio supports 16000 or 24000 Hz. - type: integer - minimum: 16000 - maximum: 24000 - enum: - - 16000 - - 24000 + - 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 - - rate - LiveSessionAudioFormatPCMUParam: - description: Raw, mono G.711 μ-law audio for a Live WebSocket connection. + - id + - turn_id + - status + - sender_agent_id + - recipient_agent_id + - content + additionalProperties: false + description: A request to send input to another agent. + ResumeSubagentCallItemResource: type: object properties: type: - description: The audio encoding. Always `audio/pcmu`. - default: audio/pcmu - x-stainless-const: true type: string enum: - - audio/pcmu - rate: - description: Audio sample rate in hertz. G.711 audio uses 8000 Hz. - type: integer - minimum: 8000 - maximum: 8000 + - 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 - - rate - LiveSessionAudioFormatPCMAParam: - description: Raw, mono G.711 A-law audio for a Live WebSocket connection. + - id + - turn_id + - status + - sender_agent_id + - recipient_agent_id + additionalProperties: false + description: A request to resume a subagent. + WaitForSubagentsCallItemResource: type: object properties: type: - description: The audio encoding. Always `audio/pcma`. - default: audio/pcma - x-stainless-const: true type: string enum: - - audio/pcma - rate: - description: Audio sample rate in hertz. G.711 audio uses 8000 Hz. - type: integer - minimum: 8000 - maximum: 8000 - required: - - type - - rate - LiveAudioFormat: - description: Audio encoding and sample rate for audio sent and received over a Live WebSocket connection. WebRTC and SIP negotiate their media format separately. - discriminator: - propertyName: type - anyOf: - - $ref: '#/components/schemas/LiveSessionAudioFormatPCMParam' - - $ref: '#/components/schemas/LiveSessionAudioFormatPCMUParam' - - $ref: '#/components/schemas/LiveSessionAudioFormatPCMAParam' - LiveInitialSessionAudioParam: - description: Startup audio configuration. Only primary WebSockets accept audio.format; WebRTC and SIP negotiate their media format. Voice and format are immutable after startup. - type: object - properties: - format: - description: Audio encoding and sample rate for audio sent and received over a Live WebSocket connection. WebRTC and SIP negotiate their media format separately. - $ref: '#/components/schemas/LiveAudioFormat' - output: - description: The voice used for speech generated by the Live model. - $ref: '#/components/schemas/LiveInitialSessionAudioOutputParam' - required: [] - LiveSessionCreateParams: - description: Initial configuration for a Live session, including its model, conversation instructions, audio, and delegated task handling. - type: object - properties: - model: - $ref: '#/components/schemas/ModelIdsLive' - instructions: - anyOf: - - description: Frontend instructions for voice, conversation, interruptions, and when to delegate. Start with the [Live prompting guide](https://developers.openai.com/api/docs/guides/live-prompting); put business rules and tool workflows in a separate [backend prompt](https://developers.openai.com/api/docs/guides/live-delegation#start-with-your-existing-backend-prompt). Limited to 16,384 client-supplied tokens. Omitted or blank instructions use server defaults. Immutable after startup. - type: string - - type: 'null' - input: - description: Ordered text-only history supplied before startup. Supports developer, user, and assistant messages with one text part each; at most 128 messages and 8,192 rendered tokens in total. + - 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: - $ref: '#/components/schemas/LiveInitialItem' - maxItems: 128 - audio: - description: Startup audio configuration. Only primary WebSockets accept audio.format; WebRTC and SIP negotiate their media format. Voice and format are immutable after startup. - $ref: '#/components/schemas/LiveInitialSessionAudioParam' - delegation: - anyOf: - - description: Who handles tasks delegated by the Live model. Omitted or null selects your application; use `responses` to let the API manage a Responses backend. - discriminator: - propertyName: type - anyOf: - - $ref: '#/components/schemas/LiveClientDelegationParam' - - $ref: '#/components/schemas/LiveResponsesDelegationParam' - - type: 'null' - store: - description: Whether to store the session for later forking and recording download. Defaults to false for new sessions. - type: boolean - client: - description: Startup-only capabilities for an untrusted frontend attached to a unified WebRTC session. Trusted sideband connections are unaffected. - $ref: '#/components/schemas/LiveClientConfigParam' + type: string + minLength: 0 + minItems: 0 + maxItems: 2000 + description: The IDs of the agents to wait for. required: - - model - LiveSessionStartEvent: - description: Start a Live session on a primary WebSocket. Send this event before other commands and wait for `session.started`. - example: - type: session.start - event_id: evt_start_001 - session: - model: gpt-live-1 - instructions: Help the caller plan a restaurant reservation. Confirm details before booking. - audio: - format: - type: audio/pcm - rate: 24000 - output: - voice: marin - delegation: - type: client + - type + - id + - turn_id + - status + - sender_agent_id + - recipient_agent_ids + additionalProperties: false + description: A request to wait for one or more subagents. + CloseSubagentCallItemResource: type: object properties: - event_id: - anyOf: - - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. - type: string - maxLength: 512 - - type: 'null' type: - description: The Live client event type. Always `session.start`. - default: session.start - x-stainless-const: true type: string enum: - - session.start - session: - description: Initial configuration for a primary WebSocket. Send session.start first and wait for session.started before application commands. WebRTC creation already starts the session; do not send this event again on its data channel. - $ref: '#/components/schemas/LiveSessionCreateParams' + - 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 - - session - x-oaiMeta: - example: - type: session.start - event_id: evt_start_001 - session: - model: gpt-live-1 - instructions: Help the caller plan a restaurant reservation. Confirm details before booking. - audio: - format: - type: audio/pcm - rate: 24000 - output: - voice: marin - delegation: - type: client - LiveSessionUpdateParams: - description: Changes to an active Live session. Only delegation backend settings can be updated after startup. - type: object - properties: - delegation: - anyOf: - - description: Delegation settings to update. The delegation type must match the current session; omitted settings retain their values. - discriminator: - propertyName: type - anyOf: - - $ref: '#/components/schemas/LiveClientDelegationParam' - - $ref: '#/components/schemas/LiveResponsesDelegationUpdateParam' - - type: 'null' - required: [] - LiveSessionUpdateParam: - description: Update the delegation settings of an active Live session. The server acknowledges accepted changes with `session.updated`. - example: - type: session.update - event_id: evt_update_001 - session: - delegation: - type: responses - responses: - instructions: Check restaurant availability. Ask before confirming a booking. - max_output_tokens: 1024 + - id + - turn_id + - status + - sender_agent_id + - recipient_agent_id + additionalProperties: false + description: A request to close a subagent. + SessionTurnItemResource: + description: An item associated with a session turn. + 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 + anyOf: + - $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' + SessionItemListResource: type: object properties: - event_id: - anyOf: - - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. - type: string - maxLength: 512 - - type: 'null' - type: - description: The Live client event type. Always `session.update`. - default: session.update - x-stainless-const: true + object: type: string enum: - - session.update - session: - description: Sparse delegation updates. Omitted settings retain their values. The delegation type cannot change, including resetting Responses delegation to null or client. Model, frontend instructions, audio, and startup input are immutable. - $ref: '#/components/schemas/LiveSessionUpdateParams' + - 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: - - type - - session - x-oaiMeta: - example: - type: session.update - event_id: evt_update_001 - session: - delegation: - type: responses - responses: - instructions: Check restaurant availability. Ask before confirming a booking. - max_output_tokens: 1024 - LiveInputAudioAppendEvent: - description: Send audio to a Live session over its primary WebSocket. WebRTC and SIP sessions send audio over their media transport. - example: - type: session.input_audio.append - audio: AACAAIAAAIAAAP9/AIAAgA== + - 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. + TurnObjectResource: + type: string + enum: + - agent.session.turn + default: agent.session.turn + x-stainless-const: true + description: The object type for a turn. + 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. + 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. + SessionTurnErrorResource: type: object properties: - event_id: - anyOf: - - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. - type: string - maxLength: 512 - - type: 'null' - type: - description: The Live client event type. Always `session.input_audio.append`. - default: session.input_audio.append - x-stainless-const: true - type: string - enum: - - session.input_audio.append - audio: - description: Base64-encoded raw audio in the startup-selected format, without a WAV or other container header. Primary WebSocket only; media transports use their audio track. Audio appends have no acknowledgment. Reflected sideband server events reuse this event type and audio key, with no timestamps or event_id; their audio is always mono PCM16LE at 24 kHz. + code: + $ref: '#/components/schemas/SessionTurnErrorCodeResource' + description: A stable, machine-readable failure category. + message: type: string - minLength: 1 + minLength: 0 + description: A customer-safe explanation of the failure. required: - - type - - audio - x-oaiMeta: - example: - type: session.input_audio.append - audio: AACAAIAAAIAAAP9/AIAAgA== - LiveInputAudioMuteParam: - description: Mute audio input to the Live model without closing the session. The server acknowledges with `session.input_audio.muted`. - example: - type: session.input_audio.mute - event_id: evt_mute_001 + - code + - message + additionalProperties: false + description: A customer-safe error describing why a session request failed. + InputTokensDetailsResource: type: object properties: - event_id: - anyOf: - - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. - type: string - maxLength: 512 - - type: 'null' - type: - description: The Live client event type. Always `session.input_audio.mute`. - default: session.input_audio.mute - x-stainless-const: true - type: string - enum: - - session.input_audio.mute + cached_tokens: + type: integer + format: int64 + description: The number of input tokens retrieved from the prompt cache. required: - - type - x-oaiMeta: - example: - type: session.input_audio.mute - event_id: evt_mute_001 - LiveInputAudioUnmuteParam: - description: Resume audio input to a Live model after muting it. The server acknowledges with `session.input_audio.unmuted`. - example: - type: session.input_audio.unmute - event_id: evt_unmute_001 + - cached_tokens + additionalProperties: false + description: A breakdown of input token usage for a session or turn. + OutputTokensDetailsResource: type: object properties: - event_id: - anyOf: - - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. - type: string - maxLength: 512 - - type: 'null' - type: - description: The Live client event type. Always `session.input_audio.unmute`. - default: session.input_audio.unmute - x-stainless-const: true - type: string - enum: - - session.input_audio.unmute + reasoning_tokens: + type: integer + format: int64 + description: The number of output tokens used for reasoning. required: - - type - x-oaiMeta: - example: - type: session.input_audio.unmute - event_id: evt_unmute_001 - LiveInstructionsAppendParam: - description: Append instructions to the Live conversation while it is running, optionally associating them with an existing client delegation. - example: - type: session.instructions.append - event_id: evt_instructions_001 - delegation_id: null - content: The caller prefers outdoor seating. + - reasoning_tokens + additionalProperties: false + description: A breakdown of output token usage for a session or turn. + TokenUsageResource: type: object properties: - event_id: - anyOf: - - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. - type: string - maxLength: 512 - - type: 'null' - type: - description: The Live client event type. Always `session.instructions.append`. - default: session.instructions.append - x-stainless-const: true - type: string - enum: - - session.instructions.append - delegation_id: - anyOf: - - description: Required, nullable. Set null for general session context, or use the ID from session.delegation.created for an existing client delegation. Non-null IDs are not accepted with Responses delegation. - type: string - minLength: 1 - - type: 'null' - content: - description: Instruction text to append, limited to 500 tokens. This is a plain string, not an array of content parts. - type: string + 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: - - type - - delegation_id - - content - x-oaiMeta: - example: - type: session.instructions.append - event_id: evt_instructions_001 - delegation_id: null - content: The caller prefers outdoor seating. - LiveThinkingAppendParam: - description: Provide silent reasoning or progress context to the Live model, optionally for an existing client delegation. - example: - type: session.thinking.append - event_id: evt_thinking_001 - delegation_id: del_abc123 - content: Checking availability for two guests at 7 PM. + - 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. + TurnResource: type: object properties: - event_id: - anyOf: - - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. - type: string - maxLength: 512 - - type: 'null' - type: - description: The Live client event type. Always `session.thinking.append`. - default: session.thinking.append - x-stainless-const: true + id: type: string - enum: - - session.thinking.append - delegation_id: - anyOf: - - description: Required, nullable. Set null for general session context, or use the ID from session.delegation.created for an existing client delegation. Non-null IDs are not accepted with Responses delegation. - type: string - minLength: 1 - - type: 'null' - content: - description: Silent reasoning or progress context, limited to 500 tokens. It does not directly request speech, but can influence later speech and is not a secrecy boundary. + 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 - required: - - type - - delegation_id - - content - x-oaiMeta: - example: - type: session.thinking.append - event_id: evt_thinking_001 - delegation_id: del_abc123 - content: Checking availability for two guests at 7 PM. - LiveCommentaryAppendParam: - description: Provide context the Live model can communicate to the user, optionally for an existing client delegation. - example: - type: session.commentary.append - event_id: evt_commentary_001 - delegation_id: del_abc123 - content: There is an outdoor table for two at 7 PM. Ask whether to reserve it. - type: object - properties: - event_id: + 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: - - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. - type: string - maxLength: 512 + - $ref: '#/components/schemas/SessionTurnErrorResource' - type: 'null' - type: - description: The Live client event type. Always `session.commentary.append`. - default: session.commentary.append - x-stainless-const: true - type: string - enum: - - session.commentary.append - delegation_id: + description: A customer-safe error. Non-null only for a failed turn. + usage: anyOf: - - description: Required, nullable. Set null for general session context, or use the ID from session.delegation.created for an existing client delegation. Non-null IDs are not accepted with Responses delegation. - type: string - minLength: 1 + - $ref: '#/components/schemas/TokenUsageResource' - type: 'null' - content: - description: Speakable context for the Live model, limited to 500 tokens. Use this for a result the model should communicate; use session.thinking.append for silent context. - type: string + description: Best-effort token usage for the turn, or null if unknown. Recorded usage may change. required: - - type - - delegation_id - - content - x-oaiMeta: - example: - type: session.commentary.append - event_id: evt_commentary_001 - delegation_id: del_abc123 - content: There is an outdoor table for two at 7 PM. Ask whether to reserve it. - LiveResponseItemCreateParam: - description: Add an input item to the Live session’s Responses backend. Requires Responses delegation; use `response.create` to request a response. - example: - type: response.item.create - event_id: evt_item_001 - item: - type: message - role: user - content: - - type: input_text - text: Please check for a table for two at 7 PM. + - 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. + SessionTurnListResource: type: object properties: - event_id: - anyOf: - - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. - type: string - maxLength: 512 - - type: 'null' - type: - description: The Live client event type. Always `response.item.create`. - default: response.item.create - x-stainless-const: true + object: type: string enum: - - response.item.create - item: - description: An input item to append to the Responses backend conversation, such as a user message or a function tool result. - $ref: '#/components/schemas/InputItem' + - 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: - - type - - item - x-oaiMeta: - example: - type: response.item.create - event_id: evt_item_001 - item: - type: message - role: user - content: - - type: input_text - text: Please check for a table for two at 7 PM. - LiveResponseCreateParam: - description: Request a response from the Live session’s Responses backend, or continue a delegated response waiting for tool results. Requires Responses delegation. - example: - type: response.create - event_id: evt_response_001 + - object + - data + - first_id + - last_id + - has_more + additionalProperties: false + description: A page of Agents API resources, with IDs for retrieving additional pages. + ReasoningEffortResource: + type: string + enum: + - none + - minimal + - low + - medium + - high + - xhigh + - max + description: The amount of reasoning effort used by an agent. + 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. + ReasoningResource: type: object properties: - event_id: + effort: anyOf: - - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. - type: string - maxLength: 512 + - $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. + TextFormatResourceText: + type: object + properties: type: - description: The Live client event type. Always `response.create`. - default: response.create - x-stainless-const: true type: string enum: - - response.create + - text + default: text + x-stainless-const: true + description: The type of the object. Always `text`. required: - type - x-oaiMeta: - example: - type: response.create - event_id: evt_response_001 - LiveSessionCloseParam: - description: Request that the Live session close. The terminal `session.closed` event contains the close reason and final usage. - example: - type: session.close - event_id: evt_close_001 + additionalProperties: false + description: Generates ordinary text without a structured-output constraint. + TextFormatResourceJsonSchema: type: object properties: - event_id: - anyOf: - - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. - type: string - maxLength: 512 - - type: 'null' type: - description: The Live client event type. Always `session.close`. - default: session.close - x-stainless-const: true type: string enum: - - session.close + - 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 - x-oaiMeta: - example: - type: session.close - event_id: evt_close_001 - LiveForkAudioParam: - description: Audio format for the new WebSocket connection to a forked Live session. The stored voice is preserved. + - schema + additionalProperties: false + description: Constrains generated text to a JSON Schema. + TextFormatResource: + description: The effective output format for generated text. + discriminator: + propertyName: type + mapping: + text: '#/components/schemas/TextFormatResourceText' + json_schema: '#/components/schemas/TextFormatResourceJsonSchema' + x-oai-discriminator-values: + - text + - json_schema + anyOf: + - $ref: '#/components/schemas/TextFormatResourceText' + - $ref: '#/components/schemas/TextFormatResourceJsonSchema' + VerbosityResource: + type: string + enum: + - low + - medium + - high + description: The amount of text produced by an agent. + TextResource: type: object properties: format: - description: Audio encoding and sample rate for audio sent and received over a Live WebSocket connection. WebRTC and SIP negotiate their media format separately. - $ref: '#/components/schemas/LiveAudioFormat' - required: [] - LiveForkSessionConfigParam: - description: Overrides for a stored session after connecting to the fork WebSocket. An empty object inherits the stored configuration; do not supply a new model. audio.format applies only to the new WebSocket connection. client overrides are only supported for WebRTC forks. + $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. + ServiceTierResource: + type: string + enum: + - auto + - default + - flex + - priority + - fast + description: The service-tier policy configured for an agent. + PersistedAgentToolResourceFunction: type: object properties: - audio: - description: Audio format for a WebSocket fork. WebRTC forks negotiate their audio format and must omit this field. - $ref: '#/components/schemas/LiveForkAudioParam' - delegation: - description: Overrides for the stored session’s Responses backend. Only supported when the stored session already uses Responses delegation; the delegation type cannot change. - $ref: '#/components/schemas/LiveResponsesDelegationUpdateParam' - store: - description: Whether to store the forked session. Omission inherits the stored session's setting. + 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 - client: - description: Frontend data-channel permissions for a WebRTC fork. Omitted permissions inherit the stored values. Not supported for WebSocket forks. - $ref: '#/components/schemas/LiveClientConfigParam' - required: [] - LiveForkSessionStartEvent: - description: Start a Live session after connecting to a stored session’s fork WebSocket. Send an empty `session` object to use the stored configuration. - example: - type: session.start - session: {} + 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. + PersistedAgentToolResourceToolSearch: type: object properties: - event_id: - anyOf: - - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. - type: string - maxLength: 512 - - type: 'null' type: - description: The Live client event type. Always `session.start`. - default: session.start - x-stainless-const: true type: string enum: - - session.start - session: - description: Overrides for a stored session after connecting to the fork WebSocket. An empty object inherits the stored configuration; do not supply a new model. audio.format applies only to the new WebSocket connection. client overrides are only supported for WebRTC forks. - $ref: '#/components/schemas/LiveForkSessionConfigParam' + - tool_search + default: tool_search + x-stainless-const: true + description: The type of the object. Always `tool_search`. required: - type - - session - x-oaiMeta: - example: - type: session.start - session: {} - LiveSessionResourceParam: - description: The resolved Live session configuration and server-assigned session metadata. + additionalProperties: false + description: Discovers deferred function tools and loads them into the model context. + PersistedAgentToolResourceProgrammaticToolCalling: type: object properties: - model: - $ref: '#/components/schemas/ModelIdsLive' - instructions: - anyOf: - - description: Frontend instructions for voice, conversation, interruptions, and when to delegate. Start with the [Live prompting guide](https://developers.openai.com/api/docs/guides/live-prompting); put business rules and tool workflows in a separate [backend prompt](https://developers.openai.com/api/docs/guides/live-delegation#start-with-your-existing-backend-prompt). Limited to 16,384 client-supplied tokens. Omitted or blank instructions use server defaults. Immutable after startup. - type: string - - type: 'null' - input: - description: Ordered text-only history supplied before startup. Supports developer, user, and assistant messages with one text part each; at most 128 messages and 8,192 rendered tokens in total. - type: array - items: - $ref: '#/components/schemas/LiveInitialItem' - maxItems: 128 - audio: - description: Startup audio configuration. Only primary WebSockets accept audio.format; WebRTC and SIP negotiate their media format. Voice and format are immutable after startup. - $ref: '#/components/schemas/LiveInitialSessionAudioParam' - delegation: - anyOf: - - description: Who handles tasks delegated by the Live model. Omitted or null selects your application; use `responses` to let the API manage a Responses backend. - discriminator: - propertyName: type - anyOf: - - $ref: '#/components/schemas/LiveClientDelegationParam' - - $ref: '#/components/schemas/LiveResponsesDelegationParam' - - type: 'null' - store: - description: Whether to store the session for later forking and recording download. Defaults to false for new sessions. - type: boolean - client: - description: Startup-only capabilities for an untrusted frontend attached to a unified WebRTC session. Trusted sideband connections are unaffected. - $ref: '#/components/schemas/LiveClientConfigParam' - id: - description: The unique ID of the Live session. Use this ID for sideband connections, forking, and recording download. + type: type: string - expires_at: - description: The Unix timestamp, in seconds, at which the Live session expires. - type: integer - status: - description: The status of the session snapshot. Always `active`, including the final snapshot in session.closed; use the event type to determine that the session has closed. - default: active + 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. + PersistedMcpTransportResourceHttp: + type: object + properties: + type: type: string enum: - - active + - 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: - - model - - id - - expires_at - - status - LiveSessionStarted: - description: Returned when a Live session has started. Contains the resolved session configuration, including server defaults. - example: - type: session.started - event_id: evt_started_001 - client_event_id: evt_start_001 - session: - id: live_abc123 - model: gpt-live-1 - status: active - expires_at: 1788555600 - instructions: Help the caller plan a restaurant reservation. Confirm details before booking. - input: [] - audio: - format: - type: audio/pcm - rate: 24000 - output: - voice: marin - delegation: - type: client + - type + - server_url + - headers + additionalProperties: false + description: Connects to an MCP server over HTTP. + PersistedMcpTransportResourceStdio: type: object properties: type: - description: The event type, always `session.started`. - default: session.started - x-stainless-const: true type: string enum: - - session.started - event_id: - description: The unique ID of the Live server event. + - stdio + default: stdio + x-stainless-const: true + description: The type of the object. Always `stdio`. + command: type: string - client_event_id: - description: The event_id of the client command associated with this server event, when supplied. + 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 - session: - $ref: '#/components/schemas/LiveSessionResourceParam' + 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 - - event_id - - session - x-oaiMeta: - example: - type: session.started - event_id: evt_started_001 - client_event_id: evt_start_001 - session: - id: live_abc123 - model: gpt-live-1 - status: active - expires_at: 1788555600 - instructions: Help the caller plan a restaurant reservation. Confirm details before booking. - input: [] - audio: - format: - type: audio/pcm - rate: 24000 - output: - voice: marin - delegation: - type: client - LiveSessionUpdated: - description: Returned when a Live session update is accepted. Contains the resolved session configuration after the update. - example: - type: session.updated - event_id: evt_updated_001 - client_event_id: evt_update_001 - session: - id: live_def456 - model: gpt-live-1 - status: active - expires_at: 1788555600 - instructions: Help the caller plan a restaurant reservation. Confirm details before booking. - input: [] - audio: - format: - type: audio/pcm - rate: 24000 - output: - voice: marin - delegation: - type: responses - responses: - model: gpt-6-astra - instructions: Check restaurant availability. Ask before confirming a booking. - max_output_tokens: 1024 - tools: [] + - command + - args + - cwd + - env_vars + additionalProperties: false + description: Starts an MCP server as a local process. + PersistedMcpTransportResource: + description: A credential-free transport used to connect to an MCP server. + discriminator: + propertyName: type + mapping: + http: '#/components/schemas/PersistedMcpTransportResourceHttp' + stdio: '#/components/schemas/PersistedMcpTransportResourceStdio' + x-oai-discriminator-values: + - http + - stdio + anyOf: + - $ref: '#/components/schemas/PersistedMcpTransportResourceHttp' + - $ref: '#/components/schemas/PersistedMcpTransportResourceStdio' + McpConnectionOriginResource: + type: string + enum: + - service + - environment + description: Where outbound MCP HTTP connections originate. + PersistedAgentToolResourceMcp: type: object properties: type: - description: The event type, always `session.updated`. - default: session.updated - x-stainless-const: true type: string enum: - - session.updated - event_id: - description: The unique ID of the Live server event. - type: string - client_event_id: - description: The event_id of the client command associated with this server event, when supplied. + - mcp + default: mcp + x-stainless-const: true + description: The type of the object. Always `mcp`. + server_label: type: string - session: - $ref: '#/components/schemas/LiveSessionResourceParam' + 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. + WebSearchModeResource: + type: string + enum: + - disabled + - cached + - live + description: The source used for web search results. + WebSearchContextSizeResource: + type: string + enum: + - low + - medium + - high + description: The amount of web search context made available to the model. + 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: - - type - - event_id - - session - x-oaiMeta: - example: - type: session.updated - event_id: evt_updated_001 - client_event_id: evt_update_001 - session: - id: live_def456 - model: gpt-live-1 - status: active - expires_at: 1788555600 - instructions: Help the caller plan a restaurant reservation. Confirm details before booking. - input: [] - audio: - format: - type: audio/pcm - rate: 24000 - output: - voice: marin - delegation: - type: responses - responses: - model: gpt-6-astra - instructions: Check restaurant availability. Ask before confirming a booking. - max_output_tokens: 1024 - tools: [] - LiveInputAudioMuted: - description: Returned when a session.input_audio.mute command is accepted. Input audio is no longer sent to the model; sideband audio reflection continues. - example: - type: session.input_audio.muted - event_id: evt_muted_001 - client_event_id: evt_mute_001 + - country + - region + - city + - timezone + additionalProperties: false + description: Approximate user location used to localize web search results. + PersistedAgentToolResourceWebSearch: type: object properties: - event_id: - description: The unique ID of the Live server event. - type: string - client_event_id: - description: The event_id of the client command associated with this server event, when supplied. - type: string type: - description: The event type, always `session.input_audio.muted`. - default: session.input_audio.muted - x-stainless-const: true type: string enum: - - session.input_audio.muted + - 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: - - event_id - type - x-oaiMeta: - example: - type: session.input_audio.muted - event_id: evt_muted_001 - client_event_id: evt_mute_001 - LiveInputAudioUnmuted: - description: Returned when a session.input_audio.unmute command is accepted. Input audio is sent to the model again. - example: - type: session.input_audio.unmuted - event_id: evt_unmuted_001 - client_event_id: evt_unmute_001 + - mode + - context_size + - allowed_domains + - location + additionalProperties: false + description: Web search. + PersistedAgentToolResource: + description: A credential-free tool available to a reusable agent. + 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 + anyOf: + - $ref: '#/components/schemas/PersistedAgentToolResourceFunction' + - $ref: '#/components/schemas/PersistedAgentToolResourceToolSearch' + - $ref: '#/components/schemas/PersistedAgentToolResourceProgrammaticToolCalling' + - $ref: '#/components/schemas/PersistedAgentToolResourceMcp' + - $ref: '#/components/schemas/PersistedAgentToolResourceWebSearch' + MultiAgentConfigResource: type: object properties: - event_id: - description: The unique ID of the Live server event. - type: string - client_event_id: - description: The event_id of the client command associated with this server event, when supplied. - type: string - type: - description: The event type, always `session.input_audio.unmuted`. - default: session.input_audio.unmuted - x-stainless-const: true - type: string - enum: - - session.input_audio.unmuted + 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: - - event_id - - type - x-oaiMeta: - example: - type: session.input_audio.unmuted - event_id: evt_unmuted_001 - client_event_id: evt_unmute_001 - LiveInstructionsAppended: - description: Returned when a session.instructions.append command is accepted into the Live session timeline. Acknowledges the appended instructions without guaranteeing that the model has acted on them. - example: - type: session.instructions.appended - event_id: evt_instructions_002 - client_event_id: evt_instructions_001 - start_ms: 1200 - end_ms: 1400 + - enabled + - max_concurrent_subagents + additionalProperties: false + description: The resolved configuration for creating and coordinating subagents. + AgentResource: type: object properties: - event_id: - description: The unique ID of the Live server event. + id: type: string - client_event_id: - description: The event_id of the client command associated with this server event, when supplied. + minLength: 0 + description: The ID of the reusable agent. + object: type: string - start_ms: - description: The start of this event on the Live session timeline, in milliseconds from the beginning of the session. + enum: + - agent + default: agent + x-stainless-const: true + description: The object type. Always `agent`. + created_at: type: integer - end_ms: - description: The end of this event on the Live session timeline, in milliseconds from the beginning of the session. For appended context, this can equal start_ms. + format: int64 + description: The Unix timestamp, in seconds, when the agent was created. + updated_at: type: integer - type: - description: The event type, always `session.instructions.appended`. - default: session.instructions.appended - x-stainless-const: true + 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 - enum: - - session.instructions.appended + 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: - - event_id - - start_ms - - end_ms - - type - x-oaiMeta: - example: - type: session.instructions.appended - event_id: evt_instructions_002 - client_event_id: evt_instructions_001 - start_ms: 1200 - end_ms: 1400 - LiveThinkingAppended: - description: Returned when a session.thinking.append command is accepted into the Live session timeline. Acknowledges the added reasoning context without guaranteeing any spoken output. - example: - type: session.thinking.appended - event_id: evt_thinking_002 - client_event_id: evt_thinking_001 - start_ms: 4600 - end_ms: 4800 + - 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. + AgentListResource: type: object properties: - event_id: - description: The unique ID of the Live server event. - type: string - client_event_id: - description: The event_id of the client command associated with this server event, when supplied. - type: string - start_ms: - description: The start of this event on the Live session timeline, in milliseconds from the beginning of the session. - type: integer - end_ms: - description: The end of this event on the Live session timeline, in milliseconds from the beginning of the session. For appended context, this can equal start_ms. - type: integer - type: - description: The event type, always `session.thinking.appended`. - default: session.thinking.appended - x-stainless-const: true + object: type: string enum: - - session.thinking.appended + - 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: - - event_id - - start_ms - - end_ms - - type - x-oaiMeta: - example: - type: session.thinking.appended - event_id: evt_thinking_002 - client_event_id: evt_thinking_001 - start_ms: 4600 - end_ms: 4800 - LiveCommentaryAppended: - description: Returned when a session.commentary.append command is accepted into the Live session timeline. Acknowledges the added commentary without guaranteeing exact wording or completed audio playback. - example: - type: session.commentary.appended - event_id: evt_commentary_002 - client_event_id: evt_commentary_001 - start_ms: 5200 - end_ms: 5400 + - object + - data + - first_id + - last_id + - has_more + additionalProperties: false + description: A page of Agents API resources, with IDs for retrieving additional pages. + ReasoningEffortParam: + type: string + enum: + - none + - minimal + - low + - medium + - high + - xhigh + - max + description: The amount of reasoning effort the model should use. + 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. + 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. + TextFormatParamText: type: object properties: - event_id: - description: The unique ID of the Live server event. - type: string - client_event_id: - description: The event_id of the client command associated with this server event, when supplied. - type: string - start_ms: - description: The start of this event on the Live session timeline, in milliseconds from the beginning of the session. - type: integer - end_ms: - description: The end of this event on the Live session timeline, in milliseconds from the beginning of the session. For appended context, this can equal start_ms. - type: integer type: - description: The event type, always `session.commentary.appended`. - default: session.commentary.appended - x-stainless-const: true type: string enum: - - session.commentary.appended + - text + default: text + x-stainless-const: true + description: The type of the object. Always `text`. required: - - event_id - - start_ms - - end_ms - type - x-oaiMeta: - example: - type: session.commentary.appended - event_id: evt_commentary_002 - client_event_id: evt_commentary_001 - start_ms: 5200 - end_ms: 5400 - LiveInputAudioAppend: - description: Input audio received from the primary transport and reflected to a Live sideband connection before model-input muting. - example: - type: session.input_audio.append - audio: AACAAIAAAIAAAP9/AIAAgA== + additionalProperties: false + description: Generates ordinary text without a structured-output constraint. + TextFormatParamJsonSchema: type: object properties: type: - description: The event type, always `session.input_audio.append`. - default: session.input_audio.append - x-stainless-const: true type: string enum: - - session.input_audio.append - audio: - description: Base64-encoded raw mono PCM16LE at 24 kHz received from the primary transport, reflected to the sideband before model-input muting. This server event uses the same audio key as the client command, but is not an acknowledgment of it. - type: string + - 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 - - audio - x-oaiMeta: - example: - type: session.input_audio.append - audio: AACAAIAAAIAAAP9/AIAAgA== - LiveOutputAudioDelta: - description: An audio chunk generated by the Live model. Decode and play primary WebSocket chunks in delivery order using the configured session audio format. Sideband connections receive reflected output audio with timestamps. - example: - type: session.output_audio.delta - delta: AACAAIAAAIAAAP9/AIAAgA== - start_ms: 1000 - end_ms: 1200 + - schema + additionalProperties: false + description: Constrains generated text to a JSON Schema. + TextFormatParam: + description: The output format for generated text. + discriminator: + propertyName: type + mapping: + text: '#/components/schemas/TextFormatParamText' + json_schema: '#/components/schemas/TextFormatParamJsonSchema' + x-oai-discriminator-values: + - text + - json_schema + anyOf: + - $ref: '#/components/schemas/TextFormatParamText' + - $ref: '#/components/schemas/TextFormatParamJsonSchema' + 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. + 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. + 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. + PersistedAgentToolConfigParamFunction: type: object properties: type: - description: The event type, always `session.output_audio.delta`. - default: session.output_audio.delta - x-stainless-const: true type: string enum: - - session.output_audio.delta - delta: - description: Base64-encoded raw audio. Primary WebSocket events use the session's configured format; reflected sideband events use mono PCM16LE at 24 kHz. + - function + default: function + x-stainless-const: true + description: The type of the object. Always `function`. + name: type: string - start_ms: - description: Inclusive session-relative start in milliseconds. Required on reflected sideband events; omitted on the primary WebSocket. - type: integer - end_ms: - description: Exclusive session-relative end in milliseconds. Required on reflected sideband events; omitted on the primary WebSocket. Dropped output frames leave gaps between reflected ranges. - type: integer + 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 - - delta - x-oaiMeta: - example: - type: session.output_audio.delta - delta: AACAAIAAAIAAAP9/AIAAgA== - start_ms: 1000 - end_ms: 1200 - LiveInputTranscriptDelta: - description: A transcript fragment for user input audio in the Live session. Accumulate fragments in delivery order; these events do not define complete turns or include a transcript-done event. - example: - type: session.input_transcript.delta - event_id: evt_input_transcript_001 - delta: A table for two at seven, please. - start_ms: 1600 - end_ms: 3400 + - name + - description + - parameters + additionalProperties: false + description: A function defined by the application. + PersistedAgentToolConfigParamToolSearch: type: object properties: - event_id: - description: The unique ID of the Live server event. - type: string - client_event_id: - description: The event_id of the client command associated with this server event, when supplied. - type: string - start_ms: - description: The start of this event on the Live session timeline, in milliseconds from the beginning of the session. - type: integer - end_ms: - description: The end of this event on the Live session timeline, in milliseconds from the beginning of the session. For appended context, this can equal start_ms. - type: integer - delta: - description: The transcript text fragment for the audio in this time range. Append fragments in delivery order to build the transcript. - type: string type: - description: The event type, always `session.input_transcript.delta`. - default: session.input_transcript.delta - x-stainless-const: true type: string enum: - - session.input_transcript.delta + - tool_search + default: tool_search + x-stainless-const: true + description: The type of the object. Always `tool_search`. required: - - event_id - - start_ms - - end_ms - - delta - type - x-oaiMeta: - example: - type: session.input_transcript.delta - event_id: evt_input_transcript_001 - delta: A table for two at seven, please. - start_ms: 1600 - end_ms: 3400 - LiveOutputTranscriptDelta: - description: A transcript fragment for assistant output audio in the Live session. Accumulate fragments in delivery order; these events do not define complete turns or include a transcript-done event. - example: - type: session.output_transcript.delta - event_id: evt_output_transcript_001 - delta: Would you like me to reserve that table? - start_ms: 5400 - end_ms: 7200 + additionalProperties: false + description: Discovers deferred function tools and loads them into the model context. + PersistedAgentToolConfigParamProgrammaticToolCalling: type: object properties: - event_id: - description: The unique ID of the Live server event. - type: string - client_event_id: - description: The event_id of the client command associated with this server event, when supplied. - type: string - start_ms: - description: The start of this event on the Live session timeline, in milliseconds from the beginning of the session. - type: integer - end_ms: - description: The end of this event on the Live session timeline, in milliseconds from the beginning of the session. For appended context, this can equal start_ms. - type: integer - delta: - description: The transcript text fragment for the audio in this time range. Append fragments in delivery order to build the transcript. - type: string type: - description: The event type, always `session.output_transcript.delta`. - default: session.output_transcript.delta - x-stainless-const: true type: string enum: - - session.output_transcript.delta + - 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: - - event_id - - start_ms - - end_ms - - delta - type - x-oaiMeta: - example: - type: session.output_transcript.delta - event_id: evt_output_transcript_001 - delta: Would you like me to reserve that table? - start_ms: 5400 - end_ms: 7200 - LiveDelegationItem: - description: Metadata for work delegated by the Live model. Client delegations are handled by your application; Responses delegations run on the configured backend. + additionalProperties: false + description: Enables calling tools from model-generated code. + PersistedMcpTransportConfigParamHttp: type: object properties: - id: - description: The unique ID of the delegation. Use this as delegation_id when replying to client-owned work or correlating Responses events. - type: string type: - description: The object type, always `delegation`. - default: delegation - x-stainless-const: true type: string enum: - - delegation - target: - description: 'Where the Live model delegated the work: `client` for your application, or `responses` for the configured Responses backend.' - anyOf: - - default: client - x-stainless-const: true + - 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 - enum: - - client - - default: responses - x-stainless-const: true + minLength: 0 + maxLength: 1048576 + propertyNames: type: string - enum: - - responses - response_id: - description: The ID of the Responses API response associated with a Responses delegation. Omitted for client delegations. - type: string + minLength: 1 + maxLength: 256 + minProperties: 0 + maxProperties: 1024 + description: Non-secret HTTP headers sent to the MCP server. required: - - id - type - - target - LiveDelegationCreated: - description: Returned when the Live model delegates work to your application or a Responses backend. Contains delegation metadata and the position on the session timeline where the work was delegated. - example: - type: session.delegation.created - event_id: evt_delegation_001 - offset_ms: 3600 - delegation: - id: del_abc123 - type: delegation - target: client + - server_url + additionalProperties: false + description: Connects to an MCP server over HTTP. + PersistedMcpTransportConfigParamStdio: type: object properties: - event_id: - description: The unique ID of the Live server event. - type: string - client_event_id: - description: The event_id of the client command associated with this server event, when supplied. - type: string type: - description: The event type, always `session.delegation.created`. - default: session.delegation.created - x-stainless-const: true type: string enum: - - session.delegation.created - offset_ms: - description: The position on the Live session timeline where the delegation was created, in milliseconds from the beginning of the session. - type: integer - delegation: - description: The delegated work identifier and destination. This object contains metadata, not the task text. - $ref: '#/components/schemas/LiveDelegationItem' + - 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: - - event_id - type - - offset_ms - - delegation - x-oaiMeta: - example: - type: session.delegation.created - event_id: evt_delegation_001 - offset_ms: 3600 - delegation: - id: del_abc123 - type: delegation - target: client - LiveResponseEvent: - description: A streaming Responses API event from a backend delegated to by the Live session. Use the outer delegation_id to associate the nested stream with its Live delegation. - example: - type: response.event - event_id: evt_response_002 - delegation_id: del_responses123 - event: - type: response.output_text.delta - item_id: msg_abc123 - output_index: 0 - content_index: 0 - delta: An outdoor table is available at 7 PM. - sequence_number: 3 - logprobs: [] + - command + - cwd + additionalProperties: false + description: Starts an MCP server as a local process. + PersistedMcpTransportConfigParam: + description: A credential-free transport used to connect to an MCP server. + discriminator: + propertyName: type + mapping: + http: '#/components/schemas/PersistedMcpTransportConfigParamHttp' + stdio: '#/components/schemas/PersistedMcpTransportConfigParamStdio' + x-oai-discriminator-values: + - http + - stdio + anyOf: + - $ref: '#/components/schemas/PersistedMcpTransportConfigParamHttp' + - $ref: '#/components/schemas/PersistedMcpTransportConfigParamStdio' + 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. + PersistedAgentToolConfigParamMcp: type: object properties: - event_id: - description: The unique ID of the Live server event. - type: string - client_event_id: - description: The event_id of the client command associated with this server event, when supplied. - type: string type: - description: The event type, always `response.event`. - default: response.event - x-stainless-const: true type: string enum: - - response.event - delegation_id: - anyOf: - - description: The Live delegation associated with the nested Responses event. May be null or omitted when the event cannot be correlated with a delegation. + - 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' - event: - description: The nested Responses streaming event. Dispatch on its type field. Response lifecycle snapshots omit input and clear instructions, tools, and output to keep messages small; consume granular output events for the generated content. - type: object - additionalProperties: {} + description: Selects where outbound MCP HTTP connections originate. required: - - event_id - type - - event - x-oaiMeta: - example: - type: response.event - event_id: evt_response_002 - delegation_id: del_responses123 - event: - type: response.output_text.delta - item_id: msg_abc123 - output_index: 0 - content_index: 0 - delta: An outdoor table is available at 7 PM. - sequence_number: 3 - logprobs: [] - LiveSessionUsage: - description: Cumulative audio duration for a Live session. Values are totals for the session, not increments to sum across usage events. - type: object - properties: - seconds: - description: The cumulative Live audio duration in seconds. Do not sum this value across usage events. - type: number - required: - - seconds - LiveContextWindowUsage: - description: The latest measured context-window usage of the Live model. This is separate from billing usage and delegated Responses token usage. - type: object - properties: - usage_ratio: - description: The latest active context token count divided by the Live model context limit. Can decrease after compaction and may lag between measured audio frames. - type: number - required: - - usage_ratio - LiveSessionUsageUpdated: - description: Reports cumulative Live audio usage and, when available, the most recent context-window usage. Delegated Responses token usage is reported separately in response.event events. - example: - type: session.usage.updated - event_id: evt_usage_001 - usage: - seconds: 32.5 - context_window: - usage_ratio: 0.12 + - server_label + - transport + additionalProperties: false + description: Tools provided by a remote MCP server without stored credentials. + 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. + WebSearchContextSizeParam: + type: string + enum: + - low + - medium + - high + description: The amount of web search context made available to the model. + WebSearchLocationParam: type: object properties: - event_id: - description: The unique ID of the Live server event. - type: string - client_event_id: - description: The event_id of the client command associated with this server event, when supplied. - type: string - type: - description: The event type, always `session.usage.updated`. - default: session.usage.updated - x-stainless-const: true - type: string - enum: - - session.usage.updated - usage: - description: The cumulative Live audio usage so far. - $ref: '#/components/schemas/LiveSessionUsage' - context_window: - description: The latest measured Live context-window usage. Omitted when the context limit is unknown. - $ref: '#/components/schemas/LiveContextWindowUsage' - required: - - event_id - - type - - usage - x-oaiMeta: - example: - type: session.usage.updated - event_id: evt_usage_001 - usage: - seconds: 32.5 - context_window: - usage_ratio: 0.12 - LiveSessionClosed: - description: Returned after the Live session finishes finalizing, with the close reason, final session snapshot, and cumulative audio usage. A connection closing without this event does not confirm successful finalization. - example: - type: session.closed - event_id: evt_closed_001 - client_event_id: evt_close_001 - reason: close_requested - session: - id: live_abc123 - model: gpt-live-1 - status: active - expires_at: 1788555600 - instructions: Help the caller plan a restaurant reservation. Confirm details before booking. - input: [] - audio: - format: - type: audio/pcm - rate: 24000 - output: - voice: marin - delegation: - type: client - usage: - seconds: 45.8 + 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. + PersistedAgentToolConfigParamWebSearch: type: object properties: - event_id: - description: The unique ID of the Live server event. - type: string - client_event_id: - description: The event_id of the client command associated with this server event, when supplied. - type: string type: - description: The event type, always `session.closed`. - default: session.closed - x-stainless-const: true type: string enum: - - session.closed - reason: - description: 'Why the Live session ended: `close_requested` for an application close or hangup request, `expired` for the session duration limit, `content` for a safety filter, `remote_hangup` for a graceful remote disconnect, or `connection_lost` for an unexpected primary or upstream disconnection.' + - web_search + default: web_search + x-stainless-const: true + description: The type of the object. Always `web_search`. + mode: anyOf: - - default: close_requested - x-stainless-const: true - type: string - enum: - - close_requested - - default: expired - x-stainless-const: true - type: string - enum: - - expired - - default: content - x-stainless-const: true - type: string - enum: - - content - - default: remote_hangup - x-stainless-const: true - type: string - enum: - - remote_hangup - - default: connection_lost - x-stainless-const: true + - $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 - enum: - - connection_lost - session: - $ref: '#/components/schemas/LiveSessionResourceParam' - usage: - description: The final cumulative Live audio usage after session finalization. - $ref: '#/components/schemas/LiveSessionUsage' + 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: - - event_id - type - - reason - - session - - usage - x-oaiMeta: - example: - type: session.closed - event_id: evt_closed_001 - client_event_id: evt_close_001 - reason: close_requested - session: - id: live_abc123 - model: gpt-live-1 - status: active - expires_at: 1788555600 - instructions: Help the caller plan a restaurant reservation. Confirm details before booking. - input: [] - audio: - format: - type: audio/pcm - rate: 24000 - output: - voice: marin - delegation: - type: client - usage: - seconds: 45.8 - LiveLiveError: - description: Details of an error encountered by the Live session, including the affected parameter or client command when available. + additionalProperties: false + description: Web search. + PersistedAgentToolConfigParam: + description: A tool that can be stored on a reusable agent without session credentials. + 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 + anyOf: + - $ref: '#/components/schemas/PersistedAgentToolConfigParamFunction' + - $ref: '#/components/schemas/PersistedAgentToolConfigParamToolSearch' + - $ref: '#/components/schemas/PersistedAgentToolConfigParamProgrammaticToolCalling' + - $ref: '#/components/schemas/PersistedAgentToolConfigParamMcp' + - $ref: '#/components/schemas/PersistedAgentToolConfigParamWebSearch' + MultiAgentConfigCurrentParam: type: object properties: - type: - description: The category of error, such as `invalid_request_error` for an invalid Live client command. - type: string - code: - description: A machine-readable code identifying the Live error, such as `unknown_parameter`. - type: string - message: - description: A human-readable explanation of the Live error. - type: string - param: - description: The parameter that caused the error, when applicable, such as `session.voice`. - type: string - client_event_id: - description: The event_id of the client command that caused the error, when supplied. - type: string + 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: - - type - - code - - message - LiveErrorEvent: - description: Reports an error in the Live session, such as an invalid client command. Use error.client_event_id, when present, to identify the command that caused the error. - example: - type: error - event_id: evt_error_001 - error: - type: invalid_request_error - code: unknown_parameter - message: 'Unknown parameter: ''session.voice''.' - param: session.voice - client_event_id: evt_invalid_001 + - enabled + additionalProperties: false + description: Explicit configuration for creating and coordinating subagents. + CreateAgentParams: type: object properties: - event_id: - description: The unique ID of the Live server event. - type: string - client_event_id: - description: The event_id of the client command associated with this server event, when supplied. - type: string - type: - description: The event type, always `error`. - default: error - x-stainless-const: true + 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 - enum: - - error - error: - description: Details of the Live error and the client command that caused it, when known. - $ref: '#/components/schemas/LiveLiveError' + 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: - - event_id - - type - - error - x-oaiMeta: - example: - type: error - event_id: evt_error_001 - error: - type: invalid_request_error - code: unknown_parameter - message: 'Unknown parameter: ''session.voice''.' - param: session.voice - client_event_id: evt_invalid_001 - LiveInfoEvent: - description: An informational notice about the Live session, such as the event permissions applied to a frontend data channel. - example: - type: info - event_id: evt_info_001 - code: data_channel_permissions - message: The frontend data channel is configured with restricted event permissions. + - model + additionalProperties: false + description: Parameters for creating a reusable agent. + UpdateAgentParams: type: object properties: - event_id: - description: The unique ID of the Live server event. + model: type: string - client_event_id: - description: The event_id of the client command associated with this server event, when supplied. + 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. + DeletedAgentResource: + type: object + properties: + id: type: string - type: - description: The event type, always `info`. - default: info - x-stainless-const: true + minLength: 0 + description: The ID of the deleted agent. + object: type: string enum: - - info - code: - description: A machine-readable code for the notice, such as `data_channel_permissions`. - type: string - message: - description: A human-readable explanation of the Live session notice. - type: string + - 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: - - event_id - - type - - code - - message - x-oaiMeta: - example: - type: info - event_id: evt_info_001 - code: data_channel_permissions - message: The frontend data channel is configured with restricted event permissions. - LiveTransportDTMFReceived: - description: A SIP DTMF keypress received from the caller. Delivered only to sideband observers. - example: - type: transport.dtmf.received - event_id: event_dtmf_1 - event: '5' + - id + - object + - deleted + additionalProperties: false + description: A deleted reusable agent. + EnvironmentPackagesResource: type: object properties: - type: - default: transport.dtmf.received - x-stainless-const: true - type: string - enum: - - transport.dtmf.received - event_id: - type: string - event: - type: string - minLength: 1 - maxLength: 1 - pattern: ^[0-9A-D*#]$ + 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: - - type - - event_id - - event - x-oaiMeta: - example: - type: transport.dtmf.received - event_id: event_dtmf_1 - event: '5' - LiveTransportDTMFSend: - description: A SIP DTMF keypress successfully sent by the hosted tool. Delivered only to sideband observers; this is not a client command. - example: - type: transport.dtmf.send - event_id: event_dtmf_2 - event: '#' + - python + - system + - npm + additionalProperties: false + description: Packages installed in an OpenAI-hosted environment. + 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. + NetworkPolicyResource: type: object properties: - type: - default: transport.dtmf.send - x-stainless-const: true - type: string - enum: - - transport.dtmf.send - event_id: - type: string - event: - type: string - minLength: 1 - maxLength: 1 - pattern: ^[0-9A-D*#]$ + 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: - - type - - event_id - - event - x-oaiMeta: - example: - type: transport.dtmf.send - event_id: event_dtmf_2 - event: '#' - LiveTransportRinging: - description: The outbound SIP provider leg is ringing or providing early media. Delivered only to sideband observers. - example: - type: transport.ringing - event_id: event_call_1 - session_id: live_u0_123 + - access + - allowed_domains + additionalProperties: false + description: Network access for an OpenAI-hosted environment. + HostedTemplateSkillResourceSkillReference: type: object properties: - event_id: - type: string - session_id: - description: The canonical Live session ID. - type: string type: - default: transport.ringing - x-stainless-const: true type: string enum: - - transport.ringing + - 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: - - event_id - - session_id - type - x-oaiMeta: - example: - type: transport.ringing - event_id: event_call_1 - session_id: live_u0_123 - LiveTransportAnswered: - description: The outbound SIP provider leg answered and media is established. Delivered only to sideband observers. - example: - type: transport.answered - event_id: event_call_2 - session_id: live_u0_123 + - skill_id + - version + additionalProperties: false + description: A skill resolved afresh from the Skills API whenever a session starts. + HostedTemplateSkillResourceInline: type: object properties: - event_id: - type: string - session_id: - description: The canonical Live session ID. - type: string type: - default: transport.answered - x-stainless-const: true type: string enum: - - transport.answered + - 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: - - event_id - - session_id - type - x-oaiMeta: - example: - type: transport.answered - event_id: event_call_2 - session_id: live_u0_123 - LiveTransportCallError: + - name + - description + additionalProperties: false + description: Safe metadata for an inline skill archive. + HostedTemplateSkillResource: + description: Safe metadata for a skill configured by an environment template. + discriminator: + propertyName: type + mapping: + skill_reference: '#/components/schemas/HostedTemplateSkillResourceSkillReference' + inline: '#/components/schemas/HostedTemplateSkillResourceInline' + x-oai-discriminator-values: + - skill_reference + - inline + anyOf: + - $ref: '#/components/schemas/HostedTemplateSkillResourceSkillReference' + - $ref: '#/components/schemas/HostedTemplateSkillResourceInline' + HostedTemplateFileResourceFileId: type: object properties: type: - default: call_error - x-stainless-const: true type: string enum: - - call_error - code: - description: The call setup failure code. - type: string - message: + - file_id + default: file_id + x-stainless-const: true + description: The type of the object. Always `file_id`. + file_id: type: string - param: - description: The parameter related to the error, if any. Empty when no parameter applies. + 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 - - code - - message - LiveTransportFailed: - description: An asynchronous outbound SIP setup failure. Delivered only to sideband observers. - example: - type: transport.failed - event_id: event_call_4 - session_id: live_u0_123 - error: - type: call_error - code: provider_invite_failed - message: provider rejected the call - param: '' + - file_id + - path + additionalProperties: false + description: A project-scoped Files API reference resolved separately for each session. + HostedTemplateFileResourceInline: type: object properties: - event_id: - type: string - session_id: - description: The canonical Live session ID. - type: string type: - default: transport.failed - x-stainless-const: true type: string enum: - - transport.failed - error: - $ref: '#/components/schemas/LiveTransportCallError' + - 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: - - event_id - - session_id - type - - error - x-oaiMeta: - example: - type: transport.failed - event_id: event_call_4 - session_id: live_u0_123 - error: - type: call_error - code: provider_invite_failed - message: provider rejected the call - param: '' - LiveServerEvent-2: - description: An event sent by the Live API on a primary WebSocket or sideband connection. + - path + - size_bytes + additionalProperties: false + description: Metadata for confidential inline file contents. + HostedTemplateFileResource: + description: Safe metadata for a file configured by an environment template. discriminator: propertyName: type + mapping: + file_id: '#/components/schemas/HostedTemplateFileResourceFileId' + inline: '#/components/schemas/HostedTemplateFileResourceInline' + x-oai-discriminator-values: + - file_id + - inline anyOf: - - $ref: '#/components/schemas/LiveSessionStarted' - - $ref: '#/components/schemas/LiveSessionUpdated' - - $ref: '#/components/schemas/LiveInputAudioMuted' - - $ref: '#/components/schemas/LiveInputAudioUnmuted' - - $ref: '#/components/schemas/LiveInstructionsAppended' - - $ref: '#/components/schemas/LiveThinkingAppended' - - $ref: '#/components/schemas/LiveCommentaryAppended' - - $ref: '#/components/schemas/LiveInputAudioAppend' - - $ref: '#/components/schemas/LiveOutputAudioDelta' - - $ref: '#/components/schemas/LiveInputTranscriptDelta' - - $ref: '#/components/schemas/LiveOutputTranscriptDelta' - - $ref: '#/components/schemas/LiveDelegationCreated' - - $ref: '#/components/schemas/LiveResponseEvent' - - $ref: '#/components/schemas/LiveSessionUsageUpdated' - - $ref: '#/components/schemas/LiveSessionClosed' - - $ref: '#/components/schemas/LiveErrorEvent' - - $ref: '#/components/schemas/LiveInfoEvent' - - $ref: '#/components/schemas/LiveTransportDTMFReceived' - - $ref: '#/components/schemas/LiveTransportDTMFSend' - - $ref: '#/components/schemas/LiveTransportRinging' - - $ref: '#/components/schemas/LiveTransportAnswered' - - $ref: '#/components/schemas/LiveTransportFailed' - UserMessageItemParam: + - $ref: '#/components/schemas/HostedTemplateFileResourceFileId' + - $ref: '#/components/schemas/HostedTemplateFileResourceInline' + EnvironmentTemplateResource: + type: object properties: id: - anyOf: - - type: string - description: The unique ID of this message item. - example: msg_123 - - type: 'null' - type: type: string - enum: - - message - description: The item type. Always `message`. - default: message - x-stainless-const: true - role: + 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: - - user - description: The message role. Always `user`. - default: user + - agent.environment.template + default: agent.environment.template x-stainless-const: true - content: - description: The message content, as an array of content parts. - anyOf: - - items: - $ref: '#/components/schemas/ResponseSteerInputContent' - description: A piece of message content, such as text, an image, or a file. - type: array - - type: string - maxLength: 10485760 - description: The message content, as a single string. - status: - anyOf: - - type: string - description: The status of the message item. - - type: 'null' - type: object - required: - - type - - role - - content - ErrorPayload: - properties: - type: - type: string - description: The error type that was emitted. - code: - anyOf: - - type: string - description: The error code that was emitted, if any. - - type: 'null' - message: - type: string - description: The human-readable error message that was emitted. - param: - anyOf: - - type: string - description: The parameter name that was associated with the error, if any. - - type: 'null' - headers: - additionalProperties: + 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 - description: The header value that was emitted. - type: object - description: The response headers that were emitted with the error, if any. - x-oaiTypeLabel: map - misalignment: - $ref: '#/components/schemas/MisalignmentErrorDetailsResource' - type: object + 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: - - type - - code - - message - - param - title: Error payload - description: An error payload that was emitted for a streaming error event. - BetaTokenCountsResource: + - 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. + EnvironmentTemplateListResource: + type: object properties: object: type: string enum: - - response.input_tokens - default: response.input_tokens + - list + default: list x-stainless-const: true - input_tokens: - type: integer - type: object + 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 - - input_tokens - title: Token counts - example: - object: response.input_tokens - input_tokens: 123 - BetaTokenCountsBody: - properties: - model: - anyOf: - - type: string - description: Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](https://developers.openai.com/api/docs/models) to browse and compare available models. - - type: 'null' - input: - anyOf: - - description: Text, image, or file inputs to the model, used to generate a response - anyOf: - - type: string - maxLength: 10485760 - description: A text input to the model, equivalent to a text input with the `user` role. - - items: - $ref: '#/components/schemas/BetaInputItem' - type: array - maxItems: 131072 - description: A list of one or many input items to the model, containing different content types. - - type: 'null' - previous_response_id: - anyOf: - - type: string - description: The unique ID of the previous response to the model. Use this to create multi-turn conversations. Learn more about [conversation state](https://developers.openai.com/api/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. - example: resp_123 - - type: 'null' - tools: - anyOf: - - items: - $ref: '#/components/schemas/BetaTool' - type: array - description: An array of tools the model may call while generating a response. You can specify which tool to use by setting the `tool_choice` parameter. - - type: 'null' - text: - anyOf: - - $ref: '#/components/schemas/BetaResponseTextParam' - - type: 'null' - reasoning: - anyOf: - - $ref: '#/components/schemas/BetaReasoning' - description: '**gpt-5 and o-series models only** Configuration options for [reasoning models](https://developers.openai.com/api/docs/guides/reasoning).' - - type: 'null' - truncation: - $ref: '#/components/schemas/BetaTruncationEnum' - description: 'The truncation strategy to use for the model response. - `auto`: If the input to this Response exceeds the model''s context window size, the model will truncate the response to fit the context window by dropping items from the beginning of the conversation. - `disabled` (default): If the input size will exceed the context window size for a model, the request will fail with a 400 error.' - deprecated: true - instructions: - anyOf: - - type: string - description: |- - A system (or developer) message inserted into the model's context. - When used along with `previous_response_id`, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses. - - type: 'null' - personality: - $ref: '#/components/schemas/BetaPersonalityEnum' - description: A model-owned style preset to apply to this request. Omit this parameter to use the model's default style. Supported values may expand over time. Values must be at most 64 characters. - conversation: - anyOf: - - $ref: '#/components/schemas/BetaConversationParam' - - type: 'null' - tool_choice: - anyOf: - - $ref: '#/components/schemas/BetaToolChoiceParam' - description: Controls which tool the model should use, if any. - - type: 'null' - parallel_tool_calls: - anyOf: - - type: boolean - description: Whether to allow the model to run tool calls in parallel. - - type: 'null' + - data + - first_id + - last_id + - has_more + additionalProperties: false + description: A page of Agents API resources, with IDs for retrieving additional pages. + EnvironmentPackagesParam: type: object - required: [] - BetaToolChoiceParam: - description: | - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. - anyOf: - - $ref: '#/components/schemas/BetaToolChoiceOptions' - - $ref: '#/components/schemas/BetaToolChoiceAllowed' - - $ref: '#/components/schemas/BetaToolChoiceTypes' - - $ref: '#/components/schemas/BetaToolChoiceFunction' - - $ref: '#/components/schemas/BetaToolChoiceMCP' - - $ref: '#/components/schemas/BetaToolChoiceCustom' - - $ref: '#/components/schemas/BetaSpecificProgrammaticToolCallingParam' - - $ref: '#/components/schemas/BetaSpecificApplyPatchParam' - - $ref: '#/components/schemas/BetaSpecificFunctionShellParam' - BetaSpecificFunctionShellParam: properties: - type: - type: string - enum: - - shell - description: The tool to call. Always `shell`. - default: shell - x-stainless-const: true + 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. + SetupCommandParam: type: object - required: - - type - title: Specific shell tool choice - description: Forces the model to call the shell tool when a tool call is required. - BetaSpecificApplyPatchParam: properties: - type: + command: type: string - enum: - - apply_patch - description: The tool to call. Always `apply_patch`. - default: apply_patch - x-stainless-const: true - type: object + 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: - - type - title: Specific apply patch tool choice - description: Forces the model to call the apply_patch tool when executing a tool call. - BetaSpecificProgrammaticToolCallingParam: - properties: - type: - type: string - enum: - - programmatic_tool_calling - description: The tool to call. Always `programmatic_tool_calling`. - default: programmatic_tool_calling - x-stainless-const: true + - command + additionalProperties: false + description: A confidential setup command executed before the hosted agent starts. + 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. + 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: - - type - BetaToolChoiceCustom: + - access + additionalProperties: false + description: Network access for an OpenAI-hosted environment. + HostedSkillParamSkillReference: type: object - title: Custom tool - description: | - Use this option to force the model to call a specific custom tool. properties: type: type: string enum: - - custom - description: For custom tool calling, the type is always `custom`. + - skill_reference + default: skill_reference x-stainless-const: true - name: + description: The type of the object. Always `skill_reference`. + skill_id: type: string - description: The name of the custom tool to call. + 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 - - name - BetaToolChoiceMCP: + - skill_id + additionalProperties: false + description: References a skill uploaded through the Skills API. + InlineCapabilitySourceParamBase64: type: object - title: MCP tool - description: | - Use this option to force the model to call a specific tool on a remote MCP server. properties: type: type: string enum: - - mcp - description: For MCP tools, the type is always `mcp`. + - base64 + default: base64 x-stainless-const: true - server_label: + description: The type of the object. Always `base64`. + media_type: type: string - description: | - The label of the MCP server to use. - name: - anyOf: - - type: string - description: | - The name of the tool to call on the server. - - type: 'null' + 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 - - server_label - BetaToolChoiceFunction: + - media_type + - data + additionalProperties: false + description: Provides ZIP bytes encoded with standard base64. + InlineCapabilitySourceParam: + description: The encoded ZIP archive for an inline skill or plugin. + discriminator: + propertyName: type + mapping: + base64: '#/components/schemas/InlineCapabilitySourceParamBase64' + x-oai-discriminator-values: + - base64 + anyOf: + - $ref: '#/components/schemas/InlineCapabilitySourceParamBase64' + HostedSkillParamInline: type: object - title: Function tool - description: | - Use this option to force the model to call a specific function. properties: type: type: string enum: - - function - description: For function calling, the type is always `function`. + - inline + default: inline x-stainless-const: true + description: The type of the object. Always `inline`. name: type: string - description: The name of the function to call. - required: - - type - - name - BetaToolChoiceTypes: - type: object - title: Hosted tool - description: | - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://developers.openai.com/api/docs/guides/tools). - properties: - type: + minLength: 1 + maxLength: 64 + description: The skill name declared in `SKILL.md`. + description: type: string - description: | - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://developers.openai.com/api/docs/guides/tools). - - Allowed values are: - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` - enum: - - file_search - - web_search_preview - - computer - - computer_use_preview - - computer_use - - web_search_preview_2025_03_11 - - image_generation - - code_interpreter + minLength: 0 + maxLength: 1048576 + description: The skill description declared in `SKILL.md`. + source: + $ref: '#/components/schemas/InlineCapabilitySourceParam' + description: The inline ZIP archive. required: - type - BetaToolChoiceAllowed: + - name + - description + - source + additionalProperties: false + description: Supplies a skill ZIP directly in the session request. + HostedSkillParam: + description: A skill installed in an OpenAI-hosted environment. + discriminator: + propertyName: type + mapping: + skill_reference: '#/components/schemas/HostedSkillParamSkillReference' + inline: '#/components/schemas/HostedSkillParamInline' + x-oai-discriminator-values: + - skill_reference + - inline + anyOf: + - $ref: '#/components/schemas/HostedSkillParamSkillReference' + - $ref: '#/components/schemas/HostedSkillParamInline' + HostedPluginParamInline: type: object - title: Allowed tools - description: | - Constrains the tools available to the model to a pre-defined set. properties: type: type: string enum: - - allowed_tools - description: Allowed tool configuration type. Always `allowed_tools`. + - inline + default: inline x-stainless-const: true - mode: + description: The type of the object. Always `inline`. + name: type: string - enum: - - auto - - required - description: | - Constrains the tools available to the model to a pre-defined set. - - `auto` allows the model to pick from among the allowed tools and generate a - message. - - `required` requires the model to call one or more of the allowed tools. - tools: - type: array - description: | - A list of tool definitions that the model should be allowed to call. - - For the Responses API, the list of tool definitions might look like: - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` - items: - type: object - description: | - A tool definition that the model should be allowed to call. - additionalProperties: true - x-oaiExpandable: false - required: - - type - - mode - - tools - BetaToolChoiceOptions: - type: string - title: Tool choice mode - description: | - Controls which (if any) tool is called by the model. - - `none` means the model will not call any tool and instead generates a message. - - `auto` means the model can pick between generating a message or calling one or - more tools. - - `required` means the model must call one or more tools. - enum: - - none - - auto - - required - BetaConversationParam: - description: | - The conversation that this response belongs to. Items from this conversation are prepended to `input_items` for this response request. - Input items and output items from this response are automatically added to this conversation after this response completes. - anyOf: - - type: string - title: Conversation ID - description: | - The unique ID of the conversation. - - $ref: '#/components/schemas/BetaConversationParam-2' - BetaConversationParam-2: - properties: - id: + minLength: 1 + maxLength: 64 + description: The plugin name declared in `.codex-plugin/plugin.json`. + description: type: string - description: The unique ID of the conversation. - example: conv_123 - type: object + 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: - - id - title: Conversation object - description: The conversation that this response belongs to. - BetaPersonalityEnum: + - type + - name + - description + - source + additionalProperties: false + description: Supplies a plugin ZIP directly in the session request. + HostedPluginParam: + description: A plugin installed in an OpenAI-hosted environment. + discriminator: + propertyName: type + mapping: + inline: '#/components/schemas/HostedPluginParamInline' + x-oai-discriminator-values: + - inline anyOf: - - type: string - - type: string - enum: - - friendly - - pragmatic - BetaTruncationEnum: - type: string - enum: - - auto - - disabled - BetaReasoning: + - $ref: '#/components/schemas/HostedPluginParamInline' + CreateEnvironmentTemplateParams: type: object - description: | - Configuration options for - [reasoning models](https://developers.openai.com/api/docs/guides/reasoning). - title: Reasoning properties: - mode: - $ref: '#/components/schemas/BetaReasoningModeEnum' - description: | - Controls the reasoning execution mode for the request. - - When returned on a response, this is the effective execution mode. - effort: - $ref: '#/components/schemas/BetaReasoningEffort' - summary: - anyOf: - - type: string - description: | - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. - - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - enum: - - auto - - concise - - detailed - - type: 'null' - context: + packages: anyOf: - - type: string - description: | - Controls which reasoning items are rendered back to the model on later turns. - If omitted or set to `auto`, the model determines the context mode. The - `gpt-5.6` model family defaults to `all_turns`; earlier models default to - `current_turn`. - - When returned on a response, this is the effective reasoning context mode - used for the response. - enum: - - auto - - current_turn - - all_turns + - $ref: '#/components/schemas/EnvironmentPackagesParam' - type: 'null' - generate_summary: + 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: - - type: string - deprecated: true - description: | - **Deprecated:** use `summary` instead. - - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. - enum: - - auto - - concise - - detailed + - $ref: '#/components/schemas/NetworkPolicyParam' - type: 'null' - BetaReasoningEffort: - anyOf: - - type: string - enum: - - none - - minimal - - low - - medium - - high - - xhigh - - max - default: medium - description: | - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://developers.openai.com/api/docs/guides/reasoning) - for model-specific support. - - type: 'null' - BetaReasoningModeEnum: - anyOf: - - type: string - - type: string - enum: - - standard - - pro - BetaResponseTextParam: - type: object - description: | - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: - - [Text inputs and outputs](https://developers.openai.com/api/docs/guides/text) - - [Structured Outputs](https://developers.openai.com/api/docs/guides/structured-outputs) - properties: - format: - $ref: '#/components/schemas/BetaTextResponseFormatConfiguration' - verbosity: - $ref: '#/components/schemas/BetaVerbosity' - BetaVerbosity: - anyOf: - - type: string - enum: - - low - - medium - - high - default: medium - description: | - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. The default is - `medium`. - - type: 'null' - BetaTextResponseFormatConfiguration: - description: | - An object specifying the format that the model must output. - - Configuring `{ "type": "json_schema" }` enables Structured Outputs, - which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](https://developers.openai.com/api/docs/guides/structured-outputs). - - The default format is `{ "type": "text" }` with no additional options. - - **Not recommended for gpt-4o and newer models:** - - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. - anyOf: - - $ref: '#/components/schemas/BetaResponseFormatText' - - $ref: '#/components/schemas/BetaTextResponseFormatJsonSchema' - - $ref: '#/components/schemas/BetaResponseFormatJsonObject' - discriminator: - propertyName: type - BetaResponseFormatJsonObject: + 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. + UpdateEnvironmentTemplateParams: type: object - title: JSON object - description: | - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. properties: - type: + 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. + DeletedEnvironmentTemplateResource: + type: object + properties: + id: + type: string + minLength: 0 + description: The ID of the deleted environment template. + object: type: string - description: The type of response format being defined. Always `json_object`. enum: - - json_object + - 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: - - type - BetaTextResponseFormatJsonSchema: + - id + - object + - deleted + additionalProperties: false + description: A deleted reusable 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. + SessionRequiredActionResourceFunctionCall: type: object - title: JSON schema - description: | - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://developers.openai.com/api/docs/guides/structured-outputs). properties: type: type: string - description: The type of response format being defined. Always `json_schema`. enum: - - json_schema + - function_call + default: function_call x-stainless-const: true - description: + description: The type of the object. Always `function_call`. + turn_id: type: string - description: | - A description of what the response format is for, used by the model to - determine how to respond in the format. + 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 - description: | - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. - schema: - $ref: '#/components/schemas/BetaResponseFormatJsonSchemaSchema' - strict: - anyOf: - - type: boolean - default: false - description: | - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://developers.openai.com/api/docs/guides/structured-outputs). - - type: 'null' + minLength: 0 + description: The function name. + arguments: + description: The arguments supplied by the model. required: - type - - schema + - turn_id + - call_id - name - BetaResponseFormatJsonSchemaSchema: - type: object - title: JSON schema - description: | - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). - additionalProperties: true - BetaResponseFormatText: + - arguments + additionalProperties: false + description: Run a function tool and submit its result. + SessionRequiredActionResourceEnvironmentConnection: type: object - title: Text - description: | - Default response format. Used to generate text responses. properties: type: type: string - description: The type of response format being defined. Always `text`. enum: - - text + - 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 - BetaTool: - description: | - A tool that can be used to generate a response. + - environment_id + additionalProperties: false + description: Reconnect a session environment. + SessionRequiredActionResource: + description: An action that must be completed before a session can continue. discriminator: propertyName: type + mapping: + function_call: '#/components/schemas/SessionRequiredActionResourceFunctionCall' + environment_connection: '#/components/schemas/SessionRequiredActionResourceEnvironmentConnection' + x-oai-discriminator-values: + - function_call + - environment_connection anyOf: - - $ref: '#/components/schemas/BetaFunctionTool' - - $ref: '#/components/schemas/BetaFileSearchTool' - - $ref: '#/components/schemas/BetaComputerTool' - - $ref: '#/components/schemas/BetaComputerUsePreviewTool' - - $ref: '#/components/schemas/BetaWebSearchTool' - - $ref: '#/components/schemas/BetaMCPTool' - - $ref: '#/components/schemas/BetaCodeInterpreterTool' - - $ref: '#/components/schemas/BetaProgrammaticToolCallingParam' - - $ref: '#/components/schemas/BetaImageGenTool' - - $ref: '#/components/schemas/BetaLocalShellToolParam' - - $ref: '#/components/schemas/BetaFunctionShellToolParam' - - $ref: '#/components/schemas/BetaCustomToolParam' - - $ref: '#/components/schemas/BetaNamespaceToolParam' - - $ref: '#/components/schemas/BetaToolSearchToolParam' - - $ref: '#/components/schemas/BetaWebSearchPreviewTool' - - $ref: '#/components/schemas/BetaApplyPatchToolParam' - BetaApplyPatchToolParam: - properties: - type: - type: string - enum: - - apply_patch - description: The type of the tool. Always `apply_patch`. - default: apply_patch - x-stainless-const: true - allowed_callers: - anyOf: - - items: - $ref: '#/components/schemas/BetaCallableToolAllowedCaller' - type: array - minItems: 1 - description: The tool invocation context(s). - - type: 'null' + - $ref: '#/components/schemas/SessionRequiredActionResourceFunctionCall' + - $ref: '#/components/schemas/SessionRequiredActionResourceEnvironmentConnection' + AgentToolResourceFunction: type: object - required: - - type - title: Apply patch tool - description: Allows the assistant to create, delete, or update files using unified diffs. - BetaCallableToolAllowedCaller: - type: string - enum: - - direct - - programmatic - BetaWebSearchPreviewTool: properties: type: type: string enum: - - web_search_preview - - web_search_preview_2025_03_11 - description: The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - default: web_search_preview + - function + default: function x-stainless-const: true - user_location: - anyOf: - - $ref: '#/components/schemas/BetaApproximateLocation' - description: The user's location. - - type: 'null' - search_context_size: - $ref: '#/components/schemas/BetaSearchContextSize' - description: High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - search_content_types: - items: - $ref: '#/components/schemas/BetaSearchContentType' - type: array - type: object + 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 - title: Web search preview - description: This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://developers.openai.com/api/docs/guides/tools-web-search). - BetaSearchContentType: - type: string - enum: - - text - - image - BetaSearchContextSize: - type: string - enum: - - low - - medium - - high - BetaApproximateLocation: + - name + - description + - parameters + - defer_loading + additionalProperties: false + description: A function defined by the application. + AgentToolResourceProgrammaticToolCalling: + type: object properties: type: type: string enum: - - approximate - description: The type of location approximation. Always `approximate`. - default: approximate + - programmatic_tool_calling + default: programmatic_tool_calling x-stainless-const: true - country: - anyOf: - - type: string - description: The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - type: 'null' - region: - anyOf: - - type: string - description: Free text input for the region of the user, e.g. `California`. - - type: 'null' - city: - anyOf: - - type: string - description: Free text input for the city of the user, e.g. `San Francisco`. - - type: 'null' - timezone: - anyOf: - - type: string - description: The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - type: 'null' - type: object + 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 - BetaToolSearchToolParam: + - enabled + additionalProperties: false + description: Enables calling tools from model-generated code. + McpTransportResourceHttp: + type: object properties: type: type: string enum: - - tool_search - description: The type of the tool. Always `tool_search`. - default: tool_search + - http + default: http x-stainless-const: true - execution: - $ref: '#/components/schemas/BetaToolSearchExecutionType' - description: Whether tool search is executed by the server or by the client. - description: - anyOf: - - type: string - description: Description shown to the model for a client-executed tool search tool. - - type: 'null' - parameters: - anyOf: - - $ref: '#/components/schemas/BetaEmptyModelParam' - description: Parameter schema for a client-executed tool search tool. - - type: 'null' - type: object + description: The type of the object. Always `http`. + server_url: + type: string + minLength: 0 + description: The URL of the MCP server. required: - type - title: Tool search tool - description: Hosted or BYOT tool search configuration for deferred tools. - BetaEmptyModelParam: - properties: {} + - server_url + additionalProperties: false + description: Connects to an MCP server over HTTP. + McpTransportResourceStdio: type: object - required: [] - BetaToolSearchExecutionType: - type: string - enum: - - server - - client - BetaNamespaceToolParam: properties: type: type: string enum: - - namespace - description: The type of the tool. Always `namespace`. - default: namespace + - stdio + default: stdio x-stainless-const: true - name: - type: string - minLength: 1 - description: The namespace name used in tool calls (for example, `crm`). - description: + description: The type of the object. Always `stdio`. + command: type: string - description: A description of the namespace shown to the model. - tools: + minLength: 0 + description: The command used to start the MCP server. + args: + type: array items: - discriminator: - propertyName: type - description: A function or custom tool that belongs to a namespace. - anyOf: - - $ref: '#/components/schemas/BetaFunctionToolParam' - - $ref: '#/components/schemas/BetaCustomToolParam' + 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 - minItems: 1 - description: The function/custom tools available inside this namespace. - type: object + items: + type: string + minLength: 0 + minItems: 0 + maxItems: 2000 + description: Environment variable names inherited from the execution environment. required: - type - - name - - description - - tools - title: Namespace - description: Groups function/custom tools under a shared namespace. - BetaCustomToolParam: - properties: - type: - type: string - enum: - - custom - description: The type of the custom tool. Always `custom`. - default: custom - x-stainless-const: true - name: - type: string - description: The name of the custom tool, used to identify it in tool calls. - async: - type: boolean - description: Whether the tool response can be returned asynchronously versus immediately returned on next response creation. - description: - type: string - description: Optional description of the custom tool, used to provide more context. - format: - discriminator: - propertyName: type - description: The input format for the custom tool. Default is unconstrained text. - anyOf: - - $ref: '#/components/schemas/BetaCustomTextFormatParam' - - $ref: '#/components/schemas/BetaCustomGrammarFormatParam' - defer_loading: - type: boolean - description: Whether this tool should be deferred and discovered via tool search. - allowed_callers: - anyOf: - - items: - $ref: '#/components/schemas/BetaCallableToolAllowedCaller' - type: array - minItems: 1 - description: The tool invocation context(s). - - type: 'null' + - command + - args + - cwd + - env_vars + additionalProperties: false + description: Starts an MCP server as a local process. + McpTransportResource: + description: The transport used to connect to an MCP server. + discriminator: + propertyName: type + mapping: + http: '#/components/schemas/McpTransportResourceHttp' + stdio: '#/components/schemas/McpTransportResourceStdio' + x-oai-discriminator-values: + - http + - stdio + anyOf: + - $ref: '#/components/schemas/McpTransportResourceHttp' + - $ref: '#/components/schemas/McpTransportResourceStdio' + AgentToolResourceMcp: type: object - required: - - type - - name - title: Custom tool - description: A custom tool that processes input using a specified format. Learn more about [custom tools](https://developers.openai.com/api/docs/guides/function-calling#custom-tools) - BetaCustomGrammarFormatParam: properties: type: type: string enum: - - grammar - description: Grammar format. Always `grammar`. - default: grammar + - mcp + default: mcp x-stainless-const: true - syntax: - $ref: '#/components/schemas/BetaGrammarSyntax1' - description: The syntax of the grammar definition. One of `lark` or `regex`. - definition: + description: The type of the object. Always `mcp`. + server_label: type: string - description: The grammar definition. - type: object + 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 - - syntax - - definition - title: Grammar format - description: A grammar defined by the user. - BetaGrammarSyntax1: - type: string - enum: - - lark - - regex - BetaCustomTextFormatParam: + - server_label + - credential_id + - transport + - request_metadata + - allowed_tools + - required + - connection_origin + additionalProperties: false + description: Tools provided by a remote MCP server. + AgentToolResourceWebSearch: + type: object properties: type: type: string enum: - - text - description: Unconstrained text format. Always `text`. - default: text + - web_search + default: web_search x-stainless-const: true - type: object + 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 - title: Text format - description: Unconstrained free-form text. - BetaFunctionToolParam: + - mode + - context_size + - allowed_domains + - location + additionalProperties: false + description: Web search. + AgentToolResource: + description: A tool available to the agent. + 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 + anyOf: + - $ref: '#/components/schemas/AgentToolResourceFunction' + - $ref: '#/components/schemas/AgentToolResourceProgrammaticToolCalling' + - $ref: '#/components/schemas/AgentToolResourceMcp' + - $ref: '#/components/schemas/AgentToolResourceWebSearch' + SessionAgentResource: + type: object properties: - name: + id: type: string - maxLength: 128 - minLength: 1 - pattern: ^[a-zA-Z0-9_-]+$ - description: - anyOf: - - type: string - - type: 'null' - parameters: - anyOf: - - $ref: '#/components/schemas/BetaEmptyModelParam' - - type: 'null' - strict: - anyOf: - - type: boolean - description: Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - - type: 'null' - type: + 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 - enum: - - function - default: function - x-stainless-const: true - async: - type: boolean - description: Whether the tool response can be returned asynchronously versus immediately returned on next response creation. - output_schema: - anyOf: - - additionalProperties: {} - type: object - description: A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - x-oaiTypeLabel: map - - type: 'null' - defer_loading: - type: boolean - description: Whether this function should be deferred and discovered via tool search. - allowed_callers: - anyOf: - - items: - $ref: '#/components/schemas/BetaCallableToolAllowedCaller' - type: array - minItems: 1 - description: The tool invocation context(s). - - type: 'null' - type: object + 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 - - type - BetaFunctionShellToolParam: + - model + - reasoning + - text + - service_tier + - instructions + - tools + - multi_agent + additionalProperties: false + description: The effective agent configuration for a session. + EnvironmentResourceNone: + type: object properties: type: type: string enum: - - shell - description: The type of the shell tool. Always `shell`. - default: shell + - none + default: none x-stainless-const: true - environment: - anyOf: - - discriminator: - propertyName: type - anyOf: - - $ref: '#/components/schemas/BetaContainerAutoParam' - - $ref: '#/components/schemas/BetaLocalEnvironmentParam' - - $ref: '#/components/schemas/BetaContainerReferenceParam' - - type: 'null' - allowed_callers: - anyOf: - - items: - $ref: '#/components/schemas/BetaCallableToolAllowedCaller' - type: array - minItems: 1 - description: The tool invocation context(s). - - type: 'null' - type: object + description: The type of the object. Always `none`. required: - type - title: Shell tool - description: A tool that allows the model to execute shell commands. - BetaContainerReferenceParam: + additionalProperties: false + description: The session talks to CCA without selecting or provisioning an execution environment. + EnvironmentResourceOpenaiHosted: + type: object properties: type: type: string enum: - - container_reference - description: References a container created with the /v1/containers endpoint - default: container_reference + - openai_hosted + default: openai_hosted x-stainless-const: true - container_id: + description: The type of the object. Always `openai_hosted`. + id: type: string - description: The ID of the referenced container. - example: cntr_123 - type: object + 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 - - container_id - BetaLocalEnvironmentParam: + - id + - packages + - network + - capability_directories + - skills + - plugins + - files + additionalProperties: false + description: An environment hosted by OpenAI. + EnvironmentResourceSelfHosted: + type: object properties: type: type: string enum: - - local - description: Use a local computer environment. - default: local + - self_hosted + default: self_hosted x-stainless-const: true - skills: - items: - $ref: '#/components/schemas/BetaLocalSkillParam' - type: array - maxItems: 200 - description: An optional list of skills. - type: object - required: - - type - BetaLocalSkillParam: - properties: - name: + description: The type of the object. Always `self_hosted`. + remote_url: type: string - description: The name of the skill. - description: + minLength: 0 + description: Pass this URL unchanged to `codex exec-server --remote` when connecting this environment. + id: type: string - description: The description of the skill. - path: + minLength: 0 + description: The public ID of the environment. + workspace_directory: type: string - description: The path to the directory containing the skill. - type: object + 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: - - name - - description - - path - BetaContainerAutoParam: + - type + - remote_url + - id + - workspace_directory + - capability_directories + additionalProperties: false + description: An environment hosted by the application. + EnvironmentResource: + description: The execution environment for a session. + 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 + anyOf: + - $ref: '#/components/schemas/EnvironmentResourceNone' + - $ref: '#/components/schemas/EnvironmentResourceOpenaiHosted' + - $ref: '#/components/schemas/EnvironmentResourceSelfHosted' + SessionResource: + type: object properties: - type: + 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: - - container_auto - description: Automatically creates a container for this request - default: container_auto + - agent.session + default: agent.session x-stainless-const: true - file_ids: + 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: - type: string - example: file-123 + $ref: '#/components/schemas/SessionRequiredActionResource' + minItems: 0 + maxItems: 2000 + description: Actions that must be completed before the session can continue. + error: + type: + - string + - 'null' + minLength: 0 + description: The error that caused the session to fail, if any. + 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 - maxItems: 50 - description: An optional list of uploaded files to make available to your code. - memory_limit: + items: + type: string + minLength: 0 + minItems: 0 + maxItems: 2000 + description: The IDs of vaults made available to the session. + usage: anyOf: - - $ref: '#/components/schemas/BetaContainerMemoryLimit' - description: The memory limit for the container. + - $ref: '#/components/schemas/TokenUsageResource' - type: 'null' - network_policy: - discriminator: - propertyName: type - description: Network access policy for the container. - anyOf: - - $ref: '#/components/schemas/BetaContainerNetworkPolicyDisabledParam' - - $ref: '#/components/schemas/BetaContainerNetworkPolicyAllowlistParam' - skills: - items: - discriminator: - propertyName: type - anyOf: - - $ref: '#/components/schemas/BetaSkillReferenceParam' - - $ref: '#/components/schemas/BetaInlineSkillParam' - type: array - maxItems: 200 - description: An optional list of skills referenced by id or inline data. + 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. + 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: - - type - BetaInlineSkillParam: + - object + - data + - first_id + - last_id + - has_more + additionalProperties: false + description: A page of Agents API resources, with IDs for retrieving additional pages. + AgentToolConfigParamFunction: + type: object properties: type: type: string enum: - - inline - description: Defines an inline skill for this request. - default: inline + - function + default: function x-stainless-const: true + description: The type of the object. Always `function`. name: type: string - description: The name of the skill. + minLength: 0 + maxLength: 1048576 + description: The name of the function. description: type: string - description: The description of the skill. - source: - $ref: '#/components/schemas/BetaInlineSkillSourceParam' - description: Inline skill payload - type: object + 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 - - source - BetaInlineSkillSourceParam: + - parameters + additionalProperties: false + description: A function defined by the application. + AgentToolConfigParamToolSearch: + type: object properties: type: type: string enum: - - base64 - description: The type of the inline skill source. Must be `base64`. - default: base64 - x-stainless-const: true - media_type: - type: string - enum: - - application/zip - description: The media type of the inline skill payload. Must be `application/zip`. - default: application/zip + - tool_search + default: tool_search x-stainless-const: true - data: - type: string - maxLength: 70254592 - minLength: 1 - description: Base64-encoded skill zip bundle. - type: object + description: The type of the object. Always `tool_search`. required: - type - - media_type - - data - description: Inline skill payload - BetaSkillReferenceParam: + additionalProperties: false + description: Discovers deferred function tools and loads them into the model context. + AgentToolConfigParamProgrammaticToolCalling: + type: object properties: type: type: string enum: - - skill_reference - description: References a skill created with the /v1/skills endpoint. - default: skill_reference + - programmatic_tool_calling + default: programmatic_tool_calling x-stainless-const: true - skill_id: - type: string - maxLength: 64 - minLength: 1 - description: The ID of the referenced skill. - version: - type: string - description: Optional skill version. Use a positive integer or 'latest'. Omit for default. - type: object + 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 - - skill_id - BetaContainerNetworkPolicyAllowlistParam: + additionalProperties: false + description: Enables calling tools from model-generated code. + McpTransportConfigParamHttp: + type: object properties: type: type: string enum: - - allowlist - description: Allow outbound network access only to specified domains. Always `allowlist`. - default: allowlist + - http + default: http x-stainless-const: true - allowed_domains: - items: + 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 - type: array - minItems: 1 - description: A list of allowed domains when type is `allowlist`. - domain_secrets: - items: - $ref: '#/components/schemas/BetaContainerNetworkPolicyDomainSecretParam' - type: array - minItems: 1 - description: Optional domain-scoped secrets for allowlisted domains. - type: object + 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 - - allowed_domains - BetaContainerNetworkPolicyDomainSecretParam: - properties: - domain: - type: string - minLength: 1 - description: The domain associated with the secret. - name: - type: string - minLength: 1 - description: The name of the secret to inject for the domain. - value: - type: string - maxLength: 10485760 - minLength: 1 - description: The secret value to inject for the domain. + - server_url + additionalProperties: false + description: Connects to an MCP server over HTTP. + McpTransportConfigParamStdio: type: object - required: - - domain - - name - - value - BetaContainerNetworkPolicyDisabledParam: properties: type: type: string enum: - - disabled - description: Disable outbound network access. Always `disabled`. - default: disabled + - stdio + default: stdio x-stainless-const: true - type: object + 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 - BetaContainerMemoryLimit: - type: string - enum: - - 1g - - 4g - - 16g - - 64g - BetaLocalShellToolParam: + - command + - cwd + additionalProperties: false + description: Starts an MCP server as a local process. + McpTransportConfigParam: + description: The transport used to connect to an MCP server. + discriminator: + propertyName: type + mapping: + http: '#/components/schemas/McpTransportConfigParamHttp' + stdio: '#/components/schemas/McpTransportConfigParamStdio' + x-oai-discriminator-values: + - http + - stdio + anyOf: + - $ref: '#/components/schemas/McpTransportConfigParamHttp' + - $ref: '#/components/schemas/McpTransportConfigParamStdio' + AgentToolConfigParamMcp: + type: object properties: type: type: string enum: - - local_shell - description: The type of the local shell tool. Always `local_shell`. - default: local_shell + - mcp + default: mcp x-stainless-const: true - type: object + 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 - title: Local shell tool - description: A tool that allows the model to execute shell commands in a local environment. - BetaImageGenTool: + - server_label + - transport + additionalProperties: false + description: Tools provided by a remote MCP server. + AgentToolConfigParamWebSearch: type: object - title: Image generation tool - description: | - A tool that generates images using the GPT image models. properties: type: type: string enum: - - image_generation - description: | - The type of the image generation tool. Always `image_generation`. + - web_search + default: web_search x-stainless-const: true - model: + description: The type of the object. Always `web_search`. + mode: anyOf: - - type: string - - type: string - enum: - - gpt-image-1 - - gpt-image-1-mini - - gpt-image-2 - - gpt-image-2-2026-04-21 - - gpt-image-2.5-sunburst - - gpt-image-2.5-sunburst-2026-09-08 - - gpt-image-2.5-flare - - gpt-image-2.5-flare-2026-09-08 - - gpt-image-1.5 - - chatgpt-image-latest - description: | - The image generation model to use. One of `gpt-image-1`, - `gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`, - `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, - `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, - `gpt-image-2.5-flare-2026-09-08`, or `chatgpt-image-latest`. Default: - `gpt-image-1`. - default: gpt-image-1 - quality: - type: string - enum: - - low - - medium - - high - - xhigh - - max - - auto - description: | - The quality of the generated image. The GPT image models support `low`, - `medium`, and `high`. `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare`, - including their `2026-09-08` snapshots, also support `xhigh` and `max`. - Default: `auto`. - default: auto - size: + - $ref: '#/components/schemas/WebSearchModeParam' + - type: 'null' + description: The source used for web search results. Defaults to `live`. + context_size: anyOf: - - type: string - - type: string - enum: - - 1024x1024 - - 1024x1536 - - 1536x1024 - - auto - description: The size of the generated images. For `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, and `gpt-image-2.5-flare-2026-09-08`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - default: auto - output_format: - type: string - enum: - - png - - webp - - jpeg - description: | - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. - default: png - output_compression: - type: integer - minimum: 0 - maximum: 100 - description: | - Compression level for the output image. Default: 100. - default: 100 - moderation: - type: string - enum: - - auto - - low - description: | - Moderation level for the generated image. Default: `auto`. - default: auto - background: - type: string - enum: - - transparent - - opaque - - auto - description: | - Allows to set transparency for the background of the generated image(s). Must - be one of `transparent`, `opaque`, or `auto` (default value). When `auto` is - used, the model will automatically determine the best background for the - image. - - `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare`, including their - `2026-09-08` snapshots, support `opaque` and `transparent` backgrounds. - Transparent backgrounds are available for supported GPT Image models. For - `gpt-image-2` and `gpt-image-2-2026-04-21`, this support is in preview. When - using `transparent`, set the output format to `png` or `webp`. - default: auto - input_fidelity: + - $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/BetaInputFidelity' + - $ref: '#/components/schemas/WebSearchLocationParam' - type: 'null' - description: Controls fidelity to the original input image(s). This parameter is supported for GPT image models that support input fidelity. `gpt-image-2` and `gpt-image-2-2026-04-21` ignore this parameter. - input_image_mask: - type: object - description: | - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). - properties: - image_url: - type: string - description: | - Base64-encoded mask image. - file_id: - type: string - description: | - File ID for the mask image. - required: [] - additionalProperties: false - partial_images: - type: integer - minimum: 0 - maximum: 3 - description: | - Number of partial images to generate in streaming mode, from 0 (default value) to 3. - default: 0 - action: - description: | - Whether to generate a new image or edit an existing image. Default: `auto`. - $ref: '#/components/schemas/BetaImageGenActionEnum' + description: Approximate location used to localize search results. required: - type - BetaImageGenActionEnum: - type: string - enum: - - generate - - edit - - auto - BetaInputFidelity: - type: string - enum: - - high - - low - description: Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - BetaProgrammaticToolCallingParam: + additionalProperties: false + description: Web search. + AgentToolConfigParam: + description: A tool available to the agent. + 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 + anyOf: + - $ref: '#/components/schemas/AgentToolConfigParamFunction' + - $ref: '#/components/schemas/AgentToolConfigParamToolSearch' + - $ref: '#/components/schemas/AgentToolConfigParamProgrammaticToolCalling' + - $ref: '#/components/schemas/AgentToolConfigParamMcp' + - $ref: '#/components/schemas/AgentToolConfigParamWebSearch' + 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. + EnvironmentParamNone: + type: object properties: type: type: string enum: - - programmatic_tool_calling - description: The type of the tool. Always `programmatic_tool_calling`. - default: programmatic_tool_calling + - none + default: none x-stainless-const: true - type: object + description: The type of the object. Always `none`. required: - type - BetaCodeInterpreterTool: + additionalProperties: false + description: Runs the agent without an execution environment. + EnvironmentParamOpenaiHosted: type: object - title: Code interpreter - description: | - A tool that runs Python code to help generate a response to a prompt. properties: type: type: string enum: - - code_interpreter - description: | - The type of the code interpreter tool. Always `code_interpreter`. + - openai_hosted + default: openai_hosted x-stainless-const: true - container: - description: | - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + description: The type of the object. Always `openai_hosted`. + packages: anyOf: - - type: string - description: The container ID. - - $ref: '#/components/schemas/BetaAutoCodeInterpreterToolParam' - allowed_callers: + - $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: - - type: array - minItems: 1 - items: - $ref: '#/components/schemas/BetaCallableToolAllowedCaller' - description: The tool invocation context(s). + - $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 - - container - BetaAutoCodeInterpreterToolParam: + additionalProperties: false + description: An OpenAI-hosted environment, optionally based on a reusable template. + EnvironmentParamSelfHosted: + type: object properties: type: type: string enum: - - auto - description: Always `auto`. - default: auto + - self_hosted + default: self_hosted x-stainless-const: true - file_ids: + 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 - example: file-123 - type: array - maxItems: 50 - description: An optional list of uploaded files to make available to your code. - memory_limit: - anyOf: - - $ref: '#/components/schemas/BetaContainerMemoryLimit' - description: The memory limit for the code interpreter container. - - type: 'null' - network_policy: - discriminator: - propertyName: type - description: Network access policy for the container. - anyOf: - - $ref: '#/components/schemas/BetaContainerNetworkPolicyDisabledParam' - - $ref: '#/components/schemas/BetaContainerNetworkPolicyAllowlistParam' - type: object + minLength: 0 + maxLength: 1048576 + minItems: 0 + maxItems: 16384 + description: Directories that contain capabilities exposed to the agent. Defaults to an empty list. required: - type - title: CodeInterpreterToolAuto - description: Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - BetaMCPTool: + - workspace_directory + additionalProperties: false + description: An application-hosted environment configured inline. + EnvironmentParam: + description: The execution environment and optional reusable template for a session. + 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 + anyOf: + - $ref: '#/components/schemas/EnvironmentParamNone' + - $ref: '#/components/schemas/EnvironmentParamOpenaiHosted' + - $ref: '#/components/schemas/EnvironmentParamSelfHosted' + InputContentParamInputText: type: object - title: MCP tool - description: | - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://developers.openai.com/api/docs/guides/tools-connectors-mcp). properties: type: type: string enum: - - mcp - description: The type of the MCP tool. Always `mcp`. + - input_text + default: input_text x-stainless-const: true - server_label: - type: string - description: | - A label for this MCP server, used to identify it in tool calls. - server_url: + description: The type of the object. Always `input_text`. + text: type: string - format: uri - description: | - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. - connector_id: + minLength: 0 + maxLength: 1048576 + description: The text sent to the model. + required: + - type + - text + additionalProperties: false + description: Text input to the model. + InputContentParamInputImage: + type: object + properties: + type: type: string - deprecated: true enum: - - connector_dropbox - - connector_gmail - - connector_googlecalendar - - connector_googledrive - - connector_microsoftteams - - connector_outlookcalendar - - connector_outlookemail - - connector_sharepoint - description: | - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](https://developers.openai.com/api/docs/guides/tools-connectors-mcp#connectors). - - This field is deprecated for models released after September 1, 2026. - Use `server_url` to connect to a remote MCP server, or `tunnel_id` to - connect through a Secure MCP Tunnel. - - Currently supported `connector_id` values are: - - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` - tunnel_id: - type: string - pattern: ^tunnel_[a-z0-9]{32}$ - description: | - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. - authorization: - type: string - description: | - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. - server_description: + - input_image + default: input_image + x-stainless-const: true + description: The type of the object. Always `input_image`. + image_url: type: string - description: | - Optional description of the MCP server, used to provide more context. - headers: - anyOf: - - type: object - additionalProperties: - type: string - description: | - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. - - type: 'null' - allowed_tools: - anyOf: - - description: | - List of allowed tool names or a filter object. - anyOf: - - type: array - title: MCP allowed tools - description: A string array of allowed tool names - items: - type: string - - $ref: '#/components/schemas/BetaMCPToolFilter' - - type: 'null' - allowed_callers: - anyOf: - - type: array - minItems: 1 - items: - $ref: '#/components/schemas/BetaCallableToolAllowedCaller' - description: The tool invocation context(s). - - type: 'null' - require_approval: - anyOf: - - description: Specify which of the MCP server's tools require approval. - default: always - anyOf: - - type: object - title: MCP tool approval filter - description: | - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. - properties: - always: - $ref: '#/components/schemas/BetaMCPToolFilter' - never: - $ref: '#/components/schemas/BetaMCPToolFilter' - additionalProperties: false - - type: string - title: MCP tool approval setting - description: | - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. - enum: - - always - - never - - type: 'null' - defer_loading: - type: boolean - description: | - Whether this MCP tool is deferred and discovered via tool search. + minLength: 0 + maxLength: 1048576 + description: The URL of the image sent to the model. required: - type - - server_label - BetaMCPToolFilter: + - image_url + additionalProperties: false + description: Image input to the model. + InputContentParam: + description: Content included in an input message. + discriminator: + propertyName: type + mapping: + input_text: '#/components/schemas/InputContentParamInputText' + input_image: '#/components/schemas/InputContentParamInputImage' + x-oai-discriminator-values: + - input_text + - input_image + anyOf: + - $ref: '#/components/schemas/InputContentParamInputText' + - $ref: '#/components/schemas/InputContentParamInputImage' + InputMessageParam: type: object - title: MCP tool filter - description: | - A filter object to specify which tools are allowed. properties: - tool_names: + 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 - title: MCP allowed tools items: - type: string - description: List of allowed tool names. - read_only: - type: boolean - description: | - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. - required: [] + $ref: '#/components/schemas/InputContentParam' + minItems: 0 + maxItems: 16384 + description: The content of the message. + required: + - role + - content additionalProperties: false - BetaWebSearchTool: + description: A user message submitted to a session. + CreateSessionInputParam: + description: Initial input submitted when creating a session. + anyOf: + - type: string + minLength: 1 + maxLength: 1048576 + - type: array + items: + $ref: '#/components/schemas/InputMessageParam' + minItems: 0 + maxItems: 16384 + CreateAgentSessionParams: type: object - title: Web search - description: | - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://developers.openai.com/api/docs/guides/tools-web-search). properties: - type: + 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 - enum: - - web_search - - web_search_2025_08_26 - description: The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - default: web_search - external_web_access: - type: boolean - default: true - description: Allow live internet access for web search. Defaults to true when omitted. When false, the web search tool runs in offline/cache-only mode and will not fetch new external content. - filters: + 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: - - type: object - description: | - Filters for the search. - properties: - allowed_domains: - anyOf: - - type: array - title: Allowed domains for the search. - description: | - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. - - Example: `["pubmed.ncbi.nlm.nih.gov"]` - items: - type: string - description: Allowed domain for the search. - default: [] - - type: 'null' + - $ref: '#/components/schemas/CreateSessionInputParam' - type: 'null' - user_location: - $ref: '#/components/schemas/BetaWebSearchApproximateLocation' - search_context_size: + 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. + SessionErrorResource: + type: object + properties: + type: type: string - enum: - - low - - medium - - high - default: medium - description: High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + 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 - BetaWebSearchApproximateLocation: - anyOf: - - type: object - title: Web search approximate location - description: | - The approximate location of the user. - properties: - type: - type: string - enum: - - approximate - description: The type of location approximation. Always `approximate`. - default: approximate - x-stainless-const: true - country: - anyOf: - - type: string - description: The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - type: 'null' - region: - anyOf: - - type: string - description: Free text input for the region of the user, e.g. `California`. - - type: 'null' - city: - anyOf: - - type: string - description: Free text input for the city of the user, e.g. `San Francisco`. - - type: 'null' - timezone: - anyOf: - - type: string - description: The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - type: 'null' - - type: 'null' - BetaComputerUsePreviewTool: + - code + - message + - param + additionalProperties: false + description: An error payload with the same public fields as Responses API streaming errors. + SessionEventError: + type: object properties: type: type: string enum: - - computer_use_preview - description: The type of the computer use tool. Always `computer_use_preview`. - default: computer_use_preview + - error + default: error x-stainless-const: true - environment: - $ref: '#/components/schemas/BetaComputerEnvironment' - description: The type of computer environment to control. - display_width: - type: integer - description: The width of the computer display. - display_height: - type: integer - description: The height of the computer display. - type: object + 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 - - environment - - display_width - - display_height - title: Computer use preview - description: A tool that controls a virtual computer. Learn more about the [computer tool](https://developers.openai.com/api/docs/guides/tools-computer-use). - BetaComputerEnvironment: + - 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 + SessionEnvironmentStatusResource: type: string enum: - - windows - - mac - - linux - - ubuntu - - browser - BetaComputerTool: + - 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. + SessionEnvironmentErrorResource: + type: object properties: type: type: string - enum: - - computer - description: The type of the computer tool. Always `computer`. - default: computer - x-stainless-const: true - type: object + 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 - title: Computer - description: A tool that controls a virtual computer. Learn more about the [computer tool](https://developers.openai.com/api/docs/guides/tools-computer-use). - BetaFileSearchTool: + - code + - message + additionalProperties: false + description: An error reported while preparing a session environment. + SessionEnvironmentStateResource: + type: object properties: + id: + type: string + minLength: 0 + description: The public ID of the environment. type: type: string - enum: - - file_search - description: The type of the file search tool. Always `file_search`. - default: file_search - x-stainless-const: true - vector_store_ids: - items: - type: string - type: array - description: The IDs of the vector stores to search. - max_num_results: - type: integer - description: The maximum number of results to return. This number should be between 1 and 50 inclusive. - ranking_options: - $ref: '#/components/schemas/BetaRankingOptions' - description: Ranking options for search. - filters: + minLength: 0 + description: The environment type. + status: + $ref: '#/components/schemas/SessionEnvironmentStatusResource' + description: The environment's connection status. + error: anyOf: - - $ref: '#/components/schemas/BetaFilters' - description: A filter to apply. + - $ref: '#/components/schemas/SessionEnvironmentErrorResource' - type: 'null' - type: object + description: The error reported while preparing the environment, if any. required: + - id - type - - vector_store_ids - title: File search - description: A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://developers.openai.com/api/docs/guides/tools-file-search). - BetaFilters: - anyOf: - - $ref: '#/components/schemas/BetaComparisonFilter' - - $ref: '#/components/schemas/BetaCompoundFilter' - BetaCompoundFilter: - $recursiveAnchor: true - type: object + - status + - error additionalProperties: false - title: Compound Filter - description: Combine multiple filters using `and` or `or`. + description: The current state of a session environment. + SessionEventAgentSessionEnvironmentReady: + type: object properties: type: type: string - description: 'Type of operation: `and` or `or`.' enum: - - and - - or - filters: - type: array - description: Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - items: - discriminator: - propertyName: type - anyOf: - - $ref: '#/components/schemas/BetaComparisonFilter' - - $recursiveRef: '#' + - 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 - - filters - x-oaiMeta: - name: CompoundFilter - BetaComparisonFilter: + - event_id + - session_id + - turn_id + - environment + additionalProperties: false + description: Emitted when a hosted session environment is ready to connect. + BetaResponseSteerEvent: type: object + title: ResponseSteerEvent additionalProperties: false - title: Comparison Filter description: | - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + Queues user input to steer a response on this WebSocket connection. Input + can contain text, images, and files. Steering is supported only for + single-agent responses on models and execution modes that support steering. + Responses bound to a conversation or using automatic compaction do not + support steering. + + A `response.steer.accepted` event acknowledges that the server owns the + queued input, not that it has been applied. The successor's `response.created` + event is the commit point. Input that cannot be committed is returned in + `response.steer.failed`. + + Steering may cause the active response to finish at a safe output boundary + with `response.incomplete` and `incomplete_details.reason` set to `steered`, + followed automatically by a successor `response.created`. Normal completion + can also be followed by an automatic successor. Automatic successors inherit + the previous response's settings and continue from it with the queued input. + + If the response stops for client-owned tool output or approval, accepted + steering input remains queued and `response.steer.pending` is emitted after + `response.completed`. Fill the `required_input` stubs from that event with + saved tool results or approval decisions, and send one explicit + `response.create` per parent with the same `previous_response_id` and + WebSocket lane. Do not rerun tools or resend accepted steering input. The + queued input is prepended in submission order to that request's input, and + the explicit request retains its own settings. + + This event accepts only `type`, `previous_response_id`, and `input`. Do not + send `stream_id`; the target response determines the WebSocket lane. properties: type: type: string - default: eq enum: - - eq - - ne - - gt - - gte - - lt - - lte - - in - - nin - description: | - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in - key: + - response.steer + description: The event discriminator. Always `response.steer`. + x-stainless-const: true + previous_response_id: type: string - description: The key to compare against the value. - value: - description: The value to compare against the attribute key; supports string, number, or boolean types. - anyOf: - - type: string - - type: number - - type: boolean - - type: array - items: - $ref: '#/components/schemas/ComparisonFilterValueItems' + description: The ID of the response to steer on this WebSocket connection. + input: + $ref: '#/components/schemas/BetaResponseSteerInput' required: - type - - key - - value + - previous_response_id + - input x-oaiMeta: - name: ComparisonFilter - BetaRankingOptions: - properties: - ranker: - $ref: '#/components/schemas/BetaRankerVersionType' - description: The ranker to use for the file search. - score_threshold: - type: number - description: The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - hybrid_search: - $ref: '#/components/schemas/BetaHybridSearchOptions' - description: Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + name: response.steer + group: responses + example: | + { + "type": "response.steer", + "previous_response_id": "resp_123", + "input": [ + { + "type": "message", + "role": "user", + "content": [ + { + "type": "input_text", + "text": "Prioritize the database rollout." + } + ] + } + ] + } + SessionEventAgentOutputCommandExecutionOutputDelta: type: object - required: [] - BetaHybridSearchOptions: properties: - embedding_weight: - type: number - description: The weight of the embedding in the reciprocal ranking fusion. - text_weight: - type: number - description: The weight of the text in the reciprocal ranking fusion. - type: object + 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: - - embedding_weight - - text_weight - BetaRankerVersionType: - type: string - enum: - - auto - - default-2024-11-15 - BetaFunctionTool: + - type + - event_id + - session_id + - turn_id + - item_id + - output_index + - delta + additionalProperties: false + description: Emitted when command execution produces an output delta. + SessionEventAgentSessionCreated: + type: object properties: type: type: string enum: - - function - description: The type of the function tool. Always `function`. - default: function + - agent.session.created + default: agent.session.created x-stainless-const: true - name: + description: The type of the object. Always `agent.session.created`. + event_id: type: string - description: The name of the function to call. - async: - type: boolean - description: - anyOf: - - type: string - description: A description of the function. Used by the model to determine whether or not to call the function. - - type: 'null' - parameters: - anyOf: - - additionalProperties: {} - type: object - description: A JSON schema object describing the parameters of the function. - x-oaiTypeLabel: map - - type: 'null' - output_schema: - anyOf: - - additionalProperties: {} - type: object - description: A JSON schema object describing the JSON value encoded in string outputs for this function. - x-oaiTypeLabel: map - - type: 'null' - strict: - anyOf: - - type: boolean - description: Whether strict parameter validation is enforced for this function tool. - - type: 'null' - defer_loading: - type: boolean - description: Whether this function is deferred and loaded via tool search. - allowed_callers: - anyOf: - - items: - $ref: '#/components/schemas/BetaCallableToolAllowedCaller' - type: array - description: The tool invocation context(s). - - type: 'null' - type: object + minLength: 0 + description: The unique ID of the event. + session: + $ref: '#/components/schemas/SessionResource' + description: The session that was created. required: - type - - name - - strict - - parameters - title: Function - description: Defines a function in your own code the model can choose to call. Learn more about [function calling](https://developers.openai.com/api/docs/guides/function-calling). - BetaInputItem: - discriminator: - propertyName: type - anyOf: - - $ref: '#/components/schemas/BetaEasyInputMessage' - - type: object - title: Item - description: | - An item representing part of the context for the response to be - generated by the model. Can contain text, images, and audio inputs, - as well as previous assistant responses and tool call outputs. - $ref: '#/components/schemas/BetaItem' - - $ref: '#/components/schemas/BetaCompactionTriggerItemParam' - - $ref: '#/components/schemas/BetaItemReferenceParam' - - $ref: '#/components/schemas/BetaProgramItemParam' - - $ref: '#/components/schemas/BetaProgramOutputItemParam' - BetaProgramOutputItemParam: + - event_id + - session + additionalProperties: false + description: Emitted when a session is created. + SessionEventAgentSessionTurnCreated: + type: object properties: - agent: - anyOf: - - $ref: '#/components/schemas/Beta_AgentTagParam' - description: The agent that produced this item. - - type: 'null' - id: - type: string - description: The unique ID of this program output item. - example: cmo_123 type: type: string enum: - - program_output - description: The item type. Always `program_output`. - default: program_output + - agent.session.turn.created + default: agent.session.turn.created x-stainless-const: true - call_id: + description: The type of the object. Always `agent.session.turn.created`. + event_id: type: string - maxLength: 64 - minLength: 1 - description: The call ID of the program item. - result: + minLength: 0 + description: The unique ID of the event. + session_id: type: string - maxLength: 10485760 - description: The result produced by the program item. - status: - $ref: '#/components/schemas/BetaProgramOutputItemStatus' - description: The terminal status of the program output. - type: object + 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: - - id - type - - call_id - - result - - status - BetaProgramOutputItemStatus: - type: string - enum: - - completed - - incomplete - Beta_AgentTagParam: - properties: - agent_name: - type: string - description: The canonical name of the agent that produced this item. + - event_id + - session_id + - turn_id + - turn + additionalProperties: false + description: Emitted when a turn is created. + SessionEventAgentSessionTurnInProgress: type: object - required: - - agent_name - description: The agent that produced this item. - x-oai-beta: responses_multi_agent=v1 - BetaProgramItemParam: properties: - agent: - anyOf: - - $ref: '#/components/schemas/Beta_AgentTagParam' - description: The agent that produced this item. - - type: 'null' - id: - type: string - description: The unique ID of this program item. - example: cm_123 type: type: string enum: - - program - description: The item type. Always `program`. - default: program + - agent.session.turn.in_progress + default: agent.session.turn.in_progress x-stainless-const: true - call_id: + description: The type of the object. Always `agent.session.turn.in_progress`. + event_id: type: string - maxLength: 64 - minLength: 1 - description: The stable call ID of the program item. - code: + minLength: 0 + description: The unique ID of the event. + session_id: type: string - maxLength: 10485760 - description: The JavaScript source executed by programmatic tool calling. - fingerprint: + minLength: 0 + description: The ID of the session associated with the event. + turn_id: type: string - maxLength: 10485760 - description: Opaque program replay fingerprint that must be round-tripped. - type: object + 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: - - id - type - - call_id - - code - - fingerprint - BetaItemReferenceParam: - properties: - agent: - anyOf: - - $ref: '#/components/schemas/Beta_AgentTagParam' - description: The agent that produced this item. - - type: 'null' - type: - anyOf: - - type: string - enum: - - item_reference - description: The type of item to reference. Always `item_reference`. - default: item_reference - x-stainless-const: true - - type: 'null' - id: - type: string - description: The ID of the item to reference. + - event_id + - session_id + - turn_id + - turn + additionalProperties: false + description: Emitted when a turn starts running. + SessionEventAgentSessionTurnCompleted: type: object - required: - - id - title: Item reference - description: An internal identifier for an item to reference. - BetaCompactionTriggerItemParam: properties: - agent: - anyOf: - - $ref: '#/components/schemas/Beta_AgentTagParam' - description: The agent that produced this item. - - type: 'null' type: type: string enum: - - compaction_trigger - description: The type of the item. Always `compaction_trigger`. - default: compaction_trigger + - agent.session.turn.completed + default: agent.session.turn.completed x-stainless-const: true - type: object + 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 - title: Compaction trigger - description: Compacts the current context. Must be the final input item. - BetaItem: - type: object - description: | - Content item used to generate a response. - discriminator: - propertyName: type - anyOf: - - $ref: '#/components/schemas/BetaInputMessage' - - $ref: '#/components/schemas/BetaOutputMessage' - - $ref: '#/components/schemas/BetaFileSearchToolCall' - - $ref: '#/components/schemas/BetaComputerToolCall' - - $ref: '#/components/schemas/BetaComputerCallOutputItemParam' - - $ref: '#/components/schemas/BetaWebSearchToolCall' - - $ref: '#/components/schemas/BetaFunctionToolCall' - - $ref: '#/components/schemas/BetaFunctionCallOutputItemParam' - - $ref: '#/components/schemas/BetaAgentMessageItemParam' - - $ref: '#/components/schemas/BetaMultiAgentCallItemParam' - - $ref: '#/components/schemas/BetaMultiAgentCallOutputItemParam' - - $ref: '#/components/schemas/BetaToolSearchCallItemParam' - - $ref: '#/components/schemas/BetaToolSearchOutputItemParam' - - $ref: '#/components/schemas/BetaAdditionalToolsItemParam' - - $ref: '#/components/schemas/BetaResponseConfigurationUpdateItemParam' - - $ref: '#/components/schemas/BetaReasoningItem' - - $ref: '#/components/schemas/BetaCompactionSummaryItemParam' - - $ref: '#/components/schemas/BetaImageGenToolCall' - - $ref: '#/components/schemas/BetaCodeInterpreterToolCall' - - $ref: '#/components/schemas/BetaLocalShellToolCall' - - $ref: '#/components/schemas/BetaLocalShellToolCallOutput' - - $ref: '#/components/schemas/BetaFunctionShellCallItemParam' - - $ref: '#/components/schemas/BetaFunctionShellCallOutputItemParam' - - $ref: '#/components/schemas/BetaApplyPatchToolCallItemParam' - - $ref: '#/components/schemas/BetaApplyPatchToolCallOutputItemParam' - - $ref: '#/components/schemas/BetaMCPListTools' - - $ref: '#/components/schemas/BetaMCPApprovalRequest' - - $ref: '#/components/schemas/BetaMCPApprovalResponse' - - $ref: '#/components/schemas/BetaMCPToolCall' - - $ref: '#/components/schemas/BetaCustomToolCallOutput' - - $ref: '#/components/schemas/BetaCustomToolCall' - BetaCustomToolCall: + - event_id + - session_id + - turn_id + - turn + - usage + additionalProperties: false + description: Emitted when a turn completes. + SessionEventAgentSessionTurnFailed: type: object - title: Custom tool call - description: | - A call to a custom tool created by the model. properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that produced this item. type: type: string enum: - - custom_tool_call + - agent.session.turn.failed + default: agent.session.turn.failed x-stainless-const: true - description: | - The type of the custom tool call. Always `custom_tool_call`. - id: + description: The type of the object. Always `agent.session.turn.failed`. + event_id: type: string - description: | - The unique ID of the custom tool call in the OpenAI platform. - call_id: + minLength: 0 + description: The unique ID of the event. + session_id: type: string - description: | - An identifier used to map this custom tool call to a tool call output. - caller: + 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/BetaToolCallCaller' + - $ref: '#/components/schemas/TokenUsageResource' - type: 'null' - namespace: - type: string - description: | - The namespace of the custom tool being called. - name: - type: string - description: | - The name of the custom tool being called. - input: - type: string - description: | - The input for the custom tool call generated by the model. - async: - type: boolean - description: | - Whether the custom tool call runs asynchronously. + description: Token usage by the root agent during the turn, when available. required: - type - - call_id - - name - - input - BetaToolCallCaller: - discriminator: - propertyName: type - description: The execution context that produced this tool call. - anyOf: - - $ref: '#/components/schemas/BetaDirectToolCallCaller' - - $ref: '#/components/schemas/BetaProgramToolCallCaller' - BetaProgramToolCallCaller: + - event_id + - session_id + - turn_id + - turn + - usage + additionalProperties: false + description: Emitted when a turn fails. + SessionEventAgentSessionTurnCancelled: + type: object properties: type: type: string enum: - - program - default: program + - agent.session.turn.cancelled + default: agent.session.turn.cancelled x-stainless-const: true - caller_id: + description: The type of the object. Always `agent.session.turn.cancelled`. + event_id: type: string - description: The call ID of the program item that produced this tool call. - type: object + 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 - - caller_id - BetaDirectToolCallCaller: + - event_id + - session_id + - turn_id + - turn + - usage + additionalProperties: false + description: Emitted when a turn is cancelled. + SessionEventAgentSessionTurnItemAdded: + type: object properties: type: type: string enum: - - direct - default: direct + - agent.session.turn.item.added + default: agent.session.turn.item.added x-stainless-const: true - type: object - required: - - type - BetaAgentTag: - properties: - agent_name: + description: The type of the object. Always `agent.session.turn.item.added`. + event_id: type: string - description: The canonical name of the agent that produced this item. - type: object + 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: - - agent_name - x-oai-beta: responses_multi_agent=v1 - BetaCustomToolCallOutput: + - type + - event_id + - session_id + - turn_id + - output_index + - item + additionalProperties: false + description: Emitted when an item is added to a turn. + SessionEventAgentSessionIdle: type: object - title: Custom tool call output - description: | - The output of a custom tool call from your code, being sent back to the model. properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that produced this item. type: type: string enum: - - custom_tool_call_output + - agent.session.idle + default: agent.session.idle x-stainless-const: true - description: | - The type of the custom tool call output. Always `custom_tool_call_output`. - id: - type: string - description: | - The unique ID of the custom tool call output in the OpenAI platform. - call_id: + description: The type of the object. Always `agent.session.idle`. + event_id: type: string - description: | - The call ID, used to map this custom tool call output to a custom tool call. - caller: - anyOf: - - $ref: '#/components/schemas/BetaToolCallCallerParam' - - type: 'null' - output: - description: | - The output from the custom tool call generated by your code. - Can be a string or an list of output content. - anyOf: - - type: string - description: | - A string of the output of the custom tool call. - title: string output - - type: array - items: - $ref: '#/components/schemas/BetaFunctionAndCustomToolCallOutput' - title: output content list - description: | - Text, image, or file output of the custom tool call. + minLength: 0 + description: The unique ID of the event. + session: + $ref: '#/components/schemas/SessionResource' + description: The session that became idle. required: - type - - call_id - - output - BetaFunctionAndCustomToolCallOutput: - discriminator: - propertyName: type - anyOf: - - $ref: '#/components/schemas/BetaInputTextContent' - - $ref: '#/components/schemas/BetaInputImageContent' - - $ref: '#/components/schemas/BetaInputFileContent' - BetaInputFileContent: + - event_id + - session + additionalProperties: false + description: Emitted when a session becomes idle. + SessionEventAgentSessionInProgress: + type: object properties: type: type: string enum: - - input_file - description: The type of the input item. Always `input_file`. - default: input_file + - agent.session.in_progress + default: agent.session.in_progress x-stainless-const: true - file_id: - anyOf: - - type: string - description: The ID of the file to be sent to the model. - - type: 'null' - filename: - type: string - description: The name of the file to be sent to the model. - file_data: - type: string - description: | - The content of the file to be sent to the model. - prompt_cache_breakpoint: - $ref: '#/components/schemas/BetaPromptCacheBreakpointConfig' - file_url: + description: The type of the object. Always `agent.session.in_progress`. + event_id: type: string - format: uri - description: The URL of the file to be sent to the model. - detail: - $ref: '#/components/schemas/BetaFileInputDetail' - description: The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - type: object + minLength: 0 + description: The unique ID of the event. + session: + $ref: '#/components/schemas/SessionResource' + description: The session that started processing. required: - type - title: Input file - description: A file input to the model. - BetaFileInputDetail: - type: string - enum: - - auto - - low - - high - BetaPromptCacheBreakpointConfig: + - event_id + - session + additionalProperties: false + description: Emitted when a session starts processing a turn. + SessionEventAgentSessionRequiresAction: + type: object properties: - mode: + type: type: string enum: - - explicit - description: The breakpoint mode. Always `explicit`. - default: explicit + - agent.session.requires_action + default: agent.session.requires_action x-stainless-const: true - type: object + 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: - - mode - title: Prompt cache breakpoint - description: Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - BetaInputImageContent: + - type + - event_id + - session + additionalProperties: false + description: Emitted when a session is waiting for one or more required actions. + SessionEventAgentSessionFailed: + type: object properties: type: type: string enum: - - input_image - description: The type of the input item. Always `input_image`. - default: input_image + - agent.session.failed + default: agent.session.failed x-stainless-const: true - image_url: - anyOf: - - type: string - format: uri - description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - type: 'null' - file_id: - anyOf: - - type: string - description: The ID of the file to be sent to the model. - - type: 'null' - detail: - $ref: '#/components/schemas/BetaImageDetail' - description: The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - prompt_cache_breakpoint: - $ref: '#/components/schemas/BetaPromptCacheBreakpointConfig' - type: object + 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 - - detail - title: Input image - description: An image input to the model. Learn about [image inputs](https://developers.openai.com/api/docs/guides/images-vision). - BetaImageDetail: - type: string - enum: - - low - - high - - auto - - original - BetaInputTextContent: + - event_id + - session + additionalProperties: false + description: Emitted when a session fails. + SessionEventAgentSessionEnvironmentPending: + type: object properties: type: type: string enum: - - input_text - description: The type of the input item. Always `input_text`. - default: input_text + - agent.session.environment.pending + default: agent.session.environment.pending x-stainless-const: true - text: + description: The type of the object. Always `agent.session.environment.pending`. + event_id: type: string - description: The text input to the model. - prompt_cache_breakpoint: - $ref: '#/components/schemas/BetaPromptCacheBreakpointConfig' - type: object + 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 - - text - title: Input text - description: A text input to the model. - BetaToolCallCallerParam: - discriminator: - propertyName: type - description: The execution context that produced this tool call. - anyOf: - - $ref: '#/components/schemas/BetaDirectToolCallCallerParam' - - $ref: '#/components/schemas/BetaProgramToolCallCallerParam' - BetaProgramToolCallCallerParam: + - event_id + - session_id + - turn_id + - environment + additionalProperties: false + description: Emitted while a session environment is being prepared. + SessionEventAgentSessionEnvironmentConnected: + type: object properties: type: type: string enum: - - program - description: The caller type. Always `program`. - default: program + - agent.session.environment.connected + default: agent.session.environment.connected x-stainless-const: true - caller_id: + description: The type of the object. Always `agent.session.environment.connected`. + event_id: type: string - maxLength: 64 - minLength: 1 - description: The call ID of the program item that produced this tool call. - type: object + 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 - - caller_id - BetaDirectToolCallCallerParam: + - event_id + - session_id + - turn_id + - environment + additionalProperties: false + description: Emitted when a session environment connects. + SessionEventAgentSessionEnvironmentDisconnected: + type: object properties: type: type: string enum: - - direct - description: The caller type. Always `direct`. - default: direct + - agent.session.environment.disconnected + default: agent.session.environment.disconnected x-stainless-const: true - type: object + 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 - BetaMCPToolCall: + - event_id + - session_id + - turn_id + - environment + additionalProperties: false + description: Emitted when a session environment disconnects. + SessionEventAgentSessionEnvironmentFailed: type: object - title: MCP tool call - description: | - An invocation of a tool on an MCP server. properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that produced this item. type: type: string enum: - - mcp_call - description: | - The type of the item. Always `mcp_call`. + - agent.session.environment.failed + default: agent.session.environment.failed x-stainless-const: true - id: - type: string - description: | - The unique ID of the tool call. - server_label: - type: string - description: | - The label of the MCP server running the tool. - name: + description: The type of the object. Always `agent.session.environment.failed`. + event_id: type: string - description: | - The name of the tool that was run. - arguments: + minLength: 0 + description: The unique ID of the event. + session_id: type: string - description: | - A JSON string of the arguments passed to the tool. - output: - anyOf: - - type: string - description: | - The output from the tool call. - - type: 'null' - error: - description: The error from the tool call, if any. - anyOf: - - $ref: '#/components/schemas/BetaMCPToolCallError' - - type: 'null' - status: - $ref: '#/components/schemas/BetaMCPToolCallStatus' - description: | - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - approval_request_id: - anyOf: - - type: string - description: | - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - type: 'null' + 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 - - id - - server_label - - name - - arguments - BetaMCPToolCallStatus: - type: string - enum: - - in_progress - - completed - - incomplete - - calling - - failed - BetaMCPToolCallError: - discriminator: - propertyName: type - anyOf: - - $ref: '#/components/schemas/BetaMCPProtocolError' - - $ref: '#/components/schemas/BetaMCPToolExecutionError' - - $ref: '#/components/schemas/BetaHTTPError' - BetaHTTPError: + - event_id + - session_id + - turn_id + - environment + additionalProperties: false + description: Emitted when a session environment fails. + SessionEventAgentSessionSubagentCreated: + type: object properties: type: type: string enum: - - http_error - default: http_error + - agent.session.subagent.created + default: agent.session.subagent.created x-stainless-const: true - code: - type: integer - message: + description: The type of the object. Always `agent.session.subagent.created`. + event_id: type: string - type: object + minLength: 0 + description: The unique ID of the event. + subagent: + $ref: '#/components/schemas/SubagentResource' + description: The subagent that was created. required: - type - - code - - message - BetaMCPToolExecutionError: + - event_id + - subagent + additionalProperties: false + description: Emitted when a subagent is created. + SessionEventAgentSessionSubagentActive: + type: object properties: type: type: string enum: - - mcp_tool_execution_error - default: mcp_tool_execution_error + - agent.session.subagent.active + default: agent.session.subagent.active x-stainless-const: true - content: {} - type: object + 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 - - content - BetaMCPProtocolError: + - event_id + - subagent + additionalProperties: false + description: Emitted when a closed subagent successfully resumes. + SessionEventAgentSessionSubagentClosed: + type: object properties: type: type: string enum: - - mcp_protocol_error - default: mcp_protocol_error + - agent.session.subagent.closed + default: agent.session.subagent.closed x-stainless-const: true - code: - type: integer - message: + description: The type of the object. Always `agent.session.subagent.closed`. + event_id: type: string - type: object + minLength: 0 + description: The unique ID of the event. + subagent: + $ref: '#/components/schemas/SubagentResource' + description: The subagent that was closed. required: - type - - code - - message - BetaMCPApprovalResponse: + - event_id + - subagent + additionalProperties: false + description: Emitted when a subagent is closed. + AssistantMessageItemResource: type: object - title: MCP approval response - description: | - A response to an MCP approval request. properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that produced this item. type: type: string enum: - - mcp_approval_response - description: | - The type of the item. Always `mcp_approval_response`. + - message + default: message x-stainless-const: true + description: The item type. Always `message`. id: - anyOf: - - type: string - description: | - The unique ID of the approval response - - type: 'null' - approval_request_id: type: string - description: | - The ID of the approval request being answered. - approve: - type: boolean - description: | - Whether the request was approved. - reason: + 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: - - type: string - description: | - Optional reason for the decision. + - $ref: '#/components/schemas/MessagePhaseResource' - type: 'null' + description: The phase of the assistant message. required: - type - - request_id - - approve - - approval_request_id - BetaMCPApprovalRequest: + - id + - turn_id + - role + - status + - content + - phase + additionalProperties: false + description: An assistant message produced by the agent. + AgentOutputItemResource: + description: An output item produced by an agent. + 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 + anyOf: + - $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' + SessionEventAgentSessionTurnItemDone: type: object - title: MCP approval request - description: | - A request for human approval of a tool invocation. properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that produced this item. type: type: string enum: - - mcp_approval_request - description: | - The type of the item. Always `mcp_approval_request`. + - agent.session.turn.item.done + default: agent.session.turn.item.done x-stainless-const: true - id: - type: string - description: | - The unique ID of the approval request. - server_label: - type: string - description: | - The label of the MCP server making the request. - name: + description: The type of the object. Always `agent.session.turn.item.done`. + event_id: type: string - description: | - The name of the tool to run. - arguments: + minLength: 0 + description: The unique ID of the event. + session_id: type: string - description: | - A JSON string of arguments for the tool. + 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 - - id - - server_label - - name - - arguments - BetaMCPListTools: - type: object - title: MCP list tools - description: | - A list of tools available on an MCP server. + - event_id + - session_id + - turn_id + - output_index + - item + additionalProperties: false + description: Emitted when an output item is complete. + SessionEventAgentSessionTurnContentPartAdded: + type: object properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that produced this item. type: type: string enum: - - mcp_list_tools - description: | - The type of the item. Always `mcp_list_tools`. + - agent.session.turn.content_part.added + default: agent.session.turn.content_part.added x-stainless-const: true - id: + description: The type of the object. Always `agent.session.turn.content_part.added`. + event_id: type: string - description: | - The unique ID of the list. - server_label: + minLength: 0 + description: The unique ID of the event. + session_id: type: string - description: | - The label of the MCP server. - tools: - type: array - items: - $ref: '#/components/schemas/BetaMCPListToolsTool' - description: | - The tools available on the server. - error: - anyOf: - - type: string - description: | - Error message if the server could not list tools. - - type: 'null' + 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 - - id - - server_label - - tools - BetaMCPListToolsTool: + - 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. + SessionEventAgentSessionTurnContentPartDone: type: object - title: MCP list tools tool - description: | - A tool available on an MCP server. - properties: - name: - type: string - description: | - The name of the tool. - description: - anyOf: - - type: string - description: | - The description of the tool. - - type: 'null' - input_schema: - type: object - description: | - The JSON schema describing the tool's input. - annotations: - anyOf: - - type: object - description: | - Additional annotations about the tool. - - type: 'null' - required: - - name - - input_schema - BetaApplyPatchToolCallOutputItemParam: properties: - agent: - anyOf: - - $ref: '#/components/schemas/Beta_AgentTagParam' - description: The agent that produced this item. - - type: 'null' type: type: string enum: - - apply_patch_call_output - description: The type of the item. Always `apply_patch_call_output`. - default: apply_patch_call_output + - agent.session.turn.content_part.done + default: agent.session.turn.content_part.done x-stainless-const: true - id: - anyOf: - - type: string - description: The unique ID of the apply patch tool call output. Populated when this item is returned via API. - example: apco_123 - - type: 'null' - call_id: + description: The type of the object. Always `agent.session.turn.content_part.done`. + event_id: type: string - maxLength: 64 - minLength: 1 - description: The unique ID of the apply patch tool call generated by the model. - caller: - anyOf: - - $ref: '#/components/schemas/BetaToolCallCallerParam' - description: The execution context that produced this tool call. - - type: 'null' - status: - $ref: '#/components/schemas/BetaApplyPatchCallOutputStatusParam' - description: The status of the apply patch tool call output. One of `completed` or `failed`. - output: - anyOf: - - type: string - maxLength: 10485760 - description: Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - - type: 'null' - type: object + 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 - - call_id - - status - title: Apply patch tool call output - description: The streamed output emitted by an apply patch tool call. - BetaApplyPatchCallOutputStatusParam: - type: string - enum: - - completed - - failed - title: Apply patch call output status - description: Outcome values reported for apply_patch tool call outputs. - BetaApplyPatchToolCallItemParam: + - event_id + - session_id + - turn_id + - item_id + - output_index + - content_index + - part + additionalProperties: false + description: Emitted when an output content part is complete. + SessionEventAgentSessionTurnOutputTextDelta: + type: object properties: - agent: - anyOf: - - $ref: '#/components/schemas/Beta_AgentTagParam' - description: The agent that produced this item. - - type: 'null' type: type: string enum: - - apply_patch_call - description: The type of the item. Always `apply_patch_call`. - default: apply_patch_call + - agent.session.turn.output_text.delta + default: agent.session.turn.output_text.delta x-stainless-const: true - id: - anyOf: - - type: string - description: The unique ID of the apply patch tool call. Populated when this item is returned via API. - example: apc_123 - - type: 'null' - call_id: + description: The type of the object. Always `agent.session.turn.output_text.delta`. + event_id: type: string - maxLength: 64 - minLength: 1 - description: The unique ID of the apply patch tool call generated by the model. - caller: - anyOf: - - $ref: '#/components/schemas/BetaToolCallCallerParam' - description: The execution context that produced this tool call. - - type: 'null' - status: - $ref: '#/components/schemas/BetaApplyPatchCallStatusParam' - description: The status of the apply patch tool call. One of `in_progress` or `completed`. - operation: - $ref: '#/components/schemas/BetaApplyPatchOperationParam' - description: The specific create, delete, or update instruction for the apply_patch tool call. - type: object + 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 - - call_id - - status - - operation - title: Apply patch tool call - description: A tool call representing a request to create, delete, or update files using diff patches. - BetaApplyPatchOperationParam: - discriminator: - propertyName: type - title: Apply patch operation - description: One of the create_file, delete_file, or update_file operations supplied to the apply_patch tool. - anyOf: - - $ref: '#/components/schemas/BetaApplyPatchCreateFileOperationParam' - - $ref: '#/components/schemas/BetaApplyPatchDeleteFileOperationParam' - - $ref: '#/components/schemas/BetaApplyPatchUpdateFileOperationParam' - BetaApplyPatchUpdateFileOperationParam: + - 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. + SessionEventAgentSessionTurnOutputTextDone: + type: object properties: type: type: string enum: - - update_file - description: The operation type. Always `update_file`. - default: update_file + - agent.session.turn.output_text.done + default: agent.session.turn.output_text.done x-stainless-const: true - path: + description: The type of the object. Always `agent.session.turn.output_text.done`. + event_id: type: string - minLength: 1 - description: Path of the file to update relative to the workspace root. - diff: + minLength: 0 + description: The unique ID of the event. + session_id: type: string - maxLength: 10485760 - description: Unified diff content to apply to the existing file. - type: object + 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 - - path - - diff - title: Apply patch update file operation - description: Instruction for updating an existing file via the apply_patch tool. - BetaApplyPatchDeleteFileOperationParam: + - 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. + SessionEventAgentSessionTurnReasoningSummaryPartAdded: + type: object properties: type: type: string enum: - - delete_file - description: The operation type. Always `delete_file`. - default: delete_file + - agent.session.turn.reasoning_summary_part.added + default: agent.session.turn.reasoning_summary_part.added x-stainless-const: true - path: + description: The type of the object. Always `agent.session.turn.reasoning_summary_part.added`. + event_id: type: string - minLength: 1 - description: Path of the file to delete relative to the workspace root. - type: object + 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 - - path - title: Apply patch delete file operation - description: Instruction for deleting an existing file via the apply_patch tool. - BetaApplyPatchCreateFileOperationParam: + - 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. + SessionEventAgentSessionTurnReasoningSummaryPartDone: + type: object properties: type: type: string enum: - - create_file - description: The operation type. Always `create_file`. - default: create_file + - agent.session.turn.reasoning_summary_part.done + default: agent.session.turn.reasoning_summary_part.done x-stainless-const: true - path: - type: string - minLength: 1 - description: Path of the file to create relative to the workspace root. - diff: + description: The type of the object. Always `agent.session.turn.reasoning_summary_part.done`. + event_id: type: string - maxLength: 10485760 - description: Unified diff content to apply when creating the file. - type: object - required: - - type - - path - - diff - title: Apply patch create file operation - description: Instruction for creating a new file via the apply_patch tool. - BetaApplyPatchCallStatusParam: - type: string - enum: - - in_progress - - completed - title: Apply patch call status - description: Status values reported for apply_patch tool calls. - BetaFunctionShellCallOutputItemParam: - properties: - agent: - anyOf: - - $ref: '#/components/schemas/Beta_AgentTagParam' - description: The agent that produced this item. - - type: 'null' - id: - anyOf: - - type: string - description: The unique ID of the shell tool call output. Populated when this item is returned via API. - example: sho_123 - - type: 'null' - call_id: + minLength: 0 + description: The unique ID of the event. + session_id: type: string - maxLength: 64 - minLength: 1 - description: The unique ID of the shell tool call generated by the model. - caller: - anyOf: - - $ref: '#/components/schemas/BetaToolCallCallerParam' - description: The execution context that produced this tool call. - - type: 'null' - type: + 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: - - shell_call_output - description: The type of the item. Always `shell_call_output`. - default: shell_call_output + - incomplete + - null + description: Present as `incomplete` when summary generation was interrupted. x-stainless-const: true - output: - items: - $ref: '#/components/schemas/BetaFunctionShellCallOutputContentParam' - type: array - description: Captured chunks of stdout and stderr output, along with their associated outcomes. - status: - anyOf: - - $ref: '#/components/schemas/BetaFunctionShellCallItemStatus' - description: The status of the shell call output. - - type: 'null' - max_output_length: - anyOf: - - type: integer - description: The maximum number of UTF-8 characters captured for this shell call's combined output. - - type: 'null' - type: object required: - - call_id - type - - output - title: Shell tool call output - description: The streamed output items emitted by a shell tool call. - BetaFunctionShellCallItemStatus: - type: string - enum: - - in_progress - - completed - - incomplete - title: Shell call status - description: Status values reported for shell tool calls. - BetaFunctionShellCallOutputContentParam: - properties: - stdout: - type: string - maxLength: 10485760 - description: Captured stdout output for the shell call. - stderr: - type: string - maxLength: 10485760 - description: Captured stderr output for the shell call. - outcome: - $ref: '#/components/schemas/BetaFunctionShellCallOutputOutcomeParam' - description: The exit or timeout outcome associated with this shell call. + - 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. + SessionEventAgentSessionTurnReasoningSummaryTextDelta: type: object - required: - - stdout - - stderr - - outcome - title: Shell output content - description: Captured stdout and stderr for a portion of a shell tool call output. - BetaFunctionShellCallOutputOutcomeParam: - discriminator: - propertyName: type - title: Shell call outcome - description: The exit or timeout outcome associated with this shell call. - anyOf: - - $ref: '#/components/schemas/BetaFunctionShellCallOutputTimeoutOutcomeParam' - - $ref: '#/components/schemas/BetaFunctionShellCallOutputExitOutcomeParam' - BetaFunctionShellCallOutputExitOutcomeParam: properties: type: type: string enum: - - exit - description: The outcome type. Always `exit`. - default: exit + - agent.session.turn.reasoning_summary_text.delta + default: agent.session.turn.reasoning_summary_text.delta x-stainless-const: true - exit_code: + 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 - description: The exit code returned by the shell process. - type: object + 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 - - exit_code - title: Shell call exit outcome - description: Indicates that the shell commands finished and returned an exit code. - BetaFunctionShellCallOutputTimeoutOutcomeParam: + - 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. + SessionEventAgentSessionTurnReasoningSummaryTextDone: + type: object properties: type: type: string enum: - - timeout - description: The outcome type. Always `timeout`. - default: timeout + - agent.session.turn.reasoning_summary_text.done + default: agent.session.turn.reasoning_summary_text.done x-stainless-const: true - type: object + 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 - title: Shell call timeout outcome - description: Indicates that the shell call exceeded its configured time limit. - BetaFunctionShellCallItemParam: + - 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. + SessionEvent: + description: An event emitted by a Managed Agents session. + discriminator: + propertyName: type + mapping: + error: '#/components/schemas/SessionEventError' + agent.session.environment.ready: '#/components/schemas/SessionEventAgentSessionEnvironmentReady' + agent.session.turn.reasoning_summary_text.done: '#/components/schemas/SessionEventAgentSessionTurnReasoningSummaryTextDone' + 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' + x-oai-discriminator-values: + - error + - agent.session.environment.ready + - 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 + anyOf: + - $ref: '#/components/schemas/SessionEventError' + - $ref: '#/components/schemas/SessionEventAgentSessionEnvironmentReady' + - $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' + UpdateSessionReasoningParam: + type: object properties: - agent: - anyOf: - - $ref: '#/components/schemas/Beta_AgentTagParam' - description: The agent that produced this item. - - type: 'null' - id: - anyOf: - - type: string - description: The unique ID of the shell tool call. Populated when this item is returned via API. - example: sh_123 - - type: 'null' - call_id: - type: string - maxLength: 64 - minLength: 1 - description: The unique ID of the shell tool call generated by the model. - caller: + effort: anyOf: - - $ref: '#/components/schemas/BetaToolCallCallerParam' - description: The execution context that produced this tool call. + - $ref: '#/components/schemas/ReasoningEffortParam' - type: 'null' - type: + 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. + UpdateSessionAgentParam: + type: object + properties: + model: type: string - enum: - - shell_call - description: The type of the item. Always `shell_call`. - default: shell_call - x-stainless-const: true - action: - $ref: '#/components/schemas/BetaFunctionShellActionParam' - description: The shell commands and limits that describe how to run the tool call. - status: - anyOf: - - $ref: '#/components/schemas/BetaFunctionShellCallItemStatus' - description: The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - type: 'null' - environment: + 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: - - discriminator: - propertyName: type - description: The environment to execute the shell commands in. - anyOf: - - $ref: '#/components/schemas/BetaLocalEnvironmentParam' - - $ref: '#/components/schemas/BetaContainerReferenceParam' + - $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. + UpdateAgentSessionParams: type: object - required: - - call_id - - type - - action - title: Shell tool call - description: A tool representing a request to execute one or more shell commands. - BetaFunctionShellActionParam: properties: - commands: - items: + agent: + $ref: '#/components/schemas/UpdateSessionAgentParam' + description: Model settings for subsequent turns. Omitted fields stay unchanged. + metadata: + type: + - object + - 'null' + additionalProperties: type: string - type: array - description: Ordered shell commands for the execution environment to run. - timeout_ms: - anyOf: - - type: integer - description: Maximum wall-clock time in milliseconds to allow the shell commands to run. - - type: 'null' - max_output_length: - anyOf: - - type: integer - description: Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - - type: 'null' - type: object - required: - - commands - title: Shell action - description: Commands and limits describing how to run the shell tool call. - BetaLocalShellToolCallOutput: + 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. + DeletedSessionResource: type: object - title: Local shell call output - description: | - The output of a local shell tool call. properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that produced this item. - type: - type: string - enum: - - local_shell_call_output - description: | - The type of the local shell tool call output. Always `local_shell_call_output`. - x-stainless-const: true id: type: string - description: | - The unique ID of the local shell tool call generated by the model. - output: + minLength: 0 + description: The ID of the deleted session. + object: type: string - description: | - A JSON string of the output of the local shell tool call. - status: - anyOf: - - type: string - enum: - - in_progress - - completed - - incomplete - description: | - The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - type: 'null' + 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 - - type - - call_id - - output - BetaLocalShellToolCall: + - object + - deleted + additionalProperties: false + description: A Managed Agents session removed from the public API. Physical cleanup may continue asynchronously. + SessionArtifactResource: type: object - title: Local shell call - description: | - A tool call to run a command on the local shell. properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that produced this item. - type: + id: + type: string + minLength: 0 + description: The immutable artifact ID. + object: type: string enum: - - local_shell_call - description: | - The type of the local shell call. Always `local_shell_call`. + - agent.session.artifact + default: agent.session.artifact x-stainless-const: true - id: + description: The object type. Always `agent.session.artifact`. + session_id: type: string - description: | - The unique ID of the local shell call. - call_id: + minLength: 0 + description: The ID of the session that owns the artifact. + environment_id: type: string - description: | - The unique ID of the local shell tool call generated by the model. - action: - $ref: '#/components/schemas/BetaLocalShellExecAction' - status: + minLength: 0 + description: The ID of the environment that produced the artifact. + turn_id: type: string - enum: - - in_progress - - completed - - incomplete - description: | - The status of the local shell call. - required: - - type - - id - - call_id - - action - - status - BetaLocalShellExecAction: - properties: - type: + minLength: 0 + description: The ID of the completed turn that published the artifact. + path: type: string - enum: - - exec - description: The type of the local shell action. Always `exec`. - default: exec - x-stainless-const: true - command: - items: - type: string - type: array - description: The command to run. - timeout_ms: - anyOf: - - type: integer - description: Optional timeout in milliseconds for the command. - - type: 'null' - working_directory: - anyOf: - - type: string - description: Optional working directory to run the command in. - - type: 'null' - env: - additionalProperties: - type: string - type: object - description: Environment variables to set for the command. - x-oaiTypeLabel: map - user: - anyOf: - - type: string - description: Optional user to run the command as. - - type: 'null' - type: object + 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: - - type - - command - - env - title: Local shell exec action - description: Execute a shell command on the server. - BetaCodeInterpreterToolCall: + - 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. + SessionArtifactListResource: type: object - title: Code interpreter tool call - description: | - A tool call to run code. properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that produced this item. - type: + object: type: string enum: - - code_interpreter_call - default: code_interpreter_call + - list + default: list x-stainless-const: true - description: | - The type of the code interpreter tool call. Always `code_interpreter_call`. + 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. + DeletedSessionArtifactResource: + type: object + properties: id: type: string - description: | - The unique ID of the code interpreter tool call. - status: + minLength: 0 + description: The ID of the deleted session artifact. + object: type: string enum: - - in_progress - - completed - - incomplete - - interpreting - - failed - description: | - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - container_id: - type: string - description: | - The ID of the container used to run the code. - code: - anyOf: - - type: string - description: | - The code to run, or null if not available. - - type: 'null' - outputs: - anyOf: - - type: array - items: - discriminator: - propertyName: type - anyOf: - - $ref: '#/components/schemas/BetaCodeInterpreterOutputLogs' - - $ref: '#/components/schemas/BetaCodeInterpreterOutputImage' - discriminator: - propertyName: type - description: | - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. - - type: 'null' + - 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: - - type - id - - status - - container_id - - code - - outputs - BetaCodeInterpreterOutputImage: + - object + - deleted + additionalProperties: false + description: Confirmation that an immutable session artifact was deleted. + SessionInputParamAgentSessionInputMessage: + type: object properties: type: type: string enum: - - image - description: The type of the output. Always `image`. - default: image + - agent.session.input.message + default: agent.session.input.message x-stainless-const: true - url: - type: string - format: uri - description: The URL of the image output from the code interpreter. - type: object + 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 - - url - title: Code interpreter output image - description: The image output from the code interpreter. - BetaCodeInterpreterOutputLogs: + - input + additionalProperties: false + description: Adds one or more user messages and starts a turn. + SessionInputParamAgentSessionInputCancel: + type: object properties: type: type: string enum: - - logs - description: The type of the output. Always `logs`. - default: logs + - agent.session.input.cancel + default: agent.session.input.cancel x-stainless-const: true - logs: - type: string - description: The logs output from the code interpreter. - type: object + description: The type of the object. Always `agent.session.input.cancel`. required: - type - - logs - title: Code interpreter output logs - description: The logs output from the code interpreter. - BetaImageGenToolCall: + additionalProperties: false + description: Cancels the session's active turn. + FunctionCallOutputParam: + description: A function result represented as text or supported model-input content. + anyOf: + - type: string + minLength: 0 + maxLength: 1048576 + - type: array + items: + $ref: '#/components/schemas/InputContentParam' + minItems: 0 + maxItems: 16384 + SessionInputParamAgentSessionInputToolResult: + type: object properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - description: The agent that produced this item. - - type: 'null' type: type: string enum: - - image_generation_call - description: The type of the image generation call. Always `image_generation_call`. + - agent.session.input.tool_result + default: agent.session.input.tool_result x-stainless-const: true - id: + description: The type of the object. Always `agent.session.input.tool_result`. + turn_id: type: string - description: The unique ID of the image generation call. - status: + minLength: 0 + maxLength: 1048576 + description: The ID of the turn that requested the function call. + call_id: type: string - enum: - - in_progress - - completed - - generating - - failed - description: The status of the image generation call. - result: - anyOf: - - type: string - description: The generated image encoded in base64. - - type: 'null' - size: - anyOf: - - anyOf: - - type: string - - type: string - enum: - - 1024x1024 - - 1024x1536 - - 1536x1024 - description: The image dimensions as a `WIDTHxHEIGHT` string, for example `1536x864`. - - type: 'null' - quality: - anyOf: - - type: string - enum: - - low - - medium - - high - - xhigh - - max - - auto - description: The quality of the image generated by the image generation tool call. One of `low`, `medium`, `high`, `xhigh`, `max`, or `auto`. - - type: 'null' - action: - anyOf: - - $ref: '#/components/schemas/BetaImageGenActionEnum' - description: The action used for image generation. - - type: 'null' - x-openai-go-optional-enum: true - background: - anyOf: - - $ref: '#/components/schemas/BetaImageBackground' - description: The background setting used for generation. - - type: 'null' - x-openai-go-optional-enum: true - output_format: - anyOf: - - $ref: '#/components/schemas/BetaImageOutputFormat' - description: The output format used for generation. - - type: 'null' - x-openai-go-optional-enum: true - revised_prompt: + minLength: 0 + maxLength: 1048576 + description: The ID of the function call. + success: + type: boolean + description: Whether the function call succeeded. + output: anyOf: - - type: string - description: The prompt that was used after any model prompt rewriting. + - $ref: '#/components/schemas/FunctionCallOutputParam' - type: 'null' - type: object + 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 - - id - - status - - result - title: Image generation call - description: An image generation request made by the model. - BetaImageOutputFormat: - type: string - enum: - - png - - webp - - jpeg - BetaImageBackground: + - turn_id + - call_id + - success + additionalProperties: false + description: Submits the result of a function call. + SessionInputParam: + description: Input submitted to an existing session. + 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 + anyOf: + - $ref: '#/components/schemas/SessionInputParamAgentSessionInputMessage' + - $ref: '#/components/schemas/SessionInputParamAgentSessionInputCancel' + - $ref: '#/components/schemas/SessionInputParamAgentSessionInputToolResult' + 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. + VaultStatusParam: type: string enum: - - transparent - - opaque - - auto - BetaCompactionSummaryItemParam: + - active + - archived + description: Whether a vault or credential is active or archived. + VaultStatusFilterParam: + description: One or more lifecycle statuses to include when listing vaults or credentials. + anyOf: + - $ref: '#/components/schemas/VaultStatusParam' + - type: array + items: + $ref: '#/components/schemas/VaultStatusParam' + minItems: 0 + maxItems: 16384 + VaultResource: + type: object properties: - agent: - anyOf: - - $ref: '#/components/schemas/Beta_AgentTagParam' - description: The agent that produced this item. - - type: 'null' id: - anyOf: - - type: string - description: The ID of the compaction item. - example: cmp_123 - - type: 'null' - type: + type: string + minLength: 0 + description: The ID of the vault. + object: type: string enum: - - compaction - description: The type of the item. Always `compaction`. - default: compaction + - vault + default: vault x-stainless-const: true - encrypted_content: - type: string - maxLength: 104857600 - description: The encrypted content of the compaction summary. - type: object + description: The object type. Always `vault`. + name: + type: + - string + - 'null' + minLength: 0 + description: The human-readable name of the vault, if set. + metadata: + type: object + additionalProperties: + type: string + minLength: 0 + propertyNames: + type: string + minLength: 0 + minProperties: 0 + description: Key-value pairs associated with the vault, such as an application or team identifier. + created_at: + type: integer + format: int64 + description: The Unix timestamp, in seconds, when the vault was created. required: - - type - - encrypted_content - title: Compaction item - description: A compaction item generated by the [`v1/responses/compact` API](https://developers.openai.com/api/reference/resources/responses/methods/compact). - BetaReasoningItem: + - id + - object + - name + - metadata + - created_at + additionalProperties: false + description: A collection of credentials that agent tools can use to authenticate to MCP servers. + VaultListResource: type: object - description: | - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://developers.openai.com/api/docs/guides/conversation-state). - title: Reasoning properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that produced this item. - type: + object: type: string - description: | - The type of the object. Always `reasoning`. enum: - - reasoning + - list + default: list x-stainless-const: true - id: - type: string - description: | - The unique identifier of the reasoning content. - encrypted_content: - anyOf: - - type: string - description: | - The encrypted content of the reasoning item. This is populated by default - for reasoning items returned by `POST /v1/responses` and WebSocket - `response.create` requests. - - When streaming, use the completed reasoning item and its - `encrypted_content` from the `response.output_item.done` event in - subsequent requests. The `encrypted_content` in - `response.output_item.added` may be incomplete. This is especially - important when `store` is `false` or when using Zero Data Retention. - - type: 'null' - summary: - type: array - description: | - Reasoning summary content. - items: - $ref: '#/components/schemas/BetaSummaryTextContent' - content: + description: The object type, which is always `list`. + data: type: array - description: | - Reasoning text content. items: - $ref: '#/components/schemas/BetaReasoningTextContent' - status: + $ref: '#/components/schemas/VaultResource' + 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. + CreateVaultParams: + type: object + properties: + name: + type: string + minLength: 1 + maxLength: 1048576 + description: The name is trimmed before storage. It must contain 1 to 256 UTF-8 bytes after trimming. + metadata: + type: + - object + - 'null' + additionalProperties: + type: string + minLength: 0 + maxLength: 1048576 + propertyNames: + type: string + minLength: 1 + maxLength: 256 + minProperties: 0 + maxProperties: 1024 + description: Key-value pairs to associate with the vault, such as an application or team identifier. + additionalProperties: false + description: Parameters for creating a vault to store credentials used by agent tools. + DeletedVaultResource: + type: object + properties: + id: + type: string + minLength: 0 + description: The ID of the deleted vault. + object: type: string - description: | - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. enum: - - in_progress - - completed - - incomplete + - vault.deleted + default: vault.deleted + x-stainless-const: true + description: The object type. Always `vault.deleted`. + deleted: + type: boolean + description: Whether the resource was deleted. Always `true`. required: - id - - summary - - type - BetaReasoningTextContent: + - object + - deleted + additionalProperties: false + description: Confirmation that a vault was deleted. + McpOauthTokenEndpointAuthResourceNone: + type: object properties: type: type: string enum: - - reasoning_text - description: The type of the reasoning text. Always `reasoning_text`. - default: reasoning_text + - none + default: none x-stainless-const: true - text: - type: string - description: The reasoning text from the model. - type: object + description: The type of the object. Always `none`. required: - type - - text - title: Reasoning text - description: Reasoning text from the model. - BetaSummaryTextContent: + additionalProperties: false + description: Sends the client ID without a client secret. + McpOauthTokenEndpointAuthResourceClientSecretBasic: + type: object properties: type: type: string enum: - - summary_text - description: The type of the object. Always `summary_text`. - default: summary_text + - client_secret_basic + default: client_secret_basic x-stainless-const: true - text: - type: string - description: A summary of the reasoning output from the model so far. - type: object + description: The type of the object. Always `client_secret_basic`. required: - type - - text - title: Summary text - description: A summary text from the model. - BetaResponseConfigurationUpdateItemParam: + additionalProperties: false + description: Sends the client ID and secret using HTTP Basic authentication. + McpOauthTokenEndpointAuthResourceClientSecretPost: type: object - description: | - An update to the conversation's response configuration. The configuration - remains in effect for subsequent responses until it is replaced by another - configuration update. properties: - agent: - anyOf: - - $ref: '#/components/schemas/Beta_AgentTagParam' - description: The agent that produced this item. - - type: 'null' - id: - anyOf: - - type: string - description: The unique ID of the configuration update item. - example: cnfu_123 - - type: 'null' type: type: string enum: - - configuration_update - description: The item type. Always `configuration_update`. - default: configuration_update + - client_secret_post + default: client_secret_post x-stainless-const: true - reasoning: - type: object - description: Updates to reasoning configuration. Only effort is supported. - properties: - effort: - $ref: '#/components/schemas/BetaReasoningEffort' - description: | - The reasoning effort to use for subsequent responses until another - configuration update replaces it. + description: The type of the object. Always `client_secret_post`. required: - type - BetaAdditionalToolsItemParam: + additionalProperties: false + description: Sends the client ID and secret in the token request body. + McpOauthTokenEndpointAuthResource: + description: The client authentication method used for OAuth token refresh. + discriminator: + propertyName: type + mapping: + none: '#/components/schemas/McpOauthTokenEndpointAuthResourceNone' + client_secret_basic: '#/components/schemas/McpOauthTokenEndpointAuthResourceClientSecretBasic' + client_secret_post: '#/components/schemas/McpOauthTokenEndpointAuthResourceClientSecretPost' + x-oai-discriminator-values: + - none + - client_secret_basic + - client_secret_post + anyOf: + - $ref: '#/components/schemas/McpOauthTokenEndpointAuthResourceNone' + - $ref: '#/components/schemas/McpOauthTokenEndpointAuthResourceClientSecretBasic' + - $ref: '#/components/schemas/McpOauthTokenEndpointAuthResourceClientSecretPost' + McpOauthRefreshResource: + type: object properties: - agent: - anyOf: - - $ref: '#/components/schemas/Beta_AgentTagParam' - description: The agent that produced this item. - - type: 'null' - id: - anyOf: - - type: string - description: The unique ID of this additional tools item. - example: at_123 - - type: 'null' - type: + token_endpoint: type: string - enum: - - additional_tools - description: The item type. Always `additional_tools`. - default: additional_tools - x-stainless-const: true - role: + minLength: 0 + description: The HTTPS OAuth token endpoint used for refresh. + client_id: type: string - enum: - - developer - description: The role that provided the additional tools. Only `developer` is supported. - default: developer - x-stainless-const: true - tools: - items: - $ref: '#/components/schemas/BetaTool' - type: array - description: A list of additional tools made available at this item. - type: object + minLength: 0 + description: The OAuth client ID used when requesting a new access token. + resource: + type: + - string + - 'null' + minLength: 0 + description: The resource URI sent to the OAuth token endpoint during refresh, if configured. + scope: + type: + - string + - 'null' + minLength: 0 + description: Space-separated OAuth scopes requested during refresh, if configured. + token_endpoint_auth: + $ref: '#/components/schemas/McpOauthTokenEndpointAuthResource' + description: How the OAuth client authenticates to the token endpoint, excluding its client secret. required: - - type - - role - - tools - BetaToolSearchOutputItemParam: + - token_endpoint + - client_id + - resource + - scope + - token_endpoint_auth + additionalProperties: false + description: Configuration used to refresh an MCP OAuth access token, excluding secret values. + VaultCredentialAuthResourceMcpOauth: + type: object properties: - agent: - anyOf: - - $ref: '#/components/schemas/Beta_AgentTagParam' - description: The agent that produced this item. - - type: 'null' - id: - anyOf: - - type: string - description: The unique ID of this tool search output. - example: tso_123 - - type: 'null' - call_id: - anyOf: - - type: string - maxLength: 64 - minLength: 1 - description: The unique ID of the tool search call generated by the model. - - type: 'null' type: type: string enum: - - tool_search_output - description: The item type. Always `tool_search_output`. - default: tool_search_output + - mcp_oauth + default: mcp_oauth x-stainless-const: true - execution: - $ref: '#/components/schemas/BetaToolSearchExecutionType' - description: Whether tool search was executed by the server or by the client. - tools: - items: - $ref: '#/components/schemas/BetaTool' - type: array - description: The loaded tool definitions returned by the tool search output. - status: + description: The type of the object. Always `mcp_oauth`. + mcp_server_url: + type: string + minLength: 0 + description: The HTTPS MCP server URL authorized by this credential. + expires_at: + type: + - string + - 'null' + minLength: 0 + description: When the OAuth access token expires, as an RFC 3339 timestamp, if known. + refresh: anyOf: - - $ref: '#/components/schemas/BetaFunctionCallItemStatus' - description: The status of the tool search output. + - $ref: '#/components/schemas/McpOauthRefreshResource' - type: 'null' - type: object + description: Public refresh metadata without refresh tokens or OAuth client secrets. required: - type - - tools - BetaFunctionCallItemStatus: - type: string - enum: - - in_progress - - completed - - incomplete - BetaToolSearchCallItemParam: + - mcp_server_url + - expires_at + - refresh + additionalProperties: false + description: Public metadata for an OAuth credential; tokens and client secrets are never returned. + VaultCredentialAuthResourceStaticBearer: + type: object properties: - agent: - anyOf: - - $ref: '#/components/schemas/Beta_AgentTagParam' - description: The agent that produced this item. - - type: 'null' - id: - anyOf: - - type: string - description: The unique ID of this tool search call. - example: tsc_123 - - type: 'null' - call_id: - anyOf: - - type: string - maxLength: 64 - minLength: 1 - description: The unique ID of the tool search call generated by the model. - - type: 'null' type: type: string enum: - - tool_search_call - description: The item type. Always `tool_search_call`. - default: tool_search_call + - static_bearer + default: static_bearer x-stainless-const: true - execution: - $ref: '#/components/schemas/BetaToolSearchExecutionType' - description: Whether tool search was executed by the server or by the client. - arguments: - $ref: '#/components/schemas/BetaEmptyModelParam' - description: The arguments supplied to the tool search call. - status: + description: The type of the object. Always `static_bearer`. + mcp_server_url: + type: string + minLength: 0 + description: The HTTPS MCP server URL authorized by this credential. + required: + - type + - mcp_server_url + additionalProperties: false + description: Metadata for a bearer-token credential, without automatic OAuth refresh. + BetaContextManagementParam: + properties: + type: + type: string + description: The context management entry type. Currently only 'compaction' is supported. + compact_threshold: anyOf: - - $ref: '#/components/schemas/BetaFunctionCallItemStatus' - description: The status of the tool search call. + - type: integer + minimum: 1000 + description: Token threshold at which compaction should be triggered for this entry. - type: 'null' type: object required: - type - - arguments - BetaMultiAgentCallOutputItemParam: + BetaResponseStreamOptions: + anyOf: + - description: | + Options for streaming responses. Only set this when you set `stream: true`. + type: object + properties: + include_obfuscation: + type: boolean + description: | + When true, stream obfuscation will be enabled. Stream obfuscation adds + random characters to an `obfuscation` field on streaming delta events to + normalize payload sizes as a mitigation to certain side-channel attacks. + These obfuscation fields are included by default, but add a small amount + of overhead to the data stream. You can set `include_obfuscation` to + false to optimize for bandwidth if you trust the network links between + your application and the OpenAI API. + - type: 'null' + BetaModerationParam: properties: - agent: + model: + type: string + description: The moderation model to use for moderated completions, e.g. 'omni-moderation-latest'. + policy: anyOf: - - $ref: '#/components/schemas/Beta_AgentTagParam' - description: The agent that produced this item. + - $ref: '#/components/schemas/BetaModerationPolicyParam' + description: The policy to apply to moderated response input and output. - type: 'null' - id: + type: object + required: + - model + description: Configuration for running moderation on the input and output of this response. + BetaResponsePromptCacheOptionsParam: + properties: + ttl: + $ref: '#/components/schemas/BetaPromptCacheTTLEnum' + description: The minimum lifetime applied to every implicit and explicit cache breakpoint written by the request. Defaults to `30m`, which is currently the only supported value. The backend may retain cache entries for longer. + mode: + $ref: '#/components/schemas/BetaPromptCacheModeEnum' + description: Controls whether OpenAI automatically creates an implicit cache breakpoint. Defaults to `implicit`. With `implicit`, OpenAI creates one implicit breakpoint and writes up to the latest three explicit breakpoints in the request. With `explicit`, OpenAI does not create an implicit breakpoint and writes up to the latest four explicit breakpoints. If there are no explicit breakpoints, the request does not use prompt caching. + prewarm: + type: boolean + description: Prepares the prompt cache without generating output. Defaults to `false`. When set to `true`, overrides the `generate` field to `false`. + comparison_response_id: anyOf: - type: string - description: The unique ID of this multi-agent call output. - example: maco_123 + description: The ID of a response to compare when diagnosing prompt cache reuse. Supplying this field requests prompt cache diagnostics when the feature is enabled. + example: resp_123 - type: 'null' - call_id: - type: string - maxLength: 64 - minLength: 1 - description: The unique ID of the multi-agent call. - type: - type: string - enum: - - multi_agent_call_output - description: The item type. Always `multi_agent_call_output`. - default: multi_agent_call_output - x-stainless-const: true - action: - $ref: '#/components/schemas/BetaMultiAgentAction1' - description: The multi-agent action that produced this result. - output: - items: - $ref: '#/components/schemas/BetaOutputTextContentParam' - type: array - description: Text output returned by the multi-agent action. type: object - required: - - call_id - - type - - action - - output - x-oai-beta: responses_multi_agent=v1 - BetaOutputTextContentParam: + required: [] + title: Prompt cache options + description: Options for prompt caching. Supported for `gpt-5.6` and later models. By default, OpenAI automatically chooses one implicit cache breakpoint. You can add explicit breakpoints to content blocks with `prompt_cache_breakpoint`. Each request can write up to four breakpoints. For cache matching, OpenAI considers up to the latest 80 breakpoints in the conversation, without a content-block lookback limit. Set `mode` to `explicit` to disable the implicit breakpoint. The `ttl` defaults to `30m`, which is currently the only supported value. See the [prompt caching guide](https://developers.openai.com/api/docs/guides/prompt-caching) for current details. + VaultCredentialAuthResource: + description: The MCP server and authentication configuration of a vault credential, excluding secrets. + discriminator: + propertyName: type + mapping: + mcp_oauth: '#/components/schemas/VaultCredentialAuthResourceMcpOauth' + static_bearer: '#/components/schemas/VaultCredentialAuthResourceStaticBearer' + x-oai-discriminator-values: + - mcp_oauth + - static_bearer + anyOf: + - $ref: '#/components/schemas/VaultCredentialAuthResourceMcpOauth' + - $ref: '#/components/schemas/VaultCredentialAuthResourceStaticBearer' + VaultCredentialResource: + type: object properties: - type: + id: + type: string + minLength: 0 + description: The ID of the credential. + object: type: string enum: - - output_text - description: The content type. Always `output_text`. - default: output_text + - vault.credential + default: vault.credential x-stainless-const: true - text: + description: The object type. Always `vault.credential`. + vault_id: type: string - maxLength: 10485760 - description: The text content. - annotations: - items: - discriminator: - propertyName: type - anyOf: - - $ref: '#/components/schemas/BetaFileCitationParam' - - $ref: '#/components/schemas/BetaUrlCitationParam' - - $ref: '#/components/schemas/BetaContainerFileCitationParam' - type: array - description: Citations associated with the text content. - type: object - required: - - type - - text - BetaContainerFileCitationParam: - properties: - type: + minLength: 0 + description: The ID of the vault containing this credential. + name: type: string - enum: - - container_file_citation - description: The citation type. Always `container_file_citation`. - default: container_file_citation - x-stainless-const: true - start_index: + minLength: 0 + description: The human-readable name of the credential. + auth: + $ref: '#/components/schemas/VaultCredentialAuthResource' + description: The authentication method and non-secret configuration for the MCP server. + created_at: type: integer - minimum: 0 - description: The index of the first character of the citation in the message. - end_index: + format: int64 + description: The Unix timestamp, in seconds, when the credential was created. + updated_at: type: integer - minimum: 0 - description: The index of the last character of the citation in the message. - container_id: - type: string - description: The ID of the container. - example: cntr_123 - file_id: - type: string - description: The ID of the container file. - example: cfile_123 - filename: - type: string - description: The filename of the container file cited. - type: object + format: int64 + description: The Unix timestamp, in seconds, when the credential was last updated. required: - - type - - start_index - - end_index - - container_id - - file_id - - filename - BetaUrlCitationParam: + - id + - object + - vault_id + - name + - auth + - created_at + - updated_at + additionalProperties: false + description: Metadata for a stored MCP server credential. Secret values are never returned. + VaultCredentialListResource: + type: object properties: - type: + object: type: string enum: - - url_citation - description: The citation type. Always `url_citation`. - default: url_citation + - list + default: list x-stainless-const: true - start_index: - type: integer - minimum: 0 - description: The index of the first character of the citation in the message. - end_index: - type: integer - minimum: 0 - description: The index of the last character of the citation in the message. - url: - type: string - format: uri - description: The URL of the cited resource. - title: - type: string - description: The title of the cited resource. + description: The object type, which is always `list`. + data: + type: array + items: + $ref: '#/components/schemas/VaultCredentialResource' + 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. + CreateMcpOauthTokenEndpointAuthParamNone: type: object - required: - - type - - start_index - - end_index - - url - - title - BetaFileCitationParam: properties: type: type: string enum: - - file_citation - description: The citation type. Always `file_citation`. - default: file_citation + - none + default: none x-stainless-const: true - index: - type: integer - minimum: 0 - description: The index of the file in the list of files. - file_id: - type: string - description: The ID of the file. - example: file-123 - filename: - type: string - description: The filename of the file cited. - type: object + description: The type of the object. Always `none`. required: - type - - index - - file_id - - filename - BetaMultiAgentAction1: - type: string - enum: - - spawn_agent - - interrupt_agent - - list_agents - - send_message - - followup_task - - wait_agent - BetaMultiAgentCallItemParam: + additionalProperties: false + description: Sends the client ID without a client secret. + CreateMcpOauthTokenEndpointAuthParamClientSecretBasic: + type: object properties: - agent: - anyOf: - - $ref: '#/components/schemas/Beta_AgentTagParam' - description: The agent that produced this item. - - type: 'null' - id: - anyOf: - - type: string - description: The unique ID of this multi-agent call. - example: mac_123 - - type: 'null' - call_id: - type: string - maxLength: 64 - minLength: 1 - description: The unique ID linking this call to its output. type: type: string enum: - - multi_agent_call - description: The item type. Always `multi_agent_call`. - default: multi_agent_call + - client_secret_basic + default: client_secret_basic x-stainless-const: true - action: - $ref: '#/components/schemas/BetaMultiAgentAction1' - description: The multi-agent action that was executed. - arguments: + description: The type of the object. Always `client_secret_basic`. + client_secret: type: string - description: The action arguments as a JSON string. - type: object + minLength: 0 + maxLength: 1048576 + description: The OAuth client secret to store. Never returned in credential resources. required: - - call_id - type - - action - - arguments - x-oai-beta: responses_multi_agent=v1 - BetaAgentMessageItemParam: + - client_secret + additionalProperties: false + description: Sends the client ID and secret using HTTP Basic authentication. + CreateMcpOauthTokenEndpointAuthParamClientSecretPost: + type: object properties: - agent: - anyOf: - - $ref: '#/components/schemas/Beta_AgentTagParam' - description: The agent that produced this item. - - type: 'null' - id: - anyOf: - - type: string - description: The unique ID of this agent message item. - example: amsg_123 - - type: 'null' type: type: string enum: - - agent_message - description: The item type. Always `agent_message`. - default: agent_message + - client_secret_post + default: client_secret_post x-stainless-const: true - author: - type: string - description: The sending agent identity. - recipient: + description: The type of the object. Always `client_secret_post`. + client_secret: type: string - description: The destination agent identity. - content: - items: - discriminator: - propertyName: type - description: A plaintext, image, or encrypted agent message content part. - anyOf: - - $ref: '#/components/schemas/BetaInputTextContentParam' - - $ref: '#/components/schemas/BetaInputImageContentParamAutoParam' - - $ref: '#/components/schemas/BetaEncryptedContentParam' - type: array - description: Plaintext, image, or encrypted content sent between agents. - type: object + minLength: 0 + maxLength: 1048576 + description: The OAuth client secret to store. Never returned in credential resources. required: - type - - author - - recipient - - content - title: Agent message - description: A message routed between agents. - x-oai-beta: responses_multi_agent=v1 - BetaEncryptedContentParam: + - client_secret + additionalProperties: false + description: Sends the client ID and secret in the token request body. + CreateMcpOauthTokenEndpointAuthParam: + description: Client authentication credentials for OAuth token refresh. + discriminator: + propertyName: type + mapping: + none: '#/components/schemas/CreateMcpOauthTokenEndpointAuthParamNone' + client_secret_basic: '#/components/schemas/CreateMcpOauthTokenEndpointAuthParamClientSecretBasic' + client_secret_post: '#/components/schemas/CreateMcpOauthTokenEndpointAuthParamClientSecretPost' + x-oai-discriminator-values: + - none + - client_secret_basic + - client_secret_post + anyOf: + - $ref: '#/components/schemas/CreateMcpOauthTokenEndpointAuthParamNone' + - $ref: '#/components/schemas/CreateMcpOauthTokenEndpointAuthParamClientSecretBasic' + - $ref: '#/components/schemas/CreateMcpOauthTokenEndpointAuthParamClientSecretPost' + CreateMcpOauthRefreshParam: + type: object properties: - type: + token_endpoint: type: string - enum: - - encrypted_content - description: The type of the input item. Always `encrypted_content`. - default: encrypted_content - x-stainless-const: true - encrypted_content: + minLength: 0 + maxLength: 1048576 + description: The HTTPS OAuth token endpoint used to exchange the refresh token for a new access token. + client_id: type: string - maxLength: 10485760 - description: Opaque encrypted content. - type: object + minLength: 0 + maxLength: 1048576 + description: The OAuth client ID used when requesting a new access token. + resource: + type: + - string + - 'null' + minLength: 0 + maxLength: 1048576 + description: The resource URI to send to the OAuth token endpoint during refresh, if required. + scope: + type: + - string + - 'null' + minLength: 0 + maxLength: 1048576 + description: Space-separated OAuth scopes to request during refresh, if required. + refresh_token: + type: string + minLength: 0 + maxLength: 1048576 + description: The refresh token to store. This secret is never returned in credential resources. + token_endpoint_auth: + $ref: '#/components/schemas/CreateMcpOauthTokenEndpointAuthParam' + description: How the OAuth client authenticates to the token endpoint. required: - - type - - encrypted_content - title: Encrypted content - description: Opaque encrypted content that Responses API decrypts inside trusted model execution. - x-oai-beta: responses_multi_agent=v1 - BetaInputImageContentParamAutoParam: + - token_endpoint + - client_id + - refresh_token + - token_endpoint_auth + additionalProperties: false + description: Configuration for refreshing the access token of an MCP OAuth credential. + CreateVaultCredentialAuthParamMcpOauth: + type: object properties: type: type: string enum: - - input_image - description: The type of the input item. Always `input_image`. - default: input_image + - mcp_oauth + default: mcp_oauth x-stainless-const: true - image_url: - anyOf: - - type: string - maxLength: 20971520 - format: uri - description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - type: 'null' - file_id: - anyOf: - - type: string - description: The ID of the file to be sent to the model. - example: file-123 - - type: 'null' - detail: - anyOf: - - $ref: '#/components/schemas/BetaDetailEnum' - description: The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - type: 'null' - prompt_cache_breakpoint: + description: The type of the object. Always `mcp_oauth`. + mcp_server_url: + type: string + minLength: 0 + maxLength: 1048576 + description: The HTTPS MCP server URL authorized by this credential. + access_token: + type: string + minLength: 0 + maxLength: 1048576 + description: A write-only OAuth access token; never returned by credential resources. + expires_at: + type: + - string + - 'null' + minLength: 0 + maxLength: 1048576 + description: When the OAuth access token expires, as an RFC 3339 timestamp, if known. + refresh: anyOf: - - $ref: '#/components/schemas/BetaPromptCacheBreakpointParam' + - $ref: '#/components/schemas/CreateMcpOauthRefreshParam' - type: 'null' - type: object + description: Optional refresh configuration for an HTTPS OAuth token endpoint. required: - type - title: Input image - description: An image input to the model. Learn about [image inputs](https://developers.openai.com/api/docs/guides/images-vision) - BetaPromptCacheBreakpointParam: - properties: - mode: - type: string - enum: - - explicit - description: The breakpoint mode. Always `explicit`. - default: explicit - x-stainless-const: true + - mcp_server_url + - access_token + additionalProperties: false + description: An OAuth credential for an HTTPS MCP destination. + CreateVaultCredentialAuthParamStaticBearer: type: object - required: - - mode - title: Prompt cache breakpoint - description: Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - BetaDetailEnum: - type: string - enum: - - low - - high - - auto - - original - BetaInputTextContentParam: properties: type: type: string enum: - - input_text - description: The type of the input item. Always `input_text`. - default: input_text + - static_bearer + default: static_bearer x-stainless-const: true - text: + description: The type of the object. Always `static_bearer`. + mcp_server_url: type: string - maxLength: 10485760 - description: The text input to the model. - prompt_cache_breakpoint: - anyOf: - - $ref: '#/components/schemas/BetaPromptCacheBreakpointParam' - - type: 'null' - type: object + minLength: 0 + maxLength: 1048576 + description: The HTTPS MCP server URL authorized by this credential. + token: + type: string + minLength: 0 + maxLength: 1048576 + description: The bearer token to store. This secret is never returned in credential resources. required: - type - - text - title: Input text - description: A text input to the model. - BetaFunctionCallOutputItemParam: + - mcp_server_url + - token + additionalProperties: false + description: A bearer token for an MCP server, without automatic OAuth refresh. + BetaModerationPolicyParam: properties: - agent: - anyOf: - - $ref: '#/components/schemas/Beta_AgentTagParam' - description: The agent that produced this item. - - type: 'null' - id: - anyOf: - - type: string - description: The unique ID of the function tool call output. Populated when this item is returned via API. - example: fc_123 - - type: 'null' - call_id: + input: anyOf: - - type: string - maxLength: 64 - minLength: 1 - description: The unique ID of the function tool call generated by the model. + - $ref: '#/components/schemas/BetaModerationConfigParam' + description: The moderation policy for the response input. - type: 'null' - type: - type: string - enum: - - function_call_output - description: The type of the function tool call output. Always `function_call_output`. - default: function_call_output - x-stainless-const: true output: - description: Text, image, or file output of the function tool call. - anyOf: - - type: string - maxLength: 10485760 - description: A JSON string of the output of the function tool call. - - items: - discriminator: - propertyName: type - description: A piece of message content, such as text, an image, or a file. - anyOf: - - $ref: '#/components/schemas/BetaInputTextContentParam' - - $ref: '#/components/schemas/BetaInputImageContentParamAutoParam' - - $ref: '#/components/schemas/BetaInputFileContentParam' - type: array - description: An array of content outputs (text, image, file) for the function tool call. - name: - anyOf: - - type: string - maxLength: 128 - minLength: 1 - description: The name of the tool that produced the output. - - type: 'null' - namespace: - anyOf: - - type: string - maxLength: 64 - minLength: 1 - pattern: ^[a-zA-Z0-9_-]+$ - description: The namespace of the tool that produced the output. - - type: 'null' - caller: - anyOf: - - $ref: '#/components/schemas/BetaToolCallCallerParam' - description: The execution context that produced this tool call. - - type: 'null' - status: anyOf: - - $ref: '#/components/schemas/BetaFunctionCallItemStatus' - description: The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + - $ref: '#/components/schemas/BetaModerationConfigParam' + description: The moderation policy for the response output. - type: 'null' type: object - required: - - type - - output - title: Function tool call output - description: The output of a function tool call. - BetaInputFileContentParam: + required: [] + description: The policy to apply to moderated response input and output. + BetaModerationConfigParam: properties: - type: - type: string - enum: - - input_file - description: The type of the input item. Always `input_file`. - default: input_file - x-stainless-const: true - file_id: - anyOf: - - type: string - description: The ID of the file to be sent to the model. - example: file-123 - - type: 'null' - filename: - anyOf: - - type: string - description: The name of the file to be sent to the model. - - type: 'null' - file_data: - anyOf: - - type: string - maxLength: 73400320 - description: The base64-encoded data of the file to be sent to the model. - - type: 'null' - file_url: - anyOf: - - type: string - format: uri - description: The URL of the file to be sent to the model. - - type: 'null' - detail: - $ref: '#/components/schemas/BetaFileDetailEnum' - description: The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - prompt_cache_breakpoint: - anyOf: - - $ref: '#/components/schemas/BetaPromptCacheBreakpointParam' - - type: 'null' + mode: + $ref: '#/components/schemas/BetaModerationMode' type: object required: - - type - title: Input file - description: A file input to the model. - BetaFileDetailEnum: + - mode + description: The moderation policy for the response input. + BetaModerationMode: type: string enum: - - auto - - low - - high - BetaFunctionToolCall: + - score + - block + BetaResponseStreamEvent: + description: Event emitted while a response is streamed. + anyOf: + - $ref: '#/components/schemas/BetaResponseAudioDeltaEvent' + - $ref: '#/components/schemas/BetaResponseAudioDoneEvent' + - $ref: '#/components/schemas/BetaResponseAudioTranscriptDeltaEvent' + - $ref: '#/components/schemas/BetaResponseAudioTranscriptDoneEvent' + - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallCodeDeltaEvent' + - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallCodeDoneEvent' + - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallCompletedEvent' + - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallInProgressEvent' + - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallInterpretingEvent' + - $ref: '#/components/schemas/BetaResponseCompactionCompactingStreamingEvent' + - $ref: '#/components/schemas/BetaResponseCompletedEvent' + - $ref: '#/components/schemas/BetaResponseContentPartAddedEvent' + - $ref: '#/components/schemas/BetaResponseContentPartDoneEvent' + - $ref: '#/components/schemas/BetaResponseCreatedEvent' + - $ref: '#/components/schemas/BetaResponseErrorEvent' + - $ref: '#/components/schemas/BetaResponseFileSearchCallCompletedEvent' + - $ref: '#/components/schemas/BetaResponseFileSearchCallInProgressEvent' + - $ref: '#/components/schemas/BetaResponseFileSearchCallSearchingEvent' + - $ref: '#/components/schemas/BetaResponseFunctionCallArgumentsDeltaEvent' + - $ref: '#/components/schemas/BetaResponseFunctionCallArgumentsDoneEvent' + - $ref: '#/components/schemas/BetaResponseShellCallCommandAddedStreamingEvent' + - $ref: '#/components/schemas/BetaResponseShellCallCommandDeltaStreamingEvent' + - $ref: '#/components/schemas/BetaResponseShellCallCommandDoneStreamingEvent' + - $ref: '#/components/schemas/BetaResponseShellCallOutputContentDeltaStreamingEvent' + x-stainless-skip: + - go + - $ref: '#/components/schemas/BetaResponseShellCallOutputContentDoneStreamingEvent' + - $ref: '#/components/schemas/BetaResponseInProgressEvent' + - $ref: '#/components/schemas/BetaResponseFailedEvent' + - $ref: '#/components/schemas/BetaResponseIncompleteEvent' + - $ref: '#/components/schemas/BetaResponseOutputItemAddedEvent' + - $ref: '#/components/schemas/BetaResponseOutputItemDoneEvent' + - $ref: '#/components/schemas/BetaResponseReasoningSummaryPartAddedEvent' + - $ref: '#/components/schemas/BetaResponseReasoningSummaryPartDoneEvent' + - $ref: '#/components/schemas/BetaResponseReasoningSummaryTextDeltaEvent' + - $ref: '#/components/schemas/BetaResponseReasoningSummaryTextDoneEvent' + - $ref: '#/components/schemas/BetaResponseReasoningTextDeltaEvent' + - $ref: '#/components/schemas/BetaResponseReasoningTextDoneEvent' + - $ref: '#/components/schemas/BetaResponseRefusalDeltaEvent' + - $ref: '#/components/schemas/BetaResponseRefusalDoneEvent' + - $ref: '#/components/schemas/BetaResponseTextDeltaEvent' + - $ref: '#/components/schemas/BetaResponseTextDoneEvent' + - $ref: '#/components/schemas/BetaResponseWebSearchCallCompletedEvent' + - $ref: '#/components/schemas/BetaResponseWebSearchCallInProgressEvent' + - $ref: '#/components/schemas/BetaResponseWebSearchCallSearchingEvent' + - $ref: '#/components/schemas/BetaResponseImageGenCallCompletedEvent' + - $ref: '#/components/schemas/BetaResponseImageGenCallGeneratingEvent' + - $ref: '#/components/schemas/BetaResponseImageGenCallInProgressEvent' + - $ref: '#/components/schemas/BetaResponseImageGenCallPartialImageEvent' + - $ref: '#/components/schemas/BetaResponseMCPCallArgumentsDeltaEvent' + - $ref: '#/components/schemas/BetaResponseMCPCallArgumentsDoneEvent' + - $ref: '#/components/schemas/BetaResponseMCPCallCompletedEvent' + - $ref: '#/components/schemas/BetaResponseMCPCallFailedEvent' + - $ref: '#/components/schemas/BetaResponseMCPCallInProgressEvent' + - $ref: '#/components/schemas/BetaResponseMCPListToolsCompletedEvent' + - $ref: '#/components/schemas/BetaResponseMCPListToolsFailedEvent' + - $ref: '#/components/schemas/BetaResponseMCPListToolsInProgressEvent' + - $ref: '#/components/schemas/BetaResponseOutputTextAnnotationAddedEvent' + - $ref: '#/components/schemas/BetaResponseQueuedEvent' + - $ref: '#/components/schemas/BetaResponseCustomToolCallInputDeltaEvent' + - $ref: '#/components/schemas/BetaResponseCustomToolCallInputDoneEvent' + discriminator: + propertyName: type + CreateVaultCredentialAuthParam: + description: Authentication credentials for an MCP server used by agent tools. + discriminator: + propertyName: type + mapping: + mcp_oauth: '#/components/schemas/CreateVaultCredentialAuthParamMcpOauth' + static_bearer: '#/components/schemas/CreateVaultCredentialAuthParamStaticBearer' + x-oai-discriminator-values: + - mcp_oauth + - static_bearer + anyOf: + - $ref: '#/components/schemas/CreateVaultCredentialAuthParamMcpOauth' + - $ref: '#/components/schemas/CreateVaultCredentialAuthParamStaticBearer' + CreateVaultCredentialParams: type: object - title: Function tool call - description: | - A tool call to run a function. See the - [function calling guide](https://developers.openai.com/api/docs/guides/function-calling) for more information. properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that produced this item. - id: - type: string - description: | - The unique ID of the function tool call. - type: - type: string - enum: - - function_call - description: | - The type of the function tool call. Always `function_call`. - x-stainless-const: true - call_id: - type: string - description: | - The unique ID of the function tool call generated by the model. - caller: - anyOf: - - $ref: '#/components/schemas/BetaToolCallCaller' - - type: 'null' - namespace: - type: string - description: | - The namespace of the function to run. name: type: string - description: | - The name of the function to run. - arguments: - type: string - description: | - A JSON string of the arguments to pass to the function. - status: - type: string - description: | - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - enum: - - in_progress - - completed - - incomplete - async: - type: boolean - description: | - Whether the function tool call runs asynchronously. + minLength: 1 + maxLength: 1048576 + description: The name is trimmed before storage. It must contain 1 to 256 UTF-8 bytes after trimming. + auth: + $ref: '#/components/schemas/CreateVaultCredentialAuthParam' + description: The authentication method and secret values to store for the MCP server. required: - - type - - call_id + - auth - name - - arguments - BetaWebSearchToolCall: + additionalProperties: false + description: Parameters for storing a credential that authorizes access to an MCP server. + RotateMcpOauthTokenEndpointAuthParamClientSecretBasic: type: object - title: Web search tool call - description: | - The results of a web search tool call. See the - [web search guide](https://developers.openai.com/api/docs/guides/tools-web-search) for more information. properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that produced this item. - id: - type: string - description: | - The unique ID of the web search tool call. type: type: string enum: - - web_search_call - description: | - The type of the web search tool call. Always `web_search_call`. + - client_secret_basic + default: client_secret_basic x-stainless-const: true - status: - description: | - The status of the web search tool call. - $ref: '#/components/schemas/BetaWebSearchCallStatus' - action: - type: object - description: | - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). - discriminator: - propertyName: type - anyOf: - - $ref: '#/components/schemas/BetaWebSearchActionSearch' - - $ref: '#/components/schemas/BetaWebSearchActionOpenPage' - - $ref: '#/components/schemas/BetaWebSearchActionFind' + description: The type of the object. Always `client_secret_basic`. + client_secret: + type: + - string + - 'null' + minLength: 0 + maxLength: 1048576 + description: The replacement OAuth client secret. Omit or pass `null` to keep the stored secret. This secret is never returned in resources. required: - - id - type - - status - - action - BetaWebSearchActionFind: + additionalProperties: false + description: Updates credentials sent using HTTP Basic authentication. + RotateMcpOauthTokenEndpointAuthParamClientSecretPost: type: object - title: Find action - description: | - Action type "find_in_page": Searches for a pattern within a loaded page. properties: type: type: string enum: - - find_in_page - description: | - The action type. + - client_secret_post + default: client_secret_post x-stainless-const: true - url: - type: string - format: uri - description: | - The URL of the page searched for the pattern. - pattern: - type: string - description: | - The pattern or text to search for within the page. + description: The type of the object. Always `client_secret_post`. + client_secret: + type: + - string + - 'null' + minLength: 0 + maxLength: 1048576 + description: The replacement OAuth client secret. Omit or pass `null` to keep the stored secret. This secret is never returned in resources. required: - type - - url - - pattern - BetaWebSearchActionOpenPage: + additionalProperties: false + description: Updates credentials sent in the token request body. + RotateMcpOauthTokenEndpointAuthParam: + description: Client-secret updates that preserve the credential's OAuth authentication method. + discriminator: + propertyName: type + mapping: + client_secret_basic: '#/components/schemas/RotateMcpOauthTokenEndpointAuthParamClientSecretBasic' + client_secret_post: '#/components/schemas/RotateMcpOauthTokenEndpointAuthParamClientSecretPost' + x-oai-discriminator-values: + - client_secret_basic + - client_secret_post + anyOf: + - $ref: '#/components/schemas/RotateMcpOauthTokenEndpointAuthParamClientSecretBasic' + - $ref: '#/components/schemas/RotateMcpOauthTokenEndpointAuthParamClientSecretPost' + RotateMcpOauthRefreshParam: type: object - title: Open page action - description: | - Action type "open_page" - Opens a specific URL from search results. properties: - type: - type: string - enum: - - open_page - description: | - The action type. - x-stainless-const: true - url: - description: | - The URL opened by the model. + refresh_token: + type: + - string + - 'null' + minLength: 0 + maxLength: 1048576 + description: The replacement refresh token. Omit or pass `null` to keep the stored token. This secret is never returned in resources. + scope: + type: + - string + - 'null' + minLength: 0 + maxLength: 1048576 + description: Replacement space-separated OAuth scopes for refresh requests. Omit to keep the scopes, or pass `null` to stop sending a scope parameter. + token_endpoint_auth: anyOf: - - type: string - format: uri + - $ref: '#/components/schemas/RotateMcpOauthTokenEndpointAuthParam' - type: 'null' - required: - - type - BetaWebSearchActionSearch: + description: Client-secret updates for the existing token endpoint authentication method. + additionalProperties: false + description: Updates to an MCP credential's existing OAuth refresh configuration. + RotateVaultCredentialAuthParamMcpOauth: type: object - title: Search action - description: | - Action type "search" - Performs a web search query. - properties: - type: - type: string - enum: - - search - description: | - The action type. - x-stainless-const: true - query: - type: string - deprecated: true - description: | - The search query. - queries: - type: array - title: Search queries - description: | - The search queries. - items: - type: string - description: | - A search query. - sources: - type: array - title: Web search sources - description: | - The sources used in the search. - items: - type: object - title: Web search source - description: | - A source used in the search. - properties: - type: - type: string - enum: - - url - description: | - The type of source. Always `url`. - x-stainless-const: true - url: - type: string - format: uri - description: | - The URL of the source. - required: - - type - - url - required: - - type - BetaWebSearchCallStatus: - type: string - enum: - - in_progress - - searching - - completed - - failed - - incomplete - BetaComputerCallOutputItemParam: properties: - agent: - anyOf: - - $ref: '#/components/schemas/Beta_AgentTagParam' - description: The agent that produced this item. - - type: 'null' - id: - anyOf: - - type: string - description: The ID of the computer tool call output. - example: cuo_123 - - type: 'null' - call_id: - type: string - maxLength: 64 - minLength: 1 - description: The ID of the computer tool call that produced the output. type: type: string enum: - - computer_call_output - description: The type of the computer tool call output. Always `computer_call_output`. - default: computer_call_output + - mcp_oauth + default: mcp_oauth x-stainless-const: true - output: - $ref: '#/components/schemas/BetaComputerScreenshotImage' - acknowledged_safety_checks: - anyOf: - - items: - $ref: '#/components/schemas/BetaComputerCallSafetyCheckParam' - type: array - description: The safety checks reported by the API that have been acknowledged by the developer. - - type: 'null' - status: + description: The type of the object. Always `mcp_oauth`. + access_token: + type: + - string + - 'null' + minLength: 0 + maxLength: 1048576 + description: A write-only replacement OAuth access token. + expires_at: + type: + - string + - 'null' + minLength: 0 + maxLength: 1048576 + description: The replacement expiry as an RFC 3339 timestamp, or `null` to clear it. Omitting this field preserves the expiry unless a new access token is supplied, in which case the expiry is cleared. + refresh: anyOf: - - $ref: '#/components/schemas/BetaFunctionCallItemStatus' - description: The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + - $ref: '#/components/schemas/RotateMcpOauthRefreshParam' - type: 'null' - type: object + description: Optional write-only refresh-token and client-secret updates. required: - - call_id - type - - output - title: Computer tool call output - description: The output of a computer tool call. - BetaComputerCallSafetyCheckParam: - properties: - id: - type: string - description: The ID of the pending safety check. - code: - anyOf: - - type: string - description: The type of the pending safety check. - - type: 'null' - message: - anyOf: - - type: string - description: Details about the pending safety check. - - type: 'null' - type: object - required: - - id - description: A pending safety check for the computer call. - BetaComputerScreenshotImage: + additionalProperties: false + description: Rotate an OAuth credential for an HTTPS MCP destination. + RotateVaultCredentialAuthParamStaticBearer: type: object - description: | - A computer screenshot image used with the computer use tool. properties: type: type: string enum: - - computer_screenshot - default: computer_screenshot - description: "Specifies the event type. For a computer screenshot, this property is \nalways set to `computer_screenshot`.\n" + - static_bearer + default: static_bearer x-stainless-const: true - image_url: - type: string - format: uri - description: The URL of the screenshot image. - file_id: + description: The type of the object. Always `static_bearer`. + token: type: string - description: The identifier of an uploaded file that contains the screenshot. + minLength: 0 + maxLength: 1048576 + description: The replacement bearer token. This secret is never returned in credential resources. required: - type - BetaComputerToolCall: + - token + additionalProperties: false + description: Replace the bearer token for the credential's MCP server. + BetaCreateModelResponseProperties: + allOf: + - $ref: '#/components/schemas/BetaModelResponseProperties' + - type: object + properties: + prompt_cache_options: + $ref: '#/components/schemas/BetaPromptCacheOptionsParam' + top_logprobs: + description: | + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. + type: integer + minimum: 0 + maximum: 20 + RotateVaultCredentialAuthParam: + description: Updates to a vault credential without changing its authentication method or MCP server. + discriminator: + propertyName: type + mapping: + mcp_oauth: '#/components/schemas/RotateVaultCredentialAuthParamMcpOauth' + static_bearer: '#/components/schemas/RotateVaultCredentialAuthParamStaticBearer' + x-oai-discriminator-values: + - mcp_oauth + - static_bearer + anyOf: + - $ref: '#/components/schemas/RotateVaultCredentialAuthParamMcpOauth' + - $ref: '#/components/schemas/RotateVaultCredentialAuthParamStaticBearer' + RotateVaultCredentialParams: + type: object + properties: + auth: + $ref: '#/components/schemas/RotateVaultCredentialAuthParam' + description: Replacement values for the credential's existing authentication method. + required: + - auth + additionalProperties: false + description: Secret, expiry, and OAuth refresh scope updates for an existing vault credential. + DeletedVaultCredentialResource: type: object - title: Computer tool call - description: | - A tool call to a computer use tool. See the - [computer use guide](https://developers.openai.com/api/docs/guides/tools-computer-use) for more information. properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that produced this item. - type: - type: string - description: The type of the computer call. Always `computer_call`. - enum: - - computer_call - default: computer_call id: type: string - description: The unique ID of the computer call. - call_id: - type: string - description: | - An identifier used when responding to the tool call with output. - action: - $ref: '#/components/schemas/BetaComputerAction' - actions: - $ref: '#/components/schemas/BetaComputerActionList' - pending_safety_checks: - type: array - items: - $ref: '#/components/schemas/BetaComputerCallSafetyCheckParam' - description: | - The pending safety checks for the computer call. - status: + minLength: 0 + description: The ID of the deleted credential. + object: type: string - description: | - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. enum: - - in_progress - - completed - - incomplete + - vault.credential.deleted + default: vault.credential.deleted + x-stainless-const: true + description: The object type. Always `vault.credential.deleted`. + deleted: + type: boolean + description: Whether the resource was deleted. Always `true`. required: - - type - id - - call_id - - pending_safety_checks - - status - BetaComputerActionList: - title: Computer Action List - type: array - description: | - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. - items: - $ref: '#/components/schemas/BetaComputerAction' - BetaComputerAction: - discriminator: - propertyName: type - anyOf: - - $ref: '#/components/schemas/BetaClickParam' - - $ref: '#/components/schemas/BetaDoubleClickAction' - - $ref: '#/components/schemas/BetaDragParam' - - $ref: '#/components/schemas/BetaKeyPressAction' - - $ref: '#/components/schemas/BetaMoveParam' - - $ref: '#/components/schemas/BetaScreenshotParam' - - $ref: '#/components/schemas/BetaScrollParam' - - $ref: '#/components/schemas/BetaTypeParam' - - $ref: '#/components/schemas/BetaWaitParam' - BetaWaitParam: + - object + - deleted + additionalProperties: false + description: Confirmation that a vault credential was deleted. + WebhookEndpointBody: properties: - type: + id: + type: string + description: The unique ID of the webhook endpoint. + object: type: string enum: - - wait - description: Specifies the event type. For a wait action, this property is always set to `wait`. - default: wait + - webhook_endpoint + description: The object type, which is always webhook_endpoint. + default: webhook_endpoint x-stainless-const: true - type: object - required: - - type - title: Wait - description: A wait action. - BetaTypeParam: - properties: - type: + created_at: + type: integer + format: unixtime + description: The Unix timestamp when the endpoint was created. + updated_at: + type: integer + format: unixtime + description: The Unix timestamp of the last endpoint configuration or signing-secret change. Initialized at creation; tests and unchanged updates do not advance it. + name: type: string - enum: - - type - description: Specifies the event type. For a type action, this property is always set to `type`. - default: type - x-stainless-const: true - text: + description: The human-readable name of the endpoint. + url: type: string - description: The text to type. + description: The HTTPS URL that receives webhook deliveries. + event_types: + items: + type: string + type: array + description: The event types that trigger deliveries to this endpoint. + signing_secret_hint: + anyOf: + - type: string + description: A masked hint for the endpoint's signing secret. + - type: 'null' type: object required: - - type - - text - title: Type - description: An action to type in text. - BetaScrollParam: + - id + - object + - created_at + - name + - url + - event_types + - signing_secret_hint + WebhookEndpointListResource: properties: - type: + object: type: string enum: - - scroll - description: Specifies the event type. For a scroll action, this property is always set to `scroll`. - default: scroll + - list + description: The object type, which is always list. + default: list x-stainless-const: true - x: - type: integer - description: The x-coordinate where the scroll occurred. - y: - type: integer - description: The y-coordinate where the scroll occurred. - scroll_x: - type: integer - description: The horizontal scroll distance. - scroll_y: - type: integer - description: The vertical scroll distance. - keys: + data: + items: + $ref: '#/components/schemas/WebhookEndpointBody' + type: array + description: The webhook endpoints in this page. + first_id: anyOf: - - items: - type: string - type: array - description: The keys being held while scrolling. + - type: string + description: The ID of the first endpoint in this page. + - type: 'null' + last_id: + anyOf: + - type: string + description: The ID of the last endpoint in this page. - type: 'null' + has_more: + type: boolean + description: Whether more webhook endpoints are available. type: object required: - - type - - x - - y - - scroll_x - - scroll_y - title: Scroll - description: A scroll action. - BetaScreenshotParam: + - object + - data + - first_id + - last_id + - has_more + ProjectEventTypeEnum: + type: string + enum: + - batch.completed + - batch.failed + - batch.expired + - batch.cancelled + - response.completed + - response.failed + - response.cancelled + - response.incomplete + - eval.run.succeeded + - eval.run.failed + - eval.run.canceled + - fine_tuning.job.succeeded + - fine_tuning.job.failed + - fine_tuning.job.cancelled + - realtime.call.incoming + - video.completed + - video.failed + - safety.alert.created + PublicCreateEndpointBody: properties: - type: + name: type: string - enum: - - screenshot - description: Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - default: screenshot - x-stainless-const: true + maxLength: 256 + minLength: 1 + description: A human-readable name for the webhook endpoint. + url: + type: string + maxLength: 2048 + pattern: ^https:// + description: The HTTPS URL that receives webhook deliveries. + event_types: + items: + $ref: '#/components/schemas/ProjectEventTypeEnum' + type: array + minItems: 1 + description: The event types that trigger deliveries to this endpoint. type: object required: - - type - title: Screenshot - description: A screenshot action. - BetaMoveParam: + - name + - url + - event_types + WebhookEndpointWithSecretResource: properties: - type: + id: + type: string + description: The unique ID of the webhook endpoint. + object: type: string enum: - - move - description: Specifies the event type. For a move action, this property is always set to `move`. - default: move + - webhook_endpoint + description: The object type, which is always webhook_endpoint. + default: webhook_endpoint x-stainless-const: true - x: + created_at: type: integer - description: The x-coordinate to move to. - y: + format: unixtime + description: The Unix timestamp when the endpoint was created. + updated_at: type: integer - description: The y-coordinate to move to. - keys: + format: unixtime + description: The Unix timestamp of the last endpoint configuration or signing-secret change. Initialized at creation; tests and unchanged updates do not advance it. + name: + type: string + description: The human-readable name of the endpoint. + url: + type: string + description: The HTTPS URL that receives webhook deliveries. + event_types: + items: + type: string + type: array + description: The event types that trigger deliveries to this endpoint. + signing_secret_hint: anyOf: - - items: - type: string - type: array - description: The keys being held while moving the mouse. + - type: string + description: A masked hint for the endpoint's signing secret. - type: 'null' + signing_secret: + type: string + description: The endpoint's signing secret. This is returned only when the endpoint is created or the secret is rotated. type: object required: - - type - - x - - y - title: Move - description: A mouse move action. - BetaKeyPressAction: + - id + - object + - created_at + - name + - url + - event_types + - signing_secret_hint + - signing_secret + PublicUpdateEndpointBody: properties: - type: + name: type: string - enum: - - keypress - description: Specifies the event type. For a keypress action, this property is always set to `keypress`. - default: keypress - x-stainless-const: true - keys: + maxLength: 256 + minLength: 1 + description: A new human-readable name for the webhook endpoint. + url: + type: string + maxLength: 2048 + pattern: ^https:// + description: A new HTTPS URL that receives webhook deliveries. + event_types: items: - type: string - description: One of the keys the model is requesting to be pressed. + $ref: '#/components/schemas/ProjectEventTypeEnum' type: array - description: The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + minItems: 1 + description: The complete set of event types that should trigger deliveries. type: object - required: - - type - - keys - title: KeyPress - description: A collection of keypresses the model would like to perform. - BetaDragParam: + required: [] + DeletedWebhookEndpointResource: properties: - type: + id: + type: string + description: The ID of the deleted webhook endpoint. + object: type: string enum: - - drag - description: Specifies the event type. For a drag action, this property is always set to `drag`. - default: drag + - webhook_endpoint.deleted + description: The object type, which is always webhook_endpoint.deleted. + default: webhook_endpoint.deleted x-stainless-const: true - path: - items: - $ref: '#/components/schemas/BetaCoordParam' - type: array - description: |- - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` - keys: - anyOf: - - items: - type: string - type: array - description: The keys being held while dragging the mouse. - - type: 'null' + deleted: + type: boolean + description: Whether the endpoint was deleted. type: object required: - - type - - path - title: Drag - description: A drag action. - BetaCoordParam: + - id + - object + - deleted + PublicRotateSecretBody: properties: - x: - type: integer - description: The x-coordinate. - y: - type: integer - description: The y-coordinate. + keep_old_secret_active_for_24_hours: + type: boolean + description: Whether to keep the previous signing secret valid for 24 hours after rotation. Defaults to false, which invalidates the previous secret immediately. + type: object + required: [] + PublicTestEndpointBody: + properties: + event_type: + $ref: '#/components/schemas/ProjectEventTypeEnum' + description: The event type to send as a sample delivery. type: object required: - - x - - y - title: Coordinate - description: 'An x/y coordinate pair, e.g. `{ x: 100, y: 200 }`.' - BetaDoubleClickAction: + - event_type + WebhookEndpointTestResultResource: properties: - type: + object: type: string enum: - - double_click - description: Specifies the event type. For a double click action, this property is always set to `double_click`. - default: double_click + - webhook_endpoint.test + description: The object type, which is always webhook_endpoint.test. + default: webhook_endpoint.test x-stainless-const: true - x: - type: integer - description: The x-coordinate where the double click occurred. - y: + webhook_endpoint_id: + type: string + description: The ID of the webhook endpoint that received the test. + event_type: + type: string + description: The event type sent in the test. + status_code: type: integer - description: The y-coordinate where the double click occurred. - keys: - anyOf: - - items: - type: string - type: array - description: The keys being held while double-clicking. - - type: 'null' + description: The HTTP status code returned by the endpoint. + success: + type: boolean + enum: + - true + description: Whether the test request completed. Always true for returned results; use status_code to determine the endpoint response. + default: true + x-stainless-const: true type: object required: - - type - - x - - y - - keys - title: DoubleClick - description: A double click action. - BetaClickParam: + - object + - webhook_endpoint_id + - event_type + - status_code + - success + WebhookEventTypeListResource: properties: - type: + object: type: string enum: - - click - description: Specifies the event type. For a click action, this property is always `click`. - default: click + - list + description: The object type, which is always list. + default: list x-stainless-const: true - button: - $ref: '#/components/schemas/BetaClickButtonType' - description: Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + data: + items: + type: string + type: array + description: The webhook event types available to the authenticated project. + type: object + required: + - object + - data + DragPoint: + properties: x: type: integer - description: The x-coordinate where the click occurred. + description: The x-coordinate. y: type: integer - description: The y-coordinate where the click occurred. - keys: - anyOf: - - items: - type: string - type: array - description: The keys being held while clicking. - - type: 'null' + description: The y-coordinate. type: object required: - - type - - button - x - y - title: Click - description: A click action. - BetaClickButtonType: - type: string - enum: - - left - - right - - wheel - - back - - forward - BetaFileSearchToolCall: + title: Coordinate + description: 'An x/y coordinate pair, e.g. `{ x: 100, y: 200 }`.' + LiveSessionAudioFormatPCMParam: + description: Raw, mono 16-bit little-endian PCM audio for a Live WebSocket connection. type: object - title: File search tool call - description: | - The results of a file search tool call. See the - [file search guide](https://developers.openai.com/api/docs/guides/tools-file-search) for more information. properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that produced this item. - id: - type: string - description: | - The unique ID of the file search tool call. type: - type: string - enum: - - file_search_call - description: | - The type of the file search tool call. Always `file_search_call`. + description: The audio encoding. Always `audio/pcm`. + default: audio/pcm x-stainless-const: true - status: type: string - description: | - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, enum: - - in_progress - - searching - - completed - - incomplete - - failed - queries: - type: array - items: - type: string - description: | - The queries used to search for files. - results: - anyOf: - - type: array - description: | - The results of the file search tool call. - items: - type: object - properties: - file_id: - type: string - description: | - The unique ID of the file. - text: - type: string - description: | - The text that was retrieved from the file. - filename: - type: string - description: | - The name of the file. - attributes: - $ref: '#/components/schemas/BetaVectorStoreFileAttributes' - score: - type: number - format: float - description: | - The relevance score of the file - a value between 0 and 1. - - type: 'null' + - audio/pcm + rate: + description: Audio sample rate in hertz. Live WebSocket PCM audio supports 16000 or 24000 Hz. + type: integer + minimum: 16000 + maximum: 24000 + enum: + - 16000 + - 24000 required: - - id - type - - status - - queries - BetaVectorStoreFileAttributes: - anyOf: - - type: object - description: | - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. - maxProperties: 16 - propertyNames: - type: string - maxLength: 64 - additionalProperties: - anyOf: - - type: string - maxLength: 512 - - type: number - - type: boolean - x-oaiTypeLabel: map - - type: 'null' - BetaOutputMessage: + - rate + LiveSessionAudioFormatPCMUParam: + description: Raw, mono G.711 μ-law audio for a Live WebSocket connection. type: object - title: Output message - description: | - An output message from the model. properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that produced this item. - id: - type: string - description: | - The unique ID of the output message. - x-stainless-go-json: omitzero type: - type: string - description: | - The type of the output message. Always `message`. - enum: - - message + description: The audio encoding. Always `audio/pcmu`. + default: audio/pcmu x-stainless-const: true - role: type: string - description: | - The role of the output message. Always `assistant`. enum: - - assistant + - audio/pcmu + rate: + description: Audio sample rate in hertz. G.711 audio uses 8000 Hz. + type: integer + minimum: 8000 + maximum: 8000 + required: + - type + - rate + LiveSessionAudioFormatPCMAParam: + description: Raw, mono G.711 A-law audio for a Live WebSocket connection. + type: object + properties: + type: + description: The audio encoding. Always `audio/pcma`. + default: audio/pcma x-stainless-const: true - content: - type: array - description: | - The content of the output message. - items: - $ref: '#/components/schemas/BetaOutputMessageContent' - phase: - anyOf: - - $ref: '#/components/schemas/BetaMessagePhase' - - type: 'null' - status: type: string - description: | - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. enum: - - in_progress - - completed - - incomplete + - audio/pcma + rate: + description: Audio sample rate in hertz. G.711 audio uses 8000 Hz. + type: integer + minimum: 8000 + maximum: 8000 required: - - id - type - - role - - content - - status - BetaMessagePhase: - type: string - description: | - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - enum: - - commentary - - final_answer - BetaOutputMessageContent: + - rate + LiveAudioFormat: + description: Audio encoding and sample rate for audio sent and received over a Live WebSocket connection. WebRTC and SIP negotiate their media format separately. discriminator: propertyName: type anyOf: - - $ref: '#/components/schemas/BetaOutputTextContent' - - $ref: '#/components/schemas/BetaRefusalContent' - BetaRefusalContent: + - $ref: '#/components/schemas/LiveSessionAudioFormatPCMParam' + - $ref: '#/components/schemas/LiveSessionAudioFormatPCMUParam' + - $ref: '#/components/schemas/LiveSessionAudioFormatPCMAParam' + LiveInitialSessionAudioParam: + description: Startup audio configuration. Only primary WebSockets accept audio.format; WebRTC and SIP negotiate their media format. Voice and format are immutable after startup. + type: object properties: - type: - type: string - enum: - - refusal - description: The type of the refusal. Always `refusal`. - default: refusal - x-stainless-const: true - refusal: - type: string - description: The refusal explanation from the model. + format: + description: Audio encoding and sample rate for audio sent and received over a Live WebSocket connection. WebRTC and SIP negotiate their media format separately. + $ref: '#/components/schemas/LiveAudioFormat' + output: + description: The voice used for speech generated by the Live model. + $ref: '#/components/schemas/LiveInitialSessionAudioOutputParam' + required: [] + LiveSessionCreateParams: + description: Initial configuration for a Live session, including its model, conversation instructions, audio, and delegated task handling. type: object + properties: + model: + $ref: '#/components/schemas/ModelIdsLive' + instructions: + anyOf: + - description: Frontend instructions for voice, conversation, interruptions, and when to delegate. Start with the [Live prompting guide](https://developers.openai.com/api/docs/guides/live-prompting); put business rules and tool workflows in a separate [backend prompt](https://developers.openai.com/api/docs/guides/live-delegation#start-with-your-existing-backend-prompt). Limited to 16,384 client-supplied tokens. Omitted or blank instructions use server defaults. Immutable after startup. + type: string + - type: 'null' + input: + description: Ordered text-only history supplied before startup. Supports developer, user, and assistant messages with one text part each; at most 128 messages and 8,192 rendered tokens in total. + type: array + items: + $ref: '#/components/schemas/LiveInitialItem' + maxItems: 128 + audio: + description: Startup audio configuration. Only primary WebSockets accept audio.format; WebRTC and SIP negotiate their media format. Voice and format are immutable after startup. + $ref: '#/components/schemas/LiveInitialSessionAudioParam' + delegation: + anyOf: + - description: Who handles tasks delegated by the Live model. Omitted or null selects your application; use `responses` to let the API manage a Responses backend. + discriminator: + propertyName: type + anyOf: + - $ref: '#/components/schemas/LiveClientDelegationParam' + - $ref: '#/components/schemas/LiveResponsesDelegationParam' + - type: 'null' + store: + description: Whether to store the session for later forking and recording download. Defaults to false for new sessions. + type: boolean + client: + description: Startup-only capabilities for an untrusted frontend attached to a unified WebRTC session. Trusted sideband connections are unaffected. + $ref: '#/components/schemas/LiveClientConfigParam' required: - - type - - refusal - title: Refusal - description: A refusal from the model. - BetaOutputTextContent: + - model + LiveSessionStartEvent: + description: Start a Live session on a primary WebSocket. Send this event before other commands and wait for `session.started`. + example: + type: session.start + event_id: evt_start_001 + session: + model: gpt-live-1 + instructions: Help the caller plan a restaurant reservation. Confirm details before booking. + audio: + format: + type: audio/pcm + rate: 24000 + output: + voice: marin + delegation: + type: client + type: object properties: + event_id: + anyOf: + - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. + type: string + maxLength: 512 + - type: 'null' type: - type: string - enum: - - output_text - description: The type of the output text. Always `output_text`. - default: output_text + description: The Live client event type. Always `session.start`. + default: session.start x-stainless-const: true - text: type: string - description: The text output from the model. - annotations: - items: - $ref: '#/components/schemas/BetaAnnotation' - type: array - description: The annotations of the text output. - logprobs: - items: - $ref: '#/components/schemas/BetaLogProb' - type: array - type: object + enum: + - session.start + session: + description: Initial configuration for a primary WebSocket. Send session.start first and wait for session.started before application commands. WebRTC creation already starts the session; do not send this event again on its data channel. + $ref: '#/components/schemas/LiveSessionCreateParams' required: - type - - text - - annotations - title: Output text - description: A text output from the model. - BetaLogProb: + - session + x-oaiMeta: + example: + type: session.start + event_id: evt_start_001 + session: + model: gpt-live-1 + instructions: Help the caller plan a restaurant reservation. Confirm details before booking. + audio: + format: + type: audio/pcm + rate: 24000 + output: + voice: marin + delegation: + type: client + LiveSessionUpdateParams: + description: Changes to an active Live session. Only delegation backend settings can be updated after startup. + type: object properties: - token: - type: string - logprob: - type: number - bytes: - items: - type: integer - type: array - top_logprobs: - items: - $ref: '#/components/schemas/BetaTopLogProb' - type: array + delegation: + anyOf: + - description: Delegation settings to update. The delegation type must match the current session; omitted settings retain their values. + discriminator: + propertyName: type + anyOf: + - $ref: '#/components/schemas/LiveClientDelegationParam' + - $ref: '#/components/schemas/LiveResponsesDelegationUpdateParam' + - type: 'null' + required: [] + LiveSessionUpdateParam: + description: Update the delegation settings of an active Live session. The server acknowledges accepted changes with `session.updated`. + example: + type: session.update + event_id: evt_update_001 + session: + delegation: + type: responses + responses: + instructions: Check restaurant availability. Ask before confirming a booking. + max_output_tokens: 1024 type: object - required: - - token - - logprob - - bytes - - top_logprobs - title: Log probability - description: The log probability of a token. - BetaTopLogProb: properties: - token: + event_id: + anyOf: + - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. + type: string + maxLength: 512 + - type: 'null' + type: + description: The Live client event type. Always `session.update`. + default: session.update + x-stainless-const: true type: string - logprob: - type: number - bytes: - items: - type: integer - type: array - type: object + enum: + - session.update + session: + description: Sparse delegation updates. Omitted settings retain their values. The delegation type cannot change, including resetting Responses delegation to null or client. Model, frontend instructions, audio, and startup input are immutable. + $ref: '#/components/schemas/LiveSessionUpdateParams' required: - - token - - logprob - - bytes - title: Top log probability - description: The top log probability of a token. - BetaAnnotation: - discriminator: - propertyName: type - description: An annotation that applies to a span of output text. - anyOf: - - $ref: '#/components/schemas/BetaFileCitationBody' - - $ref: '#/components/schemas/BetaUrlCitationBody' - - $ref: '#/components/schemas/BetaContainerFileCitationBody' - - $ref: '#/components/schemas/BetaFilePath' - BetaFilePath: + - type + - session + x-oaiMeta: + example: + type: session.update + event_id: evt_update_001 + session: + delegation: + type: responses + responses: + instructions: Check restaurant availability. Ask before confirming a booking. + max_output_tokens: 1024 + LiveInputAudioAppendEvent: + description: Send audio to a Live session over its primary WebSocket. WebRTC and SIP sessions send audio over their media transport. + example: + type: session.input_audio.append + audio: AACAAIAAAIAAAP9/AIAAgA== type: object - title: File path - description: | - A path to a file. properties: + event_id: + anyOf: + - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. + type: string + maxLength: 512 + - type: 'null' type: + description: The Live client event type. Always `session.input_audio.append`. + default: session.input_audio.append + x-stainless-const: true type: string - description: | - The type of the file path. Always `file_path`. enum: - - file_path - x-stainless-const: true - file_id: + - session.input_audio.append + audio: + description: Base64-encoded raw audio in the startup-selected format, without a WAV or other container header. Primary WebSocket only; media transports use their audio track. Audio appends have no acknowledgment. Reflected sideband server events reuse this event type and audio key, with no timestamps or event_id; their audio is always mono PCM16LE at 24 kHz. type: string - description: | - The ID of the file. - index: - type: integer - description: | - The index of the file in the list of files. + minLength: 1 required: - type - - file_id - - index - BetaContainerFileCitationBody: + - audio + x-oaiMeta: + example: + type: session.input_audio.append + audio: AACAAIAAAIAAAP9/AIAAgA== + LiveInputAudioMuteParam: + description: Mute audio input to the Live model without closing the session. The server acknowledges with `session.input_audio.muted`. + example: + type: session.input_audio.mute + event_id: evt_mute_001 + type: object properties: + event_id: + anyOf: + - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. + type: string + maxLength: 512 + - type: 'null' type: - type: string - enum: - - container_file_citation - description: The type of the container file citation. Always `container_file_citation`. - default: container_file_citation + description: The Live client event type. Always `session.input_audio.mute`. + default: session.input_audio.mute x-stainless-const: true - container_id: - type: string - description: The ID of the container file. - file_id: type: string - description: The ID of the file. - start_index: - type: integer - description: The index of the first character of the container file citation in the message. - end_index: - type: integer - description: The index of the last character of the container file citation in the message. - filename: - type: string - description: The filename of the container file cited. - type: object + enum: + - session.input_audio.mute required: - type - - container_id - - file_id - - start_index - - end_index - - filename - title: Container file citation - description: A citation for a container file used to generate a model response. - BetaUrlCitationBody: + x-oaiMeta: + example: + type: session.input_audio.mute + event_id: evt_mute_001 + LiveInputAudioUnmuteParam: + description: Resume audio input to a Live model after muting it. The server acknowledges with `session.input_audio.unmuted`. + example: + type: session.input_audio.unmute + event_id: evt_unmute_001 + type: object properties: + event_id: + anyOf: + - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. + type: string + maxLength: 512 + - type: 'null' type: + description: The Live client event type. Always `session.input_audio.unmute`. + default: session.input_audio.unmute + x-stainless-const: true type: string enum: - - url_citation - description: The type of the URL citation. Always `url_citation`. - default: url_citation + - session.input_audio.unmute + required: + - type + x-oaiMeta: + example: + type: session.input_audio.unmute + event_id: evt_unmute_001 + LiveInstructionsAppendParam: + description: Append instructions to the Live conversation while it is running, optionally associating them with an existing client delegation. + example: + type: session.instructions.append + event_id: evt_instructions_001 + delegation_id: null + content: The caller prefers outdoor seating. + type: object + properties: + event_id: + anyOf: + - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. + type: string + maxLength: 512 + - type: 'null' + type: + description: The Live client event type. Always `session.instructions.append`. + default: session.instructions.append x-stainless-const: true - url: type: string - format: uri - description: The URL of the web resource. - start_index: - type: integer - description: The index of the first character of the URL citation in the message. - end_index: - type: integer - description: The index of the last character of the URL citation in the message. - title: + enum: + - session.instructions.append + delegation_id: + anyOf: + - description: Required, nullable. Set null for general session context, or use the ID from session.delegation.created for an existing client delegation. Non-null IDs are not accepted with Responses delegation. + type: string + minLength: 1 + - type: 'null' + content: + description: Instruction text to append, limited to 500 tokens. This is a plain string, not an array of content parts. type: string - description: The title of the web resource. - type: object required: - type - - url - - start_index - - end_index - - title - title: URL citation - description: A citation for a web resource used to generate a model response. - BetaFileCitationBody: + - delegation_id + - content + x-oaiMeta: + example: + type: session.instructions.append + event_id: evt_instructions_001 + delegation_id: null + content: The caller prefers outdoor seating. + LiveThinkingAppendParam: + description: Provide silent reasoning or progress context to the Live model, optionally for an existing client delegation. + example: + type: session.thinking.append + event_id: evt_thinking_001 + delegation_id: del_abc123 + content: Checking availability for two guests at 7 PM. + type: object properties: + event_id: + anyOf: + - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. + type: string + maxLength: 512 + - type: 'null' type: - type: string - enum: - - file_citation - description: The type of the file citation. Always `file_citation`. - default: file_citation + description: The Live client event type. Always `session.thinking.append`. + default: session.thinking.append x-stainless-const: true - file_id: type: string - description: The ID of the file. - index: - type: integer - description: The index of the file in the list of files. - filename: + enum: + - session.thinking.append + delegation_id: + anyOf: + - description: Required, nullable. Set null for general session context, or use the ID from session.delegation.created for an existing client delegation. Non-null IDs are not accepted with Responses delegation. + type: string + minLength: 1 + - type: 'null' + content: + description: Silent reasoning or progress context, limited to 500 tokens. It does not directly request speech, but can influence later speech and is not a secrecy boundary. type: string - description: The filename of the file cited. - type: object required: - type - - file_id - - index - - filename - title: File citation - description: A citation to a file. - BetaInputMessage: + - delegation_id + - content + x-oaiMeta: + example: + type: session.thinking.append + event_id: evt_thinking_001 + delegation_id: del_abc123 + content: Checking availability for two guests at 7 PM. + LiveCommentaryAppendParam: + description: Provide context the Live model can communicate to the user, optionally for an existing client delegation. + example: + type: session.commentary.append + event_id: evt_commentary_001 + delegation_id: del_abc123 + content: There is an outdoor table for two at 7 PM. Ask whether to reserve it. type: object - title: Input message - description: | - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. properties: - agent: + event_id: anyOf: - - $ref: '#/components/schemas/BetaAgentTag' + - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. + type: string + maxLength: 512 - type: 'null' - description: The agent that produced this item. type: - type: string - description: | - The type of the message input. Always set to `message`. - enum: - - message + description: The Live client event type. Always `session.commentary.append`. + default: session.commentary.append x-stainless-const: true - role: - type: string - description: | - The role of the message input. One of `user`, `system`, or `developer`. - enum: - - user - - system - - developer - status: type: string - description: | - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. enum: - - in_progress - - completed - - incomplete + - session.commentary.append + delegation_id: + anyOf: + - description: Required, nullable. Set null for general session context, or use the ID from session.delegation.created for an existing client delegation. Non-null IDs are not accepted with Responses delegation. + type: string + minLength: 1 + - type: 'null' content: - $ref: '#/components/schemas/BetaInputMessageContentList' + description: Speakable context for the Live model, limited to 500 tokens. Use this for a result the model should communicate; use session.thinking.append for silent context. + type: string required: - - role + - type + - delegation_id - content - BetaInputMessageContentList: - type: array - title: Input item content list - description: "A list of one or many input items to the model, containing different content \ntypes.\n" - items: - $ref: '#/components/schemas/BetaInputContent' - BetaInputContent: - discriminator: - propertyName: type - anyOf: - - $ref: '#/components/schemas/BetaInputTextContent' - - $ref: '#/components/schemas/BetaInputImageContent' - - $ref: '#/components/schemas/BetaInputFileContent' - BetaEasyInputMessage: + x-oaiMeta: + example: + type: session.commentary.append + event_id: evt_commentary_001 + delegation_id: del_abc123 + content: There is an outdoor table for two at 7 PM. Ask whether to reserve it. + LiveResponseItemCreateParam: + description: Add an input item to the Live session’s Responses backend. Requires Responses delegation; use `response.create` to request a response. + example: + type: response.item.create + event_id: evt_item_001 + item: + type: message + role: user + content: + - type: input_text + text: Please check for a table for two at 7 PM. type: object - title: Input message - description: | - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. properties: - role: - type: string - description: | - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. - enum: - - user - - assistant - - system - - developer - content: - description: | - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. - anyOf: - - type: string - title: Text input - description: | - A text input to the model. - - $ref: '#/components/schemas/BetaInputMessageContentList' - phase: + event_id: anyOf: - - $ref: '#/components/schemas/BetaMessagePhase' + - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. + type: string + maxLength: 512 - type: 'null' type: + description: The Live client event type. Always `response.item.create`. + default: response.item.create + x-stainless-const: true type: string - description: | - The type of the message input. Always `message`. enum: - - message - x-stainless-const: true + - response.item.create + item: + description: An input item to append to the Responses backend conversation, such as a user message or a function tool result. + $ref: '#/components/schemas/InputItem' required: - - role - - content - BetaCompactResponseMethodPublicBody: + - type + - item + x-oaiMeta: + example: + type: response.item.create + event_id: evt_item_001 + item: + type: message + role: user + content: + - type: input_text + text: Please check for a table for two at 7 PM. + LiveResponseCreateParam: + description: Request a response from the Live session’s Responses backend, or continue a delegated response waiting for tool results. Requires Responses delegation. + example: + type: response.create + event_id: evt_response_001 + type: object properties: - model: - $ref: '#/components/schemas/BetaModelIdsCompaction' - input: - anyOf: - - description: Text, image, or file inputs to the model, used to generate a response - anyOf: - - type: string - maxLength: 10485760 - description: A text input to the model, equivalent to a text input with the `user` role. - - items: - $ref: '#/components/schemas/BetaInputItem' - type: array - maxItems: 131072 - description: A list of one or many input items to the model, containing different content types. - - type: 'null' - previous_response_id: - anyOf: - - type: string - description: The unique ID of the previous response to the model. Use this to create multi-turn conversations. Learn more about [conversation state](https://developers.openai.com/api/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. - example: resp_123 - - type: 'null' - instructions: - anyOf: - - type: string - description: |- - A system (or developer) message inserted into the model's context. - When used along with `previous_response_id`, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses. - - type: 'null' - prompt_cache_key: - anyOf: - - type: string - maxLength: 64 - description: A key to use when reading from or writing to the prompt cache. - - type: 'null' - prompt_cache_retention: - anyOf: - - $ref: '#/components/schemas/BetaPromptCacheRetentionEnum' - description: How long to retain a prompt cache entry created by this request. - deprecated: true - - type: 'null' - prompt_cache_options: - anyOf: - - $ref: '#/components/schemas/BetaPromptCacheOptionsParam' - - type: 'null' - service_tier: + event_id: anyOf: - - $ref: '#/components/schemas/BetaServiceTierEnum' - description: |- - Specifies the processing type used for serving the request. - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - If set to '[flex](https://developers.openai.com/api/docs/guides/flex-processing)', then the request will be processed with the Flex Processing service tier. - To opt-in to [Fast mode](https://developers.openai.com/api/docs/guides/fast-mode) at the request level, include the `service_tier=fast` or `service_tier=priority` parameter for Responses or Chat Completions. For models with a dedicated Fast tier, either value resolves to `service_tier=fast`; for other models, either value resolves to `service_tier=priority`. - When not set, the default behavior is 'auto'. - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. + type: string + maxLength: 512 - type: 'null' - type: object + type: + description: The Live client event type. Always `response.create`. + default: response.create + x-stainless-const: true + type: string + enum: + - response.create required: - - model - BetaServiceTierEnum: - type: string - enum: - - auto - - default - - fast - - flex - - priority - BetaPromptCacheOptionsParam: - properties: - ttl: - $ref: '#/components/schemas/BetaPromptCacheTTLEnum' - description: The minimum lifetime applied to every implicit and explicit cache breakpoint written by the request. Defaults to `30m`, which is currently the only supported value. The backend may retain cache entries for longer. - mode: - $ref: '#/components/schemas/BetaPromptCacheModeEnum' - description: Controls whether OpenAI automatically creates an implicit cache breakpoint. Defaults to `implicit`. With `implicit`, OpenAI creates one implicit breakpoint and writes up to the latest three explicit breakpoints in the request. With `explicit`, OpenAI does not create an implicit breakpoint and writes up to the latest four explicit breakpoints. If there are no explicit breakpoints, the request does not use prompt caching. - type: object - required: [] - title: Prompt cache options - description: Options for prompt caching. Supported for `gpt-5.6` and later models. By default, OpenAI automatically chooses one implicit cache breakpoint. You can add explicit breakpoints to content blocks with `prompt_cache_breakpoint`. Each request can write up to four breakpoints. For cache matching, OpenAI considers up to the latest 80 breakpoints in the conversation, without a content-block lookback limit. Set `mode` to `explicit` to disable the implicit breakpoint. The `ttl` defaults to `30m`, which is currently the only supported value. See the [prompt caching guide](https://developers.openai.com/api/docs/guides/prompt-caching) for current details. - BetaPromptCacheModeEnum: - type: string - enum: - - implicit - - explicit - BetaPromptCacheTTLEnum: - type: string - enum: - - 30m - BetaPromptCacheRetentionEnum: - type: string - enum: - - in_memory - - 24h - BetaModelIdsCompaction: - anyOf: - - $ref: '#/components/schemas/BetaModelIdsResponses' - - type: string - - type: 'null' - description: Model ID used to generate the response, like `gpt-6-astra`. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](https://developers.openai.com/api/docs/models) to browse and compare available models. - BetaModelIdsResponses: - example: gpt-6-astra - anyOf: - - $ref: '#/components/schemas/BetaModelIdsShared' - - type: string - title: ResponsesOnlyModel - enum: - - o1-pro - - o1-pro-2025-03-19 - - o3-pro - - o3-pro-2025-06-10 - - o3-deep-research - - o3-deep-research-2025-06-26 - - o4-mini-deep-research - - o4-mini-deep-research-2025-06-26 - - computer-use-preview - - computer-use-preview-2025-03-11 - - gpt-5.5-pro - - gpt-5.5-pro-2026-04-23 - - gpt-5-codex - - gpt-5-pro - - gpt-5-pro-2025-10-06 - - gpt-5.1-codex-max - - gpt-daybreak-blue-latest - - gpt-daybreak-red-latest - - gpt-5.6-cyber - BetaModelIdsShared: - example: gpt-6-astra - anyOf: - - type: string - - $ref: '#/components/schemas/ChatModel' - BetaError: + - type + x-oaiMeta: + example: + type: response.create + event_id: evt_response_001 + LiveSessionCloseParam: + description: Request that the Live session close. The terminal `session.closed` event contains the close reason and final usage. + example: + type: session.close + event_id: evt_close_001 type: object properties: - code: - anyOf: - - type: string - - type: 'null' - message: - type: string - param: + event_id: anyOf: - - type: string + - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. + type: string + maxLength: 512 - type: 'null' type: + description: The Live client event type. Always `session.close`. + default: session.close + x-stainless-const: true type: string - misalignment: - $ref: '#/components/schemas/BetaMisalignmentErrorDetailsResource' + enum: + - session.close required: - type - - message - - param - - code - BetaMisalignmentErrorDetailsResource: - properties: - error_type: - $ref: '#/components/schemas/Beta_MisalignmentErrorType' - description: An optional classification; clients must accept additional values. - detailed_explanation: - type: string - description: The public explanation for this block. - steer: - $ref: '#/components/schemas/Beta_MisalignmentSteer' - description: An optional public continuation instruction. + x-oaiMeta: + example: + type: session.close + event_id: evt_close_001 + LiveForkAudioParam: + description: Audio format for the new WebSocket connection to a forked Live session. The stored voice is preserved. type: object - required: [] - Beta_MisalignmentSteer: properties: - message: - type: string - description: The public continuation instruction. - type: object - required: - - message - Beta_MisalignmentErrorType: - anyOf: - - type: string - - type: string - enum: - - potentially_unintended_data_transfer - - potentially_unintended_data_access - - potentially_unintended_destructive_activity - - other - BetaResponseItemList: + format: + description: Audio encoding and sample rate for audio sent and received over a Live WebSocket connection. WebRTC and SIP negotiate their media format separately. + $ref: '#/components/schemas/LiveAudioFormat' + required: [] + LiveForkSessionConfigParam: + description: Overrides for a stored session after connecting to the fork WebSocket. An empty object inherits the stored configuration; do not supply a new model. audio.format applies only to the new WebSocket connection. client overrides are only supported for WebRTC forks. type: object - description: A list of Response items. properties: - object: - x-stainless-const: true - description: The type of object returned, must be `list`. - const: list - data: - type: array - description: A list of items used to generate this response. - items: - $ref: '#/components/schemas/BetaItemResource' - has_more: + audio: + description: Audio format for a WebSocket fork. WebRTC forks negotiate their audio format and must omit this field. + $ref: '#/components/schemas/LiveForkAudioParam' + delegation: + description: Overrides for the stored session’s Responses backend. Only supported when the stored session already uses Responses delegation; the delegation type cannot change. + $ref: '#/components/schemas/LiveResponsesDelegationUpdateParam' + store: + description: Whether to store the forked session. Omission inherits the stored session's setting. type: boolean - description: Whether there are more items available. - first_id: - type: string - description: The ID of the first item in the list. - last_id: - type: string - description: The ID of the last item in the list. - required: - - object - - data - - has_more - - first_id - - last_id - x-oaiMeta: - name: The input item list - group: responses - example: | - { - "object": "list", - "data": [ - { - "id": "msg_abc123", - "type": "message", - "role": "user", - "content": [ - { - "type": "input_text", - "text": "Tell me a three sentence bedtime story about a unicorn." - } - ] - } - ], - "first_id": "msg_abc123", - "last_id": "msg_abc123", - "has_more": false - } - BetaItemResource: - description: | - Content item used to generate a response. - discriminator: - propertyName: type - anyOf: - - $ref: '#/components/schemas/BetaInputMessageResource' - - $ref: '#/components/schemas/BetaOutputMessage' - - $ref: '#/components/schemas/BetaFileSearchToolCall' - - $ref: '#/components/schemas/BetaComputerToolCall' - - $ref: '#/components/schemas/BetaComputerToolCallOutputResource' - - $ref: '#/components/schemas/BetaWebSearchToolCall' - - $ref: '#/components/schemas/BetaFunctionToolCallResource' - - $ref: '#/components/schemas/BetaFunctionToolCallOutputResource' - - $ref: '#/components/schemas/BetaAgentMessage' - - $ref: '#/components/schemas/BetaMultiAgentCall' - - $ref: '#/components/schemas/BetaMultiAgentCallOutput' - - $ref: '#/components/schemas/BetaToolSearchCall' - - $ref: '#/components/schemas/BetaToolSearchOutput' - - $ref: '#/components/schemas/BetaAdditionalTools' - - $ref: '#/components/schemas/BetaResponseConfigurationUpdate' - - $ref: '#/components/schemas/BetaReasoningItem' - - $ref: '#/components/schemas/BetaProgram' - - $ref: '#/components/schemas/BetaProgramOutput' - - $ref: '#/components/schemas/BetaCompactionBody' - - $ref: '#/components/schemas/BetaImageGenToolCall' - - $ref: '#/components/schemas/BetaCodeInterpreterToolCall' - - $ref: '#/components/schemas/BetaLocalShellToolCall' - - $ref: '#/components/schemas/BetaLocalShellToolCallOutput' - - $ref: '#/components/schemas/BetaFunctionShellCall' - - $ref: '#/components/schemas/BetaFunctionShellCallOutput' - - $ref: '#/components/schemas/BetaApplyPatchToolCall' - - $ref: '#/components/schemas/BetaApplyPatchToolCallOutput' - - $ref: '#/components/schemas/BetaMCPListTools' - - $ref: '#/components/schemas/BetaMCPApprovalRequest' - - $ref: '#/components/schemas/BetaMCPApprovalResponseResource' - - $ref: '#/components/schemas/BetaMCPToolCall' - - $ref: '#/components/schemas/BetaCustomToolCallResource' - - $ref: '#/components/schemas/BetaCustomToolCallOutputResource' - BetaCustomToolCallOutputResource: - title: ResponseCustomToolCallOutputItem - allOf: - - $ref: '#/components/schemas/BetaCustomToolCallOutput' - - type: object - properties: - id: - type: string - description: | - The unique ID of the custom tool call output item. - status: - description: | - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - $ref: '#/components/schemas/BetaFunctionCallOutputStatusEnum' - created_by: - type: string - description: | - The identifier of the actor that created the item. - required: - - id - - status - BetaFunctionCallOutputStatusEnum: - type: string - enum: - - in_progress - - completed - - incomplete - BetaCustomToolCallResource: - title: ResponseCustomToolCallItem - allOf: - - $ref: '#/components/schemas/BetaCustomToolCall' - - type: object - properties: - id: - type: string - description: | - The unique ID of the custom tool call item. - status: - description: | - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - $ref: '#/components/schemas/BetaFunctionCallStatus' - created_by: - type: string - description: | - The identifier of the actor that created the item. - required: - - id - - status - BetaFunctionCallStatus: - type: string - enum: - - in_progress - - completed - - incomplete - BetaMCPApprovalResponseResource: + client: + description: Frontend data-channel permissions for a WebRTC fork. Omitted permissions inherit the stored values. Not supported for WebSocket forks. + $ref: '#/components/schemas/LiveClientConfigParam' + required: [] + LiveForkSessionStartEvent: + description: Start a Live session after connecting to a stored session’s fork WebSocket. Send an empty `session` object to use the stored configuration. + example: + type: session.start + session: {} type: object - title: MCP approval response - description: | - A response to an MCP approval request. properties: - agent: + event_id: anyOf: - - $ref: '#/components/schemas/BetaAgentTag' + - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. + type: string + maxLength: 512 - type: 'null' - description: The agent that produced this item. type: - type: string - enum: - - mcp_approval_response - description: | - The type of the item. Always `mcp_approval_response`. + description: The Live client event type. Always `session.start`. + default: session.start x-stainless-const: true - id: - type: string - description: | - The unique ID of the approval response - approval_request_id: type: string - description: | - The ID of the approval request being answered. - approve: - type: boolean - description: | - Whether the request was approved. - reason: - anyOf: - - type: string - description: | - Optional reason for the decision. - - type: 'null' + enum: + - session.start + session: + description: Overrides for a stored session after connecting to the fork WebSocket. An empty object inherits the stored configuration; do not supply a new model. audio.format applies only to the new WebSocket connection. client overrides are only supported for WebRTC forks. + $ref: '#/components/schemas/LiveForkSessionConfigParam' required: - type - - id - - request_id - - approve - - approval_request_id - BetaApplyPatchToolCallOutput: + - session + x-oaiMeta: + example: + type: session.start + session: {} + LiveSessionResourceParam: + description: The resolved Live session configuration and server-assigned session metadata. + type: object properties: - agent: - $ref: '#/components/schemas/BetaAgentTag' - description: The agent that produced this item. - type: - type: string - enum: - - apply_patch_call_output - description: The type of the item. Always `apply_patch_call_output`. - default: apply_patch_call_output - x-stainless-const: true - id: - type: string - description: The unique ID of the apply patch tool call output. Populated when this item is returned via API. - call_id: - type: string - description: The unique ID of the apply patch tool call generated by the model. - caller: + model: + $ref: '#/components/schemas/ModelIdsLive' + instructions: anyOf: - - $ref: '#/components/schemas/BetaToolCallCaller' - description: The execution context that produced this tool call. + - description: Frontend instructions for voice, conversation, interruptions, and when to delegate. Start with the [Live prompting guide](https://developers.openai.com/api/docs/guides/live-prompting); put business rules and tool workflows in a separate [backend prompt](https://developers.openai.com/api/docs/guides/live-delegation#start-with-your-existing-backend-prompt). Limited to 16,384 client-supplied tokens. Omitted or blank instructions use server defaults. Immutable after startup. + type: string - type: 'null' - status: - $ref: '#/components/schemas/BetaApplyPatchCallOutputStatus' - description: The status of the apply patch tool call output. One of `completed` or `failed`. - output: + input: + description: Ordered text-only history supplied before startup. Supports developer, user, and assistant messages with one text part each; at most 128 messages and 8,192 rendered tokens in total. + type: array + items: + $ref: '#/components/schemas/LiveInitialItem' + maxItems: 128 + audio: + description: Startup audio configuration. Only primary WebSockets accept audio.format; WebRTC and SIP negotiate their media format. Voice and format are immutable after startup. + $ref: '#/components/schemas/LiveInitialSessionAudioParam' + delegation: anyOf: - - type: string - description: Optional textual output returned by the apply patch tool. + - description: Who handles tasks delegated by the Live model. Omitted or null selects your application; use `responses` to let the API manage a Responses backend. + discriminator: + propertyName: type + anyOf: + - $ref: '#/components/schemas/LiveClientDelegationParam' + - $ref: '#/components/schemas/LiveResponsesDelegationParam' - type: 'null' - created_by: + store: + description: Whether to store the session for later forking and recording download. Defaults to false for new sessions. + type: boolean + client: + description: Startup-only capabilities for an untrusted frontend attached to a unified WebRTC session. Trusted sideband connections are unaffected. + $ref: '#/components/schemas/LiveClientConfigParam' + id: + description: The unique ID of the Live session. Use this ID for sideband connections, forking, and recording download. type: string - description: The ID of the entity that created this tool call output. - type: object + expires_at: + description: The Unix timestamp, in seconds, at which the Live session expires. + type: integer + status: + description: The status of the session snapshot. Always `active`, including the final snapshot in session.closed; use the event type to determine that the session has closed. + default: active + x-stainless-const: true + type: string + enum: + - active required: - - type + - model - id - - call_id + - expires_at - status - title: Apply patch tool call output - description: The output emitted by an apply patch tool call. - BetaApplyPatchCallOutputStatus: - type: string - enum: - - completed - - failed - BetaApplyPatchToolCall: + LiveSessionStarted: + description: Returned when a Live session has started. Contains the resolved session configuration, including server defaults. + example: + type: session.started + event_id: evt_started_001 + client_event_id: evt_start_001 + session: + id: live_abc123 + model: gpt-live-1 + status: active + expires_at: 1788555600 + instructions: Help the caller plan a restaurant reservation. Confirm details before booking. + input: [] + audio: + format: + type: audio/pcm + rate: 24000 + output: + voice: marin + delegation: + type: client + type: object properties: - agent: - $ref: '#/components/schemas/BetaAgentTag' - description: The agent that produced this item. type: - type: string - enum: - - apply_patch_call - description: The type of the item. Always `apply_patch_call`. - default: apply_patch_call + description: The event type, always `session.started`. + default: session.started x-stainless-const: true - id: type: string - description: The unique ID of the apply patch tool call. Populated when this item is returned via API. - call_id: + enum: + - session.started + event_id: + description: The unique ID of the Live server event. type: string - description: The unique ID of the apply patch tool call generated by the model. - caller: - anyOf: - - $ref: '#/components/schemas/BetaToolCallCaller' - description: The execution context that produced this tool call. - - type: 'null' - status: - $ref: '#/components/schemas/BetaApplyPatchCallStatus' - description: The status of the apply patch tool call. One of `in_progress` or `completed`. - operation: - discriminator: - propertyName: type - title: Apply patch operation - description: One of the create_file, delete_file, or update_file operations applied via apply_patch. - anyOf: - - $ref: '#/components/schemas/BetaApplyPatchCreateFileOperation' - - $ref: '#/components/schemas/BetaApplyPatchDeleteFileOperation' - - $ref: '#/components/schemas/BetaApplyPatchUpdateFileOperation' - created_by: + client_event_id: + description: The event_id of the client command associated with this server event, when supplied. type: string - description: The ID of the entity that created this tool call. - type: object + session: + $ref: '#/components/schemas/LiveSessionResourceParam' required: - type - - id - - call_id - - status - - operation - title: Apply patch tool call - description: A tool call that applies file diffs by creating, deleting, or updating files. - BetaApplyPatchUpdateFileOperation: + - event_id + - session + x-oaiMeta: + example: + type: session.started + event_id: evt_started_001 + client_event_id: evt_start_001 + session: + id: live_abc123 + model: gpt-live-1 + status: active + expires_at: 1788555600 + instructions: Help the caller plan a restaurant reservation. Confirm details before booking. + input: [] + audio: + format: + type: audio/pcm + rate: 24000 + output: + voice: marin + delegation: + type: client + LiveSessionUpdated: + description: Returned when a Live session update is accepted. Contains the resolved session configuration after the update. + example: + type: session.updated + event_id: evt_updated_001 + client_event_id: evt_update_001 + session: + id: live_def456 + model: gpt-live-1 + status: active + expires_at: 1788555600 + instructions: Help the caller plan a restaurant reservation. Confirm details before booking. + input: [] + audio: + format: + type: audio/pcm + rate: 24000 + output: + voice: marin + delegation: + type: responses + responses: + model: gpt-6-astra + instructions: Check restaurant availability. Ask before confirming a booking. + max_output_tokens: 1024 + tools: [] + type: object properties: type: + description: The event type, always `session.updated`. + default: session.updated + x-stainless-const: true type: string enum: - - update_file - description: Update an existing file with the provided diff. - default: update_file - x-stainless-const: true - path: + - session.updated + event_id: + description: The unique ID of the Live server event. type: string - description: Path of the file to update. - diff: + client_event_id: + description: The event_id of the client command associated with this server event, when supplied. type: string - description: Diff to apply. - type: object + session: + $ref: '#/components/schemas/LiveSessionResourceParam' required: - type - - path - - diff - title: Apply patch update file operation - description: Instruction describing how to update a file via the apply_patch tool. - BetaApplyPatchDeleteFileOperation: + - event_id + - session + x-oaiMeta: + example: + type: session.updated + event_id: evt_updated_001 + client_event_id: evt_update_001 + session: + id: live_def456 + model: gpt-live-1 + status: active + expires_at: 1788555600 + instructions: Help the caller plan a restaurant reservation. Confirm details before booking. + input: [] + audio: + format: + type: audio/pcm + rate: 24000 + output: + voice: marin + delegation: + type: responses + responses: + model: gpt-6-astra + instructions: Check restaurant availability. Ask before confirming a booking. + max_output_tokens: 1024 + tools: [] + LiveInputAudioMuted: + description: Returned when a session.input_audio.mute command is accepted. Input audio is no longer sent to the model; sideband audio reflection continues. + example: + type: session.input_audio.muted + event_id: evt_muted_001 + client_event_id: evt_mute_001 + type: object properties: - type: + event_id: + description: The unique ID of the Live server event. type: string - enum: - - delete_file - description: Delete the specified file. - default: delete_file + client_event_id: + description: The event_id of the client command associated with this server event, when supplied. + type: string + type: + description: The event type, always `session.input_audio.muted`. + default: session.input_audio.muted x-stainless-const: true - path: type: string - description: Path of the file to delete. - type: object + enum: + - session.input_audio.muted required: + - event_id - type - - path - title: Apply patch delete file operation - description: Instruction describing how to delete a file via the apply_patch tool. - BetaApplyPatchCreateFileOperation: + x-oaiMeta: + example: + type: session.input_audio.muted + event_id: evt_muted_001 + client_event_id: evt_mute_001 + LiveInputAudioUnmuted: + description: Returned when a session.input_audio.unmute command is accepted. Input audio is sent to the model again. + example: + type: session.input_audio.unmuted + event_id: evt_unmuted_001 + client_event_id: evt_unmute_001 + type: object properties: - type: + event_id: + description: The unique ID of the Live server event. type: string - enum: - - create_file - description: Create a new file with the provided diff. - default: create_file - x-stainless-const: true - path: + client_event_id: + description: The event_id of the client command associated with this server event, when supplied. type: string - description: Path of the file to create. - diff: + type: + description: The event type, always `session.input_audio.unmuted`. + default: session.input_audio.unmuted + x-stainless-const: true type: string - description: Diff to apply. - type: object + enum: + - session.input_audio.unmuted required: + - event_id - type - - path - - diff - title: Apply patch create file operation - description: Instruction describing how to create a file via the apply_patch tool. - BetaApplyPatchCallStatus: - type: string - enum: - - in_progress - - completed - BetaFunctionShellCallOutput: + x-oaiMeta: + example: + type: session.input_audio.unmuted + event_id: evt_unmuted_001 + client_event_id: evt_unmute_001 + LiveInstructionsAppended: + description: Returned when a session.instructions.append command is accepted into the Live session timeline. Acknowledges the appended instructions without guaranteeing that the model has acted on them. + example: + type: session.instructions.appended + event_id: evt_instructions_002 + client_event_id: evt_instructions_001 + start_ms: 1200 + end_ms: 1400 + type: object properties: - agent: - $ref: '#/components/schemas/BetaAgentTag' - description: The agent that produced this item. - type: - type: string - enum: - - shell_call_output - description: The type of the shell call output. Always `shell_call_output`. - default: shell_call_output - x-stainless-const: true - id: + event_id: + description: The unique ID of the Live server event. type: string - description: The unique ID of the shell call output. Populated when this item is returned via API. - call_id: + client_event_id: + description: The event_id of the client command associated with this server event, when supplied. type: string - description: The unique ID of the shell tool call generated by the model. - caller: - anyOf: - - $ref: '#/components/schemas/BetaToolCallCaller' - description: The execution context that produced this tool call. - - type: 'null' - status: - $ref: '#/components/schemas/BetaFunctionShellCallOutputStatusEnum' - description: The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - output: - items: - $ref: '#/components/schemas/BetaFunctionShellCallOutputContent' - type: array - description: An array of shell call output contents - max_output_length: - anyOf: - - type: integer - description: The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - type: 'null' - created_by: + start_ms: + description: The start of this event on the Live session timeline, in milliseconds from the beginning of the session. + type: integer + end_ms: + description: The end of this event on the Live session timeline, in milliseconds from the beginning of the session. For appended context, this can equal start_ms. + type: integer + type: + description: The event type, always `session.instructions.appended`. + default: session.instructions.appended + x-stainless-const: true type: string - description: The identifier of the actor that created the item. - type: object + enum: + - session.instructions.appended required: + - event_id + - start_ms + - end_ms - type - - id - - call_id - - status - - output - - max_output_length - title: Shell call output - description: The output of a shell tool call that was emitted. - BetaFunctionShellCallOutputContent: + x-oaiMeta: + example: + type: session.instructions.appended + event_id: evt_instructions_002 + client_event_id: evt_instructions_001 + start_ms: 1200 + end_ms: 1400 + LiveThinkingAppended: + description: Returned when a session.thinking.append command is accepted into the Live session timeline. Acknowledges the added reasoning context without guaranteeing any spoken output. + example: + type: session.thinking.appended + event_id: evt_thinking_002 + client_event_id: evt_thinking_001 + start_ms: 4600 + end_ms: 4800 + type: object properties: - stdout: - type: string - description: The standard output that was captured. - stderr: + event_id: + description: The unique ID of the Live server event. type: string - description: The standard error output that was captured. - outcome: - discriminator: - propertyName: type - title: Shell call outcome - description: Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - anyOf: - - $ref: '#/components/schemas/BetaFunctionShellCallOutputTimeoutOutcome' - - $ref: '#/components/schemas/BetaFunctionShellCallOutputExitOutcome' - created_by: + client_event_id: + description: The event_id of the client command associated with this server event, when supplied. type: string - description: The identifier of the actor that created the item. - type: object - required: - - stdout - - stderr - - outcome - title: Shell call output content - description: The content of a shell tool call output that was emitted. - BetaFunctionShellCallOutputExitOutcome: - properties: + start_ms: + description: The start of this event on the Live session timeline, in milliseconds from the beginning of the session. + type: integer + end_ms: + description: The end of this event on the Live session timeline, in milliseconds from the beginning of the session. For appended context, this can equal start_ms. + type: integer type: - type: string - enum: - - exit - description: The outcome type. Always `exit`. - default: exit + description: The event type, always `session.thinking.appended`. + default: session.thinking.appended x-stainless-const: true - exit_code: - type: integer - description: Exit code from the shell process. - type: object + type: string + enum: + - session.thinking.appended required: + - event_id + - start_ms + - end_ms - type - - exit_code - title: Shell call exit outcome - description: Indicates that the shell commands finished and returned an exit code. - BetaFunctionShellCallOutputTimeoutOutcome: + x-oaiMeta: + example: + type: session.thinking.appended + event_id: evt_thinking_002 + client_event_id: evt_thinking_001 + start_ms: 4600 + end_ms: 4800 + LiveCommentaryAppended: + description: Returned when a session.commentary.append command is accepted into the Live session timeline. Acknowledges the added commentary without guaranteeing exact wording or completed audio playback. + example: + type: session.commentary.appended + event_id: evt_commentary_002 + client_event_id: evt_commentary_001 + start_ms: 5200 + end_ms: 5400 + type: object properties: + event_id: + description: The unique ID of the Live server event. + type: string + client_event_id: + description: The event_id of the client command associated with this server event, when supplied. + type: string + start_ms: + description: The start of this event on the Live session timeline, in milliseconds from the beginning of the session. + type: integer + end_ms: + description: The end of this event on the Live session timeline, in milliseconds from the beginning of the session. For appended context, this can equal start_ms. + type: integer type: + description: The event type, always `session.commentary.appended`. + default: session.commentary.appended + x-stainless-const: true type: string enum: - - timeout - description: The outcome type. Always `timeout`. - default: timeout - x-stainless-const: true - type: object + - session.commentary.appended required: + - event_id + - start_ms + - end_ms - type - title: Shell call timeout outcome - description: Indicates that the shell call exceeded its configured time limit. - BetaFunctionShellCallOutputStatusEnum: - type: string - enum: - - in_progress - - completed - - incomplete - BetaFunctionShellCall: + x-oaiMeta: + example: + type: session.commentary.appended + event_id: evt_commentary_002 + client_event_id: evt_commentary_001 + start_ms: 5200 + end_ms: 5400 + LiveInputAudioAppend: + description: Input audio received from the primary transport and reflected to a Live sideband connection before model-input muting. + example: + type: session.input_audio.append + audio: AACAAIAAAIAAAP9/AIAAgA== + type: object properties: - agent: - $ref: '#/components/schemas/BetaAgentTag' - description: The agent that produced this item. type: - type: string - enum: - - shell_call - description: The type of the item. Always `shell_call`. - default: shell_call + description: The event type, always `session.input_audio.append`. + default: session.input_audio.append x-stainless-const: true - id: - type: string - description: The unique ID of the shell tool call. Populated when this item is returned via API. - call_id: type: string - description: The unique ID of the shell tool call generated by the model. - caller: - anyOf: - - $ref: '#/components/schemas/BetaToolCallCaller' - description: The execution context that produced this tool call. - - type: 'null' - action: - $ref: '#/components/schemas/BetaFunctionShellAction' - description: The shell commands and limits that describe how to run the tool call. - status: - $ref: '#/components/schemas/BetaFunctionShellCallStatus' - description: The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - environment: - anyOf: - - discriminator: - propertyName: type - anyOf: - - $ref: '#/components/schemas/BetaLocalEnvironmentResource' - - $ref: '#/components/schemas/BetaContainerReferenceResource' - - type: 'null' - created_by: + enum: + - session.input_audio.append + audio: + description: Base64-encoded raw mono PCM16LE at 24 kHz received from the primary transport, reflected to the sideband before model-input muting. This server event uses the same audio key as the client command, but is not an acknowledgment of it. type: string - description: The ID of the entity that created this tool call. - type: object required: - type - - id - - call_id - - action - - status - - environment - title: Shell tool call - description: A tool call that executes one or more shell commands in a managed environment. - BetaContainerReferenceResource: + - audio + x-oaiMeta: + example: + type: session.input_audio.append + audio: AACAAIAAAIAAAP9/AIAAgA== + LiveOutputAudioDelta: + description: An audio chunk generated by the Live model. Decode and play primary WebSocket chunks in delivery order using the configured session audio format. Sideband connections receive reflected output audio with timestamps. + example: + type: session.output_audio.delta + delta: AACAAIAAAIAAAP9/AIAAgA== + start_ms: 1000 + end_ms: 1200 + type: object properties: type: + description: The event type, always `session.output_audio.delta`. + default: session.output_audio.delta + x-stainless-const: true type: string enum: - - container_reference - description: The environment type. Always `container_reference`. - default: container_reference - x-stainless-const: true - container_id: + - session.output_audio.delta + delta: + description: Base64-encoded raw audio. Primary WebSocket events use the session's configured format; reflected sideband events use mono PCM16LE at 24 kHz. type: string - type: object + start_ms: + description: Inclusive session-relative start in milliseconds. Required on reflected sideband events; omitted on the primary WebSocket. + type: integer + end_ms: + description: Exclusive session-relative end in milliseconds. Required on reflected sideband events; omitted on the primary WebSocket. Dropped output frames leave gaps between reflected ranges. + type: integer required: - type - - container_id - title: Container Reference - description: Represents a container created with /v1/containers. - BetaLocalEnvironmentResource: + - delta + x-oaiMeta: + example: + type: session.output_audio.delta + delta: AACAAIAAAIAAAP9/AIAAgA== + start_ms: 1000 + end_ms: 1200 + LiveInputTranscriptDelta: + description: A transcript fragment for user input audio in the Live session. Accumulate fragments in delivery order; these events do not define complete turns or include a transcript-done event. + example: + type: session.input_transcript.delta + event_id: evt_input_transcript_001 + delta: A table for two at seven, please. + start_ms: 1600 + end_ms: 3400 + type: object properties: + event_id: + description: The unique ID of the Live server event. + type: string + client_event_id: + description: The event_id of the client command associated with this server event, when supplied. + type: string + start_ms: + description: The start of this event on the Live session timeline, in milliseconds from the beginning of the session. + type: integer + end_ms: + description: The end of this event on the Live session timeline, in milliseconds from the beginning of the session. For appended context, this can equal start_ms. + type: integer + delta: + description: The transcript text fragment for the audio in this time range. Append fragments in delivery order to build the transcript. + type: string type: + description: The event type, always `session.input_transcript.delta`. + default: session.input_transcript.delta + x-stainless-const: true type: string enum: - - local - description: The environment type. Always `local`. - default: local - x-stainless-const: true - type: object + - session.input_transcript.delta required: + - event_id + - start_ms + - end_ms + - delta - type - title: Local Environment - description: Represents the use of a local environment to perform shell actions. - BetaFunctionShellCallStatus: - type: string - enum: - - in_progress - - completed - - incomplete - BetaFunctionShellAction: - properties: - commands: - items: - type: string - description: A list of commands to run. - type: array - timeout_ms: - anyOf: - - type: integer - description: Optional timeout in milliseconds for the commands. - - type: 'null' - max_output_length: - anyOf: - - type: integer - description: Optional maximum number of characters to return from each command. - - type: 'null' + x-oaiMeta: + example: + type: session.input_transcript.delta + event_id: evt_input_transcript_001 + delta: A table for two at seven, please. + start_ms: 1600 + end_ms: 3400 + LiveOutputTranscriptDelta: + description: A transcript fragment for assistant output audio in the Live session. Accumulate fragments in delivery order; these events do not define complete turns or include a transcript-done event. + example: + type: session.output_transcript.delta + event_id: evt_output_transcript_001 + delta: Would you like me to reserve that table? + start_ms: 5400 + end_ms: 7200 type: object - required: - - commands - - timeout_ms - - max_output_length - title: Shell exec action - description: Execute a shell command. - BetaCompactionBody: properties: - agent: - $ref: '#/components/schemas/BetaAgentTag' - description: The agent that produced this item. - type: + event_id: + description: The unique ID of the Live server event. type: string - enum: - - compaction - description: The type of the item. Always `compaction`. - default: compaction - x-stainless-const: true - id: + client_event_id: + description: The event_id of the client command associated with this server event, when supplied. type: string - description: The unique ID of the compaction item. - encrypted_content: + start_ms: + description: The start of this event on the Live session timeline, in milliseconds from the beginning of the session. + type: integer + end_ms: + description: The end of this event on the Live session timeline, in milliseconds from the beginning of the session. For appended context, this can equal start_ms. + type: integer + delta: + description: The transcript text fragment for the audio in this time range. Append fragments in delivery order to build the transcript. type: string - description: The encrypted content that was produced by compaction. - created_by: + type: + description: The event type, always `session.output_transcript.delta`. + default: session.output_transcript.delta + x-stainless-const: true type: string - description: The identifier of the actor that created the item. - type: object + enum: + - session.output_transcript.delta required: + - event_id + - start_ms + - end_ms + - delta - type - - id - - encrypted_content - title: Compaction item - description: A compaction item generated by the [`v1/responses/compact` API](https://developers.openai.com/api/reference/resources/responses/methods/compact). - BetaProgramOutput: + x-oaiMeta: + example: + type: session.output_transcript.delta + event_id: evt_output_transcript_001 + delta: Would you like me to reserve that table? + start_ms: 5400 + end_ms: 7200 + LiveDelegationItem: + description: Metadata for work delegated by the Live model. Client delegations are handled by your application; Responses delegations run on the configured backend. + type: object properties: - agent: - $ref: '#/components/schemas/BetaAgentTag' - description: The agent that produced this item. - type: - type: string - enum: - - program_output - description: The type of the item. Always `program_output`. - default: program_output - x-stainless-const: true id: + description: The unique ID of the delegation. Use this as delegation_id when replying to client-owned work or correlating Responses events. type: string - description: The unique ID of the program output item. - call_id: + type: + description: The object type, always `delegation`. + default: delegation + x-stainless-const: true type: string - description: The call ID of the program item. - result: + enum: + - delegation + target: + description: 'Where the Live model delegated the work: `client` for your application, or `responses` for the configured Responses backend.' + anyOf: + - default: client + x-stainless-const: true + type: string + enum: + - client + - default: responses + x-stainless-const: true + type: string + enum: + - responses + response_id: + description: The ID of the Responses API response associated with a Responses delegation. Omitted for client delegations. type: string - description: The result produced by the program item. - status: - $ref: '#/components/schemas/BetaProgramOutputStatus' - description: The terminal status of the program output item. - type: object required: - - type - id - - call_id - - result - - status - BetaProgramOutputStatus: - type: string - enum: - - completed - - incomplete - BetaProgram: + - type + - target + LiveDelegationCreated: + description: Returned when the Live model delegates work to your application or a Responses backend. Contains delegation metadata and the position on the session timeline where the work was delegated. + example: + type: session.delegation.created + event_id: evt_delegation_001 + offset_ms: 3600 + delegation: + id: del_abc123 + type: delegation + target: client + type: object properties: - agent: - $ref: '#/components/schemas/BetaAgentTag' - description: The agent that produced this item. - type: - type: string - enum: - - program - description: The type of the item. Always `program`. - default: program - x-stainless-const: true - id: - type: string - description: The unique ID of the program item. - call_id: + event_id: + description: The unique ID of the Live server event. type: string - description: The stable call ID of the program item. - code: + client_event_id: + description: The event_id of the client command associated with this server event, when supplied. type: string - description: The JavaScript source executed by programmatic tool calling. - fingerprint: + type: + description: The event type, always `session.delegation.created`. + default: session.delegation.created + x-stainless-const: true type: string - description: Opaque program replay fingerprint that must be round-tripped. - type: object + enum: + - session.delegation.created + offset_ms: + description: The position on the Live session timeline where the delegation was created, in milliseconds from the beginning of the session. + type: integer + delegation: + description: The delegated work identifier and destination. This object contains metadata, not the task text. + $ref: '#/components/schemas/LiveDelegationItem' required: + - event_id - type - - id - - call_id - - code - - fingerprint - BetaResponseConfigurationUpdate: + - offset_ms + - delegation + x-oaiMeta: + example: + type: session.delegation.created + event_id: evt_delegation_001 + offset_ms: 3600 + delegation: + id: del_abc123 + type: delegation + target: client + LiveResponseEvent: + description: A streaming Responses API event from a backend delegated to by the Live session. Use the outer delegation_id to associate the nested stream with its Live delegation. + example: + type: response.event + event_id: evt_response_002 + delegation_id: del_responses123 + event: + type: response.output_text.delta + item_id: msg_abc123 + output_index: 0 + content_index: 0 + delta: An outdoor table is available at 7 PM. + sequence_number: 3 + logprobs: [] type: object - description: | - A configuration update that applies to subsequent responses until it is - replaced by another configuration update. properties: - agent: - $ref: '#/components/schemas/BetaAgentTag' - description: The agent that produced this item. - id: + event_id: + description: The unique ID of the Live server event. + type: string + client_event_id: + description: The event_id of the client command associated with this server event, when supplied. type: string - description: The unique ID of the configuration update item. - example: cnfu_123 type: + description: The event type, always `response.event`. + default: response.event + x-stainless-const: true type: string enum: - - configuration_update - description: The item type. Always `configuration_update`. - default: configuration_update - x-stainless-const: true - reasoning: + - response.event + delegation_id: + anyOf: + - description: The Live delegation associated with the nested Responses event. May be null or omitted when the event cannot be correlated with a delegation. + type: string + - type: 'null' + event: + description: The nested Responses streaming event. Dispatch on its type field. Response lifecycle snapshots omit input and clear instructions, tools, and output to keep messages small; consume granular output events for the generated content. type: object - description: The reasoning configuration applied by this update. - properties: - effort: - $ref: '#/components/schemas/BetaReasoningEffort' - description: | - The reasoning effort used for subsequent responses until another - configuration update replaces it. + additionalProperties: {} required: - - id + - event_id - type - BetaAdditionalTools: + - event + x-oaiMeta: + example: + type: response.event + event_id: evt_response_002 + delegation_id: del_responses123 + event: + type: response.output_text.delta + item_id: msg_abc123 + output_index: 0 + content_index: 0 + delta: An outdoor table is available at 7 PM. + sequence_number: 3 + logprobs: [] + LiveSessionUsage: + description: Cumulative audio duration for a Live session. Values are totals for the session, not increments to sum across usage events. + type: object + properties: + seconds: + description: The cumulative Live audio duration in seconds. Do not sum this value across usage events. + type: number + required: + - seconds + LiveContextWindowUsage: + description: The latest measured context-window usage of the Live model. This is separate from billing usage and delegated Responses token usage. + type: object + properties: + usage_ratio: + description: The latest active context token count divided by the Live model context limit. Can decrease after compaction and may lag between measured audio frames. + type: number + required: + - usage_ratio + LiveSessionUsageUpdated: + description: Reports cumulative Live audio usage and, when available, the most recent context-window usage. Delegated Responses token usage is reported separately in response.event events. + example: + type: session.usage.updated + event_id: evt_usage_001 + usage: + seconds: 32.5 + context_window: + usage_ratio: 0.12 + type: object properties: - agent: - $ref: '#/components/schemas/BetaAgentTag' - description: The agent that produced this item. - type: + event_id: + description: The unique ID of the Live server event. type: string - enum: - - additional_tools - description: The type of the item. Always `additional_tools`. - default: additional_tools + client_event_id: + description: The event_id of the client command associated with this server event, when supplied. + type: string + type: + description: The event type, always `session.usage.updated`. + default: session.usage.updated x-stainless-const: true - id: type: string - description: The unique ID of the additional tools item. - role: - $ref: '#/components/schemas/BetaMessageRole' - description: The role that provided the additional tools. - tools: - items: - $ref: '#/components/schemas/BetaTool' - type: array - description: The additional tool definitions made available at this item. - type: object + enum: + - session.usage.updated + usage: + description: The cumulative Live audio usage so far. + $ref: '#/components/schemas/LiveSessionUsage' + context_window: + description: The latest measured Live context-window usage. Omitted when the context limit is unknown. + $ref: '#/components/schemas/LiveContextWindowUsage' required: + - event_id - type - - id - - role - - tools - BetaMessageRole: - type: string - enum: - - unknown - - user - - assistant - - system - - critic - - discriminator - - developer - - tool - BetaToolSearchOutput: + - usage + x-oaiMeta: + example: + type: session.usage.updated + event_id: evt_usage_001 + usage: + seconds: 32.5 + context_window: + usage_ratio: 0.12 + LiveSessionClosed: + description: Returned after the Live session finishes finalizing, with the close reason, final session snapshot, and cumulative audio usage. A connection closing without this event does not confirm successful finalization. + example: + type: session.closed + event_id: evt_closed_001 + client_event_id: evt_close_001 + reason: close_requested + session: + id: live_abc123 + model: gpt-live-1 + status: active + expires_at: 1788555600 + instructions: Help the caller plan a restaurant reservation. Confirm details before booking. + input: [] + audio: + format: + type: audio/pcm + rate: 24000 + output: + voice: marin + delegation: + type: client + usage: + seconds: 45.8 + type: object properties: - agent: - $ref: '#/components/schemas/BetaAgentTag' - description: The agent that produced this item. - type: + event_id: + description: The unique ID of the Live server event. type: string - enum: - - tool_search_output - description: The type of the item. Always `tool_search_output`. - default: tool_search_output + client_event_id: + description: The event_id of the client command associated with this server event, when supplied. + type: string + type: + description: The event type, always `session.closed`. + default: session.closed x-stainless-const: true - id: type: string - description: The unique ID of the tool search output item. - call_id: + enum: + - session.closed + reason: + description: 'Why the Live session ended: `close_requested` for an application close or hangup request, `expired` for the session duration limit, `content` for a safety filter, `remote_hangup` for a graceful remote disconnect, or `connection_lost` for an unexpected primary or upstream disconnection.' anyOf: - - type: string - description: The unique ID of the tool search call generated by the model. - - type: 'null' - execution: - $ref: '#/components/schemas/BetaToolSearchExecutionType' - description: Whether tool search was executed by the server or by the client. - tools: - items: - $ref: '#/components/schemas/BetaTool' - type: array - description: The loaded tool definitions returned by tool search. - status: - $ref: '#/components/schemas/BetaFunctionCallOutputStatusEnum' - description: The status of the tool search output item that was recorded. - created_by: - type: string - description: The identifier of the actor that created the item. - type: object + - default: close_requested + x-stainless-const: true + type: string + enum: + - close_requested + - default: expired + x-stainless-const: true + type: string + enum: + - expired + - default: content + x-stainless-const: true + type: string + enum: + - content + - default: remote_hangup + x-stainless-const: true + type: string + enum: + - remote_hangup + - default: connection_lost + x-stainless-const: true + type: string + enum: + - connection_lost + session: + $ref: '#/components/schemas/LiveSessionResourceParam' + usage: + description: The final cumulative Live audio usage after session finalization. + $ref: '#/components/schemas/LiveSessionUsage' required: + - event_id - type - - id - - call_id - - execution - - tools - - status - BetaToolSearchCall: + - reason + - session + - usage + x-oaiMeta: + example: + type: session.closed + event_id: evt_closed_001 + client_event_id: evt_close_001 + reason: close_requested + session: + id: live_abc123 + model: gpt-live-1 + status: active + expires_at: 1788555600 + instructions: Help the caller plan a restaurant reservation. Confirm details before booking. + input: [] + audio: + format: + type: audio/pcm + rate: 24000 + output: + voice: marin + delegation: + type: client + usage: + seconds: 45.8 + LiveLiveError: + description: Details of an error encountered by the Live session, including the affected parameter or client command when available. + type: object properties: - agent: - $ref: '#/components/schemas/BetaAgentTag' - description: The agent that produced this item. type: + description: The category of error, such as `invalid_request_error` for an invalid Live client command. type: string - enum: - - tool_search_call - description: The type of the item. Always `tool_search_call`. - default: tool_search_call - x-stainless-const: true - id: + code: + description: A machine-readable code identifying the Live error, such as `unknown_parameter`. type: string - description: The unique ID of the tool search call item. - call_id: - anyOf: - - type: string - description: The unique ID of the tool search call generated by the model. - - type: 'null' - execution: - $ref: '#/components/schemas/BetaToolSearchExecutionType' - description: Whether tool search was executed by the server or by the client. - arguments: - description: Arguments used for the tool search call. - status: - $ref: '#/components/schemas/BetaFunctionCallStatus' - description: The status of the tool search call item that was recorded. - created_by: + message: + description: A human-readable explanation of the Live error. + type: string + param: + description: The parameter that caused the error, when applicable, such as `session.voice`. + type: string + client_event_id: + description: The event_id of the client command that caused the error, when supplied. type: string - description: The identifier of the actor that created the item. - type: object required: - type - - id - - call_id - - execution - - arguments - - status - BetaMultiAgentCallOutput: + - code + - message + LiveErrorEvent: + description: Reports an error in the Live session, such as an invalid client command. Use error.client_event_id, when present, to identify the command that caused the error. + example: + type: error + event_id: evt_error_001 + error: + type: invalid_request_error + code: unknown_parameter + message: 'Unknown parameter: ''session.voice''.' + param: session.voice + client_event_id: evt_invalid_001 + type: object properties: - agent: - $ref: '#/components/schemas/BetaAgentTag' - description: The agent that produced this item. - type: + event_id: + description: The unique ID of the Live server event. type: string - enum: - - multi_agent_call_output - description: The type of the multi-agent result. Always `multi_agent_call_output`. - default: multi_agent_call_output - x-stainless-const: true - id: + client_event_id: + description: The event_id of the client command associated with this server event, when supplied. type: string - description: The unique ID of the multi-agent call output item. - call_id: + type: + description: The event type, always `error`. + default: error + x-stainless-const: true type: string - description: The unique ID of the multi-agent call. - action: - $ref: '#/components/schemas/BetaMultiAgentAction' - description: The multi-agent action that produced this result. - output: - items: - $ref: '#/components/schemas/BetaOutputTextContent' - type: array - description: Text output returned by the multi-agent action. - type: object + enum: + - error + error: + description: Details of the Live error and the client command that caused it, when known. + $ref: '#/components/schemas/LiveLiveError' required: + - event_id - type - - id - - call_id - - action - - output - x-oai-beta: responses_multi_agent=v1 - BetaMultiAgentAction: - type: string - enum: - - spawn_agent - - interrupt_agent - - list_agents - - send_message - - followup_task - - wait_agent - BetaMultiAgentCall: + - error + x-oaiMeta: + example: + type: error + event_id: evt_error_001 + error: + type: invalid_request_error + code: unknown_parameter + message: 'Unknown parameter: ''session.voice''.' + param: session.voice + client_event_id: evt_invalid_001 + LiveInfoEvent: + description: An informational notice about the Live session, such as the event permissions applied to a frontend data channel. + example: + type: info + event_id: evt_info_001 + code: data_channel_permissions + message: The frontend data channel is configured with restricted event permissions. + type: object properties: - agent: - $ref: '#/components/schemas/BetaAgentTag' - description: The agent that produced this item. - type: + event_id: + description: The unique ID of the Live server event. type: string - enum: - - multi_agent_call - description: The type of the multi-agent call. Always `multi_agent_call`. - default: multi_agent_call + client_event_id: + description: The event_id of the client command associated with this server event, when supplied. + type: string + type: + description: The event type, always `info`. + default: info x-stainless-const: true - id: type: string - description: The unique ID of the multi-agent call item. - call_id: + enum: + - info + code: + description: A machine-readable code for the notice, such as `data_channel_permissions`. type: string - description: The unique ID linking this call to its output. - action: - $ref: '#/components/schemas/BetaMultiAgentAction' - description: The multi-agent action to execute. - arguments: + message: + description: A human-readable explanation of the Live session notice. type: string - description: The JSON string of arguments generated for the action. - type: object required: + - event_id - type - - id - - call_id - - action - - arguments - x-oai-beta: responses_multi_agent=v1 - BetaAgentMessage: + - code + - message + x-oaiMeta: + example: + type: info + event_id: evt_info_001 + code: data_channel_permissions + message: The frontend data channel is configured with restricted event permissions. + LiveTransportDTMFReceived: + description: A SIP DTMF keypress received from the caller. Delivered only to sideband observers. + example: + type: transport.dtmf.received + event_id: event_dtmf_1 + event: '5' + type: object properties: - agent: - $ref: '#/components/schemas/BetaAgentTag' - description: The agent that produced this item. type: - type: string - enum: - - agent_message - description: The type of the item. Always `agent_message`. - default: agent_message + default: transport.dtmf.received x-stainless-const: true - id: type: string - description: The unique ID of the agent message. - author: + enum: + - transport.dtmf.received + event_id: type: string - description: The sending agent identity. - recipient: + event: type: string - description: The destination agent identity. - content: - items: - discriminator: - propertyName: type - description: A content part that makes up an input or output item. - anyOf: - - $ref: '#/components/schemas/BetaInputTextContent' - - $ref: '#/components/schemas/BetaOutputTextContent' - - $ref: '#/components/schemas/BetaTextContent' - - $ref: '#/components/schemas/BetaSummaryTextContent' - - $ref: '#/components/schemas/BetaReasoningTextContent' - - $ref: '#/components/schemas/BetaRefusalContent' - - $ref: '#/components/schemas/BetaInputImageContent' - - $ref: '#/components/schemas/BetaComputerScreenshotContent' - - $ref: '#/components/schemas/BetaInputFileContent' - - $ref: '#/components/schemas/BetaEncryptedContent' - type: array - description: Encrypted content sent between agents. - type: object + minLength: 1 + maxLength: 1 + pattern: ^[0-9A-D*#]$ required: - type - - id - - author - - recipient - - content - x-oai-beta: responses_multi_agent=v1 - BetaEncryptedContent: + - event_id + - event + x-oaiMeta: + example: + type: transport.dtmf.received + event_id: event_dtmf_1 + event: '5' + LiveTransportDTMFSend: + description: A SIP DTMF keypress successfully sent by the hosted tool. Delivered only to sideband observers; this is not a client command. + example: + type: transport.dtmf.send + event_id: event_dtmf_2 + event: '#' + type: object properties: type: + default: transport.dtmf.send + x-stainless-const: true type: string enum: - - encrypted_content - description: The type of the input item. Always `encrypted_content`. - default: encrypted_content - x-stainless-const: true - encrypted_content: + - transport.dtmf.send + event_id: type: string - description: Opaque encrypted content. - type: object - required: - - type - - encrypted_content - title: Encrypted content - description: Opaque encrypted content that Responses API decrypts inside trusted model execution. - x-oai-beta: responses_multi_agent=v1 - BetaComputerScreenshotContent: - properties: - type: + event: type: string - enum: - - computer_screenshot - description: Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - default: computer_screenshot - x-stainless-const: true - image_url: - anyOf: - - type: string - format: uri - description: The URL of the screenshot image. - - type: 'null' - file_id: - anyOf: - - type: string - description: The identifier of an uploaded file that contains the screenshot. - - type: 'null' - detail: - $ref: '#/components/schemas/BetaImageDetail' - description: The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - prompt_cache_breakpoint: - $ref: '#/components/schemas/BetaPromptCacheBreakpointConfig' - type: object + minLength: 1 + maxLength: 1 + pattern: ^[0-9A-D*#]$ required: - type - - image_url - - file_id - - detail - title: Computer screenshot - description: A screenshot of a computer. - BetaTextContent: + - event_id + - event + x-oaiMeta: + example: + type: transport.dtmf.send + event_id: event_dtmf_2 + event: '#' + LiveTransportRinging: + description: The outbound SIP provider leg is ringing or providing early media. Delivered only to sideband observers. + example: + type: transport.ringing + event_id: event_call_1 + session_id: live_u0_123 + type: object properties: - type: + event_id: type: string - enum: - - text - default: text + session_id: + description: The canonical Live session ID. + type: string + type: + default: transport.ringing x-stainless-const: true - text: type: string - type: object + enum: + - transport.ringing required: + - event_id + - session_id - type - - text - title: Text Content - description: A text content. - BetaFunctionToolCallOutputResource: - allOf: - - $ref: '#/components/schemas/BetaFunctionToolCallOutput' - - type: object - properties: - id: - type: string - description: | - The unique ID of the function call tool output. - status: - description: | - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - $ref: '#/components/schemas/BetaFunctionCallOutputStatusEnum' - created_by: - type: string - description: | - The identifier of the actor that created the item. - required: - - id - - status - BetaFunctionToolCallOutput: + x-oaiMeta: + example: + type: transport.ringing + event_id: event_call_1 + session_id: live_u0_123 + LiveTransportAnswered: + description: The outbound SIP provider leg answered and media is established. Delivered only to sideband observers. + example: + type: transport.answered + event_id: event_call_2 + session_id: live_u0_123 type: object - title: Function tool call output - description: | - The output of a function tool call. properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that produced this item. - id: + event_id: type: string - description: | - The unique ID of the function tool call output. Populated when this item - is returned via API. - type: + session_id: + description: The canonical Live session ID. type: string - enum: - - function_call_output - description: | - The type of the function tool call output. Always `function_call_output`. + type: + default: transport.answered x-stainless-const: true - call_id: - type: string - description: | - The unique ID of the function tool call generated by the model. - name: - type: string - description: | - The name of the tool that produced the output. - namespace: - type: string - description: | - The namespace of the tool that produced the output. - caller: - anyOf: - - $ref: '#/components/schemas/BetaToolCallCallerParam' - - type: 'null' - output: - description: | - The output from the function call generated by your code. - Can be a string or an list of output content. - anyOf: - - type: string - description: | - A string of the output of the function call. - title: string output - - type: array - items: - $ref: '#/components/schemas/BetaFunctionAndCustomToolCallOutput' - title: output content list - description: | - Text, image, or file output of the function call. - status: type: string - description: | - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. enum: - - in_progress - - completed - - incomplete + - transport.answered required: + - event_id + - session_id - type - - output - BetaFunctionToolCallResource: - allOf: - - $ref: '#/components/schemas/BetaFunctionToolCall' - - type: object - properties: - id: - type: string - description: | - The unique ID of the function tool call. - status: - description: | - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - $ref: '#/components/schemas/BetaFunctionCallStatus' - created_by: - type: string - description: | - The identifier of the actor that created the item. - required: - - id - - status - BetaComputerToolCallOutputResource: - allOf: - - $ref: '#/components/schemas/BetaComputerToolCallOutput' - - type: object - properties: - id: - type: string - description: | - The unique ID of the computer call tool output. - status: - description: | - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. - $ref: '#/components/schemas/BetaComputerCallOutputStatus' - created_by: - type: string - description: | - The identifier of the actor that created the item. - required: - - id - - status - BetaComputerCallOutputStatus: - type: string - enum: - - completed - - incomplete - - failed - BetaComputerToolCallOutput: + x-oaiMeta: + example: + type: transport.answered + event_id: event_call_2 + session_id: live_u0_123 + LiveTransportCallError: type: object - title: Computer tool call output - description: | - The output of a computer tool call. properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that produced this item. type: + default: call_error + x-stainless-const: true type: string - description: | - The type of the computer tool call output. Always `computer_call_output`. enum: - - computer_call_output - default: computer_call_output - x-stainless-const: true - id: + - call_error + code: + description: The call setup failure code. type: string - description: | - The ID of the computer tool call output. - call_id: + message: type: string - description: | - The ID of the computer tool call that produced the output. - acknowledged_safety_checks: - type: array - description: | - The safety checks reported by the API that have been acknowledged by the - developer. - items: - $ref: '#/components/schemas/BetaComputerCallSafetyCheckParam' - output: - $ref: '#/components/schemas/BetaComputerScreenshotImage' - status: + param: + description: The parameter related to the error, if any. Empty when no parameter applies. type: string - description: | - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. - enum: - - in_progress - - completed - - incomplete required: - type - - call_id - - output - BetaInputMessageResource: - allOf: - - $ref: '#/components/schemas/BetaInputMessage' - - type: object - properties: - id: - type: string - description: | - The unique ID of the message input. - required: - - id - - type - BetaCompactResource: + - code + - message + LiveTransportFailed: + description: An asynchronous outbound SIP setup failure. Delivered only to sideband observers. + example: + type: transport.failed + event_id: event_call_4 + session_id: live_u0_123 + error: + type: call_error + code: provider_invite_failed + message: provider rejected the call + param: '' + type: object properties: - id: + event_id: type: string - description: The unique identifier for the compacted response. - object: + session_id: + description: The canonical Live session ID. type: string - enum: - - response.compaction - description: The object type. Always `response.compaction`. - default: response.compaction + type: + default: transport.failed x-stainless-const: true - output: - type: array - description: The compacted list of output items. This is a list of all user messages, followed by a single compaction item. - items: - $ref: '#/components/schemas/BetaOutputItem' - created_at: - type: integer - format: unixtime - description: Unix timestamp (in seconds) when the compacted conversation was created. - usage: - $ref: '#/components/schemas/BetaResponseUsage' - description: Token accounting for the compaction pass, including cached, reasoning, and total tokens. - type: object - required: - - id - - object - - output - - created_at - - usage - title: The compacted response object - BetaResponseUsage: - type: object - description: | - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. - properties: - input_tokens: - type: integer - description: The number of input tokens. - input_tokens_details: - type: object - description: A detailed breakdown of the input tokens. - properties: - cached_tokens: - type: integer - description: | - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://developers.openai.com/api/docs/guides/prompt-caching). - cache_write_tokens: - type: integer - description: The number of input tokens that were written to the cache. - required: - - cached_tokens - - cache_write_tokens - output_tokens: - type: integer - description: The number of output tokens. - output_tokens_details: - type: object - description: A detailed breakdown of the output tokens. - properties: - reasoning_tokens: - type: integer - description: The number of reasoning tokens. - required: - - reasoning_tokens - total_tokens: - type: integer - description: The total number of tokens used. + type: string + enum: + - transport.failed + error: + $ref: '#/components/schemas/LiveTransportCallError' required: - - input_tokens - - input_tokens_details - - output_tokens - - output_tokens_details - - total_tokens - BetaItemField: + - event_id + - session_id + - type + - error + x-oaiMeta: + example: + type: transport.failed + event_id: event_call_4 + session_id: live_u0_123 + error: + type: call_error + code: provider_invite_failed + message: provider rejected the call + param: '' + LiveServerEvent-2: + description: An event sent by the Live API on a primary WebSocket or sideband connection. discriminator: propertyName: type - description: An item representing a message, tool call, tool output, reasoning, or other response element. anyOf: - - $ref: '#/components/schemas/BetaMessage' - - $ref: '#/components/schemas/BetaProgram' - - $ref: '#/components/schemas/BetaProgramOutput' - - $ref: '#/components/schemas/BetaFunctionToolCall' - - $ref: '#/components/schemas/BetaMultiAgentCall' - - $ref: '#/components/schemas/BetaMultiAgentCallOutput' - - $ref: '#/components/schemas/BetaToolSearchCall' - - $ref: '#/components/schemas/BetaToolSearchOutput' - - $ref: '#/components/schemas/BetaAdditionalTools' - - $ref: '#/components/schemas/BetaAgentMessage' - - $ref: '#/components/schemas/BetaFunctionToolCallOutput' - - $ref: '#/components/schemas/BetaFileSearchToolCall' - - $ref: '#/components/schemas/BetaWebSearchToolCall' - - $ref: '#/components/schemas/BetaImageGenToolCall' - - $ref: '#/components/schemas/BetaComputerToolCall' - - $ref: '#/components/schemas/BetaComputerToolCallOutputResource' - - $ref: '#/components/schemas/BetaReasoningItem' - - $ref: '#/components/schemas/BetaCompactionBody' - - $ref: '#/components/schemas/BetaCodeInterpreterToolCall' - - $ref: '#/components/schemas/BetaLocalShellToolCall' - deprecated: true - - $ref: '#/components/schemas/BetaLocalShellToolCallOutput' - deprecated: true - - $ref: '#/components/schemas/BetaFunctionShellCall' - - $ref: '#/components/schemas/BetaFunctionShellCallOutput' - - $ref: '#/components/schemas/BetaApplyPatchToolCall' - - $ref: '#/components/schemas/BetaApplyPatchToolCallOutput' - - $ref: '#/components/schemas/BetaMCPListTools' - - $ref: '#/components/schemas/BetaMCPApprovalRequest' - - $ref: '#/components/schemas/BetaMCPApprovalResponseResource' - - $ref: '#/components/schemas/BetaMCPToolCall' - - $ref: '#/components/schemas/BetaCustomToolCall' - - $ref: '#/components/schemas/BetaCustomToolCallOutput' - BetaMessage: + - $ref: '#/components/schemas/LiveSessionStarted' + - $ref: '#/components/schemas/LiveSessionUpdated' + - $ref: '#/components/schemas/LiveInputAudioMuted' + - $ref: '#/components/schemas/LiveInputAudioUnmuted' + - $ref: '#/components/schemas/LiveInstructionsAppended' + - $ref: '#/components/schemas/LiveThinkingAppended' + - $ref: '#/components/schemas/LiveCommentaryAppended' + - $ref: '#/components/schemas/LiveInputAudioAppend' + - $ref: '#/components/schemas/LiveOutputAudioDelta' + - $ref: '#/components/schemas/LiveInputTranscriptDelta' + - $ref: '#/components/schemas/LiveOutputTranscriptDelta' + - $ref: '#/components/schemas/LiveDelegationCreated' + - $ref: '#/components/schemas/LiveResponseEvent' + - $ref: '#/components/schemas/LiveSessionUsageUpdated' + - $ref: '#/components/schemas/LiveSessionClosed' + - $ref: '#/components/schemas/LiveErrorEvent' + - $ref: '#/components/schemas/LiveInfoEvent' + - $ref: '#/components/schemas/LiveTransportDTMFReceived' + - $ref: '#/components/schemas/LiveTransportDTMFSend' + - $ref: '#/components/schemas/LiveTransportRinging' + - $ref: '#/components/schemas/LiveTransportAnswered' + - $ref: '#/components/schemas/LiveTransportFailed' + UserMessageItemParam: properties: - agent: - $ref: '#/components/schemas/BetaAgentTag' - description: The agent that produced this item. + id: + anyOf: + - type: string + description: The unique ID of this message item. + example: msg_123 + - type: 'null' type: type: string enum: - message - description: The type of the message. Always set to `message`. + description: The item type. Always `message`. default: message x-stainless-const: true - id: - type: string - description: The unique ID of the message. - status: - $ref: '#/components/schemas/BetaMessageStatus' - description: The status of item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. role: - $ref: '#/components/schemas/BetaMessageRole' - description: The role of the message. One of `unknown`, `user`, `assistant`, `system`, `critic`, `discriminator`, `developer`, or `tool`. - content: - items: - discriminator: - propertyName: type - description: A content part that makes up an input or output item. - anyOf: - - $ref: '#/components/schemas/BetaInputTextContent' - - $ref: '#/components/schemas/BetaOutputTextContent' - - $ref: '#/components/schemas/BetaTextContent' - - $ref: '#/components/schemas/BetaSummaryTextContent' - - $ref: '#/components/schemas/BetaReasoningTextContent' - - $ref: '#/components/schemas/BetaRefusalContent' - - $ref: '#/components/schemas/BetaInputImageContent' - - $ref: '#/components/schemas/BetaComputerScreenshotContent' - - $ref: '#/components/schemas/BetaInputFileContent' - - $ref: '#/components/schemas/BetaEncryptedContent' - type: array - description: The content of the message - phase: - anyOf: - - $ref: '#/components/schemas/BetaMessagePhase-2' - description: Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - type: 'null' - type: object - required: - - type - - id - - status - - role - - content - title: Message - description: A message to or from the model. - BetaMessagePhase-2: - type: string - enum: - - commentary - - final_answer - BetaMessageStatus: - type: string - enum: - - in_progress - - completed - - incomplete - BetaResponseCustomToolCallInputDoneEvent: - title: ResponseCustomToolCallInputDone - type: object - description: | - Event indicating that input for a custom tool call is complete. - properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. - type: type: string enum: - - response.custom_tool_call_input.done - description: The event type identifier. + - user + description: The message role. Always `user`. + default: user x-stainless-const: true - sequence_number: - type: integer - description: The sequence number of this event. - output_index: - type: integer - description: The index of the output this event applies to. - item_id: - type: string - description: Unique identifier for the API item associated with this event. - input: - type: string - description: The complete input data for the custom tool call. - required: - - type - - output_index - - item_id - - input - - sequence_number - x-oaiMeta: - name: response.custom_tool_call_input.done - group: responses - example: | - { - "type": "response.custom_tool_call_input.done", - "output_index": 0, - "item_id": "ctc_1234567890abcdef", - "input": "final complete input text" - } - BetaResponseCustomToolCallInputDeltaEvent: - title: ResponseCustomToolCallInputDelta - type: object - description: | - Event representing a delta (partial update) to the input of a custom tool call. - properties: - agent: + content: + description: The message content, as an array of content parts. + anyOf: + - items: + $ref: '#/components/schemas/ResponseSteerInputContent' + description: A piece of message content, such as text, an image, or a file. + type: array + - type: string + maxLength: 10485760 + description: The message content, as a single string. + status: anyOf: - - $ref: '#/components/schemas/BetaAgentTag' + - type: string + description: The status of the message item. - type: 'null' - description: The agent that owns this multi-agent streaming event. + type: object + required: + - type + - role + - content + ErrorPayload: + properties: type: type: string - enum: - - response.custom_tool_call_input.delta - description: The event type identifier. - x-stainless-const: true - sequence_number: - type: integer - description: The sequence number of this event. - output_index: - type: integer - description: The index of the output this delta applies to. - item_id: - type: string - description: Unique identifier for the API item associated with this event. - delta: + description: The error type that was emitted. + code: + anyOf: + - type: string + description: The error code that was emitted, if any. + - type: 'null' + message: type: string - description: The incremental input data (delta) for the custom tool call. + description: The human-readable error message that was emitted. + param: + anyOf: + - type: string + description: The parameter name that was associated with the error, if any. + - type: 'null' + headers: + additionalProperties: + type: string + description: The header value that was emitted. + type: object + description: The response headers that were emitted with the error, if any. + x-oaiTypeLabel: map + misalignment: + $ref: '#/components/schemas/MisalignmentErrorDetailsResource' + type: object required: - type - - output_index - - item_id - - delta - - sequence_number - x-oaiMeta: - name: response.custom_tool_call_input.delta - group: responses - example: | - { - "type": "response.custom_tool_call_input.delta", - "output_index": 0, - "item_id": "ctc_1234567890abcdef", - "delta": "partial input text" - } - BetaResponseQueuedEvent: - type: object - title: ResponseQueuedEvent - description: | - Emitted when a response is queued and waiting to be processed. + - code + - message + - param + title: Error payload + description: An error payload that was emitted for a streaming error event. + BetaTokenCountsResource: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. - type: + object: type: string enum: - - response.queued - description: The type of the event. Always 'response.queued'. + - response.input_tokens + default: response.input_tokens x-stainless-const: true - response: - $ref: '#/components/schemas/BetaResponse' - description: The full response object that is queued. - sequence_number: + input_tokens: type: integer - description: The sequence number for this event. + type: object required: - - type - - response - - sequence_number - x-oaiMeta: - name: response.queued - group: responses - example: | - { - "type": "response.queued", - "response": { - "id": "res_123", - "status": "queued", - "created_at": "2021-01-01T00:00:00Z", - "updated_at": "2021-01-01T00:00:00Z" - }, - "sequence_number": 1 - } - BetaResponse: - title: The response object - allOf: - - $ref: '#/components/schemas/BetaModelResponseProperties' - - $ref: '#/components/schemas/BetaResponseProperties' - - type: object - properties: - service_tier: - $ref: '#/components/schemas/BetaServiceTierResponses' - truncation: + - object + - input_tokens + title: Token counts + example: + object: response.input_tokens + input_tokens: 123 + BetaTokenCountsBody: + properties: + model: + anyOf: + - type: string + description: Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](https://developers.openai.com/api/docs/models) to browse and compare available models. + - type: 'null' + input: + anyOf: + - description: Text, image, or file inputs to the model, used to generate a response anyOf: - type: string - description: | - The truncation strategy to use for the model response. - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. - enum: - - auto - - disabled - default: disabled - - type: 'null' - id: - type: string - description: | - Unique identifier for this Response. - object: - type: string - description: | - The object type of this resource - always set to `response`. - enum: - - response - x-stainless-const: true - status: - type: string - description: | - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. - enum: - - completed - - failed - - in_progress - - cancelled - - queued - - incomplete - created_at: - type: number - format: unixtime - description: | - Unix timestamp (in seconds) of when this Response was created. - completed_at: - anyOf: - - type: number - format: unixtime - description: | - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. - - type: 'null' - error: - $ref: '#/components/schemas/BetaResponseError' - incomplete_details: - anyOf: - - type: object - description: | - Details about why the response is incomplete. - properties: - reason: - type: string - description: | - The reason why the response is incomplete. `steered` means - the response stopped at a safe output boundary after a - WebSocket `response.steer` event. The server can then create - a successor response automatically with the queued input. - enum: - - max_output_tokens - - max_messages - - content_filter - - steered - - type: 'null' - output: + maxLength: 10485760 + description: A text input to the model, equivalent to a text input with the `user` role. + - items: + $ref: '#/components/schemas/BetaInputItem' + type: array + maxItems: 131072 + description: A list of one or many input items to the model, containing different content types. + - type: 'null' + previous_response_id: + anyOf: + - type: string + description: The unique ID of the previous response to the model. Use this to create multi-turn conversations. Learn more about [conversation state](https://developers.openai.com/api/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + example: resp_123 + - type: 'null' + tools: + anyOf: + - items: + $ref: '#/components/schemas/BetaTool' type: array - description: | - An array of content items generated by the model. - - - The length and order of items in the `output` array is dependent - on the model's response. - - Rather than accessing the first item in the `output` array and - assuming it's an `assistant` message with the content generated by - the model, you might consider using the `output_text` property where - supported in SDKs. - items: - $ref: '#/components/schemas/BetaOutputItem' - reasoning: - anyOf: - - $ref: '#/components/schemas/BetaReasoning' - - type: 'null' - instructions: - anyOf: - - description: | - A system (or developer) message inserted into the model's context. - - When using along with `previous_response_id`, the instructions from a previous - response will not be carried over to the next response. This makes it simple - to swap out system (or developer) messages in new responses. - anyOf: - - type: string - description: | - A text input to the model, equivalent to a text input with the - `developer` role. - - type: array - title: Input item list - description: | - A list of one or many input items to the model, containing - different content types. - items: - $ref: '#/components/schemas/BetaInputItem' - - type: 'null' - output_text: - anyOf: - - type: string - description: | - SDK-only convenience property that contains the aggregated text output - from all `output_text` items in the `output` array, if any are present. - Supported in the Python and JavaScript SDKs. - x-oaiSupportedSDKs: - - python - - javascript - - type: 'null' - x-stainless-skip: true - usage: - $ref: '#/components/schemas/BetaResponseUsage' - prompt_cache_options: - $ref: '#/components/schemas/BetaPromptCacheOptions' - prompt_cache_diagnostics: - $ref: '#/components/schemas/BetaPromptCacheDiagnostics' - moderation: - anyOf: - - $ref: '#/components/schemas/BetaModeration' - description: | - Moderation results for the response input and output, if moderated completions were requested. - - type: 'null' - parallel_tool_calls: - type: boolean - description: | - Whether to allow the model to run tool calls in parallel. - default: true - conversation: - anyOf: - - $ref: '#/components/schemas/BetaResponseConversation' - - type: 'null' - max_output_tokens: - anyOf: - - description: | - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://developers.openai.com/api/docs/guides/reasoning). - type: integer - - type: 'null' - required: - - id - - object - - created_at - - error - - incomplete_details - - instructions - - model - - tools - - output - - parallel_tool_calls - - metadata - - tool_choice - - temperature - - top_p - BetaResponseConversation: + description: An array of tools the model may call while generating a response. You can specify which tool to use by setting the `tool_choice` parameter. + - type: 'null' + text: + anyOf: + - $ref: '#/components/schemas/BetaResponseTextParam' + - type: 'null' + reasoning: + anyOf: + - $ref: '#/components/schemas/BetaReasoning' + description: '**gpt-5 and o-series models only** Configuration options for [reasoning models](https://developers.openai.com/api/docs/guides/reasoning).' + - type: 'null' + truncation: + $ref: '#/components/schemas/BetaTruncationEnum' + description: 'The truncation strategy to use for the model response. - `auto`: If the input to this Response exceeds the model''s context window size, the model will truncate the response to fit the context window by dropping items from the beginning of the conversation. - `disabled` (default): If the input size will exceed the context window size for a model, the request will fail with a 400 error.' + deprecated: true + instructions: + anyOf: + - type: string + description: |- + A system (or developer) message inserted into the model's context. + When used along with `previous_response_id`, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses. + - type: 'null' + personality: + $ref: '#/components/schemas/BetaPersonalityEnum' + description: A model-owned style preset to apply to this request. Omit this parameter to use the model's default style. Supported values may expand over time. Values must be at most 64 characters. + conversation: + anyOf: + - $ref: '#/components/schemas/BetaConversationParam' + - type: 'null' + tool_choice: + anyOf: + - $ref: '#/components/schemas/BetaToolChoiceParam' + description: Controls which tool the model should use, if any. + - type: 'null' + parallel_tool_calls: + anyOf: + - type: boolean + description: Whether to allow the model to run tool calls in parallel. + - type: 'null' + type: object + required: [] + BetaToolChoiceParam: + description: | + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. + anyOf: + - $ref: '#/components/schemas/BetaToolChoiceOptions' + - $ref: '#/components/schemas/BetaToolChoiceAllowed' + - $ref: '#/components/schemas/BetaToolChoiceTypes' + - $ref: '#/components/schemas/BetaToolChoiceFunction' + - $ref: '#/components/schemas/BetaToolChoiceMCP' + - $ref: '#/components/schemas/BetaToolChoiceCustom' + - $ref: '#/components/schemas/BetaSpecificProgrammaticToolCallingParam' + - $ref: '#/components/schemas/BetaSpecificApplyPatchParam' + - $ref: '#/components/schemas/BetaSpecificFunctionShellParam' + BetaSpecificFunctionShellParam: properties: - id: + type: type: string - description: The unique ID of the conversation that this response was associated with. + enum: + - shell + description: The tool to call. Always `shell`. + default: shell + x-stainless-const: true type: object required: - - id - title: Conversation - description: The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - BetaModeration: + - type + title: Specific shell tool choice + description: Forces the model to call the shell tool when a tool call is required. + BetaSpecificApplyPatchParam: properties: - input: - discriminator: - propertyName: type - description: Moderation for the response input. - anyOf: - - $ref: '#/components/schemas/BetaModerationResultBody' - - $ref: '#/components/schemas/BetaModerationErrorBody' - output: - discriminator: - propertyName: type - description: Moderation for the response output. - anyOf: - - $ref: '#/components/schemas/BetaModerationResultBody' - - $ref: '#/components/schemas/BetaModerationErrorBody' + type: + type: string + enum: + - apply_patch + description: The tool to call. Always `apply_patch`. + default: apply_patch + x-stainless-const: true type: object required: - - input - - output - title: Moderation - description: Moderation results or errors for the response input and output. - BetaModerationErrorBody: + - type + title: Specific apply patch tool choice + description: Forces the model to call the apply_patch tool when executing a tool call. + BetaSpecificProgrammaticToolCallingParam: properties: type: type: string enum: - - error - description: The object type, which was always `error` for moderation failures. - default: error + - programmatic_tool_calling + description: The tool to call. Always `programmatic_tool_calling`. + default: programmatic_tool_calling x-stainless-const: true - code: - type: string - description: The error code. - message: - type: string - description: The error message. type: object required: - type - - code - - message - title: Moderation error - description: An error produced while attempting moderation for the response input or output. - BetaModerationResultBody: + BetaToolChoiceCustom: + type: object + title: Custom tool + description: | + Use this option to force the model to call a specific custom tool. properties: type: type: string enum: - - moderation_result - description: The object type, which was always `moderation_result` for successful moderation results. - default: moderation_result + - custom + description: For custom tool calling, the type is always `custom`. x-stainless-const: true - model: + name: type: string - description: The moderation model that produced this result. - flagged: - type: boolean - description: A boolean indicating whether the content was flagged by any category. - categories: - additionalProperties: - type: boolean - type: object - description: A dictionary of moderation categories to booleans, True if the input is flagged under this category. - x-oaiTypeLabel: map - category_scores: - additionalProperties: - type: number - type: object - description: A dictionary of moderation categories to scores. - x-oaiTypeLabel: map - category_applied_input_types: - additionalProperties: - items: - $ref: '#/components/schemas/BetaModerationInputType' - type: array - type: object - description: Which modalities of input are reflected by the score for each category. - x-oaiTypeLabel: map - type: object + description: The name of the custom tool to call. required: - type - - model - - flagged - - categories - - category_scores - - category_applied_input_types - title: Moderation result - description: A moderation result produced for the response input or output. - BetaModerationInputType: - type: string - enum: - - text - - image - BetaPromptCacheDiagnostics: - discriminator: - propertyName: type - description: Prompt cache diagnostics requested for this response. - anyOf: - - $ref: '#/components/schemas/BetaPromptCacheMissDiagnosticsBody' - - $ref: '#/components/schemas/BetaPromptCacheHitDiagnosticsBody' - - $ref: '#/components/schemas/BetaPromptCacheComparisonResponseNotFoundDiagnosticsBody' - - $ref: '#/components/schemas/BetaPromptCacheUnavailableDiagnosticsBody' - BetaPromptCacheUnavailableDiagnosticsBody: + - name + BetaToolChoiceMCP: + type: object + title: MCP tool + description: | + Use this option to force the model to call a specific tool on a remote MCP server. properties: type: type: string enum: - - unavailable - default: unavailable + - mcp + description: For MCP tools, the type is always `mcp`. x-stainless-const: true - type: object + server_label: + type: string + description: | + The label of the MCP server to use. + name: + anyOf: + - type: string + description: | + The name of the tool to call on the server. + - type: 'null' required: - type - BetaPromptCacheComparisonResponseNotFoundDiagnosticsBody: + - server_label + BetaToolChoiceFunction: + type: object + title: Function tool + description: | + Use this option to force the model to call a specific function. properties: type: type: string enum: - - comparison_response_not_found - default: comparison_response_not_found + - function + description: For function calling, the type is always `function`. x-stainless-const: true - type: object + name: + type: string + description: The name of the function to call. required: - type - BetaPromptCacheHitDiagnosticsBody: + - name + BetaToolChoiceTypes: + type: object + title: Hosted tool + description: | + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](https://developers.openai.com/api/docs/guides/tools). properties: type: type: string + description: | + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://developers.openai.com/api/docs/guides/tools). + + Allowed values are: + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` enum: - - cache_hit - default: cache_hit - x-stainless-const: true - type: object + - file_search + - web_search_preview + - computer + - computer_use_preview + - computer_use + - web_search_preview_2025_03_11 + - image_generation + - code_interpreter required: - type - BetaPromptCacheMissDiagnosticsBody: + BetaToolChoiceAllowed: + type: object + title: Allowed tools + description: | + Constrains the tools available to the model to a pre-defined set. properties: type: type: string enum: - - cache_miss - default: cache_miss + - allowed_tools + description: Allowed tool configuration type. Always `allowed_tools`. x-stainless-const: true - reason: - $ref: '#/components/schemas/BetaCacheMissReasonTypeEnum' - description: The reason prompt cache reuse did not occur. - cache_missed_tokens: - type: integer - description: The estimated number of input tokens affected after the first detected divergence. - comparison_reusable_tokens: - type: integer - description: The raw token count of the reusable prefix in the compared response. - type: object - required: - - type - - reason - - cache_missed_tokens - BetaCacheMissReasonTypeEnum: - type: string - enum: - - model_changed - - prompt_cache_key_changed - - tools_changed - - text_format_changed - - reasoning_effort_changed - - verbosity_changed - - context_compacted - - input_changed - - service_tier_changed - BetaPromptCacheOptions: - properties: - ttl: - $ref: '#/components/schemas/BetaPromptCacheTTLEnum' - description: The minimum lifetime applied to each cache breakpoint. mode: - $ref: '#/components/schemas/BetaPromptCacheModeEnum' - description: Whether implicit prompt-cache breakpoints were enabled. - comparison_response_id: - anyOf: - - type: string - description: The response ID supplied as the prompt cache diagnostics comparison. - - type: 'null' - type: object + type: string + enum: + - auto + - required + description: | + Constrains the tools available to the model to a pre-defined set. + + `auto` allows the model to pick from among the allowed tools and generate a + message. + + `required` requires the model to call one or more of the allowed tools. + tools: + type: array + description: | + A list of tool definitions that the model should be allowed to call. + + For the Responses API, the list of tool definitions might look like: + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` + items: + type: object + description: | + A tool definition that the model should be allowed to call. + additionalProperties: true + x-oaiExpandable: false required: - - ttl + - type - mode - title: Prompt cache options - description: The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - BetaOutputItem: - discriminator: - propertyName: type - anyOf: - - $ref: '#/components/schemas/BetaOutputMessage' - - $ref: '#/components/schemas/BetaFileSearchToolCall' - - $ref: '#/components/schemas/BetaFunctionToolCall' - - $ref: '#/components/schemas/BetaFunctionToolCallOutputResource' - - $ref: '#/components/schemas/BetaAgentMessage' - - $ref: '#/components/schemas/BetaMultiAgentCall' - - $ref: '#/components/schemas/BetaMultiAgentCallOutput' - - $ref: '#/components/schemas/BetaWebSearchToolCall' - - $ref: '#/components/schemas/BetaComputerToolCall' - - $ref: '#/components/schemas/BetaComputerToolCallOutputResource' - - $ref: '#/components/schemas/BetaReasoningItem' - - $ref: '#/components/schemas/BetaProgram' - - $ref: '#/components/schemas/BetaProgramOutput' - - $ref: '#/components/schemas/BetaToolSearchCall' - - $ref: '#/components/schemas/BetaToolSearchOutput' - - $ref: '#/components/schemas/BetaAdditionalTools' - - $ref: '#/components/schemas/BetaCompactionBody' - - $ref: '#/components/schemas/BetaImageGenToolCall' - - $ref: '#/components/schemas/BetaCodeInterpreterToolCall' - - $ref: '#/components/schemas/BetaLocalShellToolCall' - - $ref: '#/components/schemas/BetaLocalShellToolCallOutput' - - $ref: '#/components/schemas/BetaFunctionShellCall' - - $ref: '#/components/schemas/BetaFunctionShellCallOutput' - - $ref: '#/components/schemas/BetaApplyPatchToolCall' - - $ref: '#/components/schemas/BetaApplyPatchToolCallOutput' - - $ref: '#/components/schemas/BetaMCPToolCall' - - $ref: '#/components/schemas/BetaMCPListTools' - - $ref: '#/components/schemas/BetaMCPApprovalRequest' - - $ref: '#/components/schemas/BetaMCPApprovalResponseResource' - - $ref: '#/components/schemas/BetaCustomToolCall' - - $ref: '#/components/schemas/BetaCustomToolCallOutputResource' - BetaResponseError: - anyOf: - - type: object - description: | - An error object returned when the model fails to generate a Response. - properties: - code: - $ref: '#/components/schemas/BetaResponseErrorCode' - message: - type: string - description: | - A human-readable description of the error. - misalignment: - $ref: '#/components/schemas/BetaMisalignmentErrorDetailsResource' - required: - - code - - message - - type: 'null' - BetaResponseErrorCode: + - tools + BetaToolChoiceOptions: type: string + title: Tool choice mode description: | - The error code for the response. + Controls which (if any) tool is called by the model. + + `none` means the model will not call any tool and instead generates a message. + + `auto` means the model can pick between generating a message or calling one or + more tools. + + `required` means the model must call one or more tools. enum: - - server_error - - rate_limit_exceeded - - invalid_prompt - - data_residency_mismatch - - bio_policy - - misalignment_policy_violation - - vector_store_timeout - - invalid_image - - invalid_image_format - - invalid_base64_image - - invalid_image_url - - image_too_large - - image_too_small - - image_parse_error - - image_content_policy_violation - - invalid_image_mode - - image_file_too_large - - unsupported_image_media_type - - empty_image_file - - failed_to_download_image - - image_file_not_found - BetaServiceTierResponses: + - none + - auto + - required + BetaConversationParam: + description: | + The conversation that this response belongs to. Items from this conversation are prepended to `input_items` for this response request. + Input items and output items from this response are automatically added to this conversation after this response completes. anyOf: - type: string + title: Conversation ID description: | - Specifies the processing type used for serving the request. - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://developers.openai.com/api/docs/guides/flex-processing)', then the request will be processed with the Flex Processing service tier. - - To opt-in to [Fast mode](https://developers.openai.com/api/docs/guides/fast-mode) at the request level, include the `service_tier=fast` or `service_tier=priority` parameter for Responses or Chat Completions. The response will show `service_tier=priority` regardless of if you specify `service_tier=fast` or `priority` in your request. - - If set to 'ultrafast', then the request will be processed with the access-controlled Ultrafast Processing service tier. This tier is currently available for `gpt-5.6-sol`; a response served through it will show `service_tier=ultrafast`. - - When not set, the default behavior is 'auto'. - - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - enum: - - auto - - default - - flex - - scale - - priority - - fast - - ultrafast - default: auto - - type: 'null' - BetaResponseProperties: - type: object + The unique ID of the conversation. + - $ref: '#/components/schemas/BetaConversationParam-2' + BetaConversationParam-2: properties: - previous_response_id: - anyOf: - - type: string - description: | - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](https://developers.openai.com/api/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. - - type: 'null' - model: - description: | - Model ID used to generate the response, like `gpt-6-astra`. OpenAI - offers a wide range of models with different capabilities, performance - characteristics, and price points. Refer to the [model guide](https://developers.openai.com/api/docs/models) - to browse and compare available models. - $ref: '#/components/schemas/BetaModelIdsResponses' - background: - anyOf: - - type: boolean - description: | - Whether to run the model response in the background. - [Learn more](https://developers.openai.com/api/docs/guides/background). - default: false - - type: 'null' - max_tool_calls: - anyOf: - - description: | - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - type: integer - - type: 'null' - text: - $ref: '#/components/schemas/BetaResponseTextParam' - tools: - $ref: '#/components/schemas/BetaToolsArray' - tool_choice: - $ref: '#/components/schemas/BetaToolChoiceParam' - prompt: - $ref: '#/components/schemas/BetaPrompt' - BetaPrompt: - anyOf: - - type: object - description: | - Reference to a prompt template and its variables. - [Learn more](https://developers.openai.com/api/docs/guides/text?api-mode=responses#version-prompts-in-code). - required: - - id - properties: - id: - type: string - description: The unique identifier of the prompt template to use. - version: - anyOf: - - type: string - description: Optional version of the prompt template. - - type: 'null' - variables: - $ref: '#/components/schemas/BetaResponsePromptVariables' - - type: 'null' - BetaResponsePromptVariables: + id: + type: string + description: The unique ID of the conversation. + example: conv_123 + type: object + required: + - id + title: Conversation object + description: The conversation that this response belongs to. + BetaPersonalityEnum: anyOf: - - type: object - title: Prompt Variables - description: | - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. - x-oaiExpandable: true - x-oaiTypeLabel: map - additionalProperties: - x-oaiExpandable: true - x-oaiTypeLabel: map - anyOf: - - type: string - - $ref: '#/components/schemas/BetaInputTextContent' - - $ref: '#/components/schemas/BetaInputImageContent' - - $ref: '#/components/schemas/BetaInputFileContent' - - type: 'null' - BetaToolsArray: - type: array - description: | - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. - - We support the following categories of tools: - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://developers.openai.com/api/docs/guides/tools-web-search) - or [file search](https://developers.openai.com/api/docs/guides/tools-file-search). Learn more about - [built-in tools](https://developers.openai.com/api/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Built-in - connectors using `connector_id` are deprecated for models released after - September 1, 2026. Use `server_url` to connect to a remote MCP server, or - `tunnel_id` to connect through a Secure MCP Tunnel. Learn more about - [MCP Tools](https://developers.openai.com/api/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://developers.openai.com/api/docs/guides/function-calling). You can also use - custom tools to call your own code. - items: - $ref: '#/components/schemas/BetaTool' - BetaModelResponseProperties: + - type: string + - type: string + enum: + - friendly + - pragmatic + BetaTruncationEnum: + type: string + enum: + - auto + - disabled + BetaReasoning: type: object + description: | + Configuration options for + [reasoning models](https://developers.openai.com/api/docs/guides/reasoning). + title: Reasoning properties: - metadata: - $ref: '#/components/schemas/BetaMetadata' - top_logprobs: - anyOf: - - description: | - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. - type: integer - minimum: 0 - maximum: 20 - - type: 'null' - temperature: - anyOf: - - type: number - minimum: 0 - maximum: 2 - default: 1 - example: 1 - description: | - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - We generally recommend altering this or `top_p` but not both. - - type: 'null' - top_p: - anyOf: - - type: number - minimum: 0 - maximum: 1 - default: 1 - example: 1 - description: | - An alternative to sampling with temperature, called nucleus sampling, - where the model considers the results of the tokens with top_p probability - mass. So 0.1 means only the tokens comprising the top 10% probability mass - are considered. - - We generally recommend altering this or `temperature` but not both. - - type: 'null' - user: - type: string - example: user-1234 - deprecated: true + mode: + $ref: '#/components/schemas/BetaReasoningModeEnum' description: | - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers). - safety_identifier: + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + effort: + $ref: '#/components/schemas/BetaReasoningEffort' + summary: anyOf: - type: string - maxLength: 64 - example: safety-identifier-1234 description: | - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers). + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. + + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + enum: + - auto + - concise + - detailed - type: 'null' - prompt_cache_key: + context: anyOf: - type: string - example: prompt-cache-key-1234 description: | - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://developers.openai.com/api/docs/guides/prompt-caching). + Controls which reasoning items are rendered back to the model on later turns. + If omitted or set to `auto`, the model determines the context mode. The + `gpt-5.6` model family defaults to `all_turns`; earlier models default to + `current_turn`. + + When returned on a response, this is the effective reasoning context mode + used for the response. + enum: + - auto + - current_turn + - all_turns - type: 'null' - prompt_cache_retention: - deprecated: true + generate_summary: anyOf: - type: string - enum: - - in_memory - - 24h + deprecated: true description: | - Deprecated. Use `prompt_cache_options.ttl` instead. - - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://developers.openai.com/api/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + **Deprecated:** use `summary` instead. - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. + enum: + - auto + - concise + - detailed - type: 'null' - BetaMetadata: + BetaReasoningEffort: + anyOf: + - type: string + enum: + - none + - minimal + - low + - medium + - high + - xhigh + - max + default: medium + description: | + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://developers.openai.com/api/docs/guides/reasoning) + for model-specific support. + - type: 'null' + BetaReasoningModeEnum: anyOf: - - type: object + - type: string + - type: string + enum: + - standard + - pro + BetaResponseTextParam: + type: object + description: | + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: + - [Text inputs and outputs](https://developers.openai.com/api/docs/guides/text) + - [Structured Outputs](https://developers.openai.com/api/docs/guides/structured-outputs) + properties: + format: + $ref: '#/components/schemas/BetaTextResponseFormatConfiguration' + verbosity: + $ref: '#/components/schemas/BetaVerbosity' + BetaVerbosity: + anyOf: + - type: string + enum: + - low + - medium + - high + default: medium description: | - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. - - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. - additionalProperties: - type: string - x-oaiTypeLabel: map + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. The default is + `medium`. - type: 'null' - BetaResponseOutputTextAnnotationAddedEvent: + BetaTextResponseFormatConfiguration: + description: | + An object specifying the format that the model must output. + + Configuring `{ "type": "json_schema" }` enables Structured Outputs, + which ensures the model will match your supplied JSON schema. Learn more in the + [Structured Outputs guide](https://developers.openai.com/api/docs/guides/structured-outputs). + + The default format is `{ "type": "text" }` with no additional options. + + **Not recommended for gpt-4o and newer models:** + + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. + anyOf: + - $ref: '#/components/schemas/BetaResponseFormatText' + - $ref: '#/components/schemas/BetaTextResponseFormatJsonSchema' + - $ref: '#/components/schemas/BetaResponseFormatJsonObject' + discriminator: + propertyName: type + BetaResponseFormatJsonObject: type: object - title: ResponseOutputTextAnnotationAddedEvent + title: JSON object description: | - Emitted when an annotation is added to output text content. + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string + description: The type of response format being defined. Always `json_object`. enum: - - response.output_text.annotation.added - description: The type of the event. Always 'response.output_text.annotation.added'. + - json_object x-stainless-const: true - item_id: - type: string - description: The unique identifier of the item to which the annotation is being added. - output_index: - type: integer - description: The index of the output item in the response's output array. - content_index: - type: integer - description: The index of the content part within the output item. - annotation_index: - type: integer - description: The index of the annotation within the content part. - sequence_number: - type: integer - description: The sequence number of this event. - annotation: - anyOf: - - $ref: '#/components/schemas/BetaAnnotation' - - type: 'null' - description: The annotation object being added. (See annotation schema for details.) required: - type - - item_id - - output_index - - content_index - - annotation_index - - annotation - - sequence_number - x-oaiMeta: - name: response.output_text.annotation.added - group: responses - example: | - { - "type": "response.output_text.annotation.added", - "item_id": "item-abc", - "output_index": 0, - "content_index": 0, - "annotation_index": 0, - "annotation": { - "type": "file_citation", - "file_id": "file-abc", - "index": 0, - "filename": "example.txt" - }, - "sequence_number": 1 - } - BetaResponseMCPListToolsInProgressEvent: + BetaTextResponseFormatJsonSchema: type: object - title: ResponseMCPListToolsInProgressEvent + title: JSON schema description: | - Emitted when the system is in the process of retrieving the list of available MCP tools. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://developers.openai.com/api/docs/guides/structured-outputs). properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string + description: The type of response format being defined. Always `json_schema`. enum: - - response.mcp_list_tools.in_progress - description: The type of the event. Always 'response.mcp_list_tools.in_progress'. + - json_schema x-stainless-const: true - item_id: + description: type: string - description: The ID of the MCP tool call item that is being processed. - output_index: - type: integer - description: The index of the output item that is being processed. - sequence_number: - type: integer - description: The sequence number of this event. + description: | + A description of what the response format is for, used by the model to + determine how to respond in the format. + name: + type: string + description: | + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. + schema: + $ref: '#/components/schemas/BetaResponseFormatJsonSchemaSchema' + strict: + anyOf: + - type: boolean + default: false + description: | + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://developers.openai.com/api/docs/guides/structured-outputs). + - type: 'null' required: - type - - item_id - - output_index - - sequence_number - x-oaiMeta: - name: response.mcp_list_tools.in_progress - group: responses - example: | - { - "type": "response.mcp_list_tools.in_progress", - "sequence_number": 1, - "output_index": 0, - "item_id": "mcpl_682d4379df088191886b70f4ec39f90403937d5f622d7a90" - } - BetaResponseMCPListToolsFailedEvent: + - schema + - name + BetaResponseFormatJsonSchemaSchema: type: object - title: ResponseMCPListToolsFailedEvent + title: JSON schema description: | - Emitted when the attempt to list available MCP tools has failed. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). + additionalProperties: true + BetaResponseFormatText: + type: object + title: Text + description: | + Default response format. Used to generate text responses. properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string + description: The type of response format being defined. Always `text`. enum: - - response.mcp_list_tools.failed - description: The type of the event. Always 'response.mcp_list_tools.failed'. + - text x-stainless-const: true - item_id: - type: string - description: The ID of the MCP tool call item that failed. - output_index: - type: integer - description: The index of the output item that failed. - sequence_number: - type: integer - description: The sequence number of this event. required: - type - - item_id - - output_index - - sequence_number - x-oaiMeta: - name: response.mcp_list_tools.failed - group: responses - example: | - { - "type": "response.mcp_list_tools.failed", - "sequence_number": 1, - "output_index": 0, - "item_id": "mcpl_682d4379df088191886b70f4ec39f90403937d5f622d7a90" - } - BetaResponseMCPListToolsCompletedEvent: - type: object - title: ResponseMCPListToolsCompletedEvent + BetaTool: description: | - Emitted when the list of available MCP tools has been successfully retrieved. + A tool that can be used to generate a response. + discriminator: + propertyName: type + anyOf: + - $ref: '#/components/schemas/BetaFunctionTool' + - $ref: '#/components/schemas/BetaFileSearchTool' + - $ref: '#/components/schemas/BetaComputerTool' + - $ref: '#/components/schemas/BetaComputerUsePreviewTool' + - $ref: '#/components/schemas/BetaWebSearchTool' + - $ref: '#/components/schemas/BetaMCPTool' + - $ref: '#/components/schemas/BetaCodeInterpreterTool' + - $ref: '#/components/schemas/BetaProgrammaticToolCallingParam' + - $ref: '#/components/schemas/BetaImageGenTool' + - $ref: '#/components/schemas/BetaLocalShellToolParam' + - $ref: '#/components/schemas/BetaFunctionShellToolParam' + - $ref: '#/components/schemas/BetaCustomToolParam' + - $ref: '#/components/schemas/BetaNamespaceToolParam' + - $ref: '#/components/schemas/BetaToolSearchToolParam' + - $ref: '#/components/schemas/BetaWebSearchPreviewTool' + - $ref: '#/components/schemas/BetaApplyPatchToolParam' + BetaApplyPatchToolParam: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string enum: - - response.mcp_list_tools.completed - description: The type of the event. Always 'response.mcp_list_tools.completed'. + - apply_patch + description: The type of the tool. Always `apply_patch`. + default: apply_patch x-stainless-const: true - item_id: - type: string - description: The ID of the MCP tool call item that produced this output. - output_index: - type: integer - description: The index of the output item that was processed. - sequence_number: - type: integer - description: The sequence number of this event. + allowed_callers: + anyOf: + - items: + $ref: '#/components/schemas/BetaCallableToolAllowedCaller' + type: array + minItems: 1 + description: The tool invocation context(s). + - type: 'null' + type: object required: - type - - item_id - - output_index - - sequence_number - x-oaiMeta: - name: response.mcp_list_tools.completed - group: responses - example: | - { - "type": "response.mcp_list_tools.completed", - "sequence_number": 1, - "output_index": 0, - "item_id": "mcpl_682d4379df088191886b70f4ec39f90403937d5f622d7a90" - } - BetaResponseMCPCallInProgressEvent: - type: object - title: ResponseMCPCallInProgressEvent - description: | - Emitted when an MCP tool call is in progress. + title: Apply patch tool + description: Allows the assistant to create, delete, or update files using unified diffs. + BetaCallableToolAllowedCaller: + type: string + enum: + - direct + - programmatic + BetaWebSearchPreviewTool: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string enum: - - response.mcp_call.in_progress - description: The type of the event. Always 'response.mcp_call.in_progress'. + - web_search_preview + - web_search_preview_2025_03_11 + description: The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + default: web_search_preview x-stainless-const: true - sequence_number: - type: integer - description: The sequence number of this event. - output_index: - type: integer - description: The index of the output item in the response's output array. - item_id: - type: string - description: The unique identifier of the MCP tool call item being processed. + user_location: + anyOf: + - $ref: '#/components/schemas/BetaApproximateLocation' + description: The user's location. + - type: 'null' + search_context_size: + $ref: '#/components/schemas/BetaSearchContextSize' + description: High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + search_content_types: + items: + $ref: '#/components/schemas/BetaSearchContentType' + type: array + type: object required: - type - - output_index - - item_id - - sequence_number - x-oaiMeta: - name: response.mcp_call.in_progress - group: responses - example: | - { - "type": "response.mcp_call.in_progress", - "sequence_number": 1, - "output_index": 0, - "item_id": "mcp_682d437d90a88191bf88cd03aae0c3e503937d5f622d7a90" - } - BetaResponseMCPCallFailedEvent: - type: object - title: ResponseMCPCallFailedEvent - description: | - Emitted when an MCP tool call has failed. + title: Web search preview + description: This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://developers.openai.com/api/docs/guides/tools-web-search). + BetaSearchContentType: + type: string + enum: + - text + - image + BetaSearchContextSize: + type: string + enum: + - low + - medium + - high + BetaApproximateLocation: properties: - agent: + type: + type: string + enum: + - approximate + description: The type of location approximation. Always `approximate`. + default: approximate + x-stainless-const: true + country: anyOf: - - $ref: '#/components/schemas/BetaAgentTag' + - type: string + description: The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - type: 'null' - description: The agent that owns this multi-agent streaming event. + region: + anyOf: + - type: string + description: Free text input for the region of the user, e.g. `California`. + - type: 'null' + city: + anyOf: + - type: string + description: Free text input for the city of the user, e.g. `San Francisco`. + - type: 'null' + timezone: + anyOf: + - type: string + description: The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - type: 'null' + type: object + required: + - type + BetaToolSearchToolParam: + properties: type: type: string enum: - - response.mcp_call.failed - description: The type of the event. Always 'response.mcp_call.failed'. + - tool_search + description: The type of the tool. Always `tool_search`. + default: tool_search x-stainless-const: true - item_id: - type: string - description: The ID of the MCP tool call item that failed. - output_index: - type: integer - description: The index of the output item that failed. - sequence_number: - type: integer - description: The sequence number of this event. + execution: + $ref: '#/components/schemas/BetaToolSearchExecutionType' + description: Whether tool search is executed by the server or by the client. + description: + anyOf: + - type: string + description: Description shown to the model for a client-executed tool search tool. + - type: 'null' + parameters: + anyOf: + - $ref: '#/components/schemas/BetaEmptyModelParam' + description: Parameter schema for a client-executed tool search tool. + - type: 'null' + type: object required: - type - - item_id - - output_index - - sequence_number - x-oaiMeta: - name: response.mcp_call.failed - group: responses - example: | - { - "type": "response.mcp_call.failed", - "sequence_number": 1, - "item_id": "mcp_682d437d90a88191bf88cd03aae0c3e503937d5f622d7a90", - "output_index": 0 - } - BetaResponseMCPCallCompletedEvent: + title: Tool search tool + description: Hosted or BYOT tool search configuration for deferred tools. + BetaEmptyModelParam: + properties: {} type: object - title: ResponseMCPCallCompletedEvent - description: | - Emitted when an MCP tool call has completed successfully. + required: [] + BetaToolSearchExecutionType: + type: string + enum: + - server + - client + BetaNamespaceToolParam: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string enum: - - response.mcp_call.completed - description: The type of the event. Always 'response.mcp_call.completed'. + - namespace + description: The type of the tool. Always `namespace`. + default: namespace x-stainless-const: true - item_id: + name: type: string - description: The ID of the MCP tool call item that completed. - output_index: - type: integer - description: The index of the output item that completed. - sequence_number: - type: integer - description: The sequence number of this event. - required: - - type - - item_id - - output_index - - sequence_number - x-oaiMeta: - name: response.mcp_call.completed - group: responses - example: | - { - "type": "response.mcp_call.completed", - "sequence_number": 1, - "item_id": "mcp_682d437d90a88191bf88cd03aae0c3e503937d5f622d7a90", - "output_index": 0 - } - BetaResponseMCPCallArgumentsDoneEvent: + minLength: 1 + description: The namespace name used in tool calls (for example, `crm`). + description: + type: string + description: A description of the namespace shown to the model. + tools: + items: + discriminator: + propertyName: type + description: A function or custom tool that belongs to a namespace. + anyOf: + - $ref: '#/components/schemas/BetaFunctionToolParam' + - $ref: '#/components/schemas/BetaCustomToolParam' + type: array + minItems: 1 + description: The function/custom tools available inside this namespace. type: object - title: ResponseMCPCallArgumentsDoneEvent - description: | - Emitted when the arguments for an MCP tool call are finalized. + required: + - type + - name + - description + - tools + title: Namespace + description: Groups function/custom tools under a shared namespace. + BetaCustomToolParam: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string enum: - - response.mcp_call_arguments.done - description: The type of the event. Always 'response.mcp_call_arguments.done'. + - custom + description: The type of the custom tool. Always `custom`. + default: custom x-stainless-const: true - output_index: - type: integer - description: The index of the output item in the response's output array. - item_id: + name: type: string - description: The unique identifier of the MCP tool call item being processed. - arguments: + description: The name of the custom tool, used to identify it in tool calls. + async: + type: boolean + description: Whether the tool response can be returned asynchronously versus immediately returned on next response creation. + description: type: string - description: | - A JSON string containing the finalized arguments for the MCP tool call. - sequence_number: - type: integer - description: The sequence number of this event. + description: Optional description of the custom tool, used to provide more context. + format: + discriminator: + propertyName: type + description: The input format for the custom tool. Default is unconstrained text. + anyOf: + - $ref: '#/components/schemas/BetaCustomTextFormatParam' + - $ref: '#/components/schemas/BetaCustomGrammarFormatParam' + defer_loading: + type: boolean + description: Whether this tool should be deferred and discovered via tool search. + allowed_callers: + anyOf: + - items: + $ref: '#/components/schemas/BetaCallableToolAllowedCaller' + type: array + minItems: 1 + description: The tool invocation context(s). + - type: 'null' + type: object required: - type - - output_index - - item_id - - arguments - - sequence_number - x-oaiMeta: - name: response.mcp_call_arguments.done - group: responses - example: | - { - "type": "response.mcp_call_arguments.done", - "output_index": 0, - "item_id": "item-abc", - "arguments": "{\"arg1\": \"value1\", \"arg2\": \"value2\"}", - "sequence_number": 1 - } - BetaResponseMCPCallArgumentsDeltaEvent: - type: object - title: ResponseMCPCallArgumentsDeltaEvent - description: | - Emitted when there is a delta (partial update) to the arguments of an MCP tool call. + - name + title: Custom tool + description: A custom tool that processes input using a specified format. Learn more about [custom tools](https://developers.openai.com/api/docs/guides/function-calling#custom-tools) + BetaCustomGrammarFormatParam: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string enum: - - response.mcp_call_arguments.delta - description: The type of the event. Always 'response.mcp_call_arguments.delta'. + - grammar + description: Grammar format. Always `grammar`. + default: grammar x-stainless-const: true - output_index: - type: integer - description: The index of the output item in the response's output array. - item_id: - type: string - description: The unique identifier of the MCP tool call item being processed. - delta: + syntax: + $ref: '#/components/schemas/BetaGrammarSyntax1' + description: The syntax of the grammar definition. One of `lark` or `regex`. + definition: type: string - description: | - A JSON string containing the partial update to the arguments for the MCP tool call. - sequence_number: - type: integer - description: The sequence number of this event. + description: The grammar definition. + type: object required: - type - - output_index - - item_id - - delta - - sequence_number - x-oaiMeta: - name: response.mcp_call_arguments.delta - group: responses - example: | - { - "type": "response.mcp_call_arguments.delta", - "output_index": 0, - "item_id": "item-abc", - "delta": "{", - "sequence_number": 1 - } - BetaResponseImageGenCallPartialImageEvent: - type: object - title: ResponseImageGenCallPartialImageEvent - description: | - Emitted when a partial image is available during image generation streaming. + - syntax + - definition + title: Grammar format + description: A grammar defined by the user. + BetaGrammarSyntax1: + type: string + enum: + - lark + - regex + BetaCustomTextFormatParam: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string enum: - - response.image_generation_call.partial_image - description: The type of the event. Always 'response.image_generation_call.partial_image'. + - text + description: Unconstrained text format. Always `text`. + default: text x-stainless-const: true - output_index: - type: integer - description: The index of the output item in the response's output array. - item_id: - type: string - description: The unique identifier of the image generation item being processed. - sequence_number: - type: integer - description: The sequence number of the image generation item being processed. - partial_image_index: - type: integer - description: 0-based index for the partial image (backend is 1-based, but this is 0-based for the user). - partial_image_b64: - type: string - description: Base64-encoded partial image data, suitable for rendering as an image. - size: - type: string - description: The image size that was used. - quality: - type: string - description: The image quality that was used. - background: - type: string - description: The background setting that was used. - output_format: - type: string - description: The output format that was used. + type: object required: - type - - output_index - - item_id - - sequence_number - - partial_image_index - - partial_image_b64 - x-oaiMeta: - name: response.image_generation_call.partial_image - group: responses - example: | - { - "type": "response.image_generation_call.partial_image", - "output_index": 0, - "item_id": "item-123", - "sequence_number": 0, - "partial_image_index": 0, - "partial_image_b64": "..." - } - BetaResponseImageGenCallInProgressEvent: - type: object - title: ResponseImageGenCallInProgressEvent - description: | - Emitted when an image generation tool call is in progress. + title: Text format + description: Unconstrained free-form text. + BetaFunctionToolParam: properties: - agent: + name: + type: string + maxLength: 128 + minLength: 1 + pattern: ^[a-zA-Z0-9_-]+$ + description: anyOf: - - $ref: '#/components/schemas/BetaAgentTag' + - type: string + - type: 'null' + parameters: + anyOf: + - $ref: '#/components/schemas/BetaEmptyModelParam' + - type: 'null' + strict: + anyOf: + - type: boolean + description: Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string enum: - - response.image_generation_call.in_progress - description: The type of the event. Always 'response.image_generation_call.in_progress'. + - function + default: function x-stainless-const: true - output_index: - type: integer - description: The index of the output item in the response's output array. - item_id: - type: string - description: The unique identifier of the image generation item being processed. - sequence_number: - type: integer - description: The sequence number of the image generation item being processed. + async: + type: boolean + description: Whether the tool response can be returned asynchronously versus immediately returned on next response creation. + output_schema: + anyOf: + - additionalProperties: {} + type: object + description: A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + x-oaiTypeLabel: map + - type: 'null' + defer_loading: + type: boolean + description: Whether this function should be deferred and discovered via tool search. + allowed_callers: + anyOf: + - items: + $ref: '#/components/schemas/BetaCallableToolAllowedCaller' + type: array + minItems: 1 + description: The tool invocation context(s). + - type: 'null' + type: object required: + - name - type - - output_index - - item_id - - sequence_number - x-oaiMeta: - name: response.image_generation_call.in_progress - group: responses - example: | - { - "type": "response.image_generation_call.in_progress", - "output_index": 0, - "item_id": "item-123", - "sequence_number": 0 - } - BetaResponseImageGenCallGeneratingEvent: - type: object - title: ResponseImageGenCallGeneratingEvent - description: | - Emitted when an image generation tool call is actively generating an image (intermediate state). + BetaFunctionShellToolParam: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string enum: - - response.image_generation_call.generating - description: The type of the event. Always 'response.image_generation_call.generating'. + - shell + description: The type of the shell tool. Always `shell`. + default: shell x-stainless-const: true - output_index: - type: integer - description: The index of the output item in the response's output array. - item_id: - type: string - description: The unique identifier of the image generation item being processed. - sequence_number: - type: integer - description: The sequence number of the image generation item being processed. + environment: + anyOf: + - discriminator: + propertyName: type + anyOf: + - $ref: '#/components/schemas/BetaContainerAutoParam' + - $ref: '#/components/schemas/BetaLocalEnvironmentParam' + - $ref: '#/components/schemas/BetaContainerReferenceParam' + - type: 'null' + allowed_callers: + anyOf: + - items: + $ref: '#/components/schemas/BetaCallableToolAllowedCaller' + type: array + minItems: 1 + description: The tool invocation context(s). + - type: 'null' + type: object required: - type - - output_index - - item_id - - sequence_number - x-oaiMeta: - name: response.image_generation_call.generating - group: responses - example: | - { - "type": "response.image_generation_call.generating", - "output_index": 0, - "item_id": "item-123", - "sequence_number": 0 - } - BetaResponseImageGenCallCompletedEvent: - type: object - title: ResponseImageGenCallCompletedEvent - description: | - Emitted when an image generation tool call has completed and the final image is available. + title: Shell tool + description: A tool that allows the model to execute shell commands. + BetaContainerReferenceParam: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string enum: - - response.image_generation_call.completed - description: The type of the event. Always 'response.image_generation_call.completed'. + - container_reference + description: References a container created with the /v1/containers endpoint + default: container_reference x-stainless-const: true - output_index: - type: integer - description: The index of the output item in the response's output array. - sequence_number: - type: integer - description: The sequence number of this event. - item_id: + container_id: type: string - description: The unique identifier of the image generation item being processed. + description: The ID of the referenced container. + example: cntr_123 + type: object required: - type - - output_index - - item_id - - sequence_number - x-oaiMeta: - name: response.image_generation_call.completed - group: responses - example: | - { - "type": "response.image_generation_call.completed", - "output_index": 0, - "item_id": "item-123", - "sequence_number": 1 - } - BetaResponseReasoningTextDoneEvent: - type: object - description: Emitted when a reasoning text is completed. + - container_id + BetaLocalEnvironmentParam: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string - description: | - The type of the event. Always `response.reasoning_text.done`. enum: - - response.reasoning_text.done + - local + description: Use a local computer environment. + default: local x-stainless-const: true - item_id: - type: string - description: | - The ID of the item this reasoning text is associated with. - output_index: - type: integer - description: | - The index of the output item this reasoning text is associated with. - content_index: - type: integer - description: | - The index of the reasoning content part. - text: - type: string - description: | - The full text of the completed reasoning content. - sequence_number: - type: integer - description: | - The sequence number of this event. + skills: + items: + $ref: '#/components/schemas/BetaLocalSkillParam' + type: array + maxItems: 200 + description: An optional list of skills. + type: object required: - type - - item_id - - output_index - - content_index - - text - - sequence_number - x-oaiMeta: - name: response.reasoning_text.done - group: responses - example: | - { - "type": "response.reasoning_text.done", - "item_id": "rs_123", - "output_index": 0, - "content_index": 0, - "text": "The user is asking...", - "sequence_number": 4 - } - BetaResponseReasoningTextDeltaEvent: + BetaLocalSkillParam: + properties: + name: + type: string + description: The name of the skill. + description: + type: string + description: The description of the skill. + path: + type: string + description: The path to the directory containing the skill. type: object - description: Emitted when a delta is added to a reasoning text. + required: + - name + - description + - path + BetaContainerAutoParam: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string - description: | - The type of the event. Always `response.reasoning_text.delta`. enum: - - response.reasoning_text.delta + - container_auto + description: Automatically creates a container for this request + default: container_auto x-stainless-const: true - item_id: - type: string - description: | - The ID of the item this reasoning text delta is associated with. - output_index: - type: integer - description: | - The index of the output item this reasoning text delta is associated with. - content_index: - type: integer - description: | - The index of the reasoning content part this delta is associated with. - delta: - type: string - description: | - The text delta that was added to the reasoning content. - sequence_number: - type: integer - description: | - The sequence number of this event. + file_ids: + items: + type: string + example: file-123 + type: array + maxItems: 50 + description: An optional list of uploaded files to make available to your code. + memory_limit: + anyOf: + - $ref: '#/components/schemas/BetaContainerMemoryLimit' + description: The memory limit for the container. + - type: 'null' + network_policy: + discriminator: + propertyName: type + description: Network access policy for the container. + anyOf: + - $ref: '#/components/schemas/BetaContainerNetworkPolicyDisabledParam' + - $ref: '#/components/schemas/BetaContainerNetworkPolicyAllowlistParam' + skills: + items: + discriminator: + propertyName: type + anyOf: + - $ref: '#/components/schemas/BetaSkillReferenceParam' + - $ref: '#/components/schemas/BetaInlineSkillParam' + type: array + maxItems: 200 + description: An optional list of skills referenced by id or inline data. + type: object required: - type - - item_id - - output_index - - content_index - - delta - - sequence_number - x-oaiMeta: - name: response.reasoning_text.delta - group: responses - example: | - { - "type": "response.reasoning_text.delta", - "item_id": "rs_123", - "output_index": 0, - "content_index": 0, - "delta": "The", - "sequence_number": 1 - } - BetaResponseReasoningSummaryTextDoneEvent: - type: object - description: Emitted when a reasoning summary text is completed. + BetaInlineSkillParam: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string - description: | - The type of the event. Always `response.reasoning_summary_text.done`. enum: - - response.reasoning_summary_text.done + - inline + description: Defines an inline skill for this request. + default: inline x-stainless-const: true - item_id: + name: type: string - description: | - The ID of the item this summary text is associated with. - output_index: - type: integer - description: | - The index of the output item this summary text is associated with. - summary_index: - type: integer - description: | - The index of the summary part within the reasoning summary. - text: + description: The name of the skill. + description: type: string - description: | - The full text of the completed reasoning summary. - sequence_number: - type: integer - description: | - The sequence number of this event. + description: The description of the skill. + source: + $ref: '#/components/schemas/BetaInlineSkillSourceParam' + description: Inline skill payload + type: object required: - type - - item_id - - output_index - - summary_index - - text - - sequence_number - x-oaiMeta: - name: response.reasoning_summary_text.done - group: responses - example: | - { - "type": "response.reasoning_summary_text.done", - "item_id": "rs_6806bfca0b2481918a5748308061a2600d3ce51bdffd5476", - "output_index": 0, - "summary_index": 0, - "text": "**Responding to a greeting**\n\nThe user just said, \"Hello!\" So, it seems I need to engage. I'll greet them back and offer help since they're looking to chat. I could say something like, \"Hello! How can I assist you today?\" That feels friendly and open. They didn't ask a specific question, so this approach will work well for starting a conversation. Let's see where it goes from there!", - "sequence_number": 1 - } - BetaResponseReasoningSummaryTextDeltaEvent: - type: object - description: Emitted when a delta is added to a reasoning summary text. + - name + - description + - source + BetaInlineSkillSourceParam: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string - description: | - The type of the event. Always `response.reasoning_summary_text.delta`. enum: - - response.reasoning_summary_text.delta + - base64 + description: The type of the inline skill source. Must be `base64`. + default: base64 x-stainless-const: true - item_id: + media_type: type: string - description: | - The ID of the item this summary text delta is associated with. - output_index: - type: integer - description: | - The index of the output item this summary text delta is associated with. - summary_index: - type: integer - description: | - The index of the summary part within the reasoning summary. - delta: + enum: + - application/zip + description: The media type of the inline skill payload. Must be `application/zip`. + default: application/zip + x-stainless-const: true + data: type: string - description: | - The text delta that was added to the summary. - sequence_number: - type: integer - description: | - The sequence number of this event. + maxLength: 70254592 + minLength: 1 + description: Base64-encoded skill zip bundle. + type: object required: - type - - item_id - - output_index - - summary_index - - delta - - sequence_number - x-oaiMeta: - name: response.reasoning_summary_text.delta - group: responses - example: | - { - "type": "response.reasoning_summary_text.delta", - "item_id": "rs_6806bfca0b2481918a5748308061a2600d3ce51bdffd5476", - "output_index": 0, - "summary_index": 0, - "delta": "**Responding to a greeting**\n\nThe user just said, \"Hello!\" So, it seems I need to engage. I'll greet them back and offer help since they're looking to chat. I could say something like, \"Hello! How can I assist you today?\" That feels friendly and open. They didn't ask a specific question, so this approach will work well for starting a conversation. Let's see where it goes from there!", - "sequence_number": 1 - } - BetaResponseReasoningSummaryPartDoneEvent: - type: object - description: Emitted when a reasoning summary part is completed. + - media_type + - data + description: Inline skill payload + BetaSkillReferenceParam: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string - description: | - The type of the event. Always `response.reasoning_summary_part.done`. enum: - - response.reasoning_summary_part.done + - skill_reference + description: References a skill created with the /v1/skills endpoint. + default: skill_reference x-stainless-const: true - item_id: + skill_id: type: string - description: | - The ID of the item this summary part is associated with. - output_index: - type: integer - description: | - The index of the output item this summary part is associated with. - summary_index: - type: integer - description: | - The index of the summary part within the reasoning summary. - status: + maxLength: 64 + minLength: 1 + description: The ID of the referenced skill. + version: type: string - description: | - The completion status of the summary part. Omitted when the part completed - normally and set to `incomplete` when generation was interrupted. - enum: - - incomplete - sequence_number: - type: integer - description: | - The sequence number of this event. - part: - type: object - description: | - The completed summary part. - properties: - type: - type: string - description: The type of the summary part. Always `summary_text`. - enum: - - summary_text - x-stainless-const: true - text: - type: string - description: The text of the summary part. - required: - - type - - text + description: Optional skill version. Use a positive integer or 'latest'. Omit for default. + type: object required: - type - - item_id - - output_index - - summary_index - - part - - sequence_number - x-oaiMeta: - name: response.reasoning_summary_part.done - group: responses - example: | - { - "type": "response.reasoning_summary_part.done", - "item_id": "rs_6806bfca0b2481918a5748308061a2600d3ce51bdffd5476", - "output_index": 0, - "summary_index": 0, - "part": { - "type": "summary_text", - "text": "**Responding to a greeting**\n\nThe user just said, \"Hello!\" So, it seems I need to engage. I'll greet them back and offer help since they're looking to chat. I could say something like, \"Hello! How can I assist you today?\" That feels friendly and open. They didn't ask a specific question, so this approach will work well for starting a conversation. Let's see where it goes from there!" - }, - "sequence_number": 1 - } - BetaResponseReasoningSummaryPartAddedEvent: - type: object - description: Emitted when a new reasoning summary part is added. + - skill_id + BetaContainerNetworkPolicyAllowlistParam: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string - description: | - The type of the event. Always `response.reasoning_summary_part.added`. enum: - - response.reasoning_summary_part.added + - allowlist + description: Allow outbound network access only to specified domains. Always `allowlist`. + default: allowlist x-stainless-const: true - item_id: - type: string - description: | - The ID of the item this summary part is associated with. - output_index: - type: integer - description: | - The index of the output item this summary part is associated with. - summary_index: - type: integer - description: | - The index of the summary part within the reasoning summary. - sequence_number: - type: integer - description: | - The sequence number of this event. - part: - type: object - description: | - The summary part that was added. - properties: - type: - type: string - description: The type of the summary part. Always `summary_text`. - enum: - - summary_text - x-stainless-const: true - text: - type: string - description: The text of the summary part. - required: - - type - - text + allowed_domains: + items: + type: string + type: array + minItems: 1 + description: A list of allowed domains when type is `allowlist`. + domain_secrets: + items: + $ref: '#/components/schemas/BetaContainerNetworkPolicyDomainSecretParam' + type: array + minItems: 1 + description: Optional domain-scoped secrets for allowlisted domains. + type: object required: - type - - item_id - - output_index - - summary_index - - part - - sequence_number - x-oaiMeta: - name: response.reasoning_summary_part.added - group: responses - example: | - { - "type": "response.reasoning_summary_part.added", - "item_id": "rs_6806bfca0b2481918a5748308061a2600d3ce51bdffd5476", - "output_index": 0, - "summary_index": 0, - "part": { - "type": "summary_text", - "text": "" - }, - "sequence_number": 1 - } - BetaResponseTextDoneEvent: - type: object - description: Emitted when text content is finalized. + - allowed_domains + BetaContainerNetworkPolicyDomainSecretParam: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. - type: + domain: type: string - description: | - The type of the event. Always `response.output_text.done`. - enum: - - response.output_text.done - x-stainless-const: true - item_id: + minLength: 1 + description: The domain associated with the secret. + name: type: string - description: | - The ID of the output item that the text content is finalized. - output_index: - type: integer - description: | - The index of the output item that the text content is finalized. - content_index: - type: integer - description: | - The index of the content part that the text content is finalized. - text: + minLength: 1 + description: The name of the secret to inject for the domain. + value: type: string - description: | - The text content that is finalized. - sequence_number: - type: integer - description: The sequence number for this event. - logprobs: - type: array - description: | - The log probabilities of the tokens in the delta. - items: - $ref: '#/components/schemas/BetaResponseLogProb' - required: - - type - - item_id - - output_index - - content_index - - text - - sequence_number - - logprobs - x-oaiMeta: - name: response.output_text.done - group: responses - example: | - { - "type": "response.output_text.done", - "item_id": "msg_123", - "output_index": 0, - "content_index": 0, - "text": "In a shimmering forest under a sky full of stars, a lonely unicorn named Lila discovered a hidden pond that glowed with moonlight. Every night, she would leave sparkling, magical flowers by the water's edge, hoping to share her beauty with others. One enchanting evening, she woke to find a group of friendly animals gathered around, eager to be friends and share in her magic.", - "sequence_number": 1 - } - BetaResponseLogProb: + maxLength: 10485760 + minLength: 1 + description: The secret value to inject for the domain. type: object - description: "A logprob is the logarithmic probability that the model assigns to producing \na particular token at a given position in the sequence. Less-negative (higher) \nlogprob values indicate greater model confidence in that token choice.\n" + required: + - domain + - name + - value + BetaContainerNetworkPolicyDisabledParam: properties: - token: - description: A possible text token. + type: type: string - logprob: - description: | - The log probability of this token. - type: number - top_logprobs: - description: | - The log probabilities of up to 20 of the most likely tokens. - type: array - items: - type: object - properties: - token: - description: A possible text token. - type: string - logprob: - description: The log probability of this token. - type: number - required: - - token - - logprob - BetaResponseTextDeltaEvent: + enum: + - disabled + description: Disable outbound network access. Always `disabled`. + default: disabled + x-stainless-const: true type: object - description: Emitted when there is an additional text delta. + required: + - type + BetaContainerMemoryLimit: + type: string + enum: + - 1g + - 4g + - 16g + - 64g + BetaLocalShellToolParam: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string - description: | - The type of the event. Always `response.output_text.delta`. enum: - - response.output_text.delta + - local_shell + description: The type of the local shell tool. Always `local_shell`. + default: local_shell x-stainless-const: true - item_id: - type: string - description: | - The ID of the output item that the text delta was added to. - output_index: - type: integer - description: | - The index of the output item that the text delta was added to. - content_index: - type: integer - description: | - The index of the content part that the text delta was added to. - delta: - type: string - description: | - The text delta that was added. - sequence_number: - type: integer - description: The sequence number for this event. - logprobs: - type: array - description: | - The log probabilities of the tokens in the delta. - items: - $ref: '#/components/schemas/BetaResponseLogProb' + type: object required: - type - - item_id - - output_index - - content_index - - delta - - sequence_number - - logprobs - x-oaiMeta: - name: response.output_text.delta - group: responses - example: | - { - "type": "response.output_text.delta", - "item_id": "msg_123", - "output_index": 0, - "content_index": 0, - "delta": "In", - "sequence_number": 1 - } - BetaResponseRefusalDoneEvent: + title: Local shell tool + description: A tool that allows the model to execute shell commands in a local environment. + BetaImageGenTool: type: object - description: Emitted when refusal text is finalized. + title: Image generation tool + description: | + A tool that generates images using the GPT image models. properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string - description: | - The type of the event. Always `response.refusal.done`. enum: - - response.refusal.done - x-stainless-const: true - item_id: + - image_generation + description: | + The type of the image generation tool. Always `image_generation`. + x-stainless-const: true + model: + anyOf: + - type: string + - type: string + enum: + - gpt-image-1 + - gpt-image-1-mini + - gpt-image-2 + - gpt-image-2-2026-04-21 + - gpt-image-2.5-sunburst + - gpt-image-2.5-sunburst-2026-09-08 + - gpt-image-2.5-flare + - gpt-image-2.5-flare-2026-09-08 + - gpt-image-1.5 + - chatgpt-image-latest + description: | + The image generation model to use. One of `gpt-image-1`, + `gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`, + `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, + `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, + `gpt-image-2.5-flare-2026-09-08`, or `chatgpt-image-latest`. Default: + `gpt-image-1`. + default: gpt-image-1 + quality: + type: string + enum: + - low + - medium + - high + - xhigh + - max + - auto + description: | + The quality of the generated image. The GPT image models support `low`, + `medium`, and `high`. `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare`, + including their `2026-09-08` snapshots, also support `xhigh` and `max`. + Default: `auto`. + default: auto + size: + anyOf: + - type: string + - type: string + enum: + - 1024x1024 + - 1024x1536 + - 1536x1024 + - auto + description: The size of the generated images. For `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, and `gpt-image-2.5-flare-2026-09-08`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + default: auto + output_format: type: string + enum: + - png + - webp + - jpeg description: | - The ID of the output item that the refusal text is finalized. - output_index: + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. + default: png + output_compression: type: integer + minimum: 0 + maximum: 100 description: | - The index of the output item that the refusal text is finalized. - content_index: - type: integer + Compression level for the output image. Default: 100. + default: 100 + moderation: + type: string + enum: + - auto + - low description: | - The index of the content part that the refusal text is finalized. - refusal: + Moderation level for the generated image. Default: `auto`. + default: auto + background: type: string + enum: + - transparent + - opaque + - auto description: | - The refusal text that is finalized. - sequence_number: + Allows to set transparency for the background of the generated image(s). Must + be one of `transparent`, `opaque`, or `auto` (default value). When `auto` is + used, the model will automatically determine the best background for the + image. + + `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare`, including their + `2026-09-08` snapshots, support `opaque` and `transparent` backgrounds. + Transparent backgrounds are available for supported GPT Image models. For + `gpt-image-2` and `gpt-image-2-2026-04-21`, this support is in preview. When + using `transparent`, set the output format to `png` or `webp`. + default: auto + input_fidelity: + anyOf: + - $ref: '#/components/schemas/BetaInputFidelity' + - type: 'null' + description: Controls fidelity to the original input image(s). This parameter is supported for GPT image models that support input fidelity. `gpt-image-2` and `gpt-image-2-2026-04-21` ignore this parameter. + input_image_mask: + type: object + description: | + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + properties: + image_url: + type: string + description: | + Base64-encoded mask image. + file_id: + type: string + description: | + File ID for the mask image. + required: [] + additionalProperties: false + partial_images: type: integer + minimum: 0 + maximum: 3 description: | - The sequence number of this event. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + default: 0 + action: + description: | + Whether to generate a new image or edit an existing image. Default: `auto`. + $ref: '#/components/schemas/BetaImageGenActionEnum' required: - type - - item_id - - output_index - - content_index - - refusal - - sequence_number - x-oaiMeta: - name: response.refusal.done - group: responses - example: | - { - "type": "response.refusal.done", - "item_id": "item-abc", - "output_index": 1, - "content_index": 2, - "refusal": "final refusal text", - "sequence_number": 1 - } - BetaResponseRefusalDeltaEvent: - type: object - description: Emitted when there is a partial refusal text. + BetaImageGenActionEnum: + type: string + enum: + - generate + - edit + - auto + BetaInputFidelity: + type: string + enum: + - high + - low + description: Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + BetaProgrammaticToolCallingParam: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string - description: | - The type of the event. Always `response.refusal.delta`. enum: - - response.refusal.delta + - programmatic_tool_calling + description: The type of the tool. Always `programmatic_tool_calling`. + default: programmatic_tool_calling x-stainless-const: true - item_id: - type: string - description: | - The ID of the output item that the refusal text is added to. - output_index: - type: integer - description: | - The index of the output item that the refusal text is added to. - content_index: - type: integer - description: | - The index of the content part that the refusal text is added to. - delta: - type: string - description: | - The refusal text that is added. - sequence_number: - type: integer - description: | - The sequence number of this event. + type: object required: - type - - item_id - - output_index - - content_index - - delta - - sequence_number - x-oaiMeta: - name: response.refusal.delta - group: responses - example: | - { - "type": "response.refusal.delta", - "item_id": "msg_123", - "output_index": 0, - "content_index": 0, - "delta": "refusal text so far", - "sequence_number": 1 - } - BetaResponseOutputItemDoneEvent: + BetaCodeInterpreterTool: type: object - description: Emitted when an output item is marked done. + title: Code interpreter + description: | + A tool that runs Python code to help generate a response to a prompt. properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string - description: | - The type of the event. Always `response.output_item.done`. enum: - - response.output_item.done - x-stainless-const: true - output_index: - type: integer - description: | - The index of the output item that was marked done. - sequence_number: - type: integer + - code_interpreter description: | - The sequence number of this event. - item: - $ref: '#/components/schemas/BetaOutputItem' + The type of the code interpreter tool. Always `code_interpreter`. + x-stainless-const: true + container: description: | - The output item that was marked done. + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. + anyOf: + - type: string + description: The container ID. + - $ref: '#/components/schemas/BetaAutoCodeInterpreterToolParam' + allowed_callers: + anyOf: + - type: array + minItems: 1 + items: + $ref: '#/components/schemas/BetaCallableToolAllowedCaller' + description: The tool invocation context(s). + - type: 'null' required: - type - - output_index - - item - - sequence_number - x-oaiMeta: - name: response.output_item.done - group: responses - example: | - { - "type": "response.output_item.done", - "output_index": 0, - "item": { - "id": "msg_123", - "status": "completed", - "type": "message", - "role": "assistant", - "content": [ - { - "type": "output_text", - "text": "In a shimmering forest under a sky full of stars, a lonely unicorn named Lila discovered a hidden pond that glowed with moonlight. Every night, she would leave sparkling, magical flowers by the water's edge, hoping to share her beauty with others. One enchanting evening, she woke to find a group of friendly animals gathered around, eager to be friends and share in her magic.", - "annotations": [] - } - ] - }, - "sequence_number": 1 - } - BetaResponseOutputItemAddedEvent: - type: object - description: Emitted when a new output item is added. + - container + BetaAutoCodeInterpreterToolParam: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string - description: | - The type of the event. Always `response.output_item.added`. enum: - - response.output_item.added + - auto + description: Always `auto`. + default: auto x-stainless-const: true - output_index: - type: integer - description: | - The index of the output item that was added. - sequence_number: - type: integer - description: | - The sequence number of this event. - item: - $ref: '#/components/schemas/BetaOutputItem' - description: | - The output item that was added. For reasoning items, `encrypted_content` - may be incomplete while the item is in progress. Use the reasoning item - from the corresponding `response.output_item.done` event when passing it - as input to a subsequent request. + file_ids: + items: + type: string + example: file-123 + type: array + maxItems: 50 + description: An optional list of uploaded files to make available to your code. + memory_limit: + anyOf: + - $ref: '#/components/schemas/BetaContainerMemoryLimit' + description: The memory limit for the code interpreter container. + - type: 'null' + network_policy: + discriminator: + propertyName: type + description: Network access policy for the container. + anyOf: + - $ref: '#/components/schemas/BetaContainerNetworkPolicyDisabledParam' + - $ref: '#/components/schemas/BetaContainerNetworkPolicyAllowlistParam' + type: object required: - type - - output_index - - item - - sequence_number - x-oaiMeta: - name: response.output_item.added - group: responses - example: | - { - "type": "response.output_item.added", - "output_index": 0, - "item": { - "id": "msg_123", - "status": "in_progress", - "type": "message", - "role": "assistant", - "content": [] - }, - "sequence_number": 1 - } - BetaResponseInProgressEvent: + title: CodeInterpreterToolAuto + description: Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + BetaMCPTool: type: object - description: Emitted when the response is in progress. + title: MCP tool + description: | + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://developers.openai.com/api/docs/guides/tools-connectors-mcp). properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string - description: | - The type of the event. Always `response.in_progress`. enum: - - response.in_progress + - mcp + description: The type of the MCP tool. Always `mcp`. x-stainless-const: true - response: - $ref: '#/components/schemas/BetaResponse' + server_label: + type: string description: | - The response that is in progress. - sequence_number: - type: integer - description: The sequence number of this event. - required: - - type - - response - - sequence_number - x-oaiMeta: - name: response.in_progress - group: responses - example: | - { - "type": "response.in_progress", - "response": { - "id": "resp_67ccfcdd16748190a91872c75d38539e09e4d4aac714747c", - "object": "response", - "created_at": 1741487325, - "status": "in_progress", - "completed_at": null, - "error": null, - "incomplete_details": null, - "instructions": null, - "max_output_tokens": null, - "model": "gpt-6-astra", - "output": [], - "parallel_tool_calls": true, - "previous_response_id": null, - "reasoning": { - "effort": null, - "summary": null - }, - "store": true, - "temperature": 1, - "text": { - "format": { - "type": "text" - } - }, - "tool_choice": "auto", - "tools": [], - "top_p": 1, - "truncation": "disabled", - "usage": null, - "user": null, - "metadata": {} - }, - "sequence_number": 1 - } - BetaResponseShellCallOutputContentDoneStreamingEvent: + A label for this MCP server, used to identify it in tool calls. + server_url: + type: string + format: uri + description: | + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. + connector_id: + type: string + deprecated: true + enum: + - connector_dropbox + - connector_gmail + - connector_googlecalendar + - connector_googledrive + - connector_microsoftteams + - connector_outlookcalendar + - connector_outlookemail + - connector_sharepoint + description: | + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://developers.openai.com/api/docs/guides/tools-connectors-mcp#connectors). + + This field is deprecated for models released after September 1, 2026. + Use `server_url` to connect to a remote MCP server, or `tunnel_id` to + connect through a Secure MCP Tunnel. + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + tunnel_id: + type: string + pattern: ^tunnel_[a-z0-9]{32}$ + description: | + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. + authorization: + type: string + description: | + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. + server_description: + type: string + description: | + Optional description of the MCP server, used to provide more context. + headers: + anyOf: + - type: object + additionalProperties: + type: string + description: | + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. + - type: 'null' + allowed_tools: + anyOf: + - description: | + List of allowed tool names or a filter object. + anyOf: + - type: array + title: MCP allowed tools + description: A string array of allowed tool names + items: + type: string + - $ref: '#/components/schemas/BetaMCPToolFilter' + - type: 'null' + allowed_callers: + anyOf: + - type: array + minItems: 1 + items: + $ref: '#/components/schemas/BetaCallableToolAllowedCaller' + description: The tool invocation context(s). + - type: 'null' + require_approval: + anyOf: + - description: Specify which of the MCP server's tools require approval. + default: always + anyOf: + - type: object + title: MCP tool approval filter + description: | + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. + properties: + always: + $ref: '#/components/schemas/BetaMCPToolFilter' + never: + $ref: '#/components/schemas/BetaMCPToolFilter' + additionalProperties: false + - type: string + title: MCP tool approval setting + description: | + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + enum: + - always + - never + - type: 'null' + defer_loading: + type: boolean + description: | + Whether this MCP tool is deferred and discovered via tool search. + required: + - type + - server_label + BetaMCPToolFilter: + type: object + title: MCP tool filter + description: | + A filter object to specify which tools are allowed. properties: - type: - type: string - enum: - - response.shell_call_output_content.done - description: The type of the event, always `response.shell_call_output_content.done`. - default: response.shell_call_output_content.done - x-stainless-const: true - sequence_number: - type: integer - description: The sequence number of the event that was emitted. - agent: - $ref: '#/components/schemas/BetaAgentTag' - description: The agent that owns this multi-agent streaming event. - item_id: - type: string - description: The ID of the output item that was updated. - output_index: - type: integer - description: The index of the output item that was updated. - command_index: - type: integer - description: The index of the shell command that produced output. - output: - items: - $ref: '#/components/schemas/BetaFunctionShellCallOutputContent' + tool_names: type: array - description: The output contents emitted for the shell command. + title: MCP allowed tools + items: + type: string + description: List of allowed tool names. + read_only: + type: boolean + description: | + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + required: [] + additionalProperties: false + BetaWebSearchTool: type: object - required: - - type - - sequence_number - - item_id - - output_index - - command_index - - output - title: Response shell call output content done event - description: A streaming event that indicated shell call output was completed. - BetaResponseShellCallOutputContentDeltaStreamingEvent: + title: Web search + description: | + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://developers.openai.com/api/docs/guides/tools-web-search). properties: type: type: string enum: - - response.shell_call_output_content.delta - description: The type of the event, always `response.shell_call_output_content.delta`. - default: response.shell_call_output_content.delta - x-stainless-const: true - sequence_number: - type: integer - description: The sequence number of the event that was emitted. - agent: - $ref: '#/components/schemas/BetaAgentTag' - description: The agent that owns this multi-agent streaming event. - item_id: + - web_search + - web_search_2025_08_26 + description: The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + default: web_search + external_web_access: + type: boolean + default: true + description: Allow live internet access for web search. Defaults to true when omitted. When false, the web search tool runs in offline/cache-only mode and will not fetch new external content. + filters: + anyOf: + - type: object + description: | + Filters for the search. + properties: + allowed_domains: + anyOf: + - type: array + title: Allowed domains for the search. + description: | + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + items: + type: string + description: Allowed domain for the search. + default: [] + - type: 'null' + - type: 'null' + user_location: + $ref: '#/components/schemas/BetaWebSearchApproximateLocation' + search_context_size: type: string - description: The ID of the output item that was updated. - output_index: - type: integer - description: The index of the output item that was updated. - command_index: - type: integer - description: The index of the shell command that produced output. - delta: - $ref: '#/components/schemas/BetaShellCallOutputDelta' - description: The stdout/stderr delta that was emitted. - type: object + enum: + - low + - medium + - high + default: medium + description: High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. required: - type - - sequence_number - - item_id - - output_index - - command_index - - delta - title: Response shell call output content delta event - description: A streaming event that indicated shell call output was incrementally added. - BetaShellCallOutputDelta: - properties: - stdout: - type: string - description: The stdout delta that was emitted. - stderr: - type: string - description: The stderr delta that was emitted. - type: object - required: [] - title: Shell call output delta - description: A delta of stdout/stderr emitted while a shell call was running. - BetaResponseShellCallCommandDoneStreamingEvent: + BetaWebSearchApproximateLocation: + anyOf: + - type: object + title: Web search approximate location + description: | + The approximate location of the user. + properties: + type: + type: string + enum: + - approximate + description: The type of location approximation. Always `approximate`. + default: approximate + x-stainless-const: true + country: + anyOf: + - type: string + description: The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - type: 'null' + region: + anyOf: + - type: string + description: Free text input for the region of the user, e.g. `California`. + - type: 'null' + city: + anyOf: + - type: string + description: Free text input for the city of the user, e.g. `San Francisco`. + - type: 'null' + timezone: + anyOf: + - type: string + description: The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - type: 'null' + - type: 'null' + BetaComputerUsePreviewTool: properties: type: type: string enum: - - response.shell_call_command.done - description: The type of the event, always `response.shell_call_command.done`. - default: response.shell_call_command.done + - computer_use_preview + description: The type of the computer use tool. Always `computer_use_preview`. + default: computer_use_preview x-stainless-const: true - sequence_number: - type: integer - description: The sequence number of the event that was emitted. - agent: - $ref: '#/components/schemas/BetaAgentTag' - description: The agent that owns this multi-agent streaming event. - output_index: + environment: + $ref: '#/components/schemas/BetaComputerEnvironment' + description: The type of computer environment to control. + display_width: type: integer - description: The index of the output item that was updated. - command_index: + description: The width of the computer display. + display_height: type: integer - description: The index of the shell command that was completed. - command: - type: string - description: The final shell command that was emitted. + description: The height of the computer display. type: object required: - type - - sequence_number - - output_index - - command_index - - command - title: Response shell command done event - description: A streaming event that indicated a shell command was completed. - BetaResponseShellCallCommandDeltaStreamingEvent: + - environment + - display_width + - display_height + title: Computer use preview + description: A tool that controls a virtual computer. Learn more about the [computer tool](https://developers.openai.com/api/docs/guides/tools-computer-use). + BetaComputerEnvironment: + type: string + enum: + - windows + - mac + - linux + - ubuntu + - browser + BetaComputerTool: properties: type: type: string enum: - - response.shell_call_command.delta - description: The type of the event, always `response.shell_call_command.delta`. - default: response.shell_call_command.delta + - computer + description: The type of the computer tool. Always `computer`. + default: computer x-stainless-const: true - sequence_number: - type: integer - description: The sequence number of the event that was emitted. - agent: - $ref: '#/components/schemas/BetaAgentTag' - description: The agent that owns this multi-agent streaming event. - output_index: - type: integer - description: The index of the output item that was updated. - command_index: - type: integer - description: The index of the shell command that was updated. - delta: - type: string - description: The shell command delta that was appended. - obfuscation: - type: string - description: An obfuscation string that was added to pad the event payload. type: object required: - type - - sequence_number - - output_index - - command_index - - delta - title: Response shell command delta event - description: A streaming event that indicated a shell command was incrementally updated. - BetaResponseShellCallCommandAddedStreamingEvent: + title: Computer + description: A tool that controls a virtual computer. Learn more about the [computer tool](https://developers.openai.com/api/docs/guides/tools-computer-use). + BetaFileSearchTool: properties: type: type: string enum: - - response.shell_call_command.added - description: The type of the event, always `response.shell_call_command.added`. - default: response.shell_call_command.added + - file_search + description: The type of the file search tool. Always `file_search`. + default: file_search x-stainless-const: true - sequence_number: - type: integer - description: The sequence number of the event that was emitted. - agent: - $ref: '#/components/schemas/BetaAgentTag' - description: The agent that owns this multi-agent streaming event. - output_index: - type: integer - description: The index of the output item that was updated. - command_index: + vector_store_ids: + items: + type: string + type: array + description: The IDs of the vector stores to search. + max_num_results: type: integer - description: The index of the shell command that was added. - command: - type: string - description: The shell command that was added. + description: The maximum number of results to return. This number should be between 1 and 50 inclusive. + ranking_options: + $ref: '#/components/schemas/BetaRankingOptions' + description: Ranking options for search. + filters: + anyOf: + - $ref: '#/components/schemas/BetaFilters' + description: A filter to apply. + - type: 'null' type: object required: - type - - sequence_number - - output_index - - command_index - - command - title: Response shell command added event - description: A streaming event that indicated a shell command was added to a tool call. - BetaResponseFunctionCallArgumentsDoneEvent: + - vector_store_ids + title: File search + description: A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://developers.openai.com/api/docs/guides/tools-file-search). + BetaFilters: + anyOf: + - $ref: '#/components/schemas/BetaComparisonFilter' + - $ref: '#/components/schemas/BetaCompoundFilter' + BetaCompoundFilter: + $recursiveAnchor: true type: object - description: Emitted when function-call arguments are finalized. + additionalProperties: false + title: Compound Filter + description: Combine multiple filters using `and` or `or`. properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string + description: 'Type of operation: `and` or `or`.' enum: - - response.function_call_arguments.done - x-stainless-const: true - item_id: - type: string - description: The ID of the item. - output_index: - type: integer - description: The index of the output item. - sequence_number: - type: integer - description: The sequence number of this event. - arguments: - type: string - description: The function-call arguments. + - and + - or + filters: + type: array + description: Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + items: + discriminator: + propertyName: type + anyOf: + - $ref: '#/components/schemas/BetaComparisonFilter' + - $recursiveRef: '#' required: - type - - item_id - - output_index - - arguments - - sequence_number + - filters x-oaiMeta: - name: response.function_call_arguments.done - group: responses - example: | - { - "type": "response.function_call_arguments.done", - "item_id": "item-abc", - "output_index": 1, - "arguments": "{ \"arg\": 123 }", - "sequence_number": 1 - } - BetaResponseFunctionCallArgumentsDeltaEvent: + name: CompoundFilter + BetaComparisonFilter: type: object - description: Emitted when there is a partial function-call arguments delta. + additionalProperties: false + title: Comparison Filter + description: | + A filter used to compare a specified attribute key to a given value using a defined comparison operation. properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string - description: | - The type of the event. Always `response.function_call_arguments.delta`. + default: eq enum: - - response.function_call_arguments.delta - x-stainless-const: true - item_id: - type: string - description: | - The ID of the output item that the function-call arguments delta is added to. - output_index: - type: integer + - eq + - ne + - gt + - gte + - lt + - lte + - in + - nin description: | - The index of the output item that the function-call arguments delta is added to. - sequence_number: - type: integer - description: The sequence number of this event. - delta: + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in + key: type: string - description: | - The function-call arguments delta that is added. + description: The key to compare against the value. + value: + description: The value to compare against the attribute key; supports string, number, or boolean types. + anyOf: + - type: string + - type: number + - type: boolean + - type: array + items: + $ref: '#/components/schemas/ComparisonFilterValueItems' required: - type - - item_id - - output_index - - delta - - sequence_number + - key + - value x-oaiMeta: - name: response.function_call_arguments.delta - group: responses - example: | - { - "type": "response.function_call_arguments.delta", - "item_id": "item-abc", - "output_index": 0, - "delta": "{ \"arg\":" - "sequence_number": 1 - } - BetaResponseFileSearchCallSearchingEvent: + name: ComparisonFilter + BetaRankingOptions: + properties: + ranker: + $ref: '#/components/schemas/BetaRankerVersionType' + description: The ranker to use for the file search. + score_threshold: + type: number + description: The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + hybrid_search: + $ref: '#/components/schemas/BetaHybridSearchOptions' + description: Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. type: object - description: Emitted when a file search is currently searching. + required: [] + BetaHybridSearchOptions: properties: - agent: + embedding_weight: + type: number + description: The weight of the embedding in the reciprocal ranking fusion. + text_weight: + type: number + description: The weight of the text in the reciprocal ranking fusion. + type: object + required: + - embedding_weight + - text_weight + BetaRankerVersionType: + type: string + enum: + - auto + - default-2024-11-15 + BetaFunctionTool: + properties: + type: + type: string + enum: + - function + description: The type of the function tool. Always `function`. + default: function + x-stainless-const: true + name: + type: string + description: The name of the function to call. + async: + type: boolean + description: + anyOf: + - type: string + description: A description of the function. Used by the model to determine whether or not to call the function. + - type: 'null' + parameters: + anyOf: + - additionalProperties: {} + type: object + description: A JSON schema object describing the parameters of the function. + x-oaiTypeLabel: map + - type: 'null' + output_schema: + anyOf: + - additionalProperties: {} + type: object + description: A JSON schema object describing the JSON value encoded in string outputs for this function. + x-oaiTypeLabel: map + - type: 'null' + strict: + anyOf: + - type: boolean + description: Whether strict parameter validation is enforced for this function tool. + - type: 'null' + defer_loading: + type: boolean + description: Whether this function is deferred and loaded via tool search. + allowed_callers: anyOf: - - $ref: '#/components/schemas/BetaAgentTag' + - items: + $ref: '#/components/schemas/BetaCallableToolAllowedCaller' + type: array + description: The tool invocation context(s). - type: 'null' - description: The agent that owns this multi-agent streaming event. - type: - type: string - description: | - The type of the event. Always `response.file_search_call.searching`. - enum: - - response.file_search_call.searching - x-stainless-const: true - output_index: - type: integer - description: | - The index of the output item that the file search call is searching. - item_id: - type: string - description: | - The ID of the output item that the file search call is initiated. - sequence_number: - type: integer - description: The sequence number of this event. + type: object required: - type - - output_index - - item_id - - sequence_number - x-oaiMeta: - name: response.file_search_call.searching - group: responses - example: | - { - "type": "response.file_search_call.searching", - "output_index": 0, - "item_id": "fs_123", - "sequence_number": 1 - } - BetaResponseFileSearchCallInProgressEvent: - type: object - description: Emitted when a file search call is initiated. + - name + - strict + - parameters + title: Function + description: Defines a function in your own code the model can choose to call. Learn more about [function calling](https://developers.openai.com/api/docs/guides/function-calling). + BetaInputItem: + discriminator: + propertyName: type + anyOf: + - $ref: '#/components/schemas/BetaEasyInputMessage' + - type: object + title: Item + description: | + An item representing part of the context for the response to be + generated by the model. Can contain text, images, and audio inputs, + as well as previous assistant responses and tool call outputs. + $ref: '#/components/schemas/BetaItem' + - $ref: '#/components/schemas/BetaCompactionTriggerItemParam' + - $ref: '#/components/schemas/BetaItemReferenceParam' + - $ref: '#/components/schemas/BetaProgramItemParam' + - $ref: '#/components/schemas/BetaProgramOutputItemParam' + BetaProgramOutputItemParam: properties: agent: anyOf: - - $ref: '#/components/schemas/BetaAgentTag' + - $ref: '#/components/schemas/Beta_AgentTagParam' + description: The agent that produced this item. - type: 'null' - description: The agent that owns this multi-agent streaming event. + id: + type: string + description: The unique ID of this program output item. + example: cmo_123 type: type: string - description: | - The type of the event. Always `response.file_search_call.in_progress`. enum: - - response.file_search_call.in_progress + - program_output + description: The item type. Always `program_output`. + default: program_output x-stainless-const: true - output_index: - type: integer - description: | - The index of the output item that the file search call is initiated. - item_id: + call_id: type: string - description: | - The ID of the output item that the file search call is initiated. - sequence_number: - type: integer - description: The sequence number of this event. + maxLength: 64 + minLength: 1 + description: The call ID of the program item. + result: + type: string + maxLength: 10485760 + description: The result produced by the program item. + status: + $ref: '#/components/schemas/BetaProgramOutputItemStatus' + description: The terminal status of the program output. + type: object required: + - id - type - - output_index - - item_id - - sequence_number - x-oaiMeta: - name: response.file_search_call.in_progress - group: responses - example: | - { - "type": "response.file_search_call.in_progress", - "output_index": 0, - "item_id": "fs_123", - "sequence_number": 1 - } - BetaResponseFileSearchCallCompletedEvent: + - call_id + - result + - status + BetaProgramOutputItemStatus: + type: string + enum: + - completed + - incomplete + Beta_AgentTagParam: + properties: + agent_name: + type: string + description: The canonical name of the agent that produced this item. type: object - description: Emitted when a file search call is completed (results found). + required: + - agent_name + description: The agent that produced this item. + x-oai-beta: responses_multi_agent=v1 + BetaProgramItemParam: properties: agent: anyOf: - - $ref: '#/components/schemas/BetaAgentTag' + - $ref: '#/components/schemas/Beta_AgentTagParam' + description: The agent that produced this item. - type: 'null' - description: The agent that owns this multi-agent streaming event. + id: + type: string + description: The unique ID of this program item. + example: cm_123 type: type: string - description: | - The type of the event. Always `response.file_search_call.completed`. enum: - - response.file_search_call.completed + - program + description: The item type. Always `program`. + default: program x-stainless-const: true - output_index: - type: integer - description: | - The index of the output item that the file search call is initiated. - item_id: + call_id: type: string - description: | - The ID of the output item that the file search call is initiated. - sequence_number: - type: integer - description: The sequence number of this event. + maxLength: 64 + minLength: 1 + description: The stable call ID of the program item. + code: + type: string + maxLength: 10485760 + description: The JavaScript source executed by programmatic tool calling. + fingerprint: + type: string + maxLength: 10485760 + description: Opaque program replay fingerprint that must be round-tripped. + type: object required: + - id - type - - output_index - - item_id - - sequence_number - x-oaiMeta: - name: response.file_search_call.completed - group: responses - example: | - { - "type": "response.file_search_call.completed", - "output_index": 0, - "item_id": "fs_123", - "sequence_number": 1 - } - BetaResponseErrorEvent: - type: object - description: Emitted when an error occurs. + - call_id + - code + - fingerprint + BetaItemReferenceParam: properties: agent: anyOf: - - $ref: '#/components/schemas/BetaAgentTag' + - $ref: '#/components/schemas/Beta_AgentTagParam' + description: The agent that produced this item. - type: 'null' - description: The agent that owns this multi-agent streaming event. type: - type: string - description: | - The type of the event. Always `error`. - enum: - - error - x-stainless-const: true - code: anyOf: - type: string - description: | - The error code. + enum: + - item_reference + description: The type of item to reference. Always `item_reference`. + default: item_reference + x-stainless-const: true - type: 'null' - message: + id: type: string - description: | - The error message. - param: - anyOf: - - type: string - description: | - The error parameter. - - type: 'null' - sequence_number: - type: integer - description: The sequence number of this event. - required: - - type - - code - - message - - param - - sequence_number - x-oaiMeta: - name: error - group: responses - example: | - { - "type": "error", - "code": "ERR_SOMETHING", - "message": "Something went wrong", - "param": null, - "sequence_number": 1 - } - BetaResponseCreatedEvent: + description: The ID of the item to reference. type: object - description: | - An event that is emitted when a response is created. + required: + - id + title: Item reference + description: An internal identifier for an item to reference. + BetaCompactionTriggerItemParam: properties: agent: anyOf: - - $ref: '#/components/schemas/BetaAgentTag' + - $ref: '#/components/schemas/Beta_AgentTagParam' + description: The agent that produced this item. - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string - description: | - The type of the event. Always `response.created`. enum: - - response.created + - compaction_trigger + description: The type of the item. Always `compaction_trigger`. + default: compaction_trigger x-stainless-const: true - response: - $ref: '#/components/schemas/BetaResponse' - description: | - The response that was created. - sequence_number: - type: integer - description: The sequence number for this event. + type: object required: - type - - response - - sequence_number - x-oaiMeta: - name: response.created - group: responses - example: | - { - "type": "response.created", - "response": { - "id": "resp_67ccfcdd16748190a91872c75d38539e09e4d4aac714747c", - "object": "response", - "created_at": 1741487325, - "status": "in_progress", - "completed_at": null, - "error": null, - "incomplete_details": null, - "instructions": null, - "max_output_tokens": null, - "model": "gpt-6-astra", - "output": [], - "parallel_tool_calls": true, - "previous_response_id": null, - "reasoning": { - "effort": null, - "summary": null - }, - "store": true, - "temperature": 1, - "text": { - "format": { - "type": "text" - } - }, - "tool_choice": "auto", - "tools": [], - "top_p": 1, - "truncation": "disabled", - "usage": null, - "user": null, - "metadata": {} - }, - "sequence_number": 1 - } - BetaResponseContentPartDoneEvent: + title: Compaction trigger + description: Compacts the current context. Must be the final input item. + BetaItem: type: object - description: Emitted when a content part is done. + description: | + Content item used to generate a response. + discriminator: + propertyName: type + anyOf: + - $ref: '#/components/schemas/BetaInputMessage' + - $ref: '#/components/schemas/BetaOutputMessage' + - $ref: '#/components/schemas/BetaFileSearchToolCall' + - $ref: '#/components/schemas/BetaComputerToolCall' + - $ref: '#/components/schemas/BetaComputerCallOutputItemParam' + - $ref: '#/components/schemas/BetaWebSearchToolCall' + - $ref: '#/components/schemas/BetaFunctionToolCall' + - $ref: '#/components/schemas/BetaFunctionCallOutputItemParam' + - $ref: '#/components/schemas/BetaAgentMessageItemParam' + - $ref: '#/components/schemas/BetaMultiAgentCallItemParam' + - $ref: '#/components/schemas/BetaMultiAgentCallOutputItemParam' + - $ref: '#/components/schemas/BetaToolSearchCallItemParam' + - $ref: '#/components/schemas/BetaToolSearchOutputItemParam' + - $ref: '#/components/schemas/BetaAdditionalToolsItemParam' + - $ref: '#/components/schemas/BetaResponseConfigurationUpdateItemParam' + - $ref: '#/components/schemas/BetaReasoningItem' + - $ref: '#/components/schemas/BetaCompactionSummaryItemParam' + - $ref: '#/components/schemas/BetaImageGenToolCall' + - $ref: '#/components/schemas/BetaCodeInterpreterToolCall' + - $ref: '#/components/schemas/BetaLocalShellToolCall' + - $ref: '#/components/schemas/BetaLocalShellToolCallOutput' + - $ref: '#/components/schemas/BetaFunctionShellCallItemParam' + - $ref: '#/components/schemas/BetaFunctionShellCallOutputItemParam' + - $ref: '#/components/schemas/BetaApplyPatchToolCallItemParam' + - $ref: '#/components/schemas/BetaApplyPatchToolCallOutputItemParam' + - $ref: '#/components/schemas/BetaMCPListTools' + - $ref: '#/components/schemas/BetaMCPApprovalRequest' + - $ref: '#/components/schemas/BetaMCPApprovalResponse' + - $ref: '#/components/schemas/BetaMCPToolCall' + - $ref: '#/components/schemas/BetaCustomToolCallOutput' + - $ref: '#/components/schemas/BetaCustomToolCall' + BetaCustomToolCall: + type: object + title: Custom tool call + description: | + A call to a custom tool created by the model. properties: agent: anyOf: - $ref: '#/components/schemas/BetaAgentTag' - type: 'null' - description: The agent that owns this multi-agent streaming event. + description: The agent that produced this item. type: type: string - description: | - The type of the event. Always `response.content_part.done`. enum: - - response.content_part.done + - custom_tool_call x-stainless-const: true - item_id: + description: | + The type of the custom tool call. Always `custom_tool_call`. + id: type: string description: | - The ID of the output item that the content part was added to. - output_index: - type: integer + The unique ID of the custom tool call in the OpenAI platform. + call_id: + type: string description: | - The index of the output item that the content part was added to. - content_index: - type: integer + An identifier used to map this custom tool call to a tool call output. + caller: + anyOf: + - $ref: '#/components/schemas/BetaToolCallCaller' + - type: 'null' + namespace: + type: string description: | - The index of the content part that is done. - sequence_number: - type: integer - description: The sequence number of this event. - part: - $ref: '#/components/schemas/BetaOutputContent' + The namespace of the custom tool being called. + name: + type: string description: | - The content part that is done. + The name of the custom tool being called. + input: + type: string + description: | + The input for the custom tool call generated by the model. + async: + type: boolean + description: | + Whether the custom tool call runs asynchronously. required: - type - - item_id - - output_index - - content_index - - part - - sequence_number - x-oaiMeta: - name: response.content_part.done - group: responses - example: | - { - "type": "response.content_part.done", - "item_id": "msg_123", - "output_index": 0, - "content_index": 0, - "sequence_number": 1, - "part": { - "type": "output_text", - "text": "In a shimmering forest under a sky full of stars, a lonely unicorn named Lila discovered a hidden pond that glowed with moonlight. Every night, she would leave sparkling, magical flowers by the water's edge, hoping to share her beauty with others. One enchanting evening, she woke to find a group of friendly animals gathered around, eager to be friends and share in her magic.", - "annotations": [] - } - } - BetaOutputContent: + - call_id + - name + - input + BetaToolCallCaller: discriminator: propertyName: type + description: The execution context that produced this tool call. anyOf: - - $ref: '#/components/schemas/BetaOutputTextContent' - - $ref: '#/components/schemas/BetaRefusalContent' - - $ref: '#/components/schemas/BetaReasoningTextContent' - BetaResponseContentPartAddedEvent: - type: object - description: Emitted when a new content part is added. + - $ref: '#/components/schemas/BetaDirectToolCallCaller' + - $ref: '#/components/schemas/BetaProgramToolCallCaller' + BetaProgramToolCallCaller: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string - description: | - The type of the event. Always `response.content_part.added`. enum: - - response.content_part.added + - program + default: program x-stainless-const: true - item_id: + caller_id: type: string - description: | - The ID of the output item that the content part was added to. - output_index: - type: integer - description: | - The index of the output item that the content part was added to. - content_index: - type: integer - description: | - The index of the content part that was added. - part: - $ref: '#/components/schemas/BetaOutputContent' - description: | - The content part that was added. - sequence_number: - type: integer - description: The sequence number of this event. + description: The call ID of the program item that produced this tool call. + type: object required: - type - - item_id - - output_index - - content_index - - part - - sequence_number - x-oaiMeta: - name: response.content_part.added - group: responses - example: | - { - "type": "response.content_part.added", - "item_id": "msg_123", - "output_index": 0, - "content_index": 0, - "part": { - "type": "output_text", - "text": "", - "annotations": [] - }, - "sequence_number": 1 - } - BetaResponseCompletedEvent: + - caller_id + BetaDirectToolCallCaller: + properties: + type: + type: string + enum: + - direct + default: direct + x-stainless-const: true + type: object + required: + - type + BetaAgentTag: + properties: + agent_name: + type: string + description: The canonical name of the agent that produced this item. + type: object + required: + - agent_name + x-oai-beta: responses_multi_agent=v1 + BetaCustomToolCallOutput: type: object - description: Emitted when the model response is complete. + title: Custom tool call output + description: | + The output of a custom tool call from your code, being sent back to the model. properties: agent: anyOf: - $ref: '#/components/schemas/BetaAgentTag' - type: 'null' - description: The agent that owns this multi-agent streaming event. + description: The agent that produced this item. type: type: string - description: | - The type of the event. Always `response.completed`. enum: - - response.completed + - custom_tool_call_output x-stainless-const: true - response: - $ref: '#/components/schemas/BetaResponse' description: | - Properties of the completed response. - sequence_number: - type: integer - description: The sequence number for this event. + The type of the custom tool call output. Always `custom_tool_call_output`. + id: + type: string + description: | + The unique ID of the custom tool call output in the OpenAI platform. + call_id: + type: string + description: | + The call ID, used to map this custom tool call output to a custom tool call. + caller: + anyOf: + - $ref: '#/components/schemas/BetaToolCallCallerParam' + - type: 'null' + output: + description: | + The output from the custom tool call generated by your code. + Can be a string or an list of output content. + anyOf: + - type: string + description: | + A string of the output of the custom tool call. + title: string output + - type: array + items: + $ref: '#/components/schemas/BetaFunctionAndCustomToolCallOutput' + title: output content list + description: | + Text, image, or file output of the custom tool call. required: - type - - response - - sequence_number - x-oaiMeta: - name: response.completed - group: responses - example: | - { - "type": "response.completed", - "response": { - "id": "resp_123", - "object": "response", - "created_at": 1740855869, - "status": "completed", - "completed_at": 1740855870, - "error": null, - "incomplete_details": null, - "input": [], - "instructions": null, - "max_output_tokens": null, - "model": "gpt-6-astra", - "output": [ - { - "id": "msg_123", - "type": "message", - "role": "assistant", - "content": [ - { - "type": "output_text", - "text": "In a shimmering forest under a sky full of stars, a lonely unicorn named Lila discovered a hidden pond that glowed with moonlight. Every night, she would leave sparkling, magical flowers by the water's edge, hoping to share her beauty with others. One enchanting evening, she woke to find a group of friendly animals gathered around, eager to be friends and share in her magic.", - "annotations": [] - } - ] - } - ], - "previous_response_id": null, - "reasoning_effort": null, - "store": false, - "temperature": 1, - "text": { - "format": { - "type": "text" - } - }, - "tool_choice": "auto", - "tools": [], - "top_p": 1, - "truncation": "disabled", - "usage": { - "input_tokens": 0, - "output_tokens": 0, - "output_tokens_details": { - "reasoning_tokens": 0 - }, - "total_tokens": 0 - }, - "user": null, - "metadata": {} - }, - "sequence_number": 1 - } - BetaResponseCompactionCompactingStreamingEvent: + - call_id + - output + BetaFunctionAndCustomToolCallOutput: + discriminator: + propertyName: type + anyOf: + - $ref: '#/components/schemas/BetaInputTextContent' + - $ref: '#/components/schemas/BetaInputImageContent' + - $ref: '#/components/schemas/BetaInputFileContent' + BetaInputFileContent: properties: type: type: string enum: - - response.compaction.compacting - description: The type of the event, always `response.compaction.compacting`. - default: response.compaction.compacting + - input_file + description: The type of the input item. Always `input_file`. + default: input_file x-stainless-const: true - sequence_number: - type: integer - description: The sequence number of the event that was emitted. - agent: - $ref: '#/components/schemas/BetaAgentTag' - description: The agent that owns this multi-agent streaming event. - output_index: - type: integer - description: The index of the compaction output item. - item_id: + file_id: + anyOf: + - type: string + description: The ID of the file to be sent to the model. + - type: 'null' + filename: type: string - description: The ID of the compaction output item. + description: The name of the file to be sent to the model. + file_data: + type: string + description: | + The content of the file to be sent to the model. + prompt_cache_breakpoint: + $ref: '#/components/schemas/BetaPromptCacheBreakpointConfig' + file_url: + type: string + format: uri + description: The URL of the file to be sent to the model. + detail: + $ref: '#/components/schemas/BetaFileInputDetail' + description: The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. type: object required: - type - - sequence_number - - output_index - - item_id - title: Response compaction compacting event - description: Emitted when new summary content is sampled for a compaction trigger. Contains no summary content. - BetaResponseCodeInterpreterCallInterpretingEvent: + title: Input file + description: A file input to the model. + BetaFileInputDetail: + type: string + enum: + - auto + - low + - high + BetaPromptCacheBreakpointConfig: + properties: + mode: + type: string + enum: + - explicit + description: The breakpoint mode. Always `explicit`. + default: explicit + x-stainless-const: true type: object - description: Emitted when the code interpreter is actively interpreting the code snippet. + required: + - mode + title: Prompt cache breakpoint + description: Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + BetaInputImageContent: properties: - agent: + type: + type: string + enum: + - input_image + description: The type of the input item. Always `input_image`. + default: input_image + x-stainless-const: true + image_url: anyOf: - - $ref: '#/components/schemas/BetaAgentTag' + - type: string + format: uri + description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - type: 'null' - description: The agent that owns this multi-agent streaming event. + file_id: + anyOf: + - type: string + description: The ID of the file to be sent to the model. + - type: 'null' + detail: + $ref: '#/components/schemas/BetaImageDetail' + description: The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + prompt_cache_breakpoint: + $ref: '#/components/schemas/BetaPromptCacheBreakpointConfig' + type: object + required: + - type + - detail + title: Input image + description: An image input to the model. Learn about [image inputs](https://developers.openai.com/api/docs/guides/images-vision). + BetaImageDetail: + type: string + enum: + - low + - high + - auto + - original + BetaInputTextContent: + properties: type: type: string - description: The type of the event. Always `response.code_interpreter_call.interpreting`. enum: - - response.code_interpreter_call.interpreting + - input_text + description: The type of the input item. Always `input_text`. + default: input_text x-stainless-const: true - output_index: - type: integer - description: The index of the output item in the response for which the code interpreter is interpreting code. - item_id: + text: type: string - description: The unique identifier of the code interpreter tool call item. - sequence_number: - type: integer - description: The sequence number of this event, used to order streaming events. + description: The text input to the model. + prompt_cache_breakpoint: + $ref: '#/components/schemas/BetaPromptCacheBreakpointConfig' + type: object required: - type - - output_index - - item_id - - sequence_number - x-oaiMeta: - name: response.code_interpreter_call.interpreting - group: responses - example: | - { - "type": "response.code_interpreter_call.interpreting", - "output_index": 4, - "item_id": "ci_12345", - "sequence_number": 1 - } - BetaResponseCodeInterpreterCallInProgressEvent: - type: object - description: Emitted when a code interpreter call is in progress. + - text + title: Input text + description: A text input to the model. + BetaToolCallCallerParam: + discriminator: + propertyName: type + description: The execution context that produced this tool call. + anyOf: + - $ref: '#/components/schemas/BetaDirectToolCallCallerParam' + - $ref: '#/components/schemas/BetaProgramToolCallCallerParam' + BetaProgramToolCallCallerParam: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string - description: The type of the event. Always `response.code_interpreter_call.in_progress`. enum: - - response.code_interpreter_call.in_progress + - program + description: The caller type. Always `program`. + default: program x-stainless-const: true - output_index: - type: integer - description: The index of the output item in the response for which the code interpreter call is in progress. - item_id: + caller_id: type: string - description: The unique identifier of the code interpreter tool call item. - sequence_number: - type: integer - description: The sequence number of this event, used to order streaming events. + maxLength: 64 + minLength: 1 + description: The call ID of the program item that produced this tool call. + type: object required: - type - - output_index - - item_id - - sequence_number - x-oaiMeta: - name: response.code_interpreter_call.in_progress - group: responses - example: | - { - "type": "response.code_interpreter_call.in_progress", - "output_index": 0, - "item_id": "ci_12345", - "sequence_number": 1 - } - BetaResponseCodeInterpreterCallCompletedEvent: - type: object - description: Emitted when the code interpreter call is completed. + - caller_id + BetaDirectToolCallCallerParam: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string - description: The type of the event. Always `response.code_interpreter_call.completed`. enum: - - response.code_interpreter_call.completed + - direct + description: The caller type. Always `direct`. + default: direct x-stainless-const: true - output_index: - type: integer - description: The index of the output item in the response for which the code interpreter call is completed. - item_id: - type: string - description: The unique identifier of the code interpreter tool call item. - sequence_number: - type: integer - description: The sequence number of this event, used to order streaming events. + type: object required: - type - - output_index - - item_id - - sequence_number - x-oaiMeta: - name: response.code_interpreter_call.completed - group: responses - example: | - { - "type": "response.code_interpreter_call.completed", - "output_index": 5, - "item_id": "ci_12345", - "sequence_number": 1 - } - BetaResponseCodeInterpreterCallCodeDoneEvent: + BetaMCPToolCall: type: object - description: Emitted when the code snippet is finalized by the code interpreter. + title: MCP tool call + description: | + An invocation of a tool on an MCP server. properties: agent: anyOf: - $ref: '#/components/schemas/BetaAgentTag' - type: 'null' - description: The agent that owns this multi-agent streaming event. + description: The agent that produced this item. type: type: string - description: The type of the event. Always `response.code_interpreter_call_code.done`. enum: - - response.code_interpreter_call_code.done + - mcp_call + description: | + The type of the item. Always `mcp_call`. x-stainless-const: true - output_index: - type: integer - description: The index of the output item in the response for which the code is finalized. - item_id: + id: type: string - description: The unique identifier of the code interpreter tool call item. - code: + description: | + The unique ID of the tool call. + server_label: type: string - description: The final code snippet output by the code interpreter. - sequence_number: - type: integer - description: The sequence number of this event, used to order streaming events. + description: | + The label of the MCP server running the tool. + name: + type: string + description: | + The name of the tool that was run. + arguments: + type: string + description: | + A JSON string of the arguments passed to the tool. + output: + anyOf: + - type: string + description: | + The output from the tool call. + - type: 'null' + error: + description: The error from the tool call, if any. + anyOf: + - $ref: '#/components/schemas/BetaMCPToolCallError' + - type: 'null' + status: + $ref: '#/components/schemas/BetaMCPToolCallStatus' + description: | + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + approval_request_id: + anyOf: + - type: string + description: | + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + - type: 'null' required: - type - - output_index - - item_id - - code - - sequence_number - x-oaiMeta: - name: response.code_interpreter_call_code.done - group: responses - example: | - { - "type": "response.code_interpreter_call_code.done", - "output_index": 3, - "item_id": "ci_12345", - "code": "print('done')", - "sequence_number": 1 - } - BetaResponseCodeInterpreterCallCodeDeltaEvent: - type: object - description: Emitted when a partial code snippet is streamed by the code interpreter. + - id + - server_label + - name + - arguments + BetaMCPToolCallStatus: + type: string + enum: + - in_progress + - completed + - incomplete + - calling + - failed + BetaMCPToolCallError: + discriminator: + propertyName: type + anyOf: + - $ref: '#/components/schemas/BetaMCPProtocolError' + - $ref: '#/components/schemas/BetaMCPToolExecutionError' + - $ref: '#/components/schemas/BetaHTTPError' + BetaHTTPError: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string - description: The type of the event. Always `response.code_interpreter_call_code.delta`. enum: - - response.code_interpreter_call_code.delta + - http_error + default: http_error x-stainless-const: true - output_index: + code: type: integer - description: The index of the output item in the response for which the code is being streamed. - item_id: - type: string - description: The unique identifier of the code interpreter tool call item. - delta: + message: type: string - description: The partial code snippet being streamed by the code interpreter. - sequence_number: - type: integer - description: The sequence number of this event, used to order streaming events. + type: object required: - type - - output_index - - item_id - - delta - - sequence_number - x-oaiMeta: - name: response.code_interpreter_call_code.delta - group: responses - example: | - { - "type": "response.code_interpreter_call_code.delta", - "output_index": 0, - "item_id": "ci_12345", - "delta": "print('Hello, world')", - "sequence_number": 1 - } - BetaResponseAudioTranscriptDoneEvent: - type: object - description: Emitted when the full audio transcript is completed. + - code + - message + BetaMCPToolExecutionError: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string - description: | - The type of the event. Always `response.audio.transcript.done`. enum: - - response.audio.transcript.done + - mcp_tool_execution_error + default: mcp_tool_execution_error x-stainless-const: true - sequence_number: - type: integer - description: The sequence number of this event. - required: - - type - - response_id - - sequence_number - x-oaiMeta: - name: response.audio.transcript.done - group: responses - example: | - { - "type": "response.audio.transcript.done", - "response_id": "resp_123", - "sequence_number": 1 - } - BetaResponseAudioTranscriptDeltaEvent: + content: {} type: object - description: Emitted when there is a partial transcript of audio. + required: + - type + - content + BetaMCPProtocolError: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string - description: | - The type of the event. Always `response.audio.transcript.delta`. enum: - - response.audio.transcript.delta + - mcp_protocol_error + default: mcp_protocol_error x-stainless-const: true - delta: - type: string - description: | - The partial transcript of the audio response. - sequence_number: + code: type: integer - description: The sequence number of this event. + message: + type: string + type: object required: - type - - response_id - - delta - - sequence_number - x-oaiMeta: - name: response.audio.transcript.delta - group: responses - example: | - { - "type": "response.audio.transcript.delta", - "response_id": "resp_123", - "delta": " ... partial transcript ... ", - "sequence_number": 1 - } - BetaResponseAudioDoneEvent: + - code + - message + BetaMCPApprovalResponse: type: object - description: Emitted when the audio response is complete. + title: MCP approval response + description: | + A response to an MCP approval request. properties: agent: anyOf: - $ref: '#/components/schemas/BetaAgentTag' - type: 'null' - description: The agent that owns this multi-agent streaming event. + description: The agent that produced this item. type: type: string - description: | - The type of the event. Always `response.audio.done`. enum: - - response.audio.done + - mcp_approval_response + description: | + The type of the item. Always `mcp_approval_response`. x-stainless-const: true - sequence_number: - type: integer + id: + anyOf: + - type: string + description: | + The unique ID of the approval response + - type: 'null' + approval_request_id: + type: string description: | - The sequence number of the delta. + The ID of the approval request being answered. + approve: + type: boolean + description: | + Whether the request was approved. + reason: + anyOf: + - type: string + description: | + Optional reason for the decision. + - type: 'null' required: - type - - sequence_number - - response_id - x-oaiMeta: - name: response.audio.done - group: responses - example: | - { - "type": "response.audio.done", - "response_id": "resp-123", - "sequence_number": 1 - } - BetaResponseAudioDeltaEvent: + - request_id + - approve + - approval_request_id + BetaMCPApprovalRequest: type: object - description: Emitted when there is a partial audio response. + title: MCP approval request + description: | + A request for human approval of a tool invocation. properties: agent: anyOf: - $ref: '#/components/schemas/BetaAgentTag' - type: 'null' - description: The agent that owns this multi-agent streaming event. + description: The agent that produced this item. type: type: string - description: | - The type of the event. Always `response.audio.delta`. enum: - - response.audio.delta + - mcp_approval_request + description: | + The type of the item. Always `mcp_approval_request`. x-stainless-const: true - sequence_number: - type: integer + id: + type: string description: | - A sequence number for this chunk of the stream response. - delta: + The unique ID of the approval request. + server_label: type: string description: | - A chunk of Base64 encoded response audio bytes. + The label of the MCP server making the request. + name: + type: string + description: | + The name of the tool to run. + arguments: + type: string + description: | + A JSON string of arguments for the tool. required: - type - - delta - - sequence_number - x-oaiMeta: - name: response.audio.delta - group: responses - example: | - { - "type": "response.audio.delta", - "response_id": "resp_123", - "delta": "base64encoded...", - "sequence_number": 1 - } - BetaResponseIncompleteEvent: + - id + - server_label + - name + - arguments + BetaMCPListTools: type: object + title: MCP list tools description: | - An event that is emitted when a response finishes as incomplete. - - Over WebSocket, steering can finish a response with - `response.incomplete_details.reason` set to `steered`, followed automatically - by a successor `response.created` that commits the queued steering input. + A list of tools available on an MCP server. properties: agent: anyOf: - $ref: '#/components/schemas/BetaAgentTag' - type: 'null' - description: The agent that owns this multi-agent streaming event. + description: The agent that produced this item. type: type: string - description: | - The type of the event. Always `response.incomplete`. enum: - - response.incomplete + - mcp_list_tools + description: | + The type of the item. Always `mcp_list_tools`. x-stainless-const: true - response: - $ref: '#/components/schemas/BetaResponse' + id: + type: string description: | - The response that was incomplete. - sequence_number: - type: integer - description: The sequence number of this event. + The unique ID of the list. + server_label: + type: string + description: | + The label of the MCP server. + tools: + type: array + items: + $ref: '#/components/schemas/BetaMCPListToolsTool' + description: | + The tools available on the server. + error: + anyOf: + - type: string + description: | + Error message if the server could not list tools. + - type: 'null' required: - type - - response - - sequence_number - x-oaiMeta: - name: response.incomplete - group: responses - example: | - { - "type": "response.incomplete", - "response": { - "id": "resp_123", - "object": "response", - "created_at": 1740855869, - "status": "incomplete", - "completed_at": null, - "error": null, - "incomplete_details": { - "reason": "max_tokens" - }, - "instructions": null, - "max_output_tokens": null, - "model": "gpt-6-astra", - "output": [], - "previous_response_id": null, - "reasoning_effort": null, - "store": false, - "temperature": 1, - "text": { - "format": { - "type": "text" - } - }, - "tool_choice": "auto", - "tools": [], - "top_p": 1, - "truncation": "disabled", - "usage": null, - "user": null, - "metadata": {} - }, - "sequence_number": 1 - } - BetaResponseFailedEvent: + - id + - server_label + - tools + BetaMCPListToolsTool: type: object + title: MCP list tools tool description: | - An event that is emitted when a response fails. + A tool available on an MCP server. properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. - type: + name: type: string description: | - The type of the event. Always `response.failed`. - enum: - - response.failed - x-stainless-const: true - sequence_number: - type: integer - description: The sequence number of this event. - response: - $ref: '#/components/schemas/BetaResponse' + The name of the tool. + description: + anyOf: + - type: string + description: | + The description of the tool. + - type: 'null' + input_schema: + type: object description: | - The response that failed. + The JSON schema describing the tool's input. + annotations: + anyOf: + - type: object + description: | + Additional annotations about the tool. + - type: 'null' required: - - type - - response - - sequence_number - x-oaiMeta: - name: response.failed - group: responses - example: | - { - "type": "response.failed", - "response": { - "id": "resp_123", - "object": "response", - "created_at": 1740855869, - "status": "failed", - "completed_at": null, - "error": { - "code": "server_error", - "message": "The model failed to generate a response." - }, - "incomplete_details": null, - "instructions": null, - "max_output_tokens": null, - "model": "gpt-6-astra", - "output": [], - "previous_response_id": null, - "reasoning_effort": null, - "store": false, - "temperature": 1, - "text": { - "format": { - "type": "text" - } - }, - "tool_choice": "auto", - "tools": [], - "top_p": 1, - "truncation": "disabled", - "usage": null, - "user": null, - "metadata": {} - } - } - BetaResponseWebSearchCallCompletedEvent: - type: object - description: Emitted when a web search call is completed. + - name + - input_schema + BetaApplyPatchToolCallOutputItemParam: properties: agent: anyOf: - - $ref: '#/components/schemas/BetaAgentTag' + - $ref: '#/components/schemas/Beta_AgentTagParam' + description: The agent that produced this item. - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string - description: | - The type of the event. Always `response.web_search_call.completed`. enum: - - response.web_search_call.completed + - apply_patch_call_output + description: The type of the item. Always `apply_patch_call_output`. + default: apply_patch_call_output x-stainless-const: true - output_index: - type: integer - description: | - The index of the output item that the web search call is associated with. - item_id: + id: + anyOf: + - type: string + description: The unique ID of the apply patch tool call output. Populated when this item is returned via API. + example: apco_123 + - type: 'null' + call_id: type: string - description: | - Unique ID for the output item associated with the web search call. - sequence_number: - type: integer - description: The sequence number of the web search call being processed. + maxLength: 64 + minLength: 1 + description: The unique ID of the apply patch tool call generated by the model. + caller: + anyOf: + - $ref: '#/components/schemas/BetaToolCallCallerParam' + description: The execution context that produced this tool call. + - type: 'null' + status: + $ref: '#/components/schemas/BetaApplyPatchCallOutputStatusParam' + description: The status of the apply patch tool call output. One of `completed` or `failed`. + output: + anyOf: + - type: string + maxLength: 10485760 + description: Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + - type: 'null' + type: object required: - type - - output_index - - item_id - - sequence_number - x-oaiMeta: - name: response.web_search_call.completed - group: responses - example: | - { - "type": "response.web_search_call.completed", - "output_index": 0, - "item_id": "ws_123", - "sequence_number": 0 - } - BetaResponseWebSearchCallSearchingEvent: - type: object - description: Emitted when a web search call is executing. + - call_id + - status + title: Apply patch tool call output + description: The streamed output emitted by an apply patch tool call. + BetaApplyPatchCallOutputStatusParam: + type: string + enum: + - completed + - failed + title: Apply patch call output status + description: Outcome values reported for apply_patch tool call outputs. + BetaApplyPatchToolCallItemParam: properties: agent: anyOf: - - $ref: '#/components/schemas/BetaAgentTag' + - $ref: '#/components/schemas/Beta_AgentTagParam' + description: The agent that produced this item. - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string - description: | - The type of the event. Always `response.web_search_call.searching`. enum: - - response.web_search_call.searching + - apply_patch_call + description: The type of the item. Always `apply_patch_call`. + default: apply_patch_call x-stainless-const: true - output_index: - type: integer - description: | - The index of the output item that the web search call is associated with. - item_id: + id: + anyOf: + - type: string + description: The unique ID of the apply patch tool call. Populated when this item is returned via API. + example: apc_123 + - type: 'null' + call_id: type: string - description: | - Unique ID for the output item associated with the web search call. - sequence_number: - type: integer - description: The sequence number of the web search call being processed. + maxLength: 64 + minLength: 1 + description: The unique ID of the apply patch tool call generated by the model. + caller: + anyOf: + - $ref: '#/components/schemas/BetaToolCallCallerParam' + description: The execution context that produced this tool call. + - type: 'null' + status: + $ref: '#/components/schemas/BetaApplyPatchCallStatusParam' + description: The status of the apply patch tool call. One of `in_progress` or `completed`. + operation: + $ref: '#/components/schemas/BetaApplyPatchOperationParam' + description: The specific create, delete, or update instruction for the apply_patch tool call. + type: object required: - type - - output_index - - item_id - - sequence_number - x-oaiMeta: - name: response.web_search_call.searching - group: responses - example: | - { - "type": "response.web_search_call.searching", - "output_index": 0, - "item_id": "ws_123", - "sequence_number": 0 - } - BetaResponseWebSearchCallInProgressEvent: - type: object - description: Emitted when a web search call is initiated. + - call_id + - status + - operation + title: Apply patch tool call + description: A tool call representing a request to create, delete, or update files using diff patches. + BetaApplyPatchOperationParam: + discriminator: + propertyName: type + title: Apply patch operation + description: One of the create_file, delete_file, or update_file operations supplied to the apply_patch tool. + anyOf: + - $ref: '#/components/schemas/BetaApplyPatchCreateFileOperationParam' + - $ref: '#/components/schemas/BetaApplyPatchDeleteFileOperationParam' + - $ref: '#/components/schemas/BetaApplyPatchUpdateFileOperationParam' + BetaApplyPatchUpdateFileOperationParam: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string - description: | - The type of the event. Always `response.web_search_call.in_progress`. enum: - - response.web_search_call.in_progress + - update_file + description: The operation type. Always `update_file`. + default: update_file x-stainless-const: true - output_index: - type: integer - description: | - The index of the output item that the web search call is associated with. - item_id: + path: type: string - description: | - Unique ID for the output item associated with the web search call. - sequence_number: - type: integer - description: The sequence number of the web search call being processed. + minLength: 1 + description: Path of the file to update relative to the workspace root. + diff: + type: string + maxLength: 10485760 + description: Unified diff content to apply to the existing file. + type: object required: - type - - output_index - - item_id - - sequence_number - x-oaiMeta: - name: response.web_search_call.in_progress - group: responses - example: | - { - "type": "response.web_search_call.in_progress", - "output_index": 0, - "item_id": "ws_123", - "sequence_number": 0 - } - BetaResponseSteerFailedEvent: + - path + - diff + title: Apply patch update file operation + description: Instruction for updating an existing file via the apply_patch tool. + BetaApplyPatchDeleteFileOperationParam: + properties: + type: + type: string + enum: + - delete_file + description: The operation type. Always `delete_file`. + default: delete_file + x-stainless-const: true + path: + type: string + minLength: 1 + description: Path of the file to delete relative to the workspace root. type: object - title: ResponseSteerFailedEvent - description: | - Emitted when steering input is rejected or cannot be committed to a - successor response. Returns the original, uncommitted input so the client - can carry it into `response.create` when appropriate. Invalid input must - be corrected before retrying. - - Failures after acceptance include the same steering ID. Failures before an - ID is allocated omit `steer.id`. A lost connection or missing acknowledgement - leaves the outcome unknown; it is not proof that the input was rejected. + required: + - type + - path + title: Apply patch delete file operation + description: Instruction for deleting an existing file via the apply_patch tool. + BetaApplyPatchCreateFileOperationParam: properties: type: type: string enum: - - response.steer.failed - description: The event discriminator. Always `response.steer.failed`. + - create_file + description: The operation type. Always `create_file`. + default: create_file x-stainless-const: true - sequence_number: - type: integer - description: The sequence number for this event. - steer: - type: object - description: The steering submission that could not be committed. - properties: - id: - type: string - description: | - The ID assigned to the steering submission, if one was allocated. - previous_response_id: - type: string - description: The ID of the response that was targeted for steering. - input: - $ref: '#/components/schemas/BetaResponseSteerInput' - required: - - previous_response_id - - input - error: - type: object - description: Information about why the input could not be committed. - properties: - type: - type: string - enum: - - invalid_request_error - description: The error type. Always `invalid_request_error`. - x-stainless-const: true - code: - $ref: '#/components/schemas/BetaResponseSteerErrorCode' - message: - type: string - description: A human-readable description of the error. - required: - - type - - code - - message - stream_id: + path: type: string - description: | - The WebSocket lane that emitted this event, when the target response is - available and its `response.create` event supplied a `stream_id`. + minLength: 1 + description: Path of the file to create relative to the workspace root. + diff: + type: string + maxLength: 10485760 + description: Unified diff content to apply when creating the file. + type: object required: - type - - sequence_number - - steer - - error - x-oaiMeta: - name: response.steer.failed - group: responses - example: | - { - "type": "response.steer.failed", - "sequence_number": 5, - "steer": { - "id": "steer_456", - "previous_response_id": "resp_123", - "input": [ - { - "type": "message", - "role": "user", - "content": [ - { - "type": "input_text", - "text": "Prioritize the database rollout." - } - ] - } - ] - }, - "error": { - "type": "invalid_request_error", - "code": "successor_creation_failed", - "message": "We couldn't start the next response. Send this steering input again with response.create." - } - } - BetaResponseSteerErrorCode: - title: ResponseSteerErrorCode - description: | - A machine-readable steering error code. Clients should handle unknown - values because additional codes may be introduced. Known values include: - - `response_not_found`: The target response is not available on this connection. - - `invalid_input`: The event or input failed validation. - - `steering_not_supported`: The model or response execution mode does not support steering. - - `too_many_pending_steers`: Too much steering input is pending for the response. - - `response_already_completed`: The response completed and is no longer accepting steering input. - - `response_not_active`: The response is no longer accepting steering input. - - `successor_creation_failed`: The successor response could not be created. - anyOf: - - type: string - enum: - - response_not_found - - invalid_input - - steering_not_supported - - too_many_pending_steers - - response_already_completed - - response_not_active - - successor_creation_failed - - type: string - BetaResponseSteerInput: - title: ResponseSteerInput - description: | - Input to queue for a continuation of the response. Uses the same string or - input-item shape as `response.create.input`, with a non-empty array when - supplying input items. - - Steering accepts only messages with the `user` role. Each message may - contain only `type`, `role`, and `content`, with `content` as a string or an - array of `input_text`, `input_image`, and `input_file` parts. The optional - `type` must be `message`. Other roles, tool outputs, and item types are not - supported for steering. - anyOf: - - type: string - title: Text input - description: A text input, equivalent to a message with the `user` role. - - $ref: '#/components/schemas/BetaResponseSteerInputItemList' - BetaResponseSteerInputItemList: - type: array - title: Response steer input item list - description: A non-empty list of message inputs to queue for the response. - minItems: 1 - items: - $ref: '#/components/schemas/BetaResponseSteerInputItem' - BetaResponseSteerInputItem: - title: Response steer input item - anyOf: - - $ref: '#/components/schemas/BetaUserMessageItemParam' - - $ref: '#/components/schemas/BetaFunctionCallOutputItemParam' - discriminator: - propertyName: type - BetaUserMessageItemParam: + - path + - diff + title: Apply patch create file operation + description: Instruction for creating a new file via the apply_patch tool. + BetaApplyPatchCallStatusParam: + type: string + enum: + - in_progress + - completed + title: Apply patch call status + description: Status values reported for apply_patch tool calls. + BetaFunctionShellCallOutputItemParam: properties: agent: anyOf: @@ -93284,1917 +91682,8021 @@ components: id: anyOf: - type: string - description: The unique ID of this message item. - example: msg_123 + description: The unique ID of the shell tool call output. Populated when this item is returned via API. + example: sho_123 - type: 'null' - type: + call_id: type: string - enum: - - message - description: The item type. Always `message`. - default: message - x-stainless-const: true - role: + maxLength: 64 + minLength: 1 + description: The unique ID of the shell tool call generated by the model. + caller: + anyOf: + - $ref: '#/components/schemas/BetaToolCallCallerParam' + description: The execution context that produced this tool call. + - type: 'null' + type: type: string enum: - - user - description: The message role. Always `user`. - default: user + - shell_call_output + description: The type of the item. Always `shell_call_output`. + default: shell_call_output x-stainless-const: true - content: - description: The message content, as an array of content parts. - anyOf: - - items: - $ref: '#/components/schemas/BetaResponseSteerInputContent' - description: A piece of message content, such as text, an image, or a file. - type: array - - type: string - maxLength: 10485760 - description: The message content, as a single string. + output: + items: + $ref: '#/components/schemas/BetaFunctionShellCallOutputContentParam' + type: array + description: Captured chunks of stdout and stderr output, along with their associated outcomes. status: anyOf: - - type: string - description: The status of the message item. + - $ref: '#/components/schemas/BetaFunctionShellCallItemStatus' + description: The status of the shell call output. + - type: 'null' + max_output_length: + anyOf: + - type: integer + description: The maximum number of UTF-8 characters captured for this shell call's combined output. - type: 'null' type: object required: + - call_id - type - - role - - content - BetaResponseSteerPendingEvent: + - output + title: Shell tool call output + description: The streamed output items emitted by a shell tool call. + BetaFunctionShellCallItemStatus: + type: string + enum: + - in_progress + - completed + - incomplete + title: Shell call status + description: Status values reported for shell tool calls. + BetaFunctionShellCallOutputContentParam: + properties: + stdout: + type: string + maxLength: 10485760 + description: Captured stdout output for the shell call. + stderr: + type: string + maxLength: 10485760 + description: Captured stderr output for the shell call. + outcome: + $ref: '#/components/schemas/BetaFunctionShellCallOutputOutcomeParam' + description: The exit or timeout outcome associated with this shell call. type: object - title: ResponseSteerPendingEvent - description: | - Emitted when accepted steering input remains queued after the target - response completes. The server still owns the input. Do not resend it. - The successor's `response.created` event is the commit point. - - When `reason` is `waiting_for_required_input`, this event follows - `response.completed` while the response waits for the tool results or - approval decisions identified by `required_input`. Copy those stubs, fill - their result fields using the ordinary `response.create` input schemas, - and submit one continuation per parent with the same `previous_response_id` - and WebSocket lane. Use saved results without rerunning tools. The queued - steering input is prepended in submission order to the continuation's - input. That explicit request retains its own settings. - - This notification is emitted at most once per steering submission. Multiple - submissions for the same parent can report the same required inputs; they - do not each require a separate continuation. + required: + - stdout + - stderr + - outcome + title: Shell output content + description: Captured stdout and stderr for a portion of a shell tool call output. + BetaFunctionShellCallOutputOutcomeParam: + discriminator: + propertyName: type + title: Shell call outcome + description: The exit or timeout outcome associated with this shell call. + anyOf: + - $ref: '#/components/schemas/BetaFunctionShellCallOutputTimeoutOutcomeParam' + - $ref: '#/components/schemas/BetaFunctionShellCallOutputExitOutcomeParam' + BetaFunctionShellCallOutputExitOutcomeParam: properties: type: type: string enum: - - response.steer.pending - description: The event discriminator. Always `response.steer.pending`. + - exit + description: The outcome type. Always `exit`. + default: exit x-stainless-const: true - sequence_number: + exit_code: type: integer - description: The sequence number for this event. - steer: - type: object - description: The steering submission that remains queued. - properties: - id: - type: string - description: The ID assigned to the steering submission. - previous_response_id: - type: string - description: The ID of the response being steered. - required: - - id - - previous_response_id - reason: - $ref: '#/components/schemas/BetaResponseSteerPendingReason' - required_input: - type: array - minItems: 1 - description: | - Input stubs identifying outstanding client-owned tool results or - approval decisions. Each stub contains identifying fields only; the - client supplies the result before including it in `response.create`. - items: - $ref: '#/components/schemas/BetaResponseSteerRequiredInput' - stream_id: + description: The exit code returned by the shell process. + type: object + required: + - type + - exit_code + title: Shell call exit outcome + description: Indicates that the shell commands finished and returned an exit code. + BetaFunctionShellCallOutputTimeoutOutcomeParam: + properties: + type: type: string - description: | - The WebSocket lane that emitted this event. This field is present when - the target response's `response.create` event supplied a `stream_id`. + enum: + - timeout + description: The outcome type. Always `timeout`. + default: timeout + x-stainless-const: true + type: object required: - type - - sequence_number - - steer - - reason - - required_input - x-oaiMeta: - name: response.steer.pending - group: responses - example: | - { - "type": "response.steer.pending", - "sequence_number": 10, - "steer": { - "id": "steer_456", - "previous_response_id": "resp_123" - }, - "reason": "waiting_for_required_input", - "required_input": [ - { - "type": "function_call_output", - "call_id": "call_789", - "name": "lookup" - } - ] - } - BetaResponseSteerRequiredInput: - title: ResponseSteerRequiredInput - description: | - An input stub identifying an outstanding client-owned tool result or - approval decision. Copy the stub and fill the result fields using the - corresponding `response.create` input schema. Use saved results without - rerunning the tool. The server does not supply results, approval decisions, - or safety acknowledgements in these stubs. - discriminator: - propertyName: type - anyOf: - - type: object - title: Required function tool call output - additionalProperties: false - description: | - Supply `output` using the function tool call output input schema. - properties: - type: - type: string - enum: - - function_call_output - x-stainless-const: true - call_id: - type: string - name: - type: string - required: - - type - - call_id - - name - - type: object - title: Required custom tool call output - additionalProperties: false - description: | - Supply `output` using the custom tool call output input schema. The - original custom tool call supplies the tool's name. - properties: - type: - type: string - enum: - - custom_tool_call_output - x-stainless-const: true - call_id: - type: string - required: - - type - - call_id - - type: object - title: Required computer tool call output - additionalProperties: false - description: | - Supply `output` using the computer tool call output input schema, - including any required `acknowledged_safety_checks`. - properties: - type: - type: string - enum: - - computer_call_output - x-stainless-const: true - call_id: - type: string - required: - - type - - call_id - - type: object - title: Required shell tool call output - additionalProperties: false - description: | - Supply `output` using the shell tool call output input schema. Each - output entry includes `stdout`, `stderr`, and `outcome`. - properties: - type: - type: string - enum: - - shell_call_output - x-stainless-const: true - call_id: - type: string - required: - - type - - call_id - - type: object - title: Required apply patch tool call output - additionalProperties: false - description: | - Supply `status` and optional `output` using the apply patch tool call - output input schema. - properties: - type: - type: string - enum: - - apply_patch_call_output - x-stainless-const: true - call_id: - type: string - required: - - type - - call_id - - type: object - title: Required tool search output - additionalProperties: false - description: | - Supply `tools` using the tool search output input schema, retaining - `execution: "client"`. - properties: - type: - type: string - enum: - - tool_search_output - x-stainless-const: true - call_id: - type: string - execution: - type: string - enum: - - client - x-stainless-const: true - required: - - type - - call_id - - execution - - type: object - title: Required MCP approval response - additionalProperties: false - description: | - Supply `approve` using the MCP approval response input schema. An - optional `reason` can be supplied when denying the request. The original - approval request identifies the tool and server. - properties: - type: - type: string - enum: - - mcp_approval_response - x-stainless-const: true - approval_request_id: + title: Shell call timeout outcome + description: Indicates that the shell call exceeded its configured time limit. + BetaFunctionShellCallItemParam: + properties: + agent: + anyOf: + - $ref: '#/components/schemas/Beta_AgentTagParam' + description: The agent that produced this item. + - type: 'null' + id: + anyOf: + - type: string + description: The unique ID of the shell tool call. Populated when this item is returned via API. + example: sh_123 + - type: 'null' + call_id: + type: string + maxLength: 64 + minLength: 1 + description: The unique ID of the shell tool call generated by the model. + caller: + anyOf: + - $ref: '#/components/schemas/BetaToolCallCallerParam' + description: The execution context that produced this tool call. + - type: 'null' + type: + type: string + enum: + - shell_call + description: The type of the item. Always `shell_call`. + default: shell_call + x-stainless-const: true + action: + $ref: '#/components/schemas/BetaFunctionShellActionParam' + description: The shell commands and limits that describe how to run the tool call. + status: + anyOf: + - $ref: '#/components/schemas/BetaFunctionShellCallItemStatus' + description: The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - type: 'null' + environment: + anyOf: + - discriminator: + propertyName: type + description: The environment to execute the shell commands in. + anyOf: + - $ref: '#/components/schemas/BetaLocalEnvironmentParam' + - $ref: '#/components/schemas/BetaContainerReferenceParam' + - type: 'null' + type: object + required: + - call_id + - type + - action + title: Shell tool call + description: A tool representing a request to execute one or more shell commands. + BetaFunctionShellActionParam: + properties: + commands: + items: type: string - required: - - type - - approval_request_id - BetaResponseSteerPendingReason: - title: ResponseSteerPendingReason - description: | - An extensible enum describing why accepted steering input is still queued. - Clients should handle unknown values because additional reasons may be - introduced. Known values include: - - `waiting_for_required_input`: The response is waiting for the tool results or approval decisions identified by `required_input`. - anyOf: - - type: string - enum: - - waiting_for_required_input - - type: string - BetaResponseSteerAcceptedEvent: + type: array + description: Ordered shell commands for the execution environment to run. + timeout_ms: + anyOf: + - type: integer + description: Maximum wall-clock time in milliseconds to allow the shell commands to run. + - type: 'null' + max_output_length: + anyOf: + - type: integer + description: Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + - type: 'null' type: object - title: ResponseSteerAcceptedEvent + required: + - commands + title: Shell action + description: Commands and limits describing how to run the shell tool call. + BetaLocalShellToolCallOutput: + type: object + title: Local shell call output description: | - Emitted when steering input has been validated and queued. Acceptance means - the server owns the input, not that it has been applied. The successor's - `response.created` event is the commit point. If accepted input cannot be - committed, `response.steer.failed` returns it with the same steering ID. - - When the response stops for client-owned tool output or approval, the input - remains queued and `response.steer.pending` is emitted after - `response.completed`. Fill the pending event's `required_input` stubs with - saved results and send one matching explicit `response.create` per parent. - Do not resend accepted input while it is still queued. + The output of a local shell tool call. properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that produced this item. type: type: string enum: - - response.steer.accepted - description: The event discriminator. Always `response.steer.accepted`. + - local_shell_call_output + description: | + The type of the local shell tool call output. Always `local_shell_call_output`. x-stainless-const: true - sequence_number: - type: integer - description: The sequence number for this event. - steer: - type: object - description: The accepted steering submission. - properties: - id: - type: string - description: The ID assigned to the steering submission. - previous_response_id: - type: string - description: The ID of the response being steered. - required: - - id - - previous_response_id - stream_id: + id: type: string description: | - The WebSocket lane that emitted this event. This field is present when - the target response's `response.create` event supplied a `stream_id`. + The unique ID of the local shell tool call generated by the model. + output: + type: string + description: | + A JSON string of the output of the local shell tool call. + status: + anyOf: + - type: string + enum: + - in_progress + - completed + - incomplete + description: | + The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - type: 'null' required: + - id - type - - sequence_number - - steer - x-oaiMeta: - name: response.steer.accepted - group: responses - example: | - { - "type": "response.steer.accepted", - "sequence_number": 2, - "steer": { - "id": "steer_456", - "previous_response_id": "resp_123" - } - } - BetaResponseSteerEvent: + - call_id + - output + BetaLocalShellToolCall: type: object - title: ResponseSteerEvent - additionalProperties: false + title: Local shell call description: | - Queues user input to steer a response on this WebSocket connection. Input - can contain text, images, and files. Steering is supported only for - single-agent responses on models and execution modes that support steering. - Responses bound to a conversation or using automatic compaction do not - support steering. - - A `response.steer.accepted` event acknowledges that the server owns the - queued input, not that it has been applied. The successor's `response.created` - event is the commit point. Input that cannot be committed is returned in - `response.steer.failed`. - - Steering may cause the active response to finish at a safe output boundary - with `response.incomplete` and `incomplete_details.reason` set to `steered`, - followed automatically by a successor `response.created`. Normal completion - can also be followed by an automatic successor. Automatic successors inherit - the previous response's settings and continue from it with the queued input. - - If the response stops for client-owned tool output or approval, accepted - steering input remains queued and `response.steer.pending` is emitted after - `response.completed`. Fill the `required_input` stubs from that event with - saved tool results or approval decisions, and send one explicit - `response.create` per parent with the same `previous_response_id` and - WebSocket lane. Do not rerun tools or resend accepted steering input. The - queued input is prepended in submission order to that request's input, and - the explicit request retains its own settings. - - This event accepts only `type`, `previous_response_id`, and `input`. Do not - send `stream_id`; the target response determines the WebSocket lane. + A tool call to run a command on the local shell. properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that produced this item. type: type: string enum: - - response.steer - description: The event discriminator. Always `response.steer`. + - local_shell_call + description: | + The type of the local shell call. Always `local_shell_call`. x-stainless-const: true - previous_response_id: + id: type: string - description: The ID of the response to steer on this WebSocket connection. - input: - $ref: '#/components/schemas/BetaResponseSteerInput' + description: | + The unique ID of the local shell call. + call_id: + type: string + description: | + The unique ID of the local shell tool call generated by the model. + action: + $ref: '#/components/schemas/BetaLocalShellExecAction' + status: + type: string + enum: + - in_progress + - completed + - incomplete + description: | + The status of the local shell call. required: - type - - previous_response_id - - input - x-oaiMeta: - name: response.steer - group: responses - example: | - { - "type": "response.steer", - "previous_response_id": "resp_123", - "input": [ - { - "type": "message", - "role": "user", - "content": [ - { - "type": "input_text", - "text": "Prioritize the database rollout." - } - ] - } - ] - } - BetaOutputAudio: + - id + - call_id + - action + - status + BetaLocalShellExecAction: + properties: + type: + type: string + enum: + - exec + description: The type of the local shell action. Always `exec`. + default: exec + x-stainless-const: true + command: + items: + type: string + type: array + description: The command to run. + timeout_ms: + anyOf: + - type: integer + description: Optional timeout in milliseconds for the command. + - type: 'null' + working_directory: + anyOf: + - type: string + description: Optional working directory to run the command in. + - type: 'null' + env: + additionalProperties: + type: string + type: object + description: Environment variables to set for the command. + x-oaiTypeLabel: map + user: + anyOf: + - type: string + description: Optional user to run the command as. + - type: 'null' type: object - title: Output audio + required: + - type + - command + - env + title: Local shell exec action + description: Execute a shell command on the server. + BetaCodeInterpreterToolCall: + type: object + title: Code interpreter tool call description: | - An audio output from the model. + A tool call to run code. properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that produced this item. type: type: string - description: | - The type of the output audio. Always `output_audio`. enum: - - output_audio + - code_interpreter_call + default: code_interpreter_call x-stainless-const: true - data: + description: | + The type of the code interpreter tool call. Always `code_interpreter_call`. + id: type: string description: | - Base64-encoded audio data from the model. - transcript: + The unique ID of the code interpreter tool call. + status: + type: string + enum: + - in_progress + - completed + - incomplete + - interpreting + - failed + description: | + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + container_id: type: string description: | - The transcript of the audio data from the model. + The ID of the container used to run the code. + code: + anyOf: + - type: string + description: | + The code to run, or null if not available. + - type: 'null' + outputs: + anyOf: + - type: array + items: + discriminator: + propertyName: type + anyOf: + - $ref: '#/components/schemas/BetaCodeInterpreterOutputLogs' + - $ref: '#/components/schemas/BetaCodeInterpreterOutputImage' + discriminator: + propertyName: type + description: | + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. + - type: 'null' required: - type - - data - - transcript - BetaInputAudio: + - id + - status + - container_id + - code + - outputs + BetaCodeInterpreterOutputImage: + properties: + type: + type: string + enum: + - image + description: The type of the output. Always `image`. + default: image + x-stainless-const: true + url: + type: string + format: uri + description: The URL of the image output from the code interpreter. type: object - title: Input audio - description: | - An audio input to the model. + required: + - type + - url + title: Code interpreter output image + description: The image output from the code interpreter. + BetaCodeInterpreterOutputLogs: properties: type: type: string - description: | - The type of the input item. Always `input_audio`. enum: - - input_audio + - logs + description: The type of the output. Always `logs`. + default: logs x-stainless-const: true - input_audio: - type: object - properties: - data: - type: string - description: | - Base64-encoded audio data. - format: - type: string - description: | - The format of the audio data. Currently supported formats are `mp3` and - `wav`. + logs: + type: string + description: The logs output from the code interpreter. + type: object + required: + - type + - logs + title: Code interpreter output logs + description: The logs output from the code interpreter. + BetaImageGenToolCall: + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + description: The agent that produced this item. + - type: 'null' + type: + type: string + enum: + - image_generation_call + description: The type of the image generation call. Always `image_generation_call`. + x-stainless-const: true + id: + type: string + description: The unique ID of the image generation call. + status: + type: string + enum: + - in_progress + - completed + - generating + - failed + description: The status of the image generation call. + result: + anyOf: + - type: string + description: The generated image encoded in base64. + - type: 'null' + size: + anyOf: + - anyOf: + - type: string + - type: string enum: - - mp3 - - wav - required: - - data - - format + - 1024x1024 + - 1024x1536 + - 1536x1024 + description: The image dimensions as a `WIDTHxHEIGHT` string, for example `1536x864`. + - type: 'null' + quality: + anyOf: + - type: string + enum: + - low + - medium + - high + - xhigh + - max + - auto + description: The quality of the image generated by the image generation tool call. One of `low`, `medium`, `high`, `xhigh`, `max`, or `auto`. + - type: 'null' + action: + anyOf: + - $ref: '#/components/schemas/BetaImageGenActionEnum' + description: The action used for image generation. + - type: 'null' + x-openai-go-optional-enum: true + background: + anyOf: + - $ref: '#/components/schemas/BetaImageBackground' + description: The background setting used for generation. + - type: 'null' + x-openai-go-optional-enum: true + output_format: + anyOf: + - $ref: '#/components/schemas/BetaImageOutputFormat' + description: The output format used for generation. + - type: 'null' + x-openai-go-optional-enum: true + revised_prompt: + anyOf: + - type: string + description: The prompt that was used after any model prompt rewriting. + - type: 'null' + type: object required: - type - - input_audio - BetaInputParam: - description: | - Text, image, or file inputs to the model, used to generate a response. - - Learn more: - - [Text inputs and outputs](https://developers.openai.com/api/docs/guides/text) - - [Image inputs](https://developers.openai.com/api/docs/guides/images-vision) - - [File inputs](https://developers.openai.com/api/docs/guides/file-inputs) - - [Conversation state](https://developers.openai.com/api/docs/guides/conversation-state) - - [Function calling](https://developers.openai.com/api/docs/guides/function-calling) - anyOf: - - type: string - title: Text input - description: | - A text input to the model, equivalent to a text input with the - `user` role. - - type: array - title: Input item list - description: | - A list of one or many input items to the model, containing - different content types. - items: - $ref: '#/components/schemas/BetaInputItem' - BetaContent: - description: | - Multi-modal input and output contents. - anyOf: - - title: Input content types - $ref: '#/components/schemas/BetaInputContent' - - title: Output content types - $ref: '#/components/schemas/BetaOutputContent' - BetaIncludeEnum: + - id + - status + - result + title: Image generation call + description: An image generation request made by the model. + BetaImageOutputFormat: type: string enum: - - file_search_call.results - - web_search_call.results - - web_search_call.action.sources - - message.input_image.image_url - - computer_call_output.output.image_url - - code_interpreter_call.outputs - - reasoning.encrypted_content - - message.output_text.logprobs - description: |- - Specify additional output data to include in the model response. Currently supported values are: - - `web_search_call.results`: Include the search results of the web search tool call. - - `web_search_call.action.sources`: Include the sources of the web search tool call. - - `code_interpreter_call.outputs`: Includes the outputs of python code execution in code interpreter tool call items. - - `computer_call_output.output.image_url`: Include image urls from the computer call output. - - `file_search_call.results`: Include the search results of the file search tool call. - - `message.input_image.image_url`: Include image urls from the input message. - - `message.output_text.logprobs`: Include logprobs with assistant messages. - - `reasoning.encrypted_content`: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the `store` parameter is set to `false`, or when an organization is enrolled in the zero data retention program). - BetaResponsesServerEvent: - discriminator: - propertyName: type - description: | - Server events emitted by the Responses WebSocket server. - anyOf: - - title: BetaResponseAudioWsDelta - description: Emitted when there is a partial audio response. - allOf: - - $ref: '#/components/schemas/BetaResponseAudioDeltaEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseAudioWsDone - description: Emitted when the audio response is complete. - allOf: - - $ref: '#/components/schemas/BetaResponseAudioDoneEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseAudioTranscriptWsDelta - description: Emitted when there is a partial transcript of audio. - allOf: - - $ref: '#/components/schemas/BetaResponseAudioTranscriptDeltaEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseAudioTranscriptWsDone - description: Emitted when the full audio transcript is completed. - allOf: - - $ref: '#/components/schemas/BetaResponseAudioTranscriptDoneEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseCodeInterpreterCallCodeWsDelta - description: Emitted when a partial code snippet is streamed by the code interpreter. - allOf: - - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallCodeDeltaEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseCodeInterpreterCallCodeWsDone - description: Emitted when the code snippet is finalized by the code interpreter. - allOf: - - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallCodeDoneEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseCodeInterpreterCallWsCompleted - description: Emitted when the code interpreter call is completed. - allOf: - - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallCompletedEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseCodeInterpreterCallInWsProgress - description: Emitted when a code interpreter call is in progress. - allOf: - - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallInProgressEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseCodeInterpreterCallWsInterpreting - description: Emitted when the code interpreter is actively interpreting the code snippet. - allOf: - - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallInterpretingEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseCompactionWsCompacting - description: Emitted when new summary content is sampled for a compaction trigger. Contains no summary content. - allOf: - - $ref: '#/components/schemas/BetaResponseCompactionCompactingStreamingEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseWsCompleted - description: Emitted when the model response is complete. - allOf: - - $ref: '#/components/schemas/BetaResponseCompletedEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseContentPartWsAdded - description: Emitted when a new content part is added. - allOf: - - $ref: '#/components/schemas/BetaResponseContentPartAddedEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseContentPartWsDone - description: Emitted when a content part is done. - allOf: - - $ref: '#/components/schemas/BetaResponseContentPartDoneEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseWsCreated - description: | - An event that is emitted when a response is created. - allOf: - - $ref: '#/components/schemas/BetaResponseCreatedEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseFileSearchCallWsCompleted - description: Emitted when a file search call is completed (results found). - allOf: - - $ref: '#/components/schemas/BetaResponseFileSearchCallCompletedEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseFileSearchCallInWsProgress - description: Emitted when a file search call is initiated. - allOf: - - $ref: '#/components/schemas/BetaResponseFileSearchCallInProgressEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseFileSearchCallWsSearching - description: Emitted when a file search is currently searching. - allOf: - - $ref: '#/components/schemas/BetaResponseFileSearchCallSearchingEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseFunctionCallArgumentsWsDelta - description: Emitted when there is a partial function-call arguments delta. - allOf: - - $ref: '#/components/schemas/BetaResponseFunctionCallArgumentsDeltaEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseFunctionCallArgumentsWsDone - description: Emitted when function-call arguments are finalized. - allOf: - - $ref: '#/components/schemas/BetaResponseFunctionCallArgumentsDoneEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseShellCallCommandWsAdded - description: A streaming event that indicated a shell command was added to a tool call. - allOf: - - $ref: '#/components/schemas/BetaResponseShellCallCommandAddedStreamingEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseShellCallCommandWsDelta - description: A streaming event that indicated a shell command was incrementally updated. - allOf: - - $ref: '#/components/schemas/BetaResponseShellCallCommandDeltaStreamingEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseShellCallCommandWsDone - description: A streaming event that indicated a shell command was completed. - allOf: - - $ref: '#/components/schemas/BetaResponseShellCallCommandDoneStreamingEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseShellCallOutputContentWsDelta - description: A streaming event that indicated shell call output was incrementally added. - allOf: - - $ref: '#/components/schemas/BetaResponseShellCallOutputContentDeltaStreamingEvent' - x-stainless-skip: - - go - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseShellCallOutputContentWsDone - description: A streaming event that indicated shell call output was completed. - allOf: - - $ref: '#/components/schemas/BetaResponseShellCallOutputContentDoneStreamingEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseInWsProgress - description: Emitted when the response is in progress. - allOf: - - $ref: '#/components/schemas/BetaResponseInProgressEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseWsFailed - description: | - An event that is emitted when a response fails. - allOf: - - $ref: '#/components/schemas/BetaResponseFailedEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseWsIncomplete - description: | - An event that is emitted when a response finishes as incomplete. - - Over WebSocket, steering can finish a response with - `response.incomplete_details.reason` set to `steered`, followed automatically - by a successor `response.created` that commits the queued steering input. - allOf: - - $ref: '#/components/schemas/BetaResponseIncompleteEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseOutputItemWsAdded - description: Emitted when a new output item is added. - allOf: - - $ref: '#/components/schemas/BetaResponseOutputItemAddedEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseOutputItemWsDone - description: Emitted when an output item is marked done. - allOf: - - $ref: '#/components/schemas/BetaResponseOutputItemDoneEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseReasoningSummaryPartWsAdded - description: Emitted when a new reasoning summary part is added. - allOf: - - $ref: '#/components/schemas/BetaResponseReasoningSummaryPartAddedEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseReasoningSummaryPartWsDone - description: Emitted when a reasoning summary part is completed. - allOf: - - $ref: '#/components/schemas/BetaResponseReasoningSummaryPartDoneEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseReasoningSummaryTextWsDelta - description: Emitted when a delta is added to a reasoning summary text. - allOf: - - $ref: '#/components/schemas/BetaResponseReasoningSummaryTextDeltaEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseReasoningSummaryTextWsDone - description: Emitted when a reasoning summary text is completed. - allOf: - - $ref: '#/components/schemas/BetaResponseReasoningSummaryTextDoneEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseReasoningTextWsDelta - description: Emitted when a delta is added to a reasoning text. - allOf: - - $ref: '#/components/schemas/BetaResponseReasoningTextDeltaEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseReasoningTextWsDone - description: Emitted when a reasoning text is completed. - allOf: - - $ref: '#/components/schemas/BetaResponseReasoningTextDoneEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseRefusalWsDelta - description: Emitted when there is a partial refusal text. - allOf: - - $ref: '#/components/schemas/BetaResponseRefusalDeltaEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseRefusalWsDone - description: Emitted when refusal text is finalized. - allOf: - - $ref: '#/components/schemas/BetaResponseRefusalDoneEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseTextWsDelta - description: Emitted when there is an additional text delta. - allOf: - - $ref: '#/components/schemas/BetaResponseTextDeltaEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseTextWsDone - description: Emitted when text content is finalized. - allOf: - - $ref: '#/components/schemas/BetaResponseTextDoneEvent' - - type: object + - png + - webp + - jpeg + BetaImageBackground: + type: string + enum: + - transparent + - opaque + - auto + BetaCompactionSummaryItemParam: + properties: + agent: + anyOf: + - $ref: '#/components/schemas/Beta_AgentTagParam' + description: The agent that produced this item. + - type: 'null' + id: + anyOf: + - type: string + description: The ID of the compaction item. + example: cmp_123 + - type: 'null' + type: + type: string + enum: + - compaction + description: The type of the item. Always `compaction`. + default: compaction + x-stainless-const: true + encrypted_content: + type: string + maxLength: 104857600 + description: The encrypted content of the compaction summary. + type: object + required: + - type + - encrypted_content + title: Compaction item + description: A compaction item generated by the [`v1/responses/compact` API](https://developers.openai.com/api/reference/resources/responses/methods/compact). + BetaReasoningItem: + type: object + description: | + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://developers.openai.com/api/docs/guides/conversation-state). + title: Reasoning + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that produced this item. + type: + type: string + description: | + The type of the object. Always `reasoning`. + enum: + - reasoning + x-stainless-const: true + id: + type: string + description: | + The unique identifier of the reasoning content. + encrypted_content: + anyOf: + - type: string + description: | + The encrypted content of the reasoning item. This is populated by default + for reasoning items returned by `POST /v1/responses` and WebSocket + `response.create` requests. + + When streaming, use the completed reasoning item and its + `encrypted_content` from the `response.output_item.done` event in + subsequent requests. The `encrypted_content` in + `response.output_item.added` may be incomplete. This is especially + important when `store` is `false` or when using Zero Data Retention. + - type: 'null' + summary: + type: array + description: | + Reasoning summary content. + items: + $ref: '#/components/schemas/BetaSummaryTextContent' + content: + type: array + description: | + Reasoning text content. + items: + $ref: '#/components/schemas/BetaReasoningTextContent' + status: + type: string + description: | + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + enum: + - in_progress + - completed + - incomplete + required: + - id + - summary + - type + BetaReasoningTextContent: + properties: + type: + type: string + enum: + - reasoning_text + description: The type of the reasoning text. Always `reasoning_text`. + default: reasoning_text + x-stainless-const: true + text: + type: string + description: The reasoning text from the model. + type: object + required: + - type + - text + title: Reasoning text + description: Reasoning text from the model. + BetaSummaryTextContent: + properties: + type: + type: string + enum: + - summary_text + description: The type of the object. Always `summary_text`. + default: summary_text + x-stainless-const: true + text: + type: string + description: A summary of the reasoning output from the model so far. + type: object + required: + - type + - text + title: Summary text + description: A summary text from the model. + BetaResponseConfigurationUpdateItemParam: + type: object + description: | + An update to the conversation's response configuration. The configuration + remains in effect for subsequent responses until it is replaced by another + configuration update. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/Beta_AgentTagParam' + description: The agent that produced this item. + - type: 'null' + id: + anyOf: + - type: string + description: The unique ID of the configuration update item. + example: cnfu_123 + - type: 'null' + type: + type: string + enum: + - configuration_update + description: The item type. Always `configuration_update`. + default: configuration_update + x-stainless-const: true + reasoning: + type: object + description: Updates to reasoning configuration. Only effort is supported. properties: - stream_id: - type: string + effort: + $ref: '#/components/schemas/BetaReasoningEffort' description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseWebSearchCallWsCompleted - description: Emitted when a web search call is completed. - allOf: - - $ref: '#/components/schemas/BetaResponseWebSearchCallCompletedEvent' - - type: object - properties: - stream_id: + The reasoning effort to use for subsequent responses until another + configuration update replaces it. + required: + - type + BetaAdditionalToolsItemParam: + properties: + agent: + anyOf: + - $ref: '#/components/schemas/Beta_AgentTagParam' + description: The agent that produced this item. + - type: 'null' + id: + anyOf: + - type: string + description: The unique ID of this additional tools item. + example: at_123 + - type: 'null' + type: + type: string + enum: + - additional_tools + description: The item type. Always `additional_tools`. + default: additional_tools + x-stainless-const: true + role: + type: string + enum: + - developer + description: The role that provided the additional tools. Only `developer` is supported. + default: developer + x-stainless-const: true + tools: + items: + $ref: '#/components/schemas/BetaTool' + type: array + description: A list of additional tools made available at this item. + type: object + required: + - type + - role + - tools + BetaToolSearchOutputItemParam: + properties: + agent: + anyOf: + - $ref: '#/components/schemas/Beta_AgentTagParam' + description: The agent that produced this item. + - type: 'null' + id: + anyOf: + - type: string + description: The unique ID of this tool search output. + example: tso_123 + - type: 'null' + call_id: + anyOf: + - type: string + maxLength: 64 + minLength: 1 + description: The unique ID of the tool search call generated by the model. + - type: 'null' + type: + type: string + enum: + - tool_search_output + description: The item type. Always `tool_search_output`. + default: tool_search_output + x-stainless-const: true + execution: + $ref: '#/components/schemas/BetaToolSearchExecutionType' + description: Whether tool search was executed by the server or by the client. + tools: + items: + $ref: '#/components/schemas/BetaTool' + type: array + description: The loaded tool definitions returned by the tool search output. + status: + anyOf: + - $ref: '#/components/schemas/BetaFunctionCallItemStatus' + description: The status of the tool search output. + - type: 'null' + type: object + required: + - type + - tools + BetaFunctionCallItemStatus: + type: string + enum: + - in_progress + - completed + - incomplete + BetaToolSearchCallItemParam: + properties: + agent: + anyOf: + - $ref: '#/components/schemas/Beta_AgentTagParam' + description: The agent that produced this item. + - type: 'null' + id: + anyOf: + - type: string + description: The unique ID of this tool search call. + example: tsc_123 + - type: 'null' + call_id: + anyOf: + - type: string + maxLength: 64 + minLength: 1 + description: The unique ID of the tool search call generated by the model. + - type: 'null' + type: + type: string + enum: + - tool_search_call + description: The item type. Always `tool_search_call`. + default: tool_search_call + x-stainless-const: true + execution: + $ref: '#/components/schemas/BetaToolSearchExecutionType' + description: Whether tool search was executed by the server or by the client. + arguments: + $ref: '#/components/schemas/BetaEmptyModelParam' + description: The arguments supplied to the tool search call. + status: + anyOf: + - $ref: '#/components/schemas/BetaFunctionCallItemStatus' + description: The status of the tool search call. + - type: 'null' + type: object + required: + - type + - arguments + BetaMultiAgentCallOutputItemParam: + properties: + agent: + anyOf: + - $ref: '#/components/schemas/Beta_AgentTagParam' + description: The agent that produced this item. + - type: 'null' + id: + anyOf: + - type: string + description: The unique ID of this multi-agent call output. + example: maco_123 + - type: 'null' + call_id: + type: string + maxLength: 64 + minLength: 1 + description: The unique ID of the multi-agent call. + type: + type: string + enum: + - multi_agent_call_output + description: The item type. Always `multi_agent_call_output`. + default: multi_agent_call_output + x-stainless-const: true + action: + $ref: '#/components/schemas/BetaMultiAgentAction1' + description: The multi-agent action that produced this result. + output: + items: + $ref: '#/components/schemas/BetaOutputTextContentParam' + type: array + description: Text output returned by the multi-agent action. + type: object + required: + - call_id + - type + - action + - output + x-oai-beta: responses_multi_agent=v1 + BetaOutputTextContentParam: + properties: + type: + type: string + enum: + - output_text + description: The content type. Always `output_text`. + default: output_text + x-stainless-const: true + text: + type: string + maxLength: 10485760 + description: The text content. + annotations: + items: + discriminator: + propertyName: type + anyOf: + - $ref: '#/components/schemas/BetaFileCitationParam' + - $ref: '#/components/schemas/BetaUrlCitationParam' + - $ref: '#/components/schemas/BetaContainerFileCitationParam' + type: array + description: Citations associated with the text content. + type: object + required: + - type + - text + BetaContainerFileCitationParam: + properties: + type: + type: string + enum: + - container_file_citation + description: The citation type. Always `container_file_citation`. + default: container_file_citation + x-stainless-const: true + start_index: + type: integer + minimum: 0 + description: The index of the first character of the citation in the message. + end_index: + type: integer + minimum: 0 + description: The index of the last character of the citation in the message. + container_id: + type: string + description: The ID of the container. + example: cntr_123 + file_id: + type: string + description: The ID of the container file. + example: cfile_123 + filename: + type: string + description: The filename of the container file cited. + type: object + required: + - type + - start_index + - end_index + - container_id + - file_id + - filename + BetaUrlCitationParam: + properties: + type: + type: string + enum: + - url_citation + description: The citation type. Always `url_citation`. + default: url_citation + x-stainless-const: true + start_index: + type: integer + minimum: 0 + description: The index of the first character of the citation in the message. + end_index: + type: integer + minimum: 0 + description: The index of the last character of the citation in the message. + url: + type: string + format: uri + description: The URL of the cited resource. + title: + type: string + description: The title of the cited resource. + type: object + required: + - type + - start_index + - end_index + - url + - title + BetaFileCitationParam: + properties: + type: + type: string + enum: + - file_citation + description: The citation type. Always `file_citation`. + default: file_citation + x-stainless-const: true + index: + type: integer + minimum: 0 + description: The index of the file in the list of files. + file_id: + type: string + description: The ID of the file. + example: file-123 + filename: + type: string + description: The filename of the file cited. + type: object + required: + - type + - index + - file_id + - filename + BetaMultiAgentAction1: + type: string + enum: + - spawn_agent + - interrupt_agent + - list_agents + - send_message + - followup_task + - wait_agent + BetaMultiAgentCallItemParam: + properties: + agent: + anyOf: + - $ref: '#/components/schemas/Beta_AgentTagParam' + description: The agent that produced this item. + - type: 'null' + id: + anyOf: + - type: string + description: The unique ID of this multi-agent call. + example: mac_123 + - type: 'null' + call_id: + type: string + maxLength: 64 + minLength: 1 + description: The unique ID linking this call to its output. + type: + type: string + enum: + - multi_agent_call + description: The item type. Always `multi_agent_call`. + default: multi_agent_call + x-stainless-const: true + action: + $ref: '#/components/schemas/BetaMultiAgentAction1' + description: The multi-agent action that was executed. + arguments: + type: string + description: The action arguments as a JSON string. + type: object + required: + - call_id + - type + - action + - arguments + x-oai-beta: responses_multi_agent=v1 + BetaAgentMessageItemParam: + properties: + agent: + anyOf: + - $ref: '#/components/schemas/Beta_AgentTagParam' + description: The agent that produced this item. + - type: 'null' + id: + anyOf: + - type: string + description: The unique ID of this agent message item. + example: amsg_123 + - type: 'null' + type: + type: string + enum: + - agent_message + description: The item type. Always `agent_message`. + default: agent_message + x-stainless-const: true + author: + type: string + description: The sending agent identity. + recipient: + type: string + description: The destination agent identity. + content: + items: + discriminator: + propertyName: type + description: A plaintext, image, or encrypted agent message content part. + anyOf: + - $ref: '#/components/schemas/BetaInputTextContentParam' + - $ref: '#/components/schemas/BetaInputImageContentParamAutoParam' + - $ref: '#/components/schemas/BetaEncryptedContentParam' + type: array + description: Plaintext, image, or encrypted content sent between agents. + type: object + required: + - type + - author + - recipient + - content + title: Agent message + description: A message routed between agents. + x-oai-beta: responses_multi_agent=v1 + BetaEncryptedContentParam: + properties: + type: + type: string + enum: + - encrypted_content + description: The type of the input item. Always `encrypted_content`. + default: encrypted_content + x-stainless-const: true + encrypted_content: + type: string + maxLength: 10485760 + description: Opaque encrypted content. + type: object + required: + - type + - encrypted_content + title: Encrypted content + description: Opaque encrypted content that Responses API decrypts inside trusted model execution. + x-oai-beta: responses_multi_agent=v1 + BetaInputImageContentParamAutoParam: + properties: + type: + type: string + enum: + - input_image + description: The type of the input item. Always `input_image`. + default: input_image + x-stainless-const: true + image_url: + anyOf: + - type: string + maxLength: 20971520 + format: uri + description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - type: 'null' + file_id: + anyOf: + - type: string + description: The ID of the file to be sent to the model. + example: file-123 + - type: 'null' + detail: + anyOf: + - $ref: '#/components/schemas/BetaDetailEnum' + description: The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - type: 'null' + prompt_cache_breakpoint: + anyOf: + - $ref: '#/components/schemas/BetaPromptCacheBreakpointParam' + - type: 'null' + type: object + required: + - type + title: Input image + description: An image input to the model. Learn about [image inputs](https://developers.openai.com/api/docs/guides/images-vision) + BetaPromptCacheBreakpointParam: + properties: + mode: + type: string + enum: + - explicit + description: The breakpoint mode. Always `explicit`. + default: explicit + x-stainless-const: true + type: object + required: + - mode + title: Prompt cache breakpoint + description: Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + BetaDetailEnum: + type: string + enum: + - low + - high + - auto + - original + BetaInputTextContentParam: + properties: + type: + type: string + enum: + - input_text + description: The type of the input item. Always `input_text`. + default: input_text + x-stainless-const: true + text: + type: string + maxLength: 10485760 + description: The text input to the model. + prompt_cache_breakpoint: + anyOf: + - $ref: '#/components/schemas/BetaPromptCacheBreakpointParam' + - type: 'null' + type: object + required: + - type + - text + title: Input text + description: A text input to the model. + BetaFunctionCallOutputItemParam: + properties: + agent: + anyOf: + - $ref: '#/components/schemas/Beta_AgentTagParam' + description: The agent that produced this item. + - type: 'null' + id: + anyOf: + - type: string + description: The unique ID of the function tool call output. Populated when this item is returned via API. + example: fc_123 + - type: 'null' + call_id: + anyOf: + - type: string + maxLength: 64 + minLength: 1 + description: The unique ID of the function tool call generated by the model. + - type: 'null' + type: + type: string + enum: + - function_call_output + description: The type of the function tool call output. Always `function_call_output`. + default: function_call_output + x-stainless-const: true + output: + description: Text, image, or file output of the function tool call. + anyOf: + - type: string + maxLength: 10485760 + description: A JSON string of the output of the function tool call. + - items: + discriminator: + propertyName: type + description: A piece of message content, such as text, an image, or a file. + anyOf: + - $ref: '#/components/schemas/BetaInputTextContentParam' + - $ref: '#/components/schemas/BetaInputImageContentParamAutoParam' + - $ref: '#/components/schemas/BetaInputFileContentParam' + type: array + description: An array of content outputs (text, image, file) for the function tool call. + name: + anyOf: + - type: string + maxLength: 128 + minLength: 1 + description: The name of the tool that produced the output. + - type: 'null' + namespace: + anyOf: + - type: string + maxLength: 64 + minLength: 1 + pattern: ^[a-zA-Z0-9_-]+$ + description: The namespace of the tool that produced the output. + - type: 'null' + caller: + anyOf: + - $ref: '#/components/schemas/BetaToolCallCallerParam' + description: The execution context that produced this tool call. + - type: 'null' + status: + anyOf: + - $ref: '#/components/schemas/BetaFunctionCallItemStatus' + description: The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + - type: 'null' + type: object + required: + - type + - output + title: Function tool call output + description: The output of a function tool call. + BetaInputFileContentParam: + properties: + type: + type: string + enum: + - input_file + description: The type of the input item. Always `input_file`. + default: input_file + x-stainless-const: true + file_id: + anyOf: + - type: string + description: The ID of the file to be sent to the model. + example: file-123 + - type: 'null' + filename: + anyOf: + - type: string + description: The name of the file to be sent to the model. + - type: 'null' + file_data: + anyOf: + - type: string + maxLength: 73400320 + description: The base64-encoded data of the file to be sent to the model. + - type: 'null' + file_url: + anyOf: + - type: string + format: uri + description: The URL of the file to be sent to the model. + - type: 'null' + detail: + $ref: '#/components/schemas/BetaFileDetailEnum' + description: The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + prompt_cache_breakpoint: + anyOf: + - $ref: '#/components/schemas/BetaPromptCacheBreakpointParam' + - type: 'null' + type: object + required: + - type + title: Input file + description: A file input to the model. + BetaFileDetailEnum: + type: string + enum: + - auto + - low + - high + BetaFunctionToolCall: + type: object + title: Function tool call + description: | + A tool call to run a function. See the + [function calling guide](https://developers.openai.com/api/docs/guides/function-calling) for more information. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that produced this item. + id: + type: string + description: | + The unique ID of the function tool call. + type: + type: string + enum: + - function_call + description: | + The type of the function tool call. Always `function_call`. + x-stainless-const: true + call_id: + type: string + description: | + The unique ID of the function tool call generated by the model. + caller: + anyOf: + - $ref: '#/components/schemas/BetaToolCallCaller' + - type: 'null' + namespace: + type: string + description: | + The namespace of the function to run. + name: + type: string + description: | + The name of the function to run. + arguments: + type: string + description: | + A JSON string of the arguments to pass to the function. + status: + type: string + description: | + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + enum: + - in_progress + - completed + - incomplete + async: + type: boolean + description: | + Whether the function tool call runs asynchronously. + required: + - type + - call_id + - name + - arguments + BetaWebSearchToolCall: + type: object + title: Web search tool call + description: | + The results of a web search tool call. See the + [web search guide](https://developers.openai.com/api/docs/guides/tools-web-search) for more information. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that produced this item. + id: + type: string + description: | + The unique ID of the web search tool call. + type: + type: string + enum: + - web_search_call + description: | + The type of the web search tool call. Always `web_search_call`. + x-stainless-const: true + status: + description: | + The status of the web search tool call. + $ref: '#/components/schemas/BetaWebSearchCallStatus' + action: + type: object + description: | + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). + discriminator: + propertyName: type + anyOf: + - $ref: '#/components/schemas/BetaWebSearchActionSearch' + - $ref: '#/components/schemas/BetaWebSearchActionOpenPage' + - $ref: '#/components/schemas/BetaWebSearchActionFind' + required: + - id + - type + - status + - action + BetaWebSearchActionFind: + type: object + title: Find action + description: | + Action type "find_in_page": Searches for a pattern within a loaded page. + properties: + type: + type: string + enum: + - find_in_page + description: | + The action type. + x-stainless-const: true + url: + type: string + format: uri + description: | + The URL of the page searched for the pattern. + pattern: + type: string + description: | + The pattern or text to search for within the page. + required: + - type + - url + - pattern + BetaWebSearchActionOpenPage: + type: object + title: Open page action + description: | + Action type "open_page" - Opens a specific URL from search results. + properties: + type: + type: string + enum: + - open_page + description: | + The action type. + x-stainless-const: true + url: + description: | + The URL opened by the model. + anyOf: + - type: string + format: uri + - type: 'null' + required: + - type + BetaWebSearchActionSearch: + type: object + title: Search action + description: | + Action type "search" - Performs a web search query. + properties: + type: + type: string + enum: + - search + description: | + The action type. + x-stainless-const: true + query: + type: string + deprecated: true + description: | + The search query. + queries: + type: array + title: Search queries + description: | + The search queries. + items: + type: string + description: | + A search query. + sources: + type: array + title: Web search sources + description: | + The sources used in the search. + items: + type: object + title: Web search source + description: | + A source used in the search. + properties: + type: + type: string + enum: + - url + description: | + The type of source. Always `url`. + x-stainless-const: true + url: + type: string + format: uri + description: | + The URL of the source. + required: + - type + - url + required: + - type + BetaWebSearchCallStatus: + type: string + enum: + - in_progress + - searching + - completed + - failed + - incomplete + BetaComputerCallOutputItemParam: + properties: + agent: + anyOf: + - $ref: '#/components/schemas/Beta_AgentTagParam' + description: The agent that produced this item. + - type: 'null' + id: + anyOf: + - type: string + description: The ID of the computer tool call output. + example: cuo_123 + - type: 'null' + call_id: + type: string + maxLength: 64 + minLength: 1 + description: The ID of the computer tool call that produced the output. + type: + type: string + enum: + - computer_call_output + description: The type of the computer tool call output. Always `computer_call_output`. + default: computer_call_output + x-stainless-const: true + output: + $ref: '#/components/schemas/BetaComputerScreenshotImage' + acknowledged_safety_checks: + anyOf: + - items: + $ref: '#/components/schemas/BetaComputerCallSafetyCheckParam' + type: array + description: The safety checks reported by the API that have been acknowledged by the developer. + - type: 'null' + status: + anyOf: + - $ref: '#/components/schemas/BetaFunctionCallItemStatus' + description: The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + - type: 'null' + type: object + required: + - call_id + - type + - output + title: Computer tool call output + description: The output of a computer tool call. + BetaComputerCallSafetyCheckParam: + properties: + id: + type: string + description: The ID of the pending safety check. + code: + anyOf: + - type: string + description: The type of the pending safety check. + - type: 'null' + message: + anyOf: + - type: string + description: Details about the pending safety check. + - type: 'null' + type: object + required: + - id + description: A pending safety check for the computer call. + BetaComputerScreenshotImage: + type: object + description: | + A computer screenshot image used with the computer use tool. + properties: + type: + type: string + enum: + - computer_screenshot + default: computer_screenshot + description: "Specifies the event type. For a computer screenshot, this property is \nalways set to `computer_screenshot`.\n" + x-stainless-const: true + image_url: + type: string + format: uri + description: The URL of the screenshot image. + file_id: + type: string + description: The identifier of an uploaded file that contains the screenshot. + required: + - type + BetaComputerToolCall: + type: object + title: Computer tool call + description: | + A tool call to a computer use tool. See the + [computer use guide](https://developers.openai.com/api/docs/guides/tools-computer-use) for more information. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that produced this item. + type: + type: string + description: The type of the computer call. Always `computer_call`. + enum: + - computer_call + default: computer_call + id: + type: string + description: The unique ID of the computer call. + call_id: + type: string + description: | + An identifier used when responding to the tool call with output. + action: + $ref: '#/components/schemas/BetaComputerAction' + actions: + $ref: '#/components/schemas/BetaComputerActionList' + pending_safety_checks: + type: array + items: + $ref: '#/components/schemas/BetaComputerCallSafetyCheckParam' + description: | + The pending safety checks for the computer call. + status: + type: string + description: | + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + enum: + - in_progress + - completed + - incomplete + required: + - type + - id + - call_id + - pending_safety_checks + - status + BetaComputerActionList: + title: Computer Action List + type: array + description: | + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. + items: + $ref: '#/components/schemas/BetaComputerAction' + BetaComputerAction: + discriminator: + propertyName: type + anyOf: + - $ref: '#/components/schemas/BetaClickParam' + - $ref: '#/components/schemas/BetaDoubleClickAction' + - $ref: '#/components/schemas/BetaDragParam' + - $ref: '#/components/schemas/BetaKeyPressAction' + - $ref: '#/components/schemas/BetaMoveParam' + - $ref: '#/components/schemas/BetaScreenshotParam' + - $ref: '#/components/schemas/BetaScrollParam' + - $ref: '#/components/schemas/BetaTypeParam' + - $ref: '#/components/schemas/BetaWaitParam' + BetaWaitParam: + properties: + type: + type: string + enum: + - wait + description: Specifies the event type. For a wait action, this property is always set to `wait`. + default: wait + x-stainless-const: true + type: object + required: + - type + title: Wait + description: A wait action. + BetaTypeParam: + properties: + type: + type: string + enum: + - type + description: Specifies the event type. For a type action, this property is always set to `type`. + default: type + x-stainless-const: true + text: + type: string + description: The text to type. + type: object + required: + - type + - text + title: Type + description: An action to type in text. + BetaScrollParam: + properties: + type: + type: string + enum: + - scroll + description: Specifies the event type. For a scroll action, this property is always set to `scroll`. + default: scroll + x-stainless-const: true + x: + type: integer + description: The x-coordinate where the scroll occurred. + y: + type: integer + description: The y-coordinate where the scroll occurred. + scroll_x: + type: integer + description: The horizontal scroll distance. + scroll_y: + type: integer + description: The vertical scroll distance. + keys: + anyOf: + - items: type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseWebSearchCallInWsProgress - description: Emitted when a web search call is initiated. - allOf: - - $ref: '#/components/schemas/BetaResponseWebSearchCallInProgressEvent' - - type: object - properties: - stream_id: + type: array + description: The keys being held while scrolling. + - type: 'null' + type: object + required: + - type + - x + - y + - scroll_x + - scroll_y + title: Scroll + description: A scroll action. + BetaScreenshotParam: + properties: + type: + type: string + enum: + - screenshot + description: Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + default: screenshot + x-stainless-const: true + type: object + required: + - type + title: Screenshot + description: A screenshot action. + BetaMoveParam: + properties: + type: + type: string + enum: + - move + description: Specifies the event type. For a move action, this property is always set to `move`. + default: move + x-stainless-const: true + x: + type: integer + description: The x-coordinate to move to. + y: + type: integer + description: The y-coordinate to move to. + keys: + anyOf: + - items: type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseWebSearchCallWsSearching - description: Emitted when a web search call is executing. - allOf: - - $ref: '#/components/schemas/BetaResponseWebSearchCallSearchingEvent' - - type: object - properties: - stream_id: + type: array + description: The keys being held while moving the mouse. + - type: 'null' + type: object + required: + - type + - x + - y + title: Move + description: A mouse move action. + BetaKeyPressAction: + properties: + type: + type: string + enum: + - keypress + description: Specifies the event type. For a keypress action, this property is always set to `keypress`. + default: keypress + x-stainless-const: true + keys: + items: + type: string + description: One of the keys the model is requesting to be pressed. + type: array + description: The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + type: object + required: + - type + - keys + title: KeyPress + description: A collection of keypresses the model would like to perform. + BetaDragParam: + properties: + type: + type: string + enum: + - drag + description: Specifies the event type. For a drag action, this property is always set to `drag`. + default: drag + x-stainless-const: true + path: + items: + $ref: '#/components/schemas/BetaCoordParam' + type: array + description: |- + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` + keys: + anyOf: + - items: type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseImageGenCallWsCompleted - description: | - Emitted when an image generation tool call has completed and the final image is available. - allOf: - - $ref: '#/components/schemas/BetaResponseImageGenCallCompletedEvent' - - type: object - properties: - stream_id: + type: array + description: The keys being held while dragging the mouse. + - type: 'null' + type: object + required: + - type + - path + title: Drag + description: A drag action. + BetaCoordParam: + properties: + x: + type: integer + description: The x-coordinate. + y: + type: integer + description: The y-coordinate. + type: object + required: + - x + - y + title: Coordinate + description: 'An x/y coordinate pair, e.g. `{ x: 100, y: 200 }`.' + BetaDoubleClickAction: + properties: + type: + type: string + enum: + - double_click + description: Specifies the event type. For a double click action, this property is always set to `double_click`. + default: double_click + x-stainless-const: true + x: + type: integer + description: The x-coordinate where the double click occurred. + y: + type: integer + description: The y-coordinate where the double click occurred. + keys: + anyOf: + - items: type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseImageGenCallWsGenerating - description: | - Emitted when an image generation tool call is actively generating an image (intermediate state). - allOf: - - $ref: '#/components/schemas/BetaResponseImageGenCallGeneratingEvent' - - type: object - properties: - stream_id: + type: array + description: The keys being held while double-clicking. + - type: 'null' + type: object + required: + - type + - x + - y + - keys + title: DoubleClick + description: A double click action. + BetaClickParam: + properties: + type: + type: string + enum: + - click + description: Specifies the event type. For a click action, this property is always `click`. + default: click + x-stainless-const: true + button: + $ref: '#/components/schemas/BetaClickButtonType' + description: Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + x: + type: integer + description: The x-coordinate where the click occurred. + y: + type: integer + description: The y-coordinate where the click occurred. + keys: + anyOf: + - items: type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseImageGenCallInWsProgress + type: array + description: The keys being held while clicking. + - type: 'null' + type: object + required: + - type + - button + - x + - y + title: Click + description: A click action. + BetaClickButtonType: + type: string + enum: + - left + - right + - wheel + - back + - forward + BetaFileSearchToolCall: + type: object + title: File search tool call + description: | + The results of a file search tool call. See the + [file search guide](https://developers.openai.com/api/docs/guides/tools-file-search) for more information. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that produced this item. + id: + type: string + description: | + The unique ID of the file search tool call. + type: + type: string + enum: + - file_search_call + description: | + The type of the file search tool call. Always `file_search_call`. + x-stainless-const: true + status: + type: string + description: | + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, + enum: + - in_progress + - searching + - completed + - incomplete + - failed + queries: + type: array + items: + type: string + description: | + The queries used to search for files. + results: + anyOf: + - type: array + description: | + The results of the file search tool call. + items: + type: object + properties: + file_id: + type: string + description: | + The unique ID of the file. + text: + type: string + description: | + The text that was retrieved from the file. + filename: + type: string + description: | + The name of the file. + attributes: + $ref: '#/components/schemas/BetaVectorStoreFileAttributes' + score: + type: number + format: float + description: | + The relevance score of the file - a value between 0 and 1. + - type: 'null' + required: + - id + - type + - status + - queries + BetaVectorStoreFileAttributes: + anyOf: + - type: object description: | - Emitted when an image generation tool call is in progress. - allOf: - - $ref: '#/components/schemas/BetaResponseImageGenCallInProgressEvent' - - type: object + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. Keys are strings + with a maximum length of 64 characters. Values are strings with a maximum + length of 512 characters, booleans, or numbers. + maxProperties: 16 + propertyNames: + type: string + maxLength: 64 + additionalProperties: + anyOf: + - type: string + maxLength: 512 + - type: number + - type: boolean + x-oaiTypeLabel: map + - type: 'null' + BetaOutputMessage: + type: object + title: Output message + description: | + An output message from the model. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that produced this item. + id: + type: string + description: | + The unique ID of the output message. + x-stainless-go-json: omitzero + type: + type: string + description: | + The type of the output message. Always `message`. + enum: + - message + x-stainless-const: true + role: + type: string + description: | + The role of the output message. Always `assistant`. + enum: + - assistant + x-stainless-const: true + content: + type: array + description: | + The content of the output message. + items: + $ref: '#/components/schemas/BetaOutputMessageContent' + phase: + anyOf: + - $ref: '#/components/schemas/BetaMessagePhase' + - type: 'null' + status: + type: string + description: | + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + enum: + - in_progress + - completed + - incomplete + required: + - id + - type + - role + - content + - status + BetaMessagePhase: + type: string + description: | + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + enum: + - commentary + - final_answer + BetaOutputMessageContent: + discriminator: + propertyName: type + anyOf: + - $ref: '#/components/schemas/BetaOutputTextContent' + - $ref: '#/components/schemas/BetaRefusalContent' + BetaRefusalContent: + properties: + type: + type: string + enum: + - refusal + description: The type of the refusal. Always `refusal`. + default: refusal + x-stainless-const: true + refusal: + type: string + description: The refusal explanation from the model. + type: object + required: + - type + - refusal + title: Refusal + description: A refusal from the model. + BetaOutputTextContent: + properties: + type: + type: string + enum: + - output_text + description: The type of the output text. Always `output_text`. + default: output_text + x-stainless-const: true + text: + type: string + description: The text output from the model. + annotations: + items: + $ref: '#/components/schemas/BetaAnnotation' + type: array + description: The annotations of the text output. + logprobs: + items: + $ref: '#/components/schemas/BetaLogProb' + type: array + type: object + required: + - type + - text + - annotations + title: Output text + description: A text output from the model. + BetaLogProb: + properties: + token: + type: string + logprob: + type: number + bytes: + items: + type: integer + type: array + top_logprobs: + items: + $ref: '#/components/schemas/BetaTopLogProb' + type: array + type: object + required: + - token + - logprob + - bytes + - top_logprobs + title: Log probability + description: The log probability of a token. + BetaTopLogProb: + properties: + token: + type: string + logprob: + type: number + bytes: + items: + type: integer + type: array + type: object + required: + - token + - logprob + - bytes + title: Top log probability + description: The top log probability of a token. + BetaAnnotation: + discriminator: + propertyName: type + description: An annotation that applies to a span of output text. + anyOf: + - $ref: '#/components/schemas/BetaFileCitationBody' + - $ref: '#/components/schemas/BetaUrlCitationBody' + - $ref: '#/components/schemas/BetaContainerFileCitationBody' + - $ref: '#/components/schemas/BetaFilePath' + BetaFilePath: + type: object + title: File path + description: | + A path to a file. + properties: + type: + type: string + description: | + The type of the file path. Always `file_path`. + enum: + - file_path + x-stainless-const: true + file_id: + type: string + description: | + The ID of the file. + index: + type: integer + description: | + The index of the file in the list of files. + required: + - type + - file_id + - index + BetaContainerFileCitationBody: + properties: + type: + type: string + enum: + - container_file_citation + description: The type of the container file citation. Always `container_file_citation`. + default: container_file_citation + x-stainless-const: true + container_id: + type: string + description: The ID of the container file. + file_id: + type: string + description: The ID of the file. + start_index: + type: integer + description: The index of the first character of the container file citation in the message. + end_index: + type: integer + description: The index of the last character of the container file citation in the message. + filename: + type: string + description: The filename of the container file cited. + type: object + required: + - type + - container_id + - file_id + - start_index + - end_index + - filename + title: Container file citation + description: A citation for a container file used to generate a model response. + BetaUrlCitationBody: + properties: + type: + type: string + enum: + - url_citation + description: The type of the URL citation. Always `url_citation`. + default: url_citation + x-stainless-const: true + url: + type: string + format: uri + description: The URL of the web resource. + start_index: + type: integer + description: The index of the first character of the URL citation in the message. + end_index: + type: integer + description: The index of the last character of the URL citation in the message. + title: + type: string + description: The title of the web resource. + type: object + required: + - type + - url + - start_index + - end_index + - title + title: URL citation + description: A citation for a web resource used to generate a model response. + BetaFileCitationBody: + properties: + type: + type: string + enum: + - file_citation + description: The type of the file citation. Always `file_citation`. + default: file_citation + x-stainless-const: true + file_id: + type: string + description: The ID of the file. + index: + type: integer + description: The index of the file in the list of files. + filename: + type: string + description: The filename of the file cited. + type: object + required: + - type + - file_id + - index + - filename + title: File citation + description: A citation to a file. + BetaInputMessage: + type: object + title: Input message + description: | + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that produced this item. + type: + type: string + description: | + The type of the message input. Always set to `message`. + enum: + - message + x-stainless-const: true + role: + type: string + description: | + The role of the message input. One of `user`, `system`, or `developer`. + enum: + - user + - system + - developer + status: + type: string + description: | + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + enum: + - in_progress + - completed + - incomplete + content: + $ref: '#/components/schemas/BetaInputMessageContentList' + required: + - role + - content + BetaInputMessageContentList: + type: array + title: Input item content list + description: "A list of one or many input items to the model, containing different content \ntypes.\n" + items: + $ref: '#/components/schemas/BetaInputContent' + BetaInputContent: + discriminator: + propertyName: type + anyOf: + - $ref: '#/components/schemas/BetaInputTextContent' + - $ref: '#/components/schemas/BetaInputImageContent' + - $ref: '#/components/schemas/BetaInputFileContent' + BetaEasyInputMessage: + type: object + title: Input message + description: | + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. + properties: + role: + type: string + description: | + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. + enum: + - user + - assistant + - system + - developer + content: + description: | + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. + anyOf: + - type: string + title: Text input + description: | + A text input to the model. + - $ref: '#/components/schemas/BetaInputMessageContentList' + phase: + anyOf: + - $ref: '#/components/schemas/BetaMessagePhase' + - type: 'null' + type: + type: string + description: | + The type of the message input. Always `message`. + enum: + - message + x-stainless-const: true + required: + - role + - content + BetaCompactResponseMethodPublicBody: + properties: + model: + $ref: '#/components/schemas/BetaModelIdsCompaction' + input: + anyOf: + - description: Text, image, or file inputs to the model, used to generate a response + anyOf: + - type: string + maxLength: 10485760 + description: A text input to the model, equivalent to a text input with the `user` role. + - items: + $ref: '#/components/schemas/BetaInputItem' + type: array + maxItems: 131072 + description: A list of one or many input items to the model, containing different content types. + - type: 'null' + previous_response_id: + anyOf: + - type: string + description: The unique ID of the previous response to the model. Use this to create multi-turn conversations. Learn more about [conversation state](https://developers.openai.com/api/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + example: resp_123 + - type: 'null' + instructions: + anyOf: + - type: string + description: |- + A system (or developer) message inserted into the model's context. + When used along with `previous_response_id`, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses. + - type: 'null' + prompt_cache_key: + anyOf: + - type: string + maxLength: 64 + description: A key to use when reading from or writing to the prompt cache. + - type: 'null' + prompt_cache_retention: + anyOf: + - $ref: '#/components/schemas/BetaPromptCacheRetentionEnum' + description: How long to retain a prompt cache entry created by this request. + deprecated: true + - type: 'null' + prompt_cache_options: + anyOf: + - $ref: '#/components/schemas/BetaPromptCacheOptionsParam' + - type: 'null' + service_tier: + anyOf: + - $ref: '#/components/schemas/BetaServiceTierEnum' + description: |- + Specifies the processing type used for serving the request. - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - If set to '[flex](https://developers.openai.com/api/docs/guides/flex-processing)', then the request will be processed with the Flex Processing service tier. - To opt-in to [Fast mode](https://developers.openai.com/api/docs/guides/fast-mode) at the request level, include the `service_tier=fast` or `service_tier=priority` parameter for Responses or Chat Completions. For models with a dedicated Fast tier, either value resolves to `service_tier=fast`; for other models, either value resolves to `service_tier=priority`. - When not set, the default behavior is 'auto'. + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + - type: 'null' + type: object + required: + - model + BetaServiceTierEnum: + type: string + enum: + - auto + - default + - fast + - flex + - priority + BetaPromptCacheOptionsParam: + properties: + ttl: + $ref: '#/components/schemas/BetaPromptCacheTTLEnum' + description: The minimum lifetime applied to every implicit and explicit cache breakpoint written by the request. Defaults to `30m`, which is currently the only supported value. The backend may retain cache entries for longer. + mode: + $ref: '#/components/schemas/BetaPromptCacheModeEnum' + description: Controls whether OpenAI automatically creates an implicit cache breakpoint. Defaults to `implicit`. With `implicit`, OpenAI creates one implicit breakpoint and writes up to the latest three explicit breakpoints in the request. With `explicit`, OpenAI does not create an implicit breakpoint and writes up to the latest four explicit breakpoints. If there are no explicit breakpoints, the request does not use prompt caching. + type: object + required: [] + title: Prompt cache options + description: Options for prompt caching. Supported for `gpt-5.6` and later models. By default, OpenAI automatically chooses one implicit cache breakpoint. You can add explicit breakpoints to content blocks with `prompt_cache_breakpoint`. Each request can write up to four breakpoints. For cache matching, OpenAI considers up to the latest 80 breakpoints in the conversation, without a content-block lookback limit. Set `mode` to `explicit` to disable the implicit breakpoint. The `ttl` defaults to `30m`, which is currently the only supported value. See the [prompt caching guide](https://developers.openai.com/api/docs/guides/prompt-caching) for current details. + BetaPromptCacheModeEnum: + type: string + enum: + - implicit + - explicit + BetaPromptCacheTTLEnum: + type: string + enum: + - 30m + BetaPromptCacheRetentionEnum: + type: string + enum: + - in_memory + - 24h + BetaModelIdsCompaction: + anyOf: + - $ref: '#/components/schemas/BetaModelIdsResponses' + - type: string + - type: 'null' + description: Model ID used to generate the response, like `gpt-6-astra`. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](https://developers.openai.com/api/docs/models) to browse and compare available models. + BetaModelIdsResponses: + example: gpt-6-astra + anyOf: + - $ref: '#/components/schemas/BetaModelIdsShared' + - type: string + title: ResponsesOnlyModel + enum: + - o1-pro + - o1-pro-2025-03-19 + - o3-pro + - o3-pro-2025-06-10 + - o3-deep-research + - o3-deep-research-2025-06-26 + - o4-mini-deep-research + - o4-mini-deep-research-2025-06-26 + - computer-use-preview + - computer-use-preview-2025-03-11 + - gpt-5.5-pro + - gpt-5.5-pro-2026-04-23 + - gpt-5-codex + - gpt-5-pro + - gpt-5-pro-2025-10-06 + - gpt-5.1-codex-max + - gpt-daybreak-blue-latest + - gpt-daybreak-red-latest + - gpt-5.6-cyber + BetaModelIdsShared: + example: gpt-6-astra + anyOf: + - type: string + - $ref: '#/components/schemas/ChatModel' + BetaErrorResponse: + type: object + properties: + error: + $ref: '#/components/schemas/BetaError' + required: + - error + BetaError: + type: object + properties: + code: + anyOf: + - type: string + - type: 'null' + message: + type: string + param: + anyOf: + - type: string + - type: 'null' + type: + type: string + misalignment: + $ref: '#/components/schemas/BetaMisalignmentErrorDetailsResource' + required: + - type + - message + - param + - code + BetaMisalignmentErrorDetailsResource: + properties: + error_type: + $ref: '#/components/schemas/Beta_MisalignmentErrorType' + description: An optional classification; clients must accept additional values. + detailed_explanation: + type: string + description: The public explanation for this block. + steer: + $ref: '#/components/schemas/Beta_MisalignmentSteer' + description: An optional public continuation instruction. + type: object + required: [] + Beta_MisalignmentSteer: + properties: + message: + type: string + description: The public continuation instruction. + type: object + required: + - message + Beta_MisalignmentErrorType: + anyOf: + - type: string + - type: string + enum: + - potentially_unintended_data_transfer + - potentially_unintended_data_access + - potentially_unintended_destructive_activity + - other + BetaResponseItemList: + type: object + description: A list of Response items. + properties: + object: + x-stainless-const: true + description: The type of object returned, must be `list`. + const: list + data: + type: array + description: A list of items used to generate this response. + items: + $ref: '#/components/schemas/BetaItemResource' + has_more: + type: boolean + description: Whether there are more items available. + first_id: + type: string + description: The ID of the first item in the list. + last_id: + type: string + description: The ID of the last item in the list. + required: + - object + - data + - has_more + - first_id + - last_id + x-oaiMeta: + name: The input item list + group: responses + example: | + { + "object": "list", + "data": [ + { + "id": "msg_abc123", + "type": "message", + "role": "user", + "content": [ + { + "type": "input_text", + "text": "Tell me a three sentence bedtime story about a unicorn." + } + ] + } + ], + "first_id": "msg_abc123", + "last_id": "msg_abc123", + "has_more": false + } + BetaItemResource: + description: | + Content item used to generate a response. + discriminator: + propertyName: type + anyOf: + - $ref: '#/components/schemas/BetaInputMessageResource' + - $ref: '#/components/schemas/BetaOutputMessage' + - $ref: '#/components/schemas/BetaFileSearchToolCall' + - $ref: '#/components/schemas/BetaComputerToolCall' + - $ref: '#/components/schemas/BetaComputerToolCallOutputResource' + - $ref: '#/components/schemas/BetaWebSearchToolCall' + - $ref: '#/components/schemas/BetaFunctionToolCallResource' + - $ref: '#/components/schemas/BetaFunctionToolCallOutputResource' + - $ref: '#/components/schemas/BetaAgentMessage' + - $ref: '#/components/schemas/BetaMultiAgentCall' + - $ref: '#/components/schemas/BetaMultiAgentCallOutput' + - $ref: '#/components/schemas/BetaToolSearchCall' + - $ref: '#/components/schemas/BetaToolSearchOutput' + - $ref: '#/components/schemas/BetaAdditionalTools' + - $ref: '#/components/schemas/BetaResponseConfigurationUpdate' + - $ref: '#/components/schemas/BetaReasoningItem' + - $ref: '#/components/schemas/BetaProgram' + - $ref: '#/components/schemas/BetaProgramOutput' + - $ref: '#/components/schemas/BetaCompactionBody' + - $ref: '#/components/schemas/BetaImageGenToolCall' + - $ref: '#/components/schemas/BetaCodeInterpreterToolCall' + - $ref: '#/components/schemas/BetaLocalShellToolCall' + - $ref: '#/components/schemas/BetaLocalShellToolCallOutput' + - $ref: '#/components/schemas/BetaFunctionShellCall' + - $ref: '#/components/schemas/BetaFunctionShellCallOutput' + - $ref: '#/components/schemas/BetaApplyPatchToolCall' + - $ref: '#/components/schemas/BetaApplyPatchToolCallOutput' + - $ref: '#/components/schemas/BetaMCPListTools' + - $ref: '#/components/schemas/BetaMCPApprovalRequest' + - $ref: '#/components/schemas/BetaMCPApprovalResponseResource' + - $ref: '#/components/schemas/BetaMCPToolCall' + - $ref: '#/components/schemas/BetaCustomToolCallResource' + - $ref: '#/components/schemas/BetaCustomToolCallOutputResource' + BetaCustomToolCallOutputResource: + title: ResponseCustomToolCallOutputItem + allOf: + - $ref: '#/components/schemas/BetaCustomToolCallOutput' + - type: object + properties: + id: + type: string + description: | + The unique ID of the custom tool call output item. + status: + description: | + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + $ref: '#/components/schemas/BetaFunctionCallOutputStatusEnum' + created_by: + type: string + description: | + The identifier of the actor that created the item. + required: + - id + - status + BetaFunctionCallOutputStatusEnum: + type: string + enum: + - in_progress + - completed + - incomplete + BetaCustomToolCallResource: + title: ResponseCustomToolCallItem + allOf: + - $ref: '#/components/schemas/BetaCustomToolCall' + - type: object + properties: + id: + type: string + description: | + The unique ID of the custom tool call item. + status: + description: | + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + $ref: '#/components/schemas/BetaFunctionCallStatus' + created_by: + type: string + description: | + The identifier of the actor that created the item. + required: + - id + - status + BetaFunctionCallStatus: + type: string + enum: + - in_progress + - completed + - incomplete + BetaMCPApprovalResponseResource: + type: object + title: MCP approval response + description: | + A response to an MCP approval request. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that produced this item. + type: + type: string + enum: + - mcp_approval_response + description: | + The type of the item. Always `mcp_approval_response`. + x-stainless-const: true + id: + type: string + description: | + The unique ID of the approval response + approval_request_id: + type: string + description: | + The ID of the approval request being answered. + approve: + type: boolean + description: | + Whether the request was approved. + reason: + anyOf: + - type: string + description: | + Optional reason for the decision. + - type: 'null' + required: + - type + - id + - request_id + - approve + - approval_request_id + BetaApplyPatchToolCallOutput: + properties: + agent: + $ref: '#/components/schemas/BetaAgentTag' + description: The agent that produced this item. + type: + type: string + enum: + - apply_patch_call_output + description: The type of the item. Always `apply_patch_call_output`. + default: apply_patch_call_output + x-stainless-const: true + id: + type: string + description: The unique ID of the apply patch tool call output. Populated when this item is returned via API. + call_id: + type: string + description: The unique ID of the apply patch tool call generated by the model. + caller: + anyOf: + - $ref: '#/components/schemas/BetaToolCallCaller' + description: The execution context that produced this tool call. + - type: 'null' + status: + $ref: '#/components/schemas/BetaApplyPatchCallOutputStatus' + description: The status of the apply patch tool call output. One of `completed` or `failed`. + output: + anyOf: + - type: string + description: Optional textual output returned by the apply patch tool. + - type: 'null' + created_by: + type: string + description: The ID of the entity that created this tool call output. + type: object + required: + - type + - id + - call_id + - status + title: Apply patch tool call output + description: The output emitted by an apply patch tool call. + BetaApplyPatchCallOutputStatus: + type: string + enum: + - completed + - failed + BetaApplyPatchToolCall: + properties: + agent: + $ref: '#/components/schemas/BetaAgentTag' + description: The agent that produced this item. + type: + type: string + enum: + - apply_patch_call + description: The type of the item. Always `apply_patch_call`. + default: apply_patch_call + x-stainless-const: true + id: + type: string + description: The unique ID of the apply patch tool call. Populated when this item is returned via API. + call_id: + type: string + description: The unique ID of the apply patch tool call generated by the model. + caller: + anyOf: + - $ref: '#/components/schemas/BetaToolCallCaller' + description: The execution context that produced this tool call. + - type: 'null' + status: + $ref: '#/components/schemas/BetaApplyPatchCallStatus' + description: The status of the apply patch tool call. One of `in_progress` or `completed`. + operation: + discriminator: + propertyName: type + title: Apply patch operation + description: One of the create_file, delete_file, or update_file operations applied via apply_patch. + anyOf: + - $ref: '#/components/schemas/BetaApplyPatchCreateFileOperation' + - $ref: '#/components/schemas/BetaApplyPatchDeleteFileOperation' + - $ref: '#/components/schemas/BetaApplyPatchUpdateFileOperation' + created_by: + type: string + description: The ID of the entity that created this tool call. + type: object + required: + - type + - id + - call_id + - status + - operation + title: Apply patch tool call + description: A tool call that applies file diffs by creating, deleting, or updating files. + BetaApplyPatchUpdateFileOperation: + properties: + type: + type: string + enum: + - update_file + description: Update an existing file with the provided diff. + default: update_file + x-stainless-const: true + path: + type: string + description: Path of the file to update. + diff: + type: string + description: Diff to apply. + type: object + required: + - type + - path + - diff + title: Apply patch update file operation + description: Instruction describing how to update a file via the apply_patch tool. + BetaApplyPatchDeleteFileOperation: + properties: + type: + type: string + enum: + - delete_file + description: Delete the specified file. + default: delete_file + x-stainless-const: true + path: + type: string + description: Path of the file to delete. + type: object + required: + - type + - path + title: Apply patch delete file operation + description: Instruction describing how to delete a file via the apply_patch tool. + BetaApplyPatchCreateFileOperation: + properties: + type: + type: string + enum: + - create_file + description: Create a new file with the provided diff. + default: create_file + x-stainless-const: true + path: + type: string + description: Path of the file to create. + diff: + type: string + description: Diff to apply. + type: object + required: + - type + - path + - diff + title: Apply patch create file operation + description: Instruction describing how to create a file via the apply_patch tool. + BetaApplyPatchCallStatus: + type: string + enum: + - in_progress + - completed + BetaFunctionShellCallOutput: + properties: + agent: + $ref: '#/components/schemas/BetaAgentTag' + description: The agent that produced this item. + type: + type: string + enum: + - shell_call_output + description: The type of the shell call output. Always `shell_call_output`. + default: shell_call_output + x-stainless-const: true + id: + type: string + description: The unique ID of the shell call output. Populated when this item is returned via API. + call_id: + type: string + description: The unique ID of the shell tool call generated by the model. + caller: + anyOf: + - $ref: '#/components/schemas/BetaToolCallCaller' + description: The execution context that produced this tool call. + - type: 'null' + status: + $ref: '#/components/schemas/BetaFunctionShellCallOutputStatusEnum' + description: The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + output: + items: + $ref: '#/components/schemas/BetaFunctionShellCallOutputContent' + type: array + description: An array of shell call output contents + max_output_length: + anyOf: + - type: integer + description: The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - type: 'null' + created_by: + type: string + description: The identifier of the actor that created the item. + type: object + required: + - type + - id + - call_id + - status + - output + - max_output_length + title: Shell call output + description: The output of a shell tool call that was emitted. + BetaFunctionShellCallOutputContent: + properties: + stdout: + type: string + description: The standard output that was captured. + stderr: + type: string + description: The standard error output that was captured. + outcome: + discriminator: + propertyName: type + title: Shell call outcome + description: Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + anyOf: + - $ref: '#/components/schemas/BetaFunctionShellCallOutputTimeoutOutcome' + - $ref: '#/components/schemas/BetaFunctionShellCallOutputExitOutcome' + created_by: + type: string + description: The identifier of the actor that created the item. + type: object + required: + - stdout + - stderr + - outcome + title: Shell call output content + description: The content of a shell tool call output that was emitted. + BetaFunctionShellCallOutputExitOutcome: + properties: + type: + type: string + enum: + - exit + description: The outcome type. Always `exit`. + default: exit + x-stainless-const: true + exit_code: + type: integer + description: Exit code from the shell process. + type: object + required: + - type + - exit_code + title: Shell call exit outcome + description: Indicates that the shell commands finished and returned an exit code. + BetaFunctionShellCallOutputTimeoutOutcome: + properties: + type: + type: string + enum: + - timeout + description: The outcome type. Always `timeout`. + default: timeout + x-stainless-const: true + type: object + required: + - type + title: Shell call timeout outcome + description: Indicates that the shell call exceeded its configured time limit. + BetaFunctionShellCallOutputStatusEnum: + type: string + enum: + - in_progress + - completed + - incomplete + BetaFunctionShellCall: + properties: + agent: + $ref: '#/components/schemas/BetaAgentTag' + description: The agent that produced this item. + type: + type: string + enum: + - shell_call + description: The type of the item. Always `shell_call`. + default: shell_call + x-stainless-const: true + id: + type: string + description: The unique ID of the shell tool call. Populated when this item is returned via API. + call_id: + type: string + description: The unique ID of the shell tool call generated by the model. + caller: + anyOf: + - $ref: '#/components/schemas/BetaToolCallCaller' + description: The execution context that produced this tool call. + - type: 'null' + action: + $ref: '#/components/schemas/BetaFunctionShellAction' + description: The shell commands and limits that describe how to run the tool call. + status: + $ref: '#/components/schemas/BetaFunctionShellCallStatus' + description: The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + environment: + anyOf: + - discriminator: + propertyName: type + anyOf: + - $ref: '#/components/schemas/BetaLocalEnvironmentResource' + - $ref: '#/components/schemas/BetaContainerReferenceResource' + - type: 'null' + created_by: + type: string + description: The ID of the entity that created this tool call. + type: object + required: + - type + - id + - call_id + - action + - status + - environment + title: Shell tool call + description: A tool call that executes one or more shell commands in a managed environment. + BetaContainerReferenceResource: + properties: + type: + type: string + enum: + - container_reference + description: The environment type. Always `container_reference`. + default: container_reference + x-stainless-const: true + container_id: + type: string + type: object + required: + - type + - container_id + title: Container Reference + description: Represents a container created with /v1/containers. + BetaLocalEnvironmentResource: + properties: + type: + type: string + enum: + - local + description: The environment type. Always `local`. + default: local + x-stainless-const: true + type: object + required: + - type + title: Local Environment + description: Represents the use of a local environment to perform shell actions. + BetaFunctionShellCallStatus: + type: string + enum: + - in_progress + - completed + - incomplete + BetaFunctionShellAction: + properties: + commands: + items: + type: string + description: A list of commands to run. + type: array + timeout_ms: + anyOf: + - type: integer + description: Optional timeout in milliseconds for the commands. + - type: 'null' + max_output_length: + anyOf: + - type: integer + description: Optional maximum number of characters to return from each command. + - type: 'null' + type: object + required: + - commands + - timeout_ms + - max_output_length + title: Shell exec action + description: Execute a shell command. + BetaCompactionBody: + properties: + agent: + $ref: '#/components/schemas/BetaAgentTag' + description: The agent that produced this item. + type: + type: string + enum: + - compaction + description: The type of the item. Always `compaction`. + default: compaction + x-stainless-const: true + id: + type: string + description: The unique ID of the compaction item. + encrypted_content: + type: string + description: The encrypted content that was produced by compaction. + created_by: + type: string + description: The identifier of the actor that created the item. + type: object + required: + - type + - id + - encrypted_content + title: Compaction item + description: A compaction item generated by the [`v1/responses/compact` API](https://developers.openai.com/api/reference/resources/responses/methods/compact). + BetaProgramOutput: + properties: + agent: + $ref: '#/components/schemas/BetaAgentTag' + description: The agent that produced this item. + type: + type: string + enum: + - program_output + description: The type of the item. Always `program_output`. + default: program_output + x-stainless-const: true + id: + type: string + description: The unique ID of the program output item. + call_id: + type: string + description: The call ID of the program item. + result: + type: string + description: The result produced by the program item. + status: + $ref: '#/components/schemas/BetaProgramOutputStatus' + description: The terminal status of the program output item. + type: object + required: + - type + - id + - call_id + - result + - status + BetaProgramOutputStatus: + type: string + enum: + - completed + - incomplete + BetaProgram: + properties: + agent: + $ref: '#/components/schemas/BetaAgentTag' + description: The agent that produced this item. + type: + type: string + enum: + - program + description: The type of the item. Always `program`. + default: program + x-stainless-const: true + id: + type: string + description: The unique ID of the program item. + call_id: + type: string + description: The stable call ID of the program item. + code: + type: string + description: The JavaScript source executed by programmatic tool calling. + fingerprint: + type: string + description: Opaque program replay fingerprint that must be round-tripped. + type: object + required: + - type + - id + - call_id + - code + - fingerprint + BetaResponseConfigurationUpdate: + type: object + description: | + A configuration update that applies to subsequent responses until it is + replaced by another configuration update. + properties: + agent: + $ref: '#/components/schemas/BetaAgentTag' + description: The agent that produced this item. + id: + type: string + description: The unique ID of the configuration update item. + example: cnfu_123 + type: + type: string + enum: + - configuration_update + description: The item type. Always `configuration_update`. + default: configuration_update + x-stainless-const: true + reasoning: + type: object + description: The reasoning configuration applied by this update. properties: - stream_id: - type: string + effort: + $ref: '#/components/schemas/BetaReasoningEffort' description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseImageGenCallPartialWsImage - description: | - Emitted when a partial image is available during image generation streaming. - allOf: - - $ref: '#/components/schemas/BetaResponseImageGenCallPartialImageEvent' - - type: object + The reasoning effort used for subsequent responses until another + configuration update replaces it. + required: + - id + - type + BetaAdditionalTools: + properties: + agent: + $ref: '#/components/schemas/BetaAgentTag' + description: The agent that produced this item. + type: + type: string + enum: + - additional_tools + description: The type of the item. Always `additional_tools`. + default: additional_tools + x-stainless-const: true + id: + type: string + description: The unique ID of the additional tools item. + role: + $ref: '#/components/schemas/BetaMessageRole' + description: The role that provided the additional tools. + tools: + items: + $ref: '#/components/schemas/BetaTool' + type: array + description: The additional tool definitions made available at this item. + type: object + required: + - type + - id + - role + - tools + BetaMessageRole: + type: string + enum: + - unknown + - user + - assistant + - system + - critic + - discriminator + - developer + - tool + BetaToolSearchOutput: + properties: + agent: + $ref: '#/components/schemas/BetaAgentTag' + description: The agent that produced this item. + type: + type: string + enum: + - tool_search_output + description: The type of the item. Always `tool_search_output`. + default: tool_search_output + x-stainless-const: true + id: + type: string + description: The unique ID of the tool search output item. + call_id: + anyOf: + - type: string + description: The unique ID of the tool search call generated by the model. + - type: 'null' + execution: + $ref: '#/components/schemas/BetaToolSearchExecutionType' + description: Whether tool search was executed by the server or by the client. + tools: + items: + $ref: '#/components/schemas/BetaTool' + type: array + description: The loaded tool definitions returned by tool search. + status: + $ref: '#/components/schemas/BetaFunctionCallOutputStatusEnum' + description: The status of the tool search output item that was recorded. + created_by: + type: string + description: The identifier of the actor that created the item. + type: object + required: + - type + - id + - call_id + - execution + - tools + - status + BetaToolSearchCall: + properties: + agent: + $ref: '#/components/schemas/BetaAgentTag' + description: The agent that produced this item. + type: + type: string + enum: + - tool_search_call + description: The type of the item. Always `tool_search_call`. + default: tool_search_call + x-stainless-const: true + id: + type: string + description: The unique ID of the tool search call item. + call_id: + anyOf: + - type: string + description: The unique ID of the tool search call generated by the model. + - type: 'null' + execution: + $ref: '#/components/schemas/BetaToolSearchExecutionType' + description: Whether tool search was executed by the server or by the client. + arguments: + description: Arguments used for the tool search call. + status: + $ref: '#/components/schemas/BetaFunctionCallStatus' + description: The status of the tool search call item that was recorded. + created_by: + type: string + description: The identifier of the actor that created the item. + type: object + required: + - type + - id + - call_id + - execution + - arguments + - status + BetaMultiAgentCallOutput: + properties: + agent: + $ref: '#/components/schemas/BetaAgentTag' + description: The agent that produced this item. + type: + type: string + enum: + - multi_agent_call_output + description: The type of the multi-agent result. Always `multi_agent_call_output`. + default: multi_agent_call_output + x-stainless-const: true + id: + type: string + description: The unique ID of the multi-agent call output item. + call_id: + type: string + description: The unique ID of the multi-agent call. + action: + $ref: '#/components/schemas/BetaMultiAgentAction' + description: The multi-agent action that produced this result. + output: + items: + $ref: '#/components/schemas/BetaOutputTextContent' + type: array + description: Text output returned by the multi-agent action. + type: object + required: + - type + - id + - call_id + - action + - output + x-oai-beta: responses_multi_agent=v1 + BetaMultiAgentAction: + type: string + enum: + - spawn_agent + - interrupt_agent + - list_agents + - send_message + - followup_task + - wait_agent + BetaMultiAgentCall: + properties: + agent: + $ref: '#/components/schemas/BetaAgentTag' + description: The agent that produced this item. + type: + type: string + enum: + - multi_agent_call + description: The type of the multi-agent call. Always `multi_agent_call`. + default: multi_agent_call + x-stainless-const: true + id: + type: string + description: The unique ID of the multi-agent call item. + call_id: + type: string + description: The unique ID linking this call to its output. + action: + $ref: '#/components/schemas/BetaMultiAgentAction' + description: The multi-agent action to execute. + arguments: + type: string + description: The JSON string of arguments generated for the action. + type: object + required: + - type + - id + - call_id + - action + - arguments + x-oai-beta: responses_multi_agent=v1 + BetaAgentMessage: + properties: + agent: + $ref: '#/components/schemas/BetaAgentTag' + description: The agent that produced this item. + type: + type: string + enum: + - agent_message + description: The type of the item. Always `agent_message`. + default: agent_message + x-stainless-const: true + id: + type: string + description: The unique ID of the agent message. + author: + type: string + description: The sending agent identity. + recipient: + type: string + description: The destination agent identity. + content: + items: + discriminator: + propertyName: type + description: A content part that makes up an input or output item. + anyOf: + - $ref: '#/components/schemas/BetaInputTextContent' + - $ref: '#/components/schemas/BetaOutputTextContent' + - $ref: '#/components/schemas/BetaTextContent' + - $ref: '#/components/schemas/BetaSummaryTextContent' + - $ref: '#/components/schemas/BetaReasoningTextContent' + - $ref: '#/components/schemas/BetaRefusalContent' + - $ref: '#/components/schemas/BetaInputImageContent' + - $ref: '#/components/schemas/BetaComputerScreenshotContent' + - $ref: '#/components/schemas/BetaInputFileContent' + - $ref: '#/components/schemas/BetaEncryptedContent' + type: array + description: Encrypted content sent between agents. + type: object + required: + - type + - id + - author + - recipient + - content + x-oai-beta: responses_multi_agent=v1 + BetaEncryptedContent: + properties: + type: + type: string + enum: + - encrypted_content + description: The type of the input item. Always `encrypted_content`. + default: encrypted_content + x-stainless-const: true + encrypted_content: + type: string + description: Opaque encrypted content. + type: object + required: + - type + - encrypted_content + title: Encrypted content + description: Opaque encrypted content that Responses API decrypts inside trusted model execution. + x-oai-beta: responses_multi_agent=v1 + BetaComputerScreenshotContent: + properties: + type: + type: string + enum: + - computer_screenshot + description: Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + default: computer_screenshot + x-stainless-const: true + image_url: + anyOf: + - type: string + format: uri + description: The URL of the screenshot image. + - type: 'null' + file_id: + anyOf: + - type: string + description: The identifier of an uploaded file that contains the screenshot. + - type: 'null' + detail: + $ref: '#/components/schemas/BetaImageDetail' + description: The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + prompt_cache_breakpoint: + $ref: '#/components/schemas/BetaPromptCacheBreakpointConfig' + type: object + required: + - type + - image_url + - file_id + - detail + title: Computer screenshot + description: A screenshot of a computer. + BetaTextContent: + properties: + type: + type: string + enum: + - text + default: text + x-stainless-const: true + text: + type: string + type: object + required: + - type + - text + title: Text Content + description: A text content. + BetaFunctionToolCallOutputResource: + allOf: + - $ref: '#/components/schemas/BetaFunctionToolCallOutput' + - type: object + properties: + id: + type: string + description: | + The unique ID of the function call tool output. + status: + description: | + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + $ref: '#/components/schemas/BetaFunctionCallOutputStatusEnum' + created_by: + type: string + description: | + The identifier of the actor that created the item. + required: + - id + - status + BetaFunctionToolCallOutput: + type: object + title: Function tool call output + description: | + The output of a function tool call. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that produced this item. + id: + type: string + description: | + The unique ID of the function tool call output. Populated when this item + is returned via API. + type: + type: string + enum: + - function_call_output + description: | + The type of the function tool call output. Always `function_call_output`. + x-stainless-const: true + call_id: + type: string + description: | + The unique ID of the function tool call generated by the model. + name: + type: string + description: | + The name of the tool that produced the output. + namespace: + type: string + description: | + The namespace of the tool that produced the output. + caller: + anyOf: + - $ref: '#/components/schemas/BetaToolCallCallerParam' + - type: 'null' + output: + description: | + The output from the function call generated by your code. + Can be a string or an list of output content. + anyOf: + - type: string + description: | + A string of the output of the function call. + title: string output + - type: array + items: + $ref: '#/components/schemas/BetaFunctionAndCustomToolCallOutput' + title: output content list + description: | + Text, image, or file output of the function call. + status: + type: string + description: | + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + enum: + - in_progress + - completed + - incomplete + required: + - type + - output + BetaFunctionToolCallResource: + allOf: + - $ref: '#/components/schemas/BetaFunctionToolCall' + - type: object + properties: + id: + type: string + description: | + The unique ID of the function tool call. + status: + description: | + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + $ref: '#/components/schemas/BetaFunctionCallStatus' + created_by: + type: string + description: | + The identifier of the actor that created the item. + required: + - id + - status + BetaComputerToolCallOutputResource: + allOf: + - $ref: '#/components/schemas/BetaComputerToolCallOutput' + - type: object + properties: + id: + type: string + description: | + The unique ID of the computer call tool output. + status: + description: | + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + $ref: '#/components/schemas/BetaComputerCallOutputStatus' + created_by: + type: string + description: | + The identifier of the actor that created the item. + required: + - id + - status + BetaComputerCallOutputStatus: + type: string + enum: + - completed + - incomplete + - failed + BetaComputerToolCallOutput: + type: object + title: Computer tool call output + description: | + The output of a computer tool call. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that produced this item. + type: + type: string + description: | + The type of the computer tool call output. Always `computer_call_output`. + enum: + - computer_call_output + default: computer_call_output + x-stainless-const: true + id: + type: string + description: | + The ID of the computer tool call output. + call_id: + type: string + description: | + The ID of the computer tool call that produced the output. + acknowledged_safety_checks: + type: array + description: | + The safety checks reported by the API that have been acknowledged by the + developer. + items: + $ref: '#/components/schemas/BetaComputerCallSafetyCheckParam' + output: + $ref: '#/components/schemas/BetaComputerScreenshotImage' + status: + type: string + description: | + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + enum: + - in_progress + - completed + - incomplete + required: + - type + - call_id + - output + BetaInputMessageResource: + allOf: + - $ref: '#/components/schemas/BetaInputMessage' + - type: object + properties: + id: + type: string + description: | + The unique ID of the message input. + required: + - id + - type + BetaCompactResource: + properties: + id: + type: string + description: The unique identifier for the compacted response. + object: + type: string + enum: + - response.compaction + description: The object type. Always `response.compaction`. + default: response.compaction + x-stainless-const: true + output: + type: array + description: The compacted list of output items. This is a list of all user messages, followed by a single compaction item. + items: + $ref: '#/components/schemas/BetaOutputItem' + created_at: + type: integer + format: unixtime + description: Unix timestamp (in seconds) when the compacted conversation was created. + usage: + $ref: '#/components/schemas/BetaResponseUsage' + description: Token accounting for the compaction pass, including cached, reasoning, and total tokens. + type: object + required: + - id + - object + - output + - created_at + - usage + title: The compacted response object + BetaResponseUsage: + type: object + description: | + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. + properties: + input_tokens: + type: integer + description: The number of input tokens. + input_tokens_details: + type: object + description: A detailed breakdown of the input tokens. properties: - stream_id: - type: string + cached_tokens: + type: integer description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseMcpCallArgumentsWsDelta - description: | - Emitted when there is a delta (partial update) to the arguments of an MCP tool call. - allOf: - - $ref: '#/components/schemas/BetaResponseMCPCallArgumentsDeltaEvent' - - type: object + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://developers.openai.com/api/docs/guides/prompt-caching). + cache_write_tokens: + type: integer + description: The number of input tokens that were written to the cache. + required: + - cached_tokens + - cache_write_tokens + output_tokens: + type: integer + description: The number of output tokens. + output_tokens_details: + type: object + description: A detailed breakdown of the output tokens. properties: - stream_id: - type: string + reasoning_tokens: + type: integer + description: The number of reasoning tokens. + required: + - reasoning_tokens + total_tokens: + type: integer + description: The total number of tokens used. + required: + - input_tokens + - input_tokens_details + - output_tokens + - output_tokens_details + - total_tokens + BetaItemField: + discriminator: + propertyName: type + description: An item representing a message, tool call, tool output, reasoning, or other response element. + anyOf: + - $ref: '#/components/schemas/BetaMessage' + - $ref: '#/components/schemas/BetaProgram' + - $ref: '#/components/schemas/BetaProgramOutput' + - $ref: '#/components/schemas/BetaFunctionToolCall' + - $ref: '#/components/schemas/BetaMultiAgentCall' + - $ref: '#/components/schemas/BetaMultiAgentCallOutput' + - $ref: '#/components/schemas/BetaToolSearchCall' + - $ref: '#/components/schemas/BetaToolSearchOutput' + - $ref: '#/components/schemas/BetaAdditionalTools' + - $ref: '#/components/schemas/BetaAgentMessage' + - $ref: '#/components/schemas/BetaFunctionToolCallOutput' + - $ref: '#/components/schemas/BetaFileSearchToolCall' + - $ref: '#/components/schemas/BetaWebSearchToolCall' + - $ref: '#/components/schemas/BetaImageGenToolCall' + - $ref: '#/components/schemas/BetaComputerToolCall' + - $ref: '#/components/schemas/BetaComputerToolCallOutputResource' + - $ref: '#/components/schemas/BetaReasoningItem' + - $ref: '#/components/schemas/BetaCompactionBody' + - $ref: '#/components/schemas/BetaCodeInterpreterToolCall' + - $ref: '#/components/schemas/BetaLocalShellToolCall' + deprecated: true + - $ref: '#/components/schemas/BetaLocalShellToolCallOutput' + deprecated: true + - $ref: '#/components/schemas/BetaFunctionShellCall' + - $ref: '#/components/schemas/BetaFunctionShellCallOutput' + - $ref: '#/components/schemas/BetaApplyPatchToolCall' + - $ref: '#/components/schemas/BetaApplyPatchToolCallOutput' + - $ref: '#/components/schemas/BetaMCPListTools' + - $ref: '#/components/schemas/BetaMCPApprovalRequest' + - $ref: '#/components/schemas/BetaMCPApprovalResponseResource' + - $ref: '#/components/schemas/BetaMCPToolCall' + - $ref: '#/components/schemas/BetaCustomToolCall' + - $ref: '#/components/schemas/BetaCustomToolCallOutput' + BetaMessage: + properties: + agent: + $ref: '#/components/schemas/BetaAgentTag' + description: The agent that produced this item. + type: + type: string + enum: + - message + description: The type of the message. Always set to `message`. + default: message + x-stainless-const: true + id: + type: string + description: The unique ID of the message. + status: + $ref: '#/components/schemas/BetaMessageStatus' + description: The status of item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + role: + $ref: '#/components/schemas/BetaMessageRole' + description: The role of the message. One of `unknown`, `user`, `assistant`, `system`, `critic`, `discriminator`, `developer`, or `tool`. + content: + items: + discriminator: + propertyName: type + description: A content part that makes up an input or output item. + anyOf: + - $ref: '#/components/schemas/BetaInputTextContent' + - $ref: '#/components/schemas/BetaOutputTextContent' + - $ref: '#/components/schemas/BetaTextContent' + - $ref: '#/components/schemas/BetaSummaryTextContent' + - $ref: '#/components/schemas/BetaReasoningTextContent' + - $ref: '#/components/schemas/BetaRefusalContent' + - $ref: '#/components/schemas/BetaInputImageContent' + - $ref: '#/components/schemas/BetaComputerScreenshotContent' + - $ref: '#/components/schemas/BetaInputFileContent' + - $ref: '#/components/schemas/BetaEncryptedContent' + type: array + description: The content of the message + phase: + anyOf: + - $ref: '#/components/schemas/BetaMessagePhase-2' + description: Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + - type: 'null' + type: object + required: + - type + - id + - status + - role + - content + title: Message + description: A message to or from the model. + BetaMessagePhase-2: + type: string + enum: + - commentary + - final_answer + BetaMessageStatus: + type: string + enum: + - in_progress + - completed + - incomplete + BetaResponseCustomToolCallInputDoneEvent: + title: ResponseCustomToolCallInputDone + type: object + description: | + Event indicating that input for a custom tool call is complete. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + enum: + - response.custom_tool_call_input.done + description: The event type identifier. + x-stainless-const: true + sequence_number: + type: integer + description: The sequence number of this event. + output_index: + type: integer + description: The index of the output this event applies to. + item_id: + type: string + description: Unique identifier for the API item associated with this event. + input: + type: string + description: The complete input data for the custom tool call. + required: + - type + - output_index + - item_id + - input + - sequence_number + x-oaiMeta: + name: response.custom_tool_call_input.done + group: responses + example: | + { + "type": "response.custom_tool_call_input.done", + "output_index": 0, + "item_id": "ctc_1234567890abcdef", + "input": "final complete input text" + } + BetaResponseCustomToolCallInputDeltaEvent: + title: ResponseCustomToolCallInputDelta + type: object + description: | + Event representing a delta (partial update) to the input of a custom tool call. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + enum: + - response.custom_tool_call_input.delta + description: The event type identifier. + x-stainless-const: true + sequence_number: + type: integer + description: The sequence number of this event. + output_index: + type: integer + description: The index of the output this delta applies to. + item_id: + type: string + description: Unique identifier for the API item associated with this event. + delta: + type: string + description: The incremental input data (delta) for the custom tool call. + required: + - type + - output_index + - item_id + - delta + - sequence_number + x-oaiMeta: + name: response.custom_tool_call_input.delta + group: responses + example: | + { + "type": "response.custom_tool_call_input.delta", + "output_index": 0, + "item_id": "ctc_1234567890abcdef", + "delta": "partial input text" + } + BetaResponseQueuedEvent: + type: object + title: ResponseQueuedEvent + description: | + Emitted when a response is queued and waiting to be processed. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + enum: + - response.queued + description: The type of the event. Always 'response.queued'. + x-stainless-const: true + response: + $ref: '#/components/schemas/BetaResponse' + description: The full response object that is queued. + sequence_number: + type: integer + description: The sequence number for this event. + required: + - type + - response + - sequence_number + x-oaiMeta: + name: response.queued + group: responses + example: | + { + "type": "response.queued", + "response": { + "id": "res_123", + "status": "queued", + "created_at": "2021-01-01T00:00:00Z", + "updated_at": "2021-01-01T00:00:00Z" + }, + "sequence_number": 1 + } + BetaResponse: + title: The response object + allOf: + - $ref: '#/components/schemas/BetaModelResponseProperties' + - $ref: '#/components/schemas/BetaResponseProperties' + - type: object + properties: + service_tier: + $ref: '#/components/schemas/BetaServiceTierResponses' + truncation: + anyOf: + - type: string description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseMcpCallArgumentsWsDone - description: | - Emitted when the arguments for an MCP tool call are finalized. - allOf: - - $ref: '#/components/schemas/BetaResponseMCPCallArgumentsDoneEvent' - - type: object - properties: - stream_id: - type: string + The truncation strategy to use for the model response. + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. + enum: + - auto + - disabled + default: disabled + - type: 'null' + id: + type: string + description: | + Unique identifier for this Response. + object: + type: string + description: | + The object type of this resource - always set to `response`. + enum: + - response + x-stainless-const: true + status: + type: string + description: | + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. + enum: + - completed + - failed + - in_progress + - cancelled + - queued + - incomplete + created_at: + type: number + format: unixtime + description: | + Unix timestamp (in seconds) of when this Response was created. + completed_at: + anyOf: + - type: number + format: unixtime description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseMcpCallWsCompleted - description: | - Emitted when an MCP tool call has completed successfully. - allOf: - - $ref: '#/components/schemas/BetaResponseMCPCallCompletedEvent' - - type: object - properties: - stream_id: - type: string + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. + - type: 'null' + error: + $ref: '#/components/schemas/BetaResponseError' + incomplete_details: + anyOf: + - type: object description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseMcpCallWsFailed - description: | - Emitted when an MCP tool call has failed. - allOf: - - $ref: '#/components/schemas/BetaResponseMCPCallFailedEvent' - - type: object - properties: - stream_id: - type: string + Details about why the response is incomplete. + properties: + reason: + type: string + description: | + The reason why the response is incomplete. `steered` means + the response stopped at a safe output boundary after a + WebSocket `response.steer` event. The server can then create + a successor response automatically with the queued input. + enum: + - max_output_tokens + - max_messages + - content_filter + - steered + - type: 'null' + output: + type: array + description: | + An array of content items generated by the model. + + - The length and order of items in the `output` array is dependent + on the model's response. + - Rather than accessing the first item in the `output` array and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. + items: + $ref: '#/components/schemas/BetaOutputItem' + reasoning: + anyOf: + - $ref: '#/components/schemas/BetaReasoning' + - type: 'null' + instructions: + anyOf: + - description: | + A system (or developer) message inserted into the model's context. + + When using along with `previous_response_id`, the instructions from a previous + response will not be carried over to the next response. This makes it simple + to swap out system (or developer) messages in new responses. + anyOf: + - type: string + description: | + A text input to the model, equivalent to a text input with the + `developer` role. + - type: array + title: Input item list + description: | + A list of one or many input items to the model, containing + different content types. + items: + $ref: '#/components/schemas/BetaInputItem' + - type: 'null' + output_text: + anyOf: + - type: string description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseMcpCallInWsProgress - description: | - Emitted when an MCP tool call is in progress. - allOf: - - $ref: '#/components/schemas/BetaResponseMCPCallInProgressEvent' - - type: object - properties: - stream_id: - type: string + SDK-only convenience property that contains the aggregated text output + from all `output_text` items in the `output` array, if any are present. + Supported in the Python and JavaScript SDKs. + x-oaiSupportedSDKs: + - python + - javascript + - type: 'null' + x-stainless-skip: true + usage: + $ref: '#/components/schemas/BetaResponseUsage' + prompt_cache_options: + $ref: '#/components/schemas/BetaPromptCacheOptions' + prompt_cache_diagnostics: + $ref: '#/components/schemas/BetaPromptCacheDiagnostics' + moderation: + anyOf: + - $ref: '#/components/schemas/BetaModeration' description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseMcpListToolsWsCompleted + Moderation results for the response input and output, if moderated completions were requested. + - type: 'null' + parallel_tool_calls: + type: boolean + description: | + Whether to allow the model to run tool calls in parallel. + default: true + conversation: + anyOf: + - $ref: '#/components/schemas/BetaResponseConversation' + - type: 'null' + max_output_tokens: + anyOf: + - description: | + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://developers.openai.com/api/docs/guides/reasoning). + type: integer + - type: 'null' + required: + - id + - object + - created_at + - error + - incomplete_details + - instructions + - model + - tools + - output + - parallel_tool_calls + - metadata + - tool_choice + - temperature + - top_p + BetaResponseConversation: + properties: + id: + type: string + description: The unique ID of the conversation that this response was associated with. + type: object + required: + - id + title: Conversation + description: The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + BetaModeration: + properties: + input: + discriminator: + propertyName: type + description: Moderation for the response input. + anyOf: + - $ref: '#/components/schemas/BetaModerationResultBody' + - $ref: '#/components/schemas/BetaModerationErrorBody' + output: + discriminator: + propertyName: type + description: Moderation for the response output. + anyOf: + - $ref: '#/components/schemas/BetaModerationResultBody' + - $ref: '#/components/schemas/BetaModerationErrorBody' + type: object + required: + - input + - output + title: Moderation + description: Moderation results or errors for the response input and output. + BetaModerationErrorBody: + properties: + type: + type: string + enum: + - error + description: The object type, which was always `error` for moderation failures. + default: error + x-stainless-const: true + code: + type: string + description: The error code. + message: + type: string + description: The error message. + type: object + required: + - type + - code + - message + title: Moderation error + description: An error produced while attempting moderation for the response input or output. + BetaModerationResultBody: + properties: + type: + type: string + enum: + - moderation_result + description: The object type, which was always `moderation_result` for successful moderation results. + default: moderation_result + x-stainless-const: true + model: + type: string + description: The moderation model that produced this result. + flagged: + type: boolean + description: A boolean indicating whether the content was flagged by any category. + categories: + additionalProperties: + type: boolean + type: object + description: A dictionary of moderation categories to booleans, True if the input is flagged under this category. + x-oaiTypeLabel: map + category_scores: + additionalProperties: + type: number + type: object + description: A dictionary of moderation categories to scores. + x-oaiTypeLabel: map + category_applied_input_types: + additionalProperties: + items: + $ref: '#/components/schemas/BetaModerationInputType' + type: array + type: object + description: Which modalities of input are reflected by the score for each category. + x-oaiTypeLabel: map + type: object + required: + - type + - model + - flagged + - categories + - category_scores + - category_applied_input_types + title: Moderation result + description: A moderation result produced for the response input or output. + BetaModerationInputType: + type: string + enum: + - text + - image + BetaPromptCacheDiagnostics: + discriminator: + propertyName: type + description: Prompt cache diagnostics requested for this response. + anyOf: + - $ref: '#/components/schemas/BetaPromptCacheMissDiagnosticsBody' + - $ref: '#/components/schemas/BetaPromptCacheHitDiagnosticsBody' + - $ref: '#/components/schemas/BetaPromptCacheComparisonResponseNotFoundDiagnosticsBody' + - $ref: '#/components/schemas/BetaPromptCacheUnavailableDiagnosticsBody' + BetaPromptCacheUnavailableDiagnosticsBody: + properties: + type: + type: string + enum: + - unavailable + default: unavailable + x-stainless-const: true + type: object + required: + - type + BetaPromptCacheComparisonResponseNotFoundDiagnosticsBody: + properties: + type: + type: string + enum: + - comparison_response_not_found + default: comparison_response_not_found + x-stainless-const: true + type: object + required: + - type + BetaPromptCacheHitDiagnosticsBody: + properties: + type: + type: string + enum: + - cache_hit + default: cache_hit + x-stainless-const: true + type: object + required: + - type + BetaPromptCacheMissDiagnosticsBody: + properties: + type: + type: string + enum: + - cache_miss + default: cache_miss + x-stainless-const: true + reason: + $ref: '#/components/schemas/BetaCacheMissReasonTypeEnum' + description: The reason prompt cache reuse did not occur. + cache_missed_tokens: + type: integer + description: The estimated number of input tokens affected after the first detected divergence. + comparison_reusable_tokens: + type: integer + description: The raw token count of the reusable prefix in the compared response. + type: object + required: + - type + - reason + - cache_missed_tokens + BetaCacheMissReasonTypeEnum: + type: string + enum: + - model_changed + - prompt_cache_key_changed + - tools_changed + - text_format_changed + - reasoning_effort_changed + - verbosity_changed + - context_compacted + - input_changed + - service_tier_changed + BetaPromptCacheOptions: + properties: + ttl: + $ref: '#/components/schemas/BetaPromptCacheTTLEnum' + description: The minimum lifetime applied to each cache breakpoint. + mode: + $ref: '#/components/schemas/BetaPromptCacheModeEnum' + description: Whether implicit prompt-cache breakpoints were enabled. + comparison_response_id: + anyOf: + - type: string + description: The response ID supplied as the prompt cache diagnostics comparison. + - type: 'null' + type: object + required: + - ttl + - mode + title: Prompt cache options + description: The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + BetaOutputItem: + discriminator: + propertyName: type + anyOf: + - $ref: '#/components/schemas/BetaOutputMessage' + - $ref: '#/components/schemas/BetaFileSearchToolCall' + - $ref: '#/components/schemas/BetaFunctionToolCall' + - $ref: '#/components/schemas/BetaFunctionToolCallOutputResource' + - $ref: '#/components/schemas/BetaAgentMessage' + - $ref: '#/components/schemas/BetaMultiAgentCall' + - $ref: '#/components/schemas/BetaMultiAgentCallOutput' + - $ref: '#/components/schemas/BetaWebSearchToolCall' + - $ref: '#/components/schemas/BetaComputerToolCall' + - $ref: '#/components/schemas/BetaComputerToolCallOutputResource' + - $ref: '#/components/schemas/BetaReasoningItem' + - $ref: '#/components/schemas/BetaProgram' + - $ref: '#/components/schemas/BetaProgramOutput' + - $ref: '#/components/schemas/BetaToolSearchCall' + - $ref: '#/components/schemas/BetaToolSearchOutput' + - $ref: '#/components/schemas/BetaAdditionalTools' + - $ref: '#/components/schemas/BetaCompactionBody' + - $ref: '#/components/schemas/BetaImageGenToolCall' + - $ref: '#/components/schemas/BetaCodeInterpreterToolCall' + - $ref: '#/components/schemas/BetaLocalShellToolCall' + - $ref: '#/components/schemas/BetaLocalShellToolCallOutput' + - $ref: '#/components/schemas/BetaFunctionShellCall' + - $ref: '#/components/schemas/BetaFunctionShellCallOutput' + - $ref: '#/components/schemas/BetaApplyPatchToolCall' + - $ref: '#/components/schemas/BetaApplyPatchToolCallOutput' + - $ref: '#/components/schemas/BetaMCPToolCall' + - $ref: '#/components/schemas/BetaMCPListTools' + - $ref: '#/components/schemas/BetaMCPApprovalRequest' + - $ref: '#/components/schemas/BetaMCPApprovalResponseResource' + - $ref: '#/components/schemas/BetaCustomToolCall' + - $ref: '#/components/schemas/BetaCustomToolCallOutputResource' + BetaResponseError: + anyOf: + - type: object description: | - Emitted when the list of available MCP tools has been successfully retrieved. - allOf: - - $ref: '#/components/schemas/BetaResponseMCPListToolsCompletedEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseMcpListToolsWsFailed + An error object returned when the model fails to generate a Response. + properties: + code: + $ref: '#/components/schemas/BetaResponseErrorCode' + message: + type: string + description: | + A human-readable description of the error. + misalignment: + $ref: '#/components/schemas/BetaMisalignmentErrorDetailsResource' + required: + - code + - message + - type: 'null' + BetaResponseErrorCode: + type: string + description: | + The error code for the response. + enum: + - server_error + - rate_limit_exceeded + - invalid_prompt + - data_residency_mismatch + - bio_policy + - misalignment_policy_violation + - vector_store_timeout + - invalid_image + - invalid_image_format + - invalid_base64_image + - invalid_image_url + - image_too_large + - image_too_small + - image_parse_error + - image_content_policy_violation + - invalid_image_mode + - image_file_too_large + - unsupported_image_media_type + - empty_image_file + - failed_to_download_image + - image_file_not_found + BetaServiceTierResponses: + anyOf: + - type: string description: | - Emitted when the attempt to list available MCP tools has failed. - allOf: - - $ref: '#/components/schemas/BetaResponseMCPListToolsFailedEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseMcpListToolsInWsProgress + Specifies the processing type used for serving the request. + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://developers.openai.com/api/docs/guides/flex-processing)', then the request will be processed with the Flex Processing service tier. + - To opt-in to [Fast mode](https://developers.openai.com/api/docs/guides/fast-mode) at the request level, include the `service_tier=fast` or `service_tier=priority` parameter for Responses or Chat Completions. The response will show `service_tier=priority` regardless of if you specify `service_tier=fast` or `priority` in your request. + - If set to 'ultrafast', then the request will be processed with the access-controlled Ultrafast Processing service tier. This tier is currently available for `gpt-5.6-sol`; a response served through it will show `service_tier=ultrafast`. + - When not set, the default behavior is 'auto'. + + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + enum: + - auto + - default + - flex + - scale + - priority + - fast + - ultrafast + default: auto + - type: 'null' + BetaResponseProperties: + type: object + properties: + previous_response_id: + anyOf: + - type: string + description: | + The unique ID of the previous response to the model. Use this to + create multi-turn conversations. Learn more about + [conversation state](https://developers.openai.com/api/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + - type: 'null' + model: + description: | + Model ID used to generate the response, like `gpt-6-astra`. OpenAI + offers a wide range of models with different capabilities, performance + characteristics, and price points. Refer to the [model guide](https://developers.openai.com/api/docs/models) + to browse and compare available models. + $ref: '#/components/schemas/BetaModelIdsResponses' + background: + anyOf: + - type: boolean + description: | + Whether to run the model response in the background. + [Learn more](https://developers.openai.com/api/docs/guides/background). + default: false + - type: 'null' + max_tool_calls: + anyOf: + - description: | + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + type: integer + - type: 'null' + text: + $ref: '#/components/schemas/BetaResponseTextParam' + tools: + $ref: '#/components/schemas/BetaToolsArray' + tool_choice: + $ref: '#/components/schemas/BetaToolChoiceParam' + prompt: + $ref: '#/components/schemas/BetaPrompt' + BetaPrompt: + anyOf: + - type: object description: | - Emitted when the system is in the process of retrieving the list of available MCP tools. - allOf: - - $ref: '#/components/schemas/BetaResponseMCPListToolsInProgressEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseOutputTextAnnotationWsAdded + Reference to a prompt template and its variables. + [Learn more](https://developers.openai.com/api/docs/guides/text?api-mode=responses#version-prompts-in-code). + required: + - id + properties: + id: + type: string + description: The unique identifier of the prompt template to use. + version: + anyOf: + - type: string + description: Optional version of the prompt template. + - type: 'null' + variables: + $ref: '#/components/schemas/BetaResponsePromptVariables' + - type: 'null' + BetaResponsePromptVariables: + anyOf: + - type: object + title: Prompt Variables description: | - Emitted when an annotation is added to output text content. - allOf: - - $ref: '#/components/schemas/BetaResponseOutputTextAnnotationAddedEvent' - - type: object + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. + x-oaiExpandable: true + x-oaiTypeLabel: map + additionalProperties: + x-oaiExpandable: true + x-oaiTypeLabel: map + anyOf: + - type: string + - $ref: '#/components/schemas/BetaInputTextContent' + - $ref: '#/components/schemas/BetaInputImageContent' + - $ref: '#/components/schemas/BetaInputFileContent' + - type: 'null' + BetaToolsArray: + type: array + description: | + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. + + We support the following categories of tools: + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://developers.openai.com/api/docs/guides/tools-web-search) + or [file search](https://developers.openai.com/api/docs/guides/tools-file-search). Learn more about + [built-in tools](https://developers.openai.com/api/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Built-in + connectors using `connector_id` are deprecated for models released after + September 1, 2026. Use `server_url` to connect to a remote MCP server, or + `tunnel_id` to connect through a Secure MCP Tunnel. Learn more about + [MCP Tools](https://developers.openai.com/api/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://developers.openai.com/api/docs/guides/function-calling). You can also use + custom tools to call your own code. + items: + $ref: '#/components/schemas/BetaTool' + BetaModelResponseProperties: + type: object + properties: + metadata: + $ref: '#/components/schemas/BetaMetadata' + top_logprobs: + anyOf: + - description: | + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. + type: integer + minimum: 0 + maximum: 20 + - type: 'null' + temperature: + anyOf: + - type: number + minimum: 0 + maximum: 2 + default: 1 + example: 1 + description: | + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. + - type: 'null' + top_p: + anyOf: + - type: number + minimum: 0 + maximum: 1 + default: 1 + example: 1 + description: | + An alternative to sampling with temperature, called nucleus sampling, + where the model considers the results of the tokens with top_p probability + mass. So 0.1 means only the tokens comprising the top 10% probability mass + are considered. + + We generally recommend altering this or `temperature` but not both. + - type: 'null' + user: + type: string + example: user-1234 + deprecated: true + description: | + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers). + safety_identifier: + anyOf: + - type: string + maxLength: 64 + example: safety-identifier-1234 + description: | + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers). + - type: 'null' + prompt_cache_key: + anyOf: + - type: string + example: prompt-cache-key-1234 + description: | + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://developers.openai.com/api/docs/guides/prompt-caching). + - type: 'null' + prompt_cache_retention: + deprecated: true + anyOf: + - type: string + enum: + - in_memory + - 24h + description: | + Deprecated. Use `prompt_cache_options.ttl` instead. + + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://developers.openai.com/api/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - type: 'null' + BetaMetadata: + anyOf: + - type: object + description: | + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. + + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. + additionalProperties: + type: string + x-oaiTypeLabel: map + - type: 'null' + BetaResponseOutputTextAnnotationAddedEvent: + type: object + title: ResponseOutputTextAnnotationAddedEvent + description: | + Emitted when an annotation is added to output text content. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + enum: + - response.output_text.annotation.added + description: The type of the event. Always 'response.output_text.annotation.added'. + x-stainless-const: true + item_id: + type: string + description: The unique identifier of the item to which the annotation is being added. + output_index: + type: integer + description: The index of the output item in the response's output array. + content_index: + type: integer + description: The index of the content part within the output item. + annotation_index: + type: integer + description: The index of the annotation within the content part. + sequence_number: + type: integer + description: The sequence number of this event. + annotation: + anyOf: + - $ref: '#/components/schemas/BetaAnnotation' + - type: 'null' + description: The annotation object being added. (See annotation schema for details.) + required: + - type + - item_id + - output_index + - content_index + - annotation_index + - annotation + - sequence_number + x-oaiMeta: + name: response.output_text.annotation.added + group: responses + example: | + { + "type": "response.output_text.annotation.added", + "item_id": "item-abc", + "output_index": 0, + "content_index": 0, + "annotation_index": 0, + "annotation": { + "type": "file_citation", + "file_id": "file-abc", + "index": 0, + "filename": "example.txt" + }, + "sequence_number": 1 + } + BetaResponseMCPListToolsInProgressEvent: + type: object + title: ResponseMCPListToolsInProgressEvent + description: | + Emitted when the system is in the process of retrieving the list of available MCP tools. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + enum: + - response.mcp_list_tools.in_progress + description: The type of the event. Always 'response.mcp_list_tools.in_progress'. + x-stainless-const: true + item_id: + type: string + description: The ID of the MCP tool call item that is being processed. + output_index: + type: integer + description: The index of the output item that is being processed. + sequence_number: + type: integer + description: The sequence number of this event. + required: + - type + - item_id + - output_index + - sequence_number + x-oaiMeta: + name: response.mcp_list_tools.in_progress + group: responses + example: | + { + "type": "response.mcp_list_tools.in_progress", + "sequence_number": 1, + "output_index": 0, + "item_id": "mcpl_682d4379df088191886b70f4ec39f90403937d5f622d7a90" + } + BetaResponseMCPListToolsFailedEvent: + type: object + title: ResponseMCPListToolsFailedEvent + description: | + Emitted when the attempt to list available MCP tools has failed. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + enum: + - response.mcp_list_tools.failed + description: The type of the event. Always 'response.mcp_list_tools.failed'. + x-stainless-const: true + item_id: + type: string + description: The ID of the MCP tool call item that failed. + output_index: + type: integer + description: The index of the output item that failed. + sequence_number: + type: integer + description: The sequence number of this event. + required: + - type + - item_id + - output_index + - sequence_number + x-oaiMeta: + name: response.mcp_list_tools.failed + group: responses + example: | + { + "type": "response.mcp_list_tools.failed", + "sequence_number": 1, + "output_index": 0, + "item_id": "mcpl_682d4379df088191886b70f4ec39f90403937d5f622d7a90" + } + BetaResponseMCPListToolsCompletedEvent: + type: object + title: ResponseMCPListToolsCompletedEvent + description: | + Emitted when the list of available MCP tools has been successfully retrieved. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + enum: + - response.mcp_list_tools.completed + description: The type of the event. Always 'response.mcp_list_tools.completed'. + x-stainless-const: true + item_id: + type: string + description: The ID of the MCP tool call item that produced this output. + output_index: + type: integer + description: The index of the output item that was processed. + sequence_number: + type: integer + description: The sequence number of this event. + required: + - type + - item_id + - output_index + - sequence_number + x-oaiMeta: + name: response.mcp_list_tools.completed + group: responses + example: | + { + "type": "response.mcp_list_tools.completed", + "sequence_number": 1, + "output_index": 0, + "item_id": "mcpl_682d4379df088191886b70f4ec39f90403937d5f622d7a90" + } + BetaResponseMCPCallInProgressEvent: + type: object + title: ResponseMCPCallInProgressEvent + description: | + Emitted when an MCP tool call is in progress. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + enum: + - response.mcp_call.in_progress + description: The type of the event. Always 'response.mcp_call.in_progress'. + x-stainless-const: true + sequence_number: + type: integer + description: The sequence number of this event. + output_index: + type: integer + description: The index of the output item in the response's output array. + item_id: + type: string + description: The unique identifier of the MCP tool call item being processed. + required: + - type + - output_index + - item_id + - sequence_number + x-oaiMeta: + name: response.mcp_call.in_progress + group: responses + example: | + { + "type": "response.mcp_call.in_progress", + "sequence_number": 1, + "output_index": 0, + "item_id": "mcp_682d437d90a88191bf88cd03aae0c3e503937d5f622d7a90" + } + BetaResponseMCPCallFailedEvent: + type: object + title: ResponseMCPCallFailedEvent + description: | + Emitted when an MCP tool call has failed. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + enum: + - response.mcp_call.failed + description: The type of the event. Always 'response.mcp_call.failed'. + x-stainless-const: true + item_id: + type: string + description: The ID of the MCP tool call item that failed. + output_index: + type: integer + description: The index of the output item that failed. + sequence_number: + type: integer + description: The sequence number of this event. + required: + - type + - item_id + - output_index + - sequence_number + x-oaiMeta: + name: response.mcp_call.failed + group: responses + example: | + { + "type": "response.mcp_call.failed", + "sequence_number": 1, + "item_id": "mcp_682d437d90a88191bf88cd03aae0c3e503937d5f622d7a90", + "output_index": 0 + } + BetaResponseMCPCallCompletedEvent: + type: object + title: ResponseMCPCallCompletedEvent + description: | + Emitted when an MCP tool call has completed successfully. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + enum: + - response.mcp_call.completed + description: The type of the event. Always 'response.mcp_call.completed'. + x-stainless-const: true + item_id: + type: string + description: The ID of the MCP tool call item that completed. + output_index: + type: integer + description: The index of the output item that completed. + sequence_number: + type: integer + description: The sequence number of this event. + required: + - type + - item_id + - output_index + - sequence_number + x-oaiMeta: + name: response.mcp_call.completed + group: responses + example: | + { + "type": "response.mcp_call.completed", + "sequence_number": 1, + "item_id": "mcp_682d437d90a88191bf88cd03aae0c3e503937d5f622d7a90", + "output_index": 0 + } + BetaResponseMCPCallArgumentsDoneEvent: + type: object + title: ResponseMCPCallArgumentsDoneEvent + description: | + Emitted when the arguments for an MCP tool call are finalized. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + enum: + - response.mcp_call_arguments.done + description: The type of the event. Always 'response.mcp_call_arguments.done'. + x-stainless-const: true + output_index: + type: integer + description: The index of the output item in the response's output array. + item_id: + type: string + description: The unique identifier of the MCP tool call item being processed. + arguments: + type: string + description: | + A JSON string containing the finalized arguments for the MCP tool call. + sequence_number: + type: integer + description: The sequence number of this event. + required: + - type + - output_index + - item_id + - arguments + - sequence_number + x-oaiMeta: + name: response.mcp_call_arguments.done + group: responses + example: | + { + "type": "response.mcp_call_arguments.done", + "output_index": 0, + "item_id": "item-abc", + "arguments": "{\"arg1\": \"value1\", \"arg2\": \"value2\"}", + "sequence_number": 1 + } + BetaResponseMCPCallArgumentsDeltaEvent: + type: object + title: ResponseMCPCallArgumentsDeltaEvent + description: | + Emitted when there is a delta (partial update) to the arguments of an MCP tool call. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + enum: + - response.mcp_call_arguments.delta + description: The type of the event. Always 'response.mcp_call_arguments.delta'. + x-stainless-const: true + output_index: + type: integer + description: The index of the output item in the response's output array. + item_id: + type: string + description: The unique identifier of the MCP tool call item being processed. + delta: + type: string + description: | + A JSON string containing the partial update to the arguments for the MCP tool call. + sequence_number: + type: integer + description: The sequence number of this event. + required: + - type + - output_index + - item_id + - delta + - sequence_number + x-oaiMeta: + name: response.mcp_call_arguments.delta + group: responses + example: | + { + "type": "response.mcp_call_arguments.delta", + "output_index": 0, + "item_id": "item-abc", + "delta": "{", + "sequence_number": 1 + } + BetaResponseImageGenCallPartialImageEvent: + type: object + title: ResponseImageGenCallPartialImageEvent + description: | + Emitted when a partial image is available during image generation streaming. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + enum: + - response.image_generation_call.partial_image + description: The type of the event. Always 'response.image_generation_call.partial_image'. + x-stainless-const: true + output_index: + type: integer + description: The index of the output item in the response's output array. + item_id: + type: string + description: The unique identifier of the image generation item being processed. + sequence_number: + type: integer + description: The sequence number of the image generation item being processed. + partial_image_index: + type: integer + description: 0-based index for the partial image (backend is 1-based, but this is 0-based for the user). + partial_image_b64: + type: string + description: Base64-encoded partial image data, suitable for rendering as an image. + size: + type: string + description: The image size that was used. + quality: + type: string + description: The image quality that was used. + background: + type: string + description: The background setting that was used. + output_format: + type: string + description: The output format that was used. + required: + - type + - output_index + - item_id + - sequence_number + - partial_image_index + - partial_image_b64 + x-oaiMeta: + name: response.image_generation_call.partial_image + group: responses + example: | + { + "type": "response.image_generation_call.partial_image", + "output_index": 0, + "item_id": "item-123", + "sequence_number": 0, + "partial_image_index": 0, + "partial_image_b64": "..." + } + BetaResponseImageGenCallInProgressEvent: + type: object + title: ResponseImageGenCallInProgressEvent + description: | + Emitted when an image generation tool call is in progress. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + enum: + - response.image_generation_call.in_progress + description: The type of the event. Always 'response.image_generation_call.in_progress'. + x-stainless-const: true + output_index: + type: integer + description: The index of the output item in the response's output array. + item_id: + type: string + description: The unique identifier of the image generation item being processed. + sequence_number: + type: integer + description: The sequence number of the image generation item being processed. + required: + - type + - output_index + - item_id + - sequence_number + x-oaiMeta: + name: response.image_generation_call.in_progress + group: responses + example: | + { + "type": "response.image_generation_call.in_progress", + "output_index": 0, + "item_id": "item-123", + "sequence_number": 0 + } + BetaResponseImageGenCallGeneratingEvent: + type: object + title: ResponseImageGenCallGeneratingEvent + description: | + Emitted when an image generation tool call is actively generating an image (intermediate state). + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + enum: + - response.image_generation_call.generating + description: The type of the event. Always 'response.image_generation_call.generating'. + x-stainless-const: true + output_index: + type: integer + description: The index of the output item in the response's output array. + item_id: + type: string + description: The unique identifier of the image generation item being processed. + sequence_number: + type: integer + description: The sequence number of the image generation item being processed. + required: + - type + - output_index + - item_id + - sequence_number + x-oaiMeta: + name: response.image_generation_call.generating + group: responses + example: | + { + "type": "response.image_generation_call.generating", + "output_index": 0, + "item_id": "item-123", + "sequence_number": 0 + } + BetaResponseImageGenCallCompletedEvent: + type: object + title: ResponseImageGenCallCompletedEvent + description: | + Emitted when an image generation tool call has completed and the final image is available. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + enum: + - response.image_generation_call.completed + description: The type of the event. Always 'response.image_generation_call.completed'. + x-stainless-const: true + output_index: + type: integer + description: The index of the output item in the response's output array. + sequence_number: + type: integer + description: The sequence number of this event. + item_id: + type: string + description: The unique identifier of the image generation item being processed. + required: + - type + - output_index + - item_id + - sequence_number + x-oaiMeta: + name: response.image_generation_call.completed + group: responses + example: | + { + "type": "response.image_generation_call.completed", + "output_index": 0, + "item_id": "item-123", + "sequence_number": 1 + } + BetaResponseReasoningTextDoneEvent: + type: object + description: Emitted when a reasoning text is completed. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.reasoning_text.done`. + enum: + - response.reasoning_text.done + x-stainless-const: true + item_id: + type: string + description: | + The ID of the item this reasoning text is associated with. + output_index: + type: integer + description: | + The index of the output item this reasoning text is associated with. + content_index: + type: integer + description: | + The index of the reasoning content part. + text: + type: string + description: | + The full text of the completed reasoning content. + sequence_number: + type: integer + description: | + The sequence number of this event. + required: + - type + - item_id + - output_index + - content_index + - text + - sequence_number + x-oaiMeta: + name: response.reasoning_text.done + group: responses + example: | + { + "type": "response.reasoning_text.done", + "item_id": "rs_123", + "output_index": 0, + "content_index": 0, + "text": "The user is asking...", + "sequence_number": 4 + } + BetaResponseReasoningTextDeltaEvent: + type: object + description: Emitted when a delta is added to a reasoning text. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.reasoning_text.delta`. + enum: + - response.reasoning_text.delta + x-stainless-const: true + item_id: + type: string + description: | + The ID of the item this reasoning text delta is associated with. + output_index: + type: integer + description: | + The index of the output item this reasoning text delta is associated with. + content_index: + type: integer + description: | + The index of the reasoning content part this delta is associated with. + delta: + type: string + description: | + The text delta that was added to the reasoning content. + sequence_number: + type: integer + description: | + The sequence number of this event. + required: + - type + - item_id + - output_index + - content_index + - delta + - sequence_number + x-oaiMeta: + name: response.reasoning_text.delta + group: responses + example: | + { + "type": "response.reasoning_text.delta", + "item_id": "rs_123", + "output_index": 0, + "content_index": 0, + "delta": "The", + "sequence_number": 1 + } + BetaResponseReasoningSummaryTextDoneEvent: + type: object + description: Emitted when a reasoning summary text is completed. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.reasoning_summary_text.done`. + enum: + - response.reasoning_summary_text.done + x-stainless-const: true + item_id: + type: string + description: | + The ID of the item this summary text is associated with. + output_index: + type: integer + description: | + The index of the output item this summary text is associated with. + summary_index: + type: integer + description: | + The index of the summary part within the reasoning summary. + text: + type: string + description: | + The full text of the completed reasoning summary. + sequence_number: + type: integer + description: | + The sequence number of this event. + required: + - type + - item_id + - output_index + - summary_index + - text + - sequence_number + x-oaiMeta: + name: response.reasoning_summary_text.done + group: responses + example: | + { + "type": "response.reasoning_summary_text.done", + "item_id": "rs_6806bfca0b2481918a5748308061a2600d3ce51bdffd5476", + "output_index": 0, + "summary_index": 0, + "text": "**Responding to a greeting**\n\nThe user just said, \"Hello!\" So, it seems I need to engage. I'll greet them back and offer help since they're looking to chat. I could say something like, \"Hello! How can I assist you today?\" That feels friendly and open. They didn't ask a specific question, so this approach will work well for starting a conversation. Let's see where it goes from there!", + "sequence_number": 1 + } + BetaResponseReasoningSummaryTextDeltaEvent: + type: object + description: Emitted when a delta is added to a reasoning summary text. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.reasoning_summary_text.delta`. + enum: + - response.reasoning_summary_text.delta + x-stainless-const: true + item_id: + type: string + description: | + The ID of the item this summary text delta is associated with. + output_index: + type: integer + description: | + The index of the output item this summary text delta is associated with. + summary_index: + type: integer + description: | + The index of the summary part within the reasoning summary. + delta: + type: string + description: | + The text delta that was added to the summary. + sequence_number: + type: integer + description: | + The sequence number of this event. + required: + - type + - item_id + - output_index + - summary_index + - delta + - sequence_number + x-oaiMeta: + name: response.reasoning_summary_text.delta + group: responses + example: | + { + "type": "response.reasoning_summary_text.delta", + "item_id": "rs_6806bfca0b2481918a5748308061a2600d3ce51bdffd5476", + "output_index": 0, + "summary_index": 0, + "delta": "**Responding to a greeting**\n\nThe user just said, \"Hello!\" So, it seems I need to engage. I'll greet them back and offer help since they're looking to chat. I could say something like, \"Hello! How can I assist you today?\" That feels friendly and open. They didn't ask a specific question, so this approach will work well for starting a conversation. Let's see where it goes from there!", + "sequence_number": 1 + } + BetaResponseReasoningSummaryPartDoneEvent: + type: object + description: Emitted when a reasoning summary part is completed. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.reasoning_summary_part.done`. + enum: + - response.reasoning_summary_part.done + x-stainless-const: true + item_id: + type: string + description: | + The ID of the item this summary part is associated with. + output_index: + type: integer + description: | + The index of the output item this summary part is associated with. + summary_index: + type: integer + description: | + The index of the summary part within the reasoning summary. + status: + type: string + description: | + The completion status of the summary part. Omitted when the part completed + normally and set to `incomplete` when generation was interrupted. + enum: + - incomplete + sequence_number: + type: integer + description: | + The sequence number of this event. + part: + type: object + description: | + The completed summary part. properties: - stream_id: + type: type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseWsQueued - description: | - Emitted when a response is queued and waiting to be processed. - allOf: - - $ref: '#/components/schemas/BetaResponseQueuedEvent' - - type: object - properties: - stream_id: + description: The type of the summary part. Always `summary_text`. + enum: + - summary_text + x-stainless-const: true + text: type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseCustomToolCallInputWsDelta - description: | - Event representing a delta (partial update) to the input of a custom tool call. - allOf: - - $ref: '#/components/schemas/BetaResponseCustomToolCallInputDeltaEvent' - - type: object + description: The text of the summary part. + required: + - type + - text + required: + - type + - item_id + - output_index + - summary_index + - part + - sequence_number + x-oaiMeta: + name: response.reasoning_summary_part.done + group: responses + example: | + { + "type": "response.reasoning_summary_part.done", + "item_id": "rs_6806bfca0b2481918a5748308061a2600d3ce51bdffd5476", + "output_index": 0, + "summary_index": 0, + "part": { + "type": "summary_text", + "text": "**Responding to a greeting**\n\nThe user just said, \"Hello!\" So, it seems I need to engage. I'll greet them back and offer help since they're looking to chat. I could say something like, \"Hello! How can I assist you today?\" That feels friendly and open. They didn't ask a specific question, so this approach will work well for starting a conversation. Let's see where it goes from there!" + }, + "sequence_number": 1 + } + BetaResponseReasoningSummaryPartAddedEvent: + type: object + description: Emitted when a new reasoning summary part is added. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.reasoning_summary_part.added`. + enum: + - response.reasoning_summary_part.added + x-stainless-const: true + item_id: + type: string + description: | + The ID of the item this summary part is associated with. + output_index: + type: integer + description: | + The index of the output item this summary part is associated with. + summary_index: + type: integer + description: | + The index of the summary part within the reasoning summary. + sequence_number: + type: integer + description: | + The sequence number of this event. + part: + type: object + description: | + The summary part that was added. properties: - stream_id: + type: type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseCustomToolCallInputWsDone - description: | - Event indicating that input for a custom tool call is complete. - allOf: - - $ref: '#/components/schemas/BetaResponseCustomToolCallInputDoneEvent' - - type: object - properties: - stream_id: + description: The type of the summary part. Always `summary_text`. + enum: + - summary_text + x-stainless-const: true + text: type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - $ref: '#/components/schemas/BetaResponseWsError' - - $ref: '#/components/schemas/BetaResponseSteerAcceptedEvent' - - $ref: '#/components/schemas/BetaResponseSteerPendingEvent' - - $ref: '#/components/schemas/BetaResponseSteerFailedEvent' - - $ref: '#/components/schemas/BetaResponseInjectCreatedEvent' - - $ref: '#/components/schemas/BetaResponseInjectFailedEvent' - BetaResponseInjectFailedEvent: + description: The text of the summary part. + required: + - type + - text + required: + - type + - item_id + - output_index + - summary_index + - part + - sequence_number + x-oaiMeta: + name: response.reasoning_summary_part.added + group: responses + example: | + { + "type": "response.reasoning_summary_part.added", + "item_id": "rs_6806bfca0b2481918a5748308061a2600d3ce51bdffd5476", + "output_index": 0, + "summary_index": 0, + "part": { + "type": "summary_text", + "text": "" + }, + "sequence_number": 1 + } + BetaResponseTextDoneEvent: + type: object + description: Emitted when text content is finalized. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.output_text.done`. + enum: + - response.output_text.done + x-stainless-const: true + item_id: + type: string + description: | + The ID of the output item that the text content is finalized. + output_index: + type: integer + description: | + The index of the output item that the text content is finalized. + content_index: + type: integer + description: | + The index of the content part that the text content is finalized. + text: + type: string + description: | + The text content that is finalized. + sequence_number: + type: integer + description: The sequence number for this event. + logprobs: + type: array + description: | + The log probabilities of the tokens in the delta. + items: + $ref: '#/components/schemas/BetaResponseLogProb' + required: + - type + - item_id + - output_index + - content_index + - text + - sequence_number + - logprobs + x-oaiMeta: + name: response.output_text.done + group: responses + example: | + { + "type": "response.output_text.done", + "item_id": "msg_123", + "output_index": 0, + "content_index": 0, + "text": "In a shimmering forest under a sky full of stars, a lonely unicorn named Lila discovered a hidden pond that glowed with moonlight. Every night, she would leave sparkling, magical flowers by the water's edge, hoping to share her beauty with others. One enchanting evening, she woke to find a group of friendly animals gathered around, eager to be friends and share in her magic.", + "sequence_number": 1 + } + BetaResponseLogProb: + type: object + description: "A logprob is the logarithmic probability that the model assigns to producing \na particular token at a given position in the sequence. Less-negative (higher) \nlogprob values indicate greater model confidence in that token choice.\n" + properties: + token: + description: A possible text token. + type: string + logprob: + description: | + The log probability of this token. + type: number + top_logprobs: + description: | + The log probabilities of up to 20 of the most likely tokens. + type: array + items: + type: object + properties: + token: + description: A possible text token. + type: string + logprob: + description: The log probability of this token. + type: number + required: + - token + - logprob + BetaResponseTextDeltaEvent: + type: object + description: Emitted when there is an additional text delta. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.output_text.delta`. + enum: + - response.output_text.delta + x-stainless-const: true + item_id: + type: string + description: | + The ID of the output item that the text delta was added to. + output_index: + type: integer + description: | + The index of the output item that the text delta was added to. + content_index: + type: integer + description: | + The index of the content part that the text delta was added to. + delta: + type: string + description: | + The text delta that was added. + sequence_number: + type: integer + description: The sequence number for this event. + logprobs: + type: array + description: | + The log probabilities of the tokens in the delta. + items: + $ref: '#/components/schemas/BetaResponseLogProb' + required: + - type + - item_id + - output_index + - content_index + - delta + - sequence_number + - logprobs + x-oaiMeta: + name: response.output_text.delta + group: responses + example: | + { + "type": "response.output_text.delta", + "item_id": "msg_123", + "output_index": 0, + "content_index": 0, + "delta": "In", + "sequence_number": 1 + } + BetaResponseRefusalDoneEvent: + type: object + description: Emitted when refusal text is finalized. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.refusal.done`. + enum: + - response.refusal.done + x-stainless-const: true + item_id: + type: string + description: | + The ID of the output item that the refusal text is finalized. + output_index: + type: integer + description: | + The index of the output item that the refusal text is finalized. + content_index: + type: integer + description: | + The index of the content part that the refusal text is finalized. + refusal: + type: string + description: | + The refusal text that is finalized. + sequence_number: + type: integer + description: | + The sequence number of this event. + required: + - type + - item_id + - output_index + - content_index + - refusal + - sequence_number + x-oaiMeta: + name: response.refusal.done + group: responses + example: | + { + "type": "response.refusal.done", + "item_id": "item-abc", + "output_index": 1, + "content_index": 2, + "refusal": "final refusal text", + "sequence_number": 1 + } + BetaResponseRefusalDeltaEvent: + type: object + description: Emitted when there is a partial refusal text. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.refusal.delta`. + enum: + - response.refusal.delta + x-stainless-const: true + item_id: + type: string + description: | + The ID of the output item that the refusal text is added to. + output_index: + type: integer + description: | + The index of the output item that the refusal text is added to. + content_index: + type: integer + description: | + The index of the content part that the refusal text is added to. + delta: + type: string + description: | + The refusal text that is added. + sequence_number: + type: integer + description: | + The sequence number of this event. + required: + - type + - item_id + - output_index + - content_index + - delta + - sequence_number + x-oaiMeta: + name: response.refusal.delta + group: responses + example: | + { + "type": "response.refusal.delta", + "item_id": "msg_123", + "output_index": 0, + "content_index": 0, + "delta": "refusal text so far", + "sequence_number": 1 + } + BetaResponseOutputItemDoneEvent: + type: object + description: Emitted when an output item is marked done. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.output_item.done`. + enum: + - response.output_item.done + x-stainless-const: true + output_index: + type: integer + description: | + The index of the output item that was marked done. + sequence_number: + type: integer + description: | + The sequence number of this event. + item: + $ref: '#/components/schemas/BetaOutputItem' + description: | + The output item that was marked done. + required: + - type + - output_index + - item + - sequence_number + x-oaiMeta: + name: response.output_item.done + group: responses + example: | + { + "type": "response.output_item.done", + "output_index": 0, + "item": { + "id": "msg_123", + "status": "completed", + "type": "message", + "role": "assistant", + "content": [ + { + "type": "output_text", + "text": "In a shimmering forest under a sky full of stars, a lonely unicorn named Lila discovered a hidden pond that glowed with moonlight. Every night, she would leave sparkling, magical flowers by the water's edge, hoping to share her beauty with others. One enchanting evening, she woke to find a group of friendly animals gathered around, eager to be friends and share in her magic.", + "annotations": [] + } + ] + }, + "sequence_number": 1 + } + BetaResponseOutputItemAddedEvent: + type: object + description: Emitted when a new output item is added. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.output_item.added`. + enum: + - response.output_item.added + x-stainless-const: true + output_index: + type: integer + description: | + The index of the output item that was added. + sequence_number: + type: integer + description: | + The sequence number of this event. + item: + $ref: '#/components/schemas/BetaOutputItem' + description: | + The output item that was added. For reasoning items, `encrypted_content` + may be incomplete while the item is in progress. Use the reasoning item + from the corresponding `response.output_item.done` event when passing it + as input to a subsequent request. + required: + - type + - output_index + - item + - sequence_number + x-oaiMeta: + name: response.output_item.added + group: responses + example: | + { + "type": "response.output_item.added", + "output_index": 0, + "item": { + "id": "msg_123", + "status": "in_progress", + "type": "message", + "role": "assistant", + "content": [] + }, + "sequence_number": 1 + } + BetaResponseInProgressEvent: + type: object + description: Emitted when the response is in progress. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.in_progress`. + enum: + - response.in_progress + x-stainless-const: true + response: + $ref: '#/components/schemas/BetaResponse' + description: | + The response that is in progress. + sequence_number: + type: integer + description: The sequence number of this event. + required: + - type + - response + - sequence_number + x-oaiMeta: + name: response.in_progress + group: responses + example: | + { + "type": "response.in_progress", + "response": { + "id": "resp_67ccfcdd16748190a91872c75d38539e09e4d4aac714747c", + "object": "response", + "created_at": 1741487325, + "status": "in_progress", + "completed_at": null, + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-6-astra", + "output": [], + "parallel_tool_calls": true, + "previous_response_id": null, + "reasoning": { + "effort": null, + "summary": null + }, + "store": true, + "temperature": 1, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [], + "top_p": 1, + "truncation": "disabled", + "usage": null, + "user": null, + "metadata": {} + }, + "sequence_number": 1 + } + BetaResponseShellCallOutputContentDoneStreamingEvent: + properties: + type: + type: string + enum: + - response.shell_call_output_content.done + description: The type of the event, always `response.shell_call_output_content.done`. + default: response.shell_call_output_content.done + x-stainless-const: true + sequence_number: + type: integer + description: The sequence number of the event that was emitted. + agent: + $ref: '#/components/schemas/BetaAgentTag' + description: The agent that owns this multi-agent streaming event. + item_id: + type: string + description: The ID of the output item that was updated. + output_index: + type: integer + description: The index of the output item that was updated. + command_index: + type: integer + description: The index of the shell command that produced output. + output: + items: + $ref: '#/components/schemas/BetaFunctionShellCallOutputContent' + type: array + description: The output contents emitted for the shell command. + type: object + required: + - type + - sequence_number + - item_id + - output_index + - command_index + - output + title: Response shell call output content done event + description: A streaming event that indicated shell call output was completed. + BetaResponseShellCallOutputContentDeltaStreamingEvent: + properties: + type: + type: string + enum: + - response.shell_call_output_content.delta + description: The type of the event, always `response.shell_call_output_content.delta`. + default: response.shell_call_output_content.delta + x-stainless-const: true + sequence_number: + type: integer + description: The sequence number of the event that was emitted. + agent: + $ref: '#/components/schemas/BetaAgentTag' + description: The agent that owns this multi-agent streaming event. + item_id: + type: string + description: The ID of the output item that was updated. + output_index: + type: integer + description: The index of the output item that was updated. + command_index: + type: integer + description: The index of the shell command that produced output. + delta: + $ref: '#/components/schemas/BetaShellCallOutputDelta' + description: The stdout/stderr delta that was emitted. + type: object + required: + - type + - sequence_number + - item_id + - output_index + - command_index + - delta + title: Response shell call output content delta event + description: A streaming event that indicated shell call output was incrementally added. + BetaShellCallOutputDelta: + properties: + stdout: + type: string + description: The stdout delta that was emitted. + stderr: + type: string + description: The stderr delta that was emitted. + type: object + required: [] + title: Shell call output delta + description: A delta of stdout/stderr emitted while a shell call was running. + BetaResponseShellCallCommandDoneStreamingEvent: + properties: + type: + type: string + enum: + - response.shell_call_command.done + description: The type of the event, always `response.shell_call_command.done`. + default: response.shell_call_command.done + x-stainless-const: true + sequence_number: + type: integer + description: The sequence number of the event that was emitted. + agent: + $ref: '#/components/schemas/BetaAgentTag' + description: The agent that owns this multi-agent streaming event. + output_index: + type: integer + description: The index of the output item that was updated. + command_index: + type: integer + description: The index of the shell command that was completed. + command: + type: string + description: The final shell command that was emitted. + type: object + required: + - type + - sequence_number + - output_index + - command_index + - command + title: Response shell command done event + description: A streaming event that indicated a shell command was completed. + BetaResponseShellCallCommandDeltaStreamingEvent: + properties: + type: + type: string + enum: + - response.shell_call_command.delta + description: The type of the event, always `response.shell_call_command.delta`. + default: response.shell_call_command.delta + x-stainless-const: true + sequence_number: + type: integer + description: The sequence number of the event that was emitted. + agent: + $ref: '#/components/schemas/BetaAgentTag' + description: The agent that owns this multi-agent streaming event. + output_index: + type: integer + description: The index of the output item that was updated. + command_index: + type: integer + description: The index of the shell command that was updated. + delta: + type: string + description: The shell command delta that was appended. + obfuscation: + type: string + description: An obfuscation string that was added to pad the event payload. + type: object + required: + - type + - sequence_number + - output_index + - command_index + - delta + title: Response shell command delta event + description: A streaming event that indicated a shell command was incrementally updated. + BetaResponseShellCallCommandAddedStreamingEvent: + properties: + type: + type: string + enum: + - response.shell_call_command.added + description: The type of the event, always `response.shell_call_command.added`. + default: response.shell_call_command.added + x-stainless-const: true + sequence_number: + type: integer + description: The sequence number of the event that was emitted. + agent: + $ref: '#/components/schemas/BetaAgentTag' + description: The agent that owns this multi-agent streaming event. + output_index: + type: integer + description: The index of the output item that was updated. + command_index: + type: integer + description: The index of the shell command that was added. + command: + type: string + description: The shell command that was added. + type: object + required: + - type + - sequence_number + - output_index + - command_index + - command + title: Response shell command added event + description: A streaming event that indicated a shell command was added to a tool call. + BetaResponseFunctionCallArgumentsDoneEvent: + type: object + description: Emitted when function-call arguments are finalized. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + enum: + - response.function_call_arguments.done + x-stainless-const: true + item_id: + type: string + description: The ID of the item. + output_index: + type: integer + description: The index of the output item. + sequence_number: + type: integer + description: The sequence number of this event. + arguments: + type: string + description: The function-call arguments. + required: + - type + - item_id + - output_index + - arguments + - sequence_number + x-oaiMeta: + name: response.function_call_arguments.done + group: responses + example: | + { + "type": "response.function_call_arguments.done", + "item_id": "item-abc", + "output_index": 1, + "arguments": "{ \"arg\": 123 }", + "sequence_number": 1 + } + BetaResponseFunctionCallArgumentsDeltaEvent: + type: object + description: Emitted when there is a partial function-call arguments delta. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.function_call_arguments.delta`. + enum: + - response.function_call_arguments.delta + x-stainless-const: true + item_id: + type: string + description: | + The ID of the output item that the function-call arguments delta is added to. + output_index: + type: integer + description: | + The index of the output item that the function-call arguments delta is added to. + sequence_number: + type: integer + description: The sequence number of this event. + delta: + type: string + description: | + The function-call arguments delta that is added. + required: + - type + - item_id + - output_index + - delta + - sequence_number + x-oaiMeta: + name: response.function_call_arguments.delta + group: responses + example: | + { + "type": "response.function_call_arguments.delta", + "item_id": "item-abc", + "output_index": 0, + "delta": "{ \"arg\":" + "sequence_number": 1 + } + BetaResponseFileSearchCallSearchingEvent: + type: object + description: Emitted when a file search is currently searching. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.file_search_call.searching`. + enum: + - response.file_search_call.searching + x-stainless-const: true + output_index: + type: integer + description: | + The index of the output item that the file search call is searching. + item_id: + type: string + description: | + The ID of the output item that the file search call is initiated. + sequence_number: + type: integer + description: The sequence number of this event. + required: + - type + - output_index + - item_id + - sequence_number + x-oaiMeta: + name: response.file_search_call.searching + group: responses + example: | + { + "type": "response.file_search_call.searching", + "output_index": 0, + "item_id": "fs_123", + "sequence_number": 1 + } + BetaResponseFileSearchCallInProgressEvent: + type: object + description: Emitted when a file search call is initiated. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.file_search_call.in_progress`. + enum: + - response.file_search_call.in_progress + x-stainless-const: true + output_index: + type: integer + description: | + The index of the output item that the file search call is initiated. + item_id: + type: string + description: | + The ID of the output item that the file search call is initiated. + sequence_number: + type: integer + description: The sequence number of this event. + required: + - type + - output_index + - item_id + - sequence_number + x-oaiMeta: + name: response.file_search_call.in_progress + group: responses + example: | + { + "type": "response.file_search_call.in_progress", + "output_index": 0, + "item_id": "fs_123", + "sequence_number": 1 + } + BetaResponseFileSearchCallCompletedEvent: + type: object + description: Emitted when a file search call is completed (results found). + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.file_search_call.completed`. + enum: + - response.file_search_call.completed + x-stainless-const: true + output_index: + type: integer + description: | + The index of the output item that the file search call is initiated. + item_id: + type: string + description: | + The ID of the output item that the file search call is initiated. + sequence_number: + type: integer + description: The sequence number of this event. + required: + - type + - output_index + - item_id + - sequence_number + x-oaiMeta: + name: response.file_search_call.completed + group: responses + example: | + { + "type": "response.file_search_call.completed", + "output_index": 0, + "item_id": "fs_123", + "sequence_number": 1 + } + BetaResponseErrorEvent: + type: object + description: Emitted when an error occurs. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `error`. + enum: + - error + x-stainless-const: true + code: + anyOf: + - type: string + description: | + The error code. + - type: 'null' + message: + type: string + description: | + The error message. + param: + anyOf: + - type: string + description: | + The error parameter. + - type: 'null' + sequence_number: + type: integer + description: The sequence number of this event. + required: + - type + - code + - message + - param + - sequence_number + x-oaiMeta: + name: error + group: responses + example: | + { + "type": "error", + "code": "ERR_SOMETHING", + "message": "Something went wrong", + "param": null, + "sequence_number": 1 + } + BetaResponseCreatedEvent: + type: object + description: | + An event that is emitted when a response is created. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.created`. + enum: + - response.created + x-stainless-const: true + response: + $ref: '#/components/schemas/BetaResponse' + description: | + The response that was created. + sequence_number: + type: integer + description: The sequence number for this event. + required: + - type + - response + - sequence_number + x-oaiMeta: + name: response.created + group: responses + example: | + { + "type": "response.created", + "response": { + "id": "resp_67ccfcdd16748190a91872c75d38539e09e4d4aac714747c", + "object": "response", + "created_at": 1741487325, + "status": "in_progress", + "completed_at": null, + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-6-astra", + "output": [], + "parallel_tool_calls": true, + "previous_response_id": null, + "reasoning": { + "effort": null, + "summary": null + }, + "store": true, + "temperature": 1, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [], + "top_p": 1, + "truncation": "disabled", + "usage": null, + "user": null, + "metadata": {} + }, + "sequence_number": 1 + } + BetaResponseContentPartDoneEvent: + type: object + description: Emitted when a content part is done. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.content_part.done`. + enum: + - response.content_part.done + x-stainless-const: true + item_id: + type: string + description: | + The ID of the output item that the content part was added to. + output_index: + type: integer + description: | + The index of the output item that the content part was added to. + content_index: + type: integer + description: | + The index of the content part that is done. + sequence_number: + type: integer + description: The sequence number of this event. + part: + $ref: '#/components/schemas/BetaOutputContent' + description: | + The content part that is done. + required: + - type + - item_id + - output_index + - content_index + - part + - sequence_number + x-oaiMeta: + name: response.content_part.done + group: responses + example: | + { + "type": "response.content_part.done", + "item_id": "msg_123", + "output_index": 0, + "content_index": 0, + "sequence_number": 1, + "part": { + "type": "output_text", + "text": "In a shimmering forest under a sky full of stars, a lonely unicorn named Lila discovered a hidden pond that glowed with moonlight. Every night, she would leave sparkling, magical flowers by the water's edge, hoping to share her beauty with others. One enchanting evening, she woke to find a group of friendly animals gathered around, eager to be friends and share in her magic.", + "annotations": [] + } + } + BetaOutputContent: + discriminator: + propertyName: type + anyOf: + - $ref: '#/components/schemas/BetaOutputTextContent' + - $ref: '#/components/schemas/BetaRefusalContent' + - $ref: '#/components/schemas/BetaReasoningTextContent' + BetaResponseContentPartAddedEvent: + type: object + description: Emitted when a new content part is added. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.content_part.added`. + enum: + - response.content_part.added + x-stainless-const: true + item_id: + type: string + description: | + The ID of the output item that the content part was added to. + output_index: + type: integer + description: | + The index of the output item that the content part was added to. + content_index: + type: integer + description: | + The index of the content part that was added. + part: + $ref: '#/components/schemas/BetaOutputContent' + description: | + The content part that was added. + sequence_number: + type: integer + description: The sequence number of this event. + required: + - type + - item_id + - output_index + - content_index + - part + - sequence_number + x-oaiMeta: + name: response.content_part.added + group: responses + example: | + { + "type": "response.content_part.added", + "item_id": "msg_123", + "output_index": 0, + "content_index": 0, + "part": { + "type": "output_text", + "text": "", + "annotations": [] + }, + "sequence_number": 1 + } + BetaResponseCompletedEvent: + type: object + description: Emitted when the model response is complete. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.completed`. + enum: + - response.completed + x-stainless-const: true + response: + $ref: '#/components/schemas/BetaResponse' + description: | + Properties of the completed response. + sequence_number: + type: integer + description: The sequence number for this event. + required: + - type + - response + - sequence_number + x-oaiMeta: + name: response.completed + group: responses + example: | + { + "type": "response.completed", + "response": { + "id": "resp_123", + "object": "response", + "created_at": 1740855869, + "status": "completed", + "completed_at": 1740855870, + "error": null, + "incomplete_details": null, + "input": [], + "instructions": null, + "max_output_tokens": null, + "model": "gpt-6-astra", + "output": [ + { + "id": "msg_123", + "type": "message", + "role": "assistant", + "content": [ + { + "type": "output_text", + "text": "In a shimmering forest under a sky full of stars, a lonely unicorn named Lila discovered a hidden pond that glowed with moonlight. Every night, she would leave sparkling, magical flowers by the water's edge, hoping to share her beauty with others. One enchanting evening, she woke to find a group of friendly animals gathered around, eager to be friends and share in her magic.", + "annotations": [] + } + ] + } + ], + "previous_response_id": null, + "reasoning_effort": null, + "store": false, + "temperature": 1, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [], + "top_p": 1, + "truncation": "disabled", + "usage": { + "input_tokens": 0, + "output_tokens": 0, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 0 + }, + "user": null, + "metadata": {} + }, + "sequence_number": 1 + } + BetaResponseCompactionCompactingStreamingEvent: + properties: + type: + type: string + enum: + - response.compaction.compacting + description: The type of the event, always `response.compaction.compacting`. + default: response.compaction.compacting + x-stainless-const: true + sequence_number: + type: integer + description: The sequence number of the event that was emitted. + agent: + $ref: '#/components/schemas/BetaAgentTag' + description: The agent that owns this multi-agent streaming event. + output_index: + type: integer + description: The index of the compaction output item. + item_id: + type: string + description: The ID of the compaction output item. + type: object + required: + - type + - sequence_number + - output_index + - item_id + title: Response compaction compacting event + description: Emitted when new summary content is sampled for a compaction trigger. Contains no summary content. + BetaResponseCodeInterpreterCallInterpretingEvent: + type: object + description: Emitted when the code interpreter is actively interpreting the code snippet. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: The type of the event. Always `response.code_interpreter_call.interpreting`. + enum: + - response.code_interpreter_call.interpreting + x-stainless-const: true + output_index: + type: integer + description: The index of the output item in the response for which the code interpreter is interpreting code. + item_id: + type: string + description: The unique identifier of the code interpreter tool call item. + sequence_number: + type: integer + description: The sequence number of this event, used to order streaming events. + required: + - type + - output_index + - item_id + - sequence_number + x-oaiMeta: + name: response.code_interpreter_call.interpreting + group: responses + example: | + { + "type": "response.code_interpreter_call.interpreting", + "output_index": 4, + "item_id": "ci_12345", + "sequence_number": 1 + } + BetaResponseCodeInterpreterCallInProgressEvent: + type: object + description: Emitted when a code interpreter call is in progress. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: The type of the event. Always `response.code_interpreter_call.in_progress`. + enum: + - response.code_interpreter_call.in_progress + x-stainless-const: true + output_index: + type: integer + description: The index of the output item in the response for which the code interpreter call is in progress. + item_id: + type: string + description: The unique identifier of the code interpreter tool call item. + sequence_number: + type: integer + description: The sequence number of this event, used to order streaming events. + required: + - type + - output_index + - item_id + - sequence_number + x-oaiMeta: + name: response.code_interpreter_call.in_progress + group: responses + example: | + { + "type": "response.code_interpreter_call.in_progress", + "output_index": 0, + "item_id": "ci_12345", + "sequence_number": 1 + } + BetaResponseCodeInterpreterCallCompletedEvent: + type: object + description: Emitted when the code interpreter call is completed. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: The type of the event. Always `response.code_interpreter_call.completed`. + enum: + - response.code_interpreter_call.completed + x-stainless-const: true + output_index: + type: integer + description: The index of the output item in the response for which the code interpreter call is completed. + item_id: + type: string + description: The unique identifier of the code interpreter tool call item. + sequence_number: + type: integer + description: The sequence number of this event, used to order streaming events. + required: + - type + - output_index + - item_id + - sequence_number + x-oaiMeta: + name: response.code_interpreter_call.completed + group: responses + example: | + { + "type": "response.code_interpreter_call.completed", + "output_index": 5, + "item_id": "ci_12345", + "sequence_number": 1 + } + BetaResponseCodeInterpreterCallCodeDoneEvent: + type: object + description: Emitted when the code snippet is finalized by the code interpreter. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: The type of the event. Always `response.code_interpreter_call_code.done`. + enum: + - response.code_interpreter_call_code.done + x-stainless-const: true + output_index: + type: integer + description: The index of the output item in the response for which the code is finalized. + item_id: + type: string + description: The unique identifier of the code interpreter tool call item. + code: + type: string + description: The final code snippet output by the code interpreter. + sequence_number: + type: integer + description: The sequence number of this event, used to order streaming events. + required: + - type + - output_index + - item_id + - code + - sequence_number + x-oaiMeta: + name: response.code_interpreter_call_code.done + group: responses + example: | + { + "type": "response.code_interpreter_call_code.done", + "output_index": 3, + "item_id": "ci_12345", + "code": "print('done')", + "sequence_number": 1 + } + BetaResponseCodeInterpreterCallCodeDeltaEvent: + type: object + description: Emitted when a partial code snippet is streamed by the code interpreter. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: The type of the event. Always `response.code_interpreter_call_code.delta`. + enum: + - response.code_interpreter_call_code.delta + x-stainless-const: true + output_index: + type: integer + description: The index of the output item in the response for which the code is being streamed. + item_id: + type: string + description: The unique identifier of the code interpreter tool call item. + delta: + type: string + description: The partial code snippet being streamed by the code interpreter. + sequence_number: + type: integer + description: The sequence number of this event, used to order streaming events. + required: + - type + - output_index + - item_id + - delta + - sequence_number + x-oaiMeta: + name: response.code_interpreter_call_code.delta + group: responses + example: | + { + "type": "response.code_interpreter_call_code.delta", + "output_index": 0, + "item_id": "ci_12345", + "delta": "print('Hello, world')", + "sequence_number": 1 + } + BetaResponseAudioTranscriptDoneEvent: + type: object + description: Emitted when the full audio transcript is completed. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.audio.transcript.done`. + enum: + - response.audio.transcript.done + x-stainless-const: true + sequence_number: + type: integer + description: The sequence number of this event. + required: + - type + - response_id + - sequence_number + x-oaiMeta: + name: response.audio.transcript.done + group: responses + example: | + { + "type": "response.audio.transcript.done", + "response_id": "resp_123", + "sequence_number": 1 + } + BetaResponseAudioTranscriptDeltaEvent: + type: object + description: Emitted when there is a partial transcript of audio. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.audio.transcript.delta`. + enum: + - response.audio.transcript.delta + x-stainless-const: true + delta: + type: string + description: | + The partial transcript of the audio response. + sequence_number: + type: integer + description: The sequence number of this event. + required: + - type + - response_id + - delta + - sequence_number + x-oaiMeta: + name: response.audio.transcript.delta + group: responses + example: | + { + "type": "response.audio.transcript.delta", + "response_id": "resp_123", + "delta": " ... partial transcript ... ", + "sequence_number": 1 + } + BetaResponseAudioDoneEvent: + type: object + description: Emitted when the audio response is complete. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.audio.done`. + enum: + - response.audio.done + x-stainless-const: true + sequence_number: + type: integer + description: | + The sequence number of the delta. + required: + - type + - sequence_number + - response_id + x-oaiMeta: + name: response.audio.done + group: responses + example: | + { + "type": "response.audio.done", + "response_id": "resp-123", + "sequence_number": 1 + } + BetaResponseAudioDeltaEvent: + type: object + description: Emitted when there is a partial audio response. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.audio.delta`. + enum: + - response.audio.delta + x-stainless-const: true + sequence_number: + type: integer + description: | + A sequence number for this chunk of the stream response. + delta: + type: string + description: | + A chunk of Base64 encoded response audio bytes. + required: + - type + - delta + - sequence_number + x-oaiMeta: + name: response.audio.delta + group: responses + example: | + { + "type": "response.audio.delta", + "response_id": "resp_123", + "delta": "base64encoded...", + "sequence_number": 1 + } + BetaResponseIncompleteEvent: type: object - title: ResponseInjectFailedEvent description: | - Emitted when injected input could not be committed to a response. The event - returns the uncommitted raw input so the client can retry it in another - response when appropriate. + An event that is emitted when a response finishes as incomplete. + + Over WebSocket, steering can finish a response with + `response.incomplete_details.reason` set to `steered`, followed automatically + by a successor `response.created` that commits the queued steering input. properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. type: type: string + description: | + The type of the event. Always `response.incomplete`. enum: - - response.inject.failed - description: The event discriminator. Always `response.inject.failed`. + - response.incomplete x-stainless-const: true - response_id: + response: + $ref: '#/components/schemas/BetaResponse' + description: | + The response that was incomplete. + sequence_number: + type: integer + description: The sequence number of this event. + required: + - type + - response + - sequence_number + x-oaiMeta: + name: response.incomplete + group: responses + example: | + { + "type": "response.incomplete", + "response": { + "id": "resp_123", + "object": "response", + "created_at": 1740855869, + "status": "incomplete", + "completed_at": null, + "error": null, + "incomplete_details": { + "reason": "max_tokens" + }, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-6-astra", + "output": [], + "previous_response_id": null, + "reasoning_effort": null, + "store": false, + "temperature": 1, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [], + "top_p": 1, + "truncation": "disabled", + "usage": null, + "user": null, + "metadata": {} + }, + "sequence_number": 1 + } + BetaResponseFailedEvent: + type: object + description: | + An event that is emitted when a response fails. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: type: string - description: The ID of the response that rejected the input. - input: - type: array - description: The raw input items that were not committed. - items: - $ref: '#/components/schemas/BetaInputItem' - error: - type: object - description: Information about why the input was not committed. - properties: - code: - type: string - enum: - - response_already_completed - - response_not_found - description: A machine-readable error code. - message: - type: string - description: A human-readable description of the error. - required: - - code - - message + description: | + The type of the event. Always `response.failed`. + enum: + - response.failed + x-stainless-const: true sequence_number: type: integer - description: The sequence number for this event. - stream_id: + description: The sequence number of this event. + response: + $ref: '#/components/schemas/BetaResponse' + description: | + The response that failed. + required: + - type + - response + - sequence_number + x-oaiMeta: + name: response.failed + group: responses + example: | + { + "type": "response.failed", + "response": { + "id": "resp_123", + "object": "response", + "created_at": 1740855869, + "status": "failed", + "completed_at": null, + "error": { + "code": "server_error", + "message": "The model failed to generate a response." + }, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-6-astra", + "output": [], + "previous_response_id": null, + "reasoning_effort": null, + "store": false, + "temperature": 1, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [], + "top_p": 1, + "truncation": "disabled", + "usage": null, + "user": null, + "metadata": {} + } + } + BetaResponseWebSearchCallCompletedEvent: + type: object + description: Emitted when a web search call is completed. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.web_search_call.completed`. + enum: + - response.web_search_call.completed + x-stainless-const: true + output_index: + type: integer + description: | + The index of the output item that the web search call is associated with. + item_id: + type: string + description: | + Unique ID for the output item associated with the web search call. + sequence_number: + type: integer + description: The sequence number of the web search call being processed. + required: + - type + - output_index + - item_id + - sequence_number + x-oaiMeta: + name: response.web_search_call.completed + group: responses + example: | + { + "type": "response.web_search_call.completed", + "output_index": 0, + "item_id": "ws_123", + "sequence_number": 0 + } + BetaResponseWebSearchCallSearchingEvent: + type: object + description: Emitted when a web search call is executing. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.web_search_call.searching`. + enum: + - response.web_search_call.searching + x-stainless-const: true + output_index: + type: integer + description: | + The index of the output item that the web search call is associated with. + item_id: type: string description: | - The multiplexed WebSocket stream that emitted the event. This field is - present only when WebSocket multiplexing is enabled separately. + Unique ID for the output item associated with the web search call. + sequence_number: + type: integer + description: The sequence number of the web search call being processed. required: - type - - response_id - - input - - error + - output_index + - item_id - sequence_number - x-oai-beta: responses_multi_agent=v1 x-oaiMeta: + name: response.web_search_call.searching + group: responses example: | { - "type": "response.inject.failed", - "response_id": "resp_123", - "input": [ - { - "type": "function_call_output", - "call_id": "call_123", - "output": "{\"temperature\":72}" - } - ], - "error": { - "code": "response_already_completed", - "message": "Response 'resp_123' has already completed." - }, - "sequence_number": 9 + "type": "response.web_search_call.searching", + "output_index": 0, + "item_id": "ws_123", + "sequence_number": 0 } - BetaResponseInjectCreatedEvent: + BetaResponseWebSearchCallInProgressEvent: type: object - title: ResponseInjectCreatedEvent - description: | - Emitted when all injected input items were validated and committed to the - active response. + description: Emitted when a web search call is initiated. properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. type: type: string + description: | + The type of the event. Always `response.web_search_call.in_progress`. enum: - - response.inject.created - description: The event discriminator. Always `response.inject.created`. + - response.web_search_call.in_progress x-stainless-const: true - response_id: - type: string - description: The ID of the response that accepted the input. - sequence_number: + output_index: type: integer - description: The sequence number for this event. - stream_id: + description: | + The index of the output item that the web search call is associated with. + item_id: type: string description: | - The multiplexed WebSocket stream that emitted the event. This field is - present only when WebSocket multiplexing is enabled separately. + Unique ID for the output item associated with the web search call. + sequence_number: + type: integer + description: The sequence number of the web search call being processed. required: - type - - response_id + - output_index + - item_id - sequence_number - x-oai-beta: responses_multi_agent=v1 x-oaiMeta: + name: response.web_search_call.in_progress + group: responses example: | { - "type": "response.inject.created", - "response_id": "resp_123", - "sequence_number": 8 + "type": "response.web_search_call.in_progress", + "output_index": 0, + "item_id": "ws_123", + "sequence_number": 0 } - BetaResponseWsError: + BetaResponseSteerFailedEvent: type: object - title: ResponseWsError - description: Emitted when an error occurs while processing a Responses WebSocket request. + title: ResponseSteerFailedEvent + description: | + Emitted when steering input is rejected or cannot be committed to a + successor response. Returns the original, uncommitted input so the client + can carry it into `response.create` when appropriate. Invalid input must + be corrected before retrying. + + Failures after acceptance include the same steering ID. Failures before an + ID is allocated omit `steer.id`. A lost connection or missing acknowledgement + leaves the outcome unknown; it is not proof that the input was rejected. properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string - description: The type of the event. Always `error`. enum: - - error + - response.steer.failed + description: The event discriminator. Always `response.steer.failed`. x-stainless-const: true - status: - type: integer - description: The HTTP status code associated with a WebSocket protocol error. sequence_number: type: integer - description: The sequence number of an error emitted by the response stream. + description: The sequence number for this event. + steer: + type: object + description: The steering submission that could not be committed. + properties: + id: + type: string + description: | + The ID assigned to the steering submission, if one was allocated. + previous_response_id: + type: string + description: The ID of the response that was targeted for steering. + input: + $ref: '#/components/schemas/BetaResponseSteerInput' + required: + - previous_response_id + - input error: - $ref: '#/components/schemas/BetaErrorPayload' - description: Details about the error. + type: object + description: Information about why the input could not be committed. + properties: + type: + type: string + enum: + - invalid_request_error + description: The error type. Always `invalid_request_error`. + x-stainless-const: true + code: + $ref: '#/components/schemas/BetaResponseSteerErrorCode' + message: + type: string + description: A human-readable description of the error. + required: + - type + - code + - message stream_id: type: string description: | - The WebSocket lane that emitted this event. This field is present when the - originating `response.create` event supplied a `stream_id`. + The WebSocket lane that emitted this event, when the target response is + available and its `response.create` event supplied a `stream_id`. required: - type + - sequence_number + - steer - error x-oaiMeta: - name: error + name: response.steer.failed group: responses example: | { - "type": "error", - "status": 400, - "stream_id": "agent_1", + "type": "response.steer.failed", + "sequence_number": 5, + "steer": { + "id": "steer_456", + "previous_response_id": "resp_123", + "input": [ + { + "type": "message", + "role": "user", + "content": [ + { + "type": "input_text", + "text": "Prioritize the database rollout." + } + ] + } + ] + }, "error": { "type": "invalid_request_error", - "code": "websocket_stream_limit_reached", - "message": "This WebSocket connection has reached its stream limit.", - "param": "stream_id" + "code": "successor_creation_failed", + "message": "We couldn't start the next response. Send this steering input again with response.create." } } - BetaErrorPayload: + BetaResponseSteerErrorCode: + title: ResponseSteerErrorCode + description: | + A machine-readable steering error code. Clients should handle unknown + values because additional codes may be introduced. Known values include: + - `response_not_found`: The target response is not available on this connection. + - `invalid_input`: The event or input failed validation. + - `steering_not_supported`: The model or response execution mode does not support steering. + - `too_many_pending_steers`: Too much steering input is pending for the response. + - `response_already_completed`: The response completed and is no longer accepting steering input. + - `response_not_active`: The response is no longer accepting steering input. + - `successor_creation_failed`: The successor response could not be created. + anyOf: + - type: string + enum: + - response_not_found + - invalid_input + - steering_not_supported + - too_many_pending_steers + - response_already_completed + - response_not_active + - successor_creation_failed + - type: string + BetaResponseSteerInput: + title: ResponseSteerInput + description: | + Input to queue for a continuation of the response. Uses the same string or + input-item shape as `response.create.input`, with a non-empty array when + supplying input items. + + Steering accepts only messages with the `user` role. Each message may + contain only `type`, `role`, and `content`, with `content` as a string or an + array of `input_text`, `input_image`, and `input_file` parts. The optional + `type` must be `message`. Other roles, tool outputs, and item types are not + supported for steering. + anyOf: + - type: string + title: Text input + description: A text input, equivalent to a message with the `user` role. + - $ref: '#/components/schemas/BetaResponseSteerInputItemList' + BetaResponseSteerInputItemList: + type: array + title: Response steer input item list + description: A non-empty list of message inputs to queue for the response. + minItems: 1 + items: + $ref: '#/components/schemas/BetaResponseSteerInputItem' + BetaResponseSteerInputItem: + title: Response steer input item + anyOf: + - $ref: '#/components/schemas/BetaUserMessageItemParam' + - $ref: '#/components/schemas/BetaFunctionCallOutputItemParam' + discriminator: + propertyName: type + BetaUserMessageItemParam: properties: - type: - type: string - description: The error type that was emitted. - code: + agent: + anyOf: + - $ref: '#/components/schemas/Beta_AgentTagParam' + description: The agent that produced this item. + - type: 'null' + id: anyOf: - type: string - description: The error code that was emitted, if any. + description: The unique ID of this message item. + example: msg_123 - type: 'null' - message: + type: type: string - description: The human-readable error message that was emitted. - param: + enum: + - message + description: The item type. Always `message`. + default: message + x-stainless-const: true + role: + type: string + enum: + - user + description: The message role. Always `user`. + default: user + x-stainless-const: true + content: + description: The message content, as an array of content parts. anyOf: + - items: + $ref: '#/components/schemas/BetaResponseSteerInputContent' + description: A piece of message content, such as text, an image, or a file. + type: array - type: string - description: The parameter name that was associated with the error, if any. + maxLength: 10485760 + description: The message content, as a single string. + status: + anyOf: + - type: string + description: The status of the message item. - type: 'null' - headers: - additionalProperties: - type: string - description: The header value that was emitted. - type: object - description: The response headers that were emitted with the error, if any. - x-oaiTypeLabel: map - misalignment: - $ref: '#/components/schemas/BetaMisalignmentErrorDetailsResource' type: object required: - type - - code - - message - - param - title: Error payload - description: An error payload that was emitted for a streaming error event. - BetaResponsesWebSocketStreamEvent: - allOf: - - anyOf: - - $ref: '#/components/schemas/BetaResponseAudioDeltaEvent' - - $ref: '#/components/schemas/BetaResponseAudioDoneEvent' - - $ref: '#/components/schemas/BetaResponseAudioTranscriptDeltaEvent' - - $ref: '#/components/schemas/BetaResponseAudioTranscriptDoneEvent' - - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallCodeDeltaEvent' - - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallCodeDoneEvent' - - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallCompletedEvent' - - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallInProgressEvent' - - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallInterpretingEvent' - - $ref: '#/components/schemas/BetaResponseCompactionCompactingStreamingEvent' - - $ref: '#/components/schemas/BetaResponseCompletedEvent' - - $ref: '#/components/schemas/BetaResponseContentPartAddedEvent' - - $ref: '#/components/schemas/BetaResponseContentPartDoneEvent' - - $ref: '#/components/schemas/BetaResponseCreatedEvent' - - $ref: '#/components/schemas/BetaResponseFileSearchCallCompletedEvent' - - $ref: '#/components/schemas/BetaResponseFileSearchCallInProgressEvent' - - $ref: '#/components/schemas/BetaResponseFileSearchCallSearchingEvent' - - $ref: '#/components/schemas/BetaResponseFunctionCallArgumentsDeltaEvent' - - $ref: '#/components/schemas/BetaResponseFunctionCallArgumentsDoneEvent' - - $ref: '#/components/schemas/BetaResponseShellCallCommandAddedStreamingEvent' - - $ref: '#/components/schemas/BetaResponseShellCallCommandDeltaStreamingEvent' - - $ref: '#/components/schemas/BetaResponseShellCallCommandDoneStreamingEvent' - - $ref: '#/components/schemas/BetaResponseShellCallOutputContentDeltaStreamingEvent' - x-stainless-skip: - - go - - $ref: '#/components/schemas/BetaResponseShellCallOutputContentDoneStreamingEvent' - - $ref: '#/components/schemas/BetaResponseInProgressEvent' - - $ref: '#/components/schemas/BetaResponseFailedEvent' - - $ref: '#/components/schemas/BetaResponseIncompleteEvent' - - $ref: '#/components/schemas/BetaResponseOutputItemAddedEvent' - - $ref: '#/components/schemas/BetaResponseOutputItemDoneEvent' - - $ref: '#/components/schemas/BetaResponseReasoningSummaryPartAddedEvent' - - $ref: '#/components/schemas/BetaResponseReasoningSummaryPartDoneEvent' - - $ref: '#/components/schemas/BetaResponseReasoningSummaryTextDeltaEvent' - - $ref: '#/components/schemas/BetaResponseReasoningSummaryTextDoneEvent' - - $ref: '#/components/schemas/BetaResponseReasoningTextDeltaEvent' - - $ref: '#/components/schemas/BetaResponseReasoningTextDoneEvent' - - $ref: '#/components/schemas/BetaResponseRefusalDeltaEvent' - - $ref: '#/components/schemas/BetaResponseRefusalDoneEvent' - - $ref: '#/components/schemas/BetaResponseTextDeltaEvent' - - $ref: '#/components/schemas/BetaResponseTextDoneEvent' - - $ref: '#/components/schemas/BetaResponseWebSearchCallCompletedEvent' - - $ref: '#/components/schemas/BetaResponseWebSearchCallInProgressEvent' - - $ref: '#/components/schemas/BetaResponseWebSearchCallSearchingEvent' - - $ref: '#/components/schemas/BetaResponseImageGenCallCompletedEvent' - - $ref: '#/components/schemas/BetaResponseImageGenCallGeneratingEvent' - - $ref: '#/components/schemas/BetaResponseImageGenCallInProgressEvent' - - $ref: '#/components/schemas/BetaResponseImageGenCallPartialImageEvent' - - $ref: '#/components/schemas/BetaResponseMCPCallArgumentsDeltaEvent' - - $ref: '#/components/schemas/BetaResponseMCPCallArgumentsDoneEvent' - - $ref: '#/components/schemas/BetaResponseMCPCallCompletedEvent' - - $ref: '#/components/schemas/BetaResponseMCPCallFailedEvent' - - $ref: '#/components/schemas/BetaResponseMCPCallInProgressEvent' - - $ref: '#/components/schemas/BetaResponseMCPListToolsCompletedEvent' - - $ref: '#/components/schemas/BetaResponseMCPListToolsFailedEvent' - - $ref: '#/components/schemas/BetaResponseMCPListToolsInProgressEvent' - - $ref: '#/components/schemas/BetaResponseOutputTextAnnotationAddedEvent' - - $ref: '#/components/schemas/BetaResponseQueuedEvent' - - $ref: '#/components/schemas/BetaResponseCustomToolCallInputDeltaEvent' - - $ref: '#/components/schemas/BetaResponseCustomToolCallInputDoneEvent' + - role + - content + BetaResponseSteerPendingEvent: + type: object + title: ResponseSteerPendingEvent + description: | + Emitted when accepted steering input remains queued after the target + response completes. The server still owns the input. Do not resend it. + The successor's `response.created` event is the commit point. + + When `reason` is `waiting_for_required_input`, this event follows + `response.completed` while the response waits for the tool results or + approval decisions identified by `required_input`. Copy those stubs, fill + their result fields using the ordinary `response.create` input schemas, + and submit one continuation per parent with the same `previous_response_id` + and WebSocket lane. Use saved results without rerunning tools. The queued + steering input is prepended in submission order to the continuation's + input. That explicit request retains its own settings. + + This notification is emitted at most once per steering submission. Multiple + submissions for the same parent can report the same required inputs; they + do not each require a separate continuation. + properties: + type: + type: string + enum: + - response.steer.pending + description: The event discriminator. Always `response.steer.pending`. + x-stainless-const: true + sequence_number: + type: integer + description: The sequence number for this event. + steer: + type: object + description: The steering submission that remains queued. + properties: + id: + type: string + description: The ID assigned to the steering submission. + previous_response_id: + type: string + description: The ID of the response being steered. + required: + - id + - previous_response_id + reason: + $ref: '#/components/schemas/BetaResponseSteerPendingReason' + required_input: + type: array + minItems: 1 + description: | + Input stubs identifying outstanding client-owned tool results or + approval decisions. Each stub contains identifying fields only; the + client supplies the result before including it in `response.create`. + items: + $ref: '#/components/schemas/BetaResponseSteerRequiredInput' + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present when + the target response's `response.create` event supplied a `stream_id`. + required: + - type + - sequence_number + - steer + - reason + - required_input + x-oaiMeta: + name: response.steer.pending + group: responses + example: | + { + "type": "response.steer.pending", + "sequence_number": 10, + "steer": { + "id": "steer_456", + "previous_response_id": "resp_123" + }, + "reason": "waiting_for_required_input", + "required_input": [ + { + "type": "function_call_output", + "call_id": "call_789", + "name": "lookup" + } + ] + } + BetaResponseSteerRequiredInput: + title: ResponseSteerRequiredInput + description: | + An input stub identifying an outstanding client-owned tool result or + approval decision. Copy the stub and fill the result fields using the + corresponding `response.create` input schema. Use saved results without + rerunning the tool. The server does not supply results, approval decisions, + or safety acknowledgements in these stubs. + discriminator: + propertyName: type + anyOf: + - type: object + title: Required function tool call output + additionalProperties: false + description: | + Supply `output` using the function tool call output input schema. + properties: + type: + type: string + enum: + - function_call_output + x-stainless-const: true + call_id: + type: string + name: + type: string + required: + - type + - call_id + - name + - type: object + title: Required custom tool call output + additionalProperties: false + description: | + Supply `output` using the custom tool call output input schema. The + original custom tool call supplies the tool's name. + properties: + type: + type: string + enum: + - custom_tool_call_output + x-stainless-const: true + call_id: + type: string + required: + - type + - call_id + - type: object + title: Required computer tool call output + additionalProperties: false + description: | + Supply `output` using the computer tool call output input schema, + including any required `acknowledged_safety_checks`. + properties: + type: + type: string + enum: + - computer_call_output + x-stainless-const: true + call_id: + type: string + required: + - type + - call_id + - type: object + title: Required shell tool call output + additionalProperties: false + description: | + Supply `output` using the shell tool call output input schema. Each + output entry includes `stdout`, `stderr`, and `outcome`. + properties: + type: + type: string + enum: + - shell_call_output + x-stainless-const: true + call_id: + type: string + required: + - type + - call_id - type: object + title: Required apply patch tool call output + additionalProperties: false + description: | + Supply `status` and optional `output` using the apply patch tool call + output input schema. properties: - stream_id: + type: type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - BetaResponsesClientEvent: - discriminator: - propertyName: type - description: | - Client events accepted by the Responses WebSocket server. - anyOf: - - $ref: '#/components/schemas/BetaResponsesClientEventResponseCreate' - - $ref: '#/components/schemas/BetaResponseSteerEvent' - - $ref: '#/components/schemas/BetaResponseInjectEvent' - BetaResponseInjectEvent: - type: object - title: ResponseInjectEvent - description: | - Injects input items into an active response over a WebSocket connection. - The items are validated and committed atomically. Currently, the server - accepts client-owned tool outputs that resume a waiting agent. - properties: - type: - type: string - enum: - - response.inject - description: The event discriminator. Always `response.inject`. - x-stainless-const: true - response_id: - type: string - description: The ID of the active response that should receive the input. - input: - type: array - maxItems: 16384 - description: Input items to inject into the active response. - items: - $ref: '#/components/schemas/BetaInputItem' - required: - - type - - response_id - - input - x-oai-beta: responses_multi_agent=v1 - x-oaiMeta: - example: | - { - "type": "response.inject", - "response_id": "resp_123", - "input": [ - { - "type": "function_call_output", - "call_id": "call_123", - "output": "{\"temperature\":72}" - } - ] - } - BetaResponsesClientEventResponseCreate: - allOf: + enum: + - apply_patch_call_output + x-stainless-const: true + call_id: + type: string + required: + - type + - call_id - type: object + title: Required tool search output + additionalProperties: false + description: | + Supply `tools` using the tool search output input schema, retaining + `execution: "client"`. properties: type: type: string enum: - - response.create - description: | - The type of the client event. Always `response.create`. + - tool_search_output x-stainless-const: true - stream_id: + call_id: type: string - minLength: 1 - maxLength: 256 - pattern: ^[A-Za-z0-9_.-]+$ - description: | - The WebSocket lane for this response. Requests with the same - `stream_id` are processed FIFO, and events for the response echo the - same `stream_id`. - - `stream_id` controls routing; `previous_response_id` controls - conversation lineage, so a new lane can fork from a response created - on another lane. + execution: + type: string + enum: + - client + x-stainless-const: true required: - type - - $ref: '#/components/schemas/BetaCreateResponse' - description: | - Client event for creating a response over a persistent WebSocket connection. - This payload uses the same top-level fields as `POST /v1/responses`, plus - WebSocket-only envelope metadata. - - Notes: - - `stream` is implicit over WebSocket and should not be sent. - - `background` is not supported over WebSocket. - - `stream_id` is WebSocket-only and is not part of `POST /v1/responses`. - x-oaiMeta: - example: | - { - "type": "response.create", - "stream_id": "agent_1", - "model": "gpt-6-astra", - "input": "Say hello." - } - BetaCreateResponse: - allOf: - - $ref: '#/components/schemas/BetaCreateModelResponseProperties' - - $ref: '#/components/schemas/BetaResponseProperties' + - call_id + - execution - type: object + title: Required MCP approval response + additionalProperties: false + description: | + Supply `approve` using the MCP approval response input schema. An + optional `reason` can be supplied when denying the request. The original + approval request identifies the tool and server. properties: - prompt_cache_options: - $ref: '#/components/schemas/BetaResponsePromptCacheOptionsParam' - service_tier: - $ref: '#/components/schemas/BetaServiceTierResponses' - truncation: - deprecated: true - anyOf: - - type: string - description: | - The truncation strategy to use for the model response. - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. - enum: - - auto - - disabled - default: disabled - - type: 'null' - reasoning: - anyOf: - - $ref: '#/components/schemas/BetaReasoning' - - type: 'null' - input: - $ref: '#/components/schemas/BetaInputParam' - include: - anyOf: - - type: array - description: |- - Specify additional output data to include in the model response. Currently supported values are: - - `web_search_call.action.sources`: Include the sources of the web search tool call. - - `code_interpreter_call.outputs`: Includes the outputs of python code execution in code interpreter tool call items. - - `computer_call_output.output.image_url`: Include image urls from the computer call output. - - `file_search_call.results`: Include the search results of the file search tool call. - - `message.input_image.image_url`: Include image urls from the input message. - - `message.output_text.logprobs`: Include logprobs with assistant messages. - - `reasoning.encrypted_content`: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the `store` parameter is set to `false`, or when an organization is enrolled in the zero data retention program). - items: - $ref: '#/components/schemas/BetaIncludeEnum' - - type: 'null' - parallel_tool_calls: - anyOf: - - type: boolean - description: | - Whether to allow the model to run tool calls in parallel. - default: true - - type: 'null' - store: - anyOf: - - type: boolean - description: | - Whether to store the generated model response for later retrieval via - API. - Defaults to true when omitted. - If set to true, response data will be stored for at least 30 days, subject to the [data retention exceptions](https://developers.openai.com/api/docs/guides/your-data#v1responses). - default: true - - type: 'null' - instructions: - anyOf: - - type: string - description: | - A system (or developer) message inserted into the model's context. - - When using along with `previous_response_id`, the instructions from a previous - response will not be carried over to the next response. This makes it simple - to swap out system (or developer) messages in new responses. - - type: 'null' - moderation: - anyOf: - - $ref: '#/components/schemas/BetaModerationParam' - description: | - Configuration for running moderation on the input and output of this response. - - type: 'null' - stream: - anyOf: - - description: | - If set to true, the model response data will be streamed to the client - as it is generated using [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format). - See the [Streaming section below](https://developers.openai.com/api/reference/resources/responses/streaming-events) - for more information. - type: boolean - default: false - - type: 'null' - stream_options: - $ref: '#/components/schemas/BetaResponseStreamOptions' - conversation: - anyOf: - - $ref: '#/components/schemas/BetaConversationParam' - - type: 'null' - context_management: - anyOf: - - type: array - example: - - type: compaction - compact_threshold: 1000 - description: | - Context management configuration for this request. - minItems: 1 - items: - $ref: '#/components/schemas/BetaContextManagementParam' - - type: 'null' - max_output_tokens: - anyOf: - - description: | - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://developers.openai.com/api/docs/guides/reasoning). - type: integer - minimum: 16 - - type: 'null' - multi_agent: - anyOf: - - $ref: '#/components/schemas/BetaMultiAgentParam' - description: Configuration for server-hosted multi-agent execution. - - type: 'null' - BetaMultiAgentParam: - properties: - enabled: - type: boolean - description: Whether to enable server-hosted multi-agent execution for this response. - max_concurrent_subagents: - type: integer - minimum: 1 - description: |- - `max_concurrent_subagents` sets the maximum number of subagents that can be active simultaneously across the entire agent tree. It includes all descendants—children, grandchildren, and deeper subagents—but excludes the root agent. - The API does not impose a fixed upper bound on this setting. The default is `3`, which is recommended for most workloads. Multi-agent runs also have no fixed limit on tree depth or the total number of subagents created during a run. + type: + type: string + enum: + - mcp_approval_response + x-stainless-const: true + approval_request_id: + type: string + required: + - type + - approval_request_id + BetaResponseSteerPendingReason: + title: ResponseSteerPendingReason + description: | + An extensible enum describing why accepted steering input is still queued. + Clients should handle unknown values because additional reasons may be + introduced. Known values include: + - `waiting_for_required_input`: The response is waiting for the tool results or approval decisions identified by `required_input`. + anyOf: + - type: string + enum: + - waiting_for_required_input + - type: string + BetaResponseSteerAcceptedEvent: type: object - required: - - enabled - description: Configuration for server-hosted multi-agent execution. - x-oai-beta: responses_multi_agent=v1 - BetaContextManagementParam: + title: ResponseSteerAcceptedEvent + description: | + Emitted when steering input has been validated and queued. Acceptance means + the server owns the input, not that it has been applied. The successor's + `response.created` event is the commit point. If accepted input cannot be + committed, `response.steer.failed` returns it with the same steering ID. + + When the response stops for client-owned tool output or approval, the input + remains queued and `response.steer.pending` is emitted after + `response.completed`. Fill the pending event's `required_input` stubs with + saved results and send one matching explicit `response.create` per parent. + Do not resend accepted input while it is still queued. properties: type: type: string - description: The context management entry type. Currently only 'compaction' is supported. - compact_threshold: - anyOf: - - type: integer - minimum: 1000 - description: Token threshold at which compaction should be triggered for this entry. - - type: 'null' - type: object - required: - - type - BetaResponseStreamOptions: - anyOf: - - description: | - Options for streaming responses. Only set this when you set `stream: true`. - type: object - properties: - include_obfuscation: - type: boolean - description: | - When true, stream obfuscation will be enabled. Stream obfuscation adds - random characters to an `obfuscation` field on streaming delta events to - normalize payload sizes as a mitigation to certain side-channel attacks. - These obfuscation fields are included by default, but add a small amount - of overhead to the data stream. You can set `include_obfuscation` to - false to optimize for bandwidth if you trust the network links between - your application and the OpenAI API. - - type: 'null' - BetaModerationParam: - properties: - model: + enum: + - response.steer.accepted + description: The event discriminator. Always `response.steer.accepted`. + x-stainless-const: true + sequence_number: + type: integer + description: The sequence number for this event. + steer: + type: object + description: The accepted steering submission. + properties: + id: + type: string + description: The ID assigned to the steering submission. + previous_response_id: + type: string + description: The ID of the response being steered. + required: + - id + - previous_response_id + stream_id: type: string - description: The moderation model to use for moderated completions, e.g. 'omni-moderation-latest'. - policy: - anyOf: - - $ref: '#/components/schemas/BetaModerationPolicyParam' - description: The policy to apply to moderated response input and output. - - type: 'null' - type: object - required: - - model - description: Configuration for running moderation on the input and output of this response. - BetaModerationPolicyParam: - properties: - input: - anyOf: - - $ref: '#/components/schemas/BetaModerationConfigParam' - description: The moderation policy for the response input. - - type: 'null' - output: - anyOf: - - $ref: '#/components/schemas/BetaModerationConfigParam' - description: The moderation policy for the response output. - - type: 'null' - type: object - required: [] - description: The policy to apply to moderated response input and output. - BetaModerationConfigParam: - properties: - mode: - $ref: '#/components/schemas/BetaModerationMode' - type: object + description: | + The WebSocket lane that emitted this event. This field is present when + the target response's `response.create` event supplied a `stream_id`. required: - - mode - description: The moderation policy for the response input. - BetaModerationMode: - type: string - enum: - - score - - block - BetaResponsePromptCacheOptionsParam: - properties: - ttl: - $ref: '#/components/schemas/BetaPromptCacheTTLEnum' - description: The minimum lifetime applied to every implicit and explicit cache breakpoint written by the request. Defaults to `30m`, which is currently the only supported value. The backend may retain cache entries for longer. - mode: - $ref: '#/components/schemas/BetaPromptCacheModeEnum' - description: Controls whether OpenAI automatically creates an implicit cache breakpoint. Defaults to `implicit`. With `implicit`, OpenAI creates one implicit breakpoint and writes up to the latest three explicit breakpoints in the request. With `explicit`, OpenAI does not create an implicit breakpoint and writes up to the latest four explicit breakpoints. If there are no explicit breakpoints, the request does not use prompt caching. - prewarm: - type: boolean - description: Prepares the prompt cache without generating output. Defaults to `false`. When set to `true`, overrides the `generate` field to `false`. - comparison_response_id: - anyOf: - - type: string - description: The ID of a response to compare when diagnosing prompt cache reuse. Supplying this field requests prompt cache diagnostics when the feature is enabled. - example: resp_123 - - type: 'null' - type: object - required: [] - title: Prompt cache options - description: Options for prompt caching. Supported for `gpt-5.6` and later models. By default, OpenAI automatically chooses one implicit cache breakpoint. You can add explicit breakpoints to content blocks with `prompt_cache_breakpoint`. Each request can write up to four breakpoints. For cache matching, OpenAI considers up to the latest 80 breakpoints in the conversation, without a content-block lookback limit. Set `mode` to `explicit` to disable the implicit breakpoint. The `ttl` defaults to `30m`, which is currently the only supported value. See the [prompt caching guide](https://developers.openai.com/api/docs/guides/prompt-caching) for current details. - BetaCreateModelResponseProperties: - allOf: - - $ref: '#/components/schemas/BetaModelResponseProperties' - - type: object - properties: - prompt_cache_options: - $ref: '#/components/schemas/BetaPromptCacheOptionsParam' - top_logprobs: - description: | - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. - type: integer - minimum: 0 - maximum: 20 - BetaResponseStreamEvent: - description: Event emitted while a response is streamed. - anyOf: - - $ref: '#/components/schemas/BetaResponseAudioDeltaEvent' - - $ref: '#/components/schemas/BetaResponseAudioDoneEvent' - - $ref: '#/components/schemas/BetaResponseAudioTranscriptDeltaEvent' - - $ref: '#/components/schemas/BetaResponseAudioTranscriptDoneEvent' - - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallCodeDeltaEvent' - - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallCodeDoneEvent' - - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallCompletedEvent' - - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallInProgressEvent' - - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallInterpretingEvent' - - $ref: '#/components/schemas/BetaResponseCompactionCompactingStreamingEvent' - - $ref: '#/components/schemas/BetaResponseCompletedEvent' - - $ref: '#/components/schemas/BetaResponseContentPartAddedEvent' - - $ref: '#/components/schemas/BetaResponseContentPartDoneEvent' - - $ref: '#/components/schemas/BetaResponseCreatedEvent' - - $ref: '#/components/schemas/BetaResponseErrorEvent' - - $ref: '#/components/schemas/BetaResponseFileSearchCallCompletedEvent' - - $ref: '#/components/schemas/BetaResponseFileSearchCallInProgressEvent' - - $ref: '#/components/schemas/BetaResponseFileSearchCallSearchingEvent' - - $ref: '#/components/schemas/BetaResponseFunctionCallArgumentsDeltaEvent' - - $ref: '#/components/schemas/BetaResponseFunctionCallArgumentsDoneEvent' - - $ref: '#/components/schemas/BetaResponseShellCallCommandAddedStreamingEvent' - - $ref: '#/components/schemas/BetaResponseShellCallCommandDeltaStreamingEvent' - - $ref: '#/components/schemas/BetaResponseShellCallCommandDoneStreamingEvent' - - $ref: '#/components/schemas/BetaResponseShellCallOutputContentDeltaStreamingEvent' - x-stainless-skip: - - go - - $ref: '#/components/schemas/BetaResponseShellCallOutputContentDoneStreamingEvent' - - $ref: '#/components/schemas/BetaResponseInProgressEvent' - - $ref: '#/components/schemas/BetaResponseFailedEvent' - - $ref: '#/components/schemas/BetaResponseIncompleteEvent' - - $ref: '#/components/schemas/BetaResponseOutputItemAddedEvent' - - $ref: '#/components/schemas/BetaResponseOutputItemDoneEvent' - - $ref: '#/components/schemas/BetaResponseReasoningSummaryPartAddedEvent' - - $ref: '#/components/schemas/BetaResponseReasoningSummaryPartDoneEvent' - - $ref: '#/components/schemas/BetaResponseReasoningSummaryTextDeltaEvent' - - $ref: '#/components/schemas/BetaResponseReasoningSummaryTextDoneEvent' - - $ref: '#/components/schemas/BetaResponseReasoningTextDeltaEvent' - - $ref: '#/components/schemas/BetaResponseReasoningTextDoneEvent' - - $ref: '#/components/schemas/BetaResponseRefusalDeltaEvent' - - $ref: '#/components/schemas/BetaResponseRefusalDoneEvent' - - $ref: '#/components/schemas/BetaResponseTextDeltaEvent' - - $ref: '#/components/schemas/BetaResponseTextDoneEvent' - - $ref: '#/components/schemas/BetaResponseWebSearchCallCompletedEvent' - - $ref: '#/components/schemas/BetaResponseWebSearchCallInProgressEvent' - - $ref: '#/components/schemas/BetaResponseWebSearchCallSearchingEvent' - - $ref: '#/components/schemas/BetaResponseImageGenCallCompletedEvent' - - $ref: '#/components/schemas/BetaResponseImageGenCallGeneratingEvent' - - $ref: '#/components/schemas/BetaResponseImageGenCallInProgressEvent' - - $ref: '#/components/schemas/BetaResponseImageGenCallPartialImageEvent' - - $ref: '#/components/schemas/BetaResponseMCPCallArgumentsDeltaEvent' - - $ref: '#/components/schemas/BetaResponseMCPCallArgumentsDoneEvent' - - $ref: '#/components/schemas/BetaResponseMCPCallCompletedEvent' - - $ref: '#/components/schemas/BetaResponseMCPCallFailedEvent' - - $ref: '#/components/schemas/BetaResponseMCPCallInProgressEvent' - - $ref: '#/components/schemas/BetaResponseMCPListToolsCompletedEvent' - - $ref: '#/components/schemas/BetaResponseMCPListToolsFailedEvent' - - $ref: '#/components/schemas/BetaResponseMCPListToolsInProgressEvent' - - $ref: '#/components/schemas/BetaResponseOutputTextAnnotationAddedEvent' - - $ref: '#/components/schemas/BetaResponseQueuedEvent' - - $ref: '#/components/schemas/BetaResponseCustomToolCallInputDeltaEvent' - - $ref: '#/components/schemas/BetaResponseCustomToolCallInputDoneEvent' - discriminator: - propertyName: type + - type + - sequence_number + - steer + x-oaiMeta: + name: response.steer.accepted + group: responses + example: | + { + "type": "response.steer.accepted", + "sequence_number": 2, + "steer": { + "id": "steer_456", + "previous_response_id": "resp_123" + } + } OAuthErrorCode: anyOf: - enum: