diff --git a/.github/workflows/api-acceptance.yml b/.github/workflows/api-acceptance.yml index d4437a4c9..ee010ed18 100644 --- a/.github/workflows/api-acceptance.yml +++ b/.github/workflows/api-acceptance.yml @@ -62,6 +62,7 @@ jobs: OAC_TEST_SERVER_BIN: ${{ runner.temp }}/oac-core-build/oac-core OAC_TEST_OFFICIAL_SDK_PYTHON: python run: | + python services/core/tests/official_schema_test.py python services/core/tests/official_client.py go test ./services/core/tests/integration -run '^(TestFunctionStateOfficialClientReadsAndLiveEvents|TestSavedReferenceRetryOfficialClient|TestAgentUpdateOfficialClient|TestAgentDeletionOfficialClient|TestSessionAgentFilterOfficialClient|TestSessionDeletionOfficialClient|TestEnvironmentInitialFailureOfficialClient|TestSelfHostedInitialCreationOfficialClient|TestSelfHostedCancellationOfficialClient)$' -count=1 - uses: ./.github/actions/e2b-provider diff --git a/AGENTS.md b/AGENTS.md index 8ec48e767..d6e200722 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -25,7 +25,7 @@ Do not multiply entities without necessity. The long-term goal is minimal code, | Boundary | Protocol code | Protocol doc | | --- | --- | --- | -| Application–Core (`/v1`) | Types in `contracts/agents-api/v1/` and route annotations in `services/core/internal/api/`; `make openapi` generates `contracts/agents-api/openapi.yaml` | [Agents API guide](docs/api/public-agent-api.md) | +| Application–Core (`/v1`) | Official schema pinned by `contracts/agents-api/upstream.json` plus Go-owned `x_agents_core` extensions; `make openapi` generates public Go types and `contracts/agents-api/openapi.yaml` | [Agents API guide](docs/api/public-agent-api.md) | | Web and operators–Core (`/core/v1`) | Route annotations in `services/core/internal/api/`; `make openapi` generates `contracts/agents-api/core.openapi.yaml` | [Core administration API](contracts/agents-api/admin-api.md) | | Nodes and daemons–Core (`/api/v1` HTTP routes; the node and daemon wire protocols are separate rows) | Route annotations in `services/core/internal/api/`; `make openapi` generates `contracts/agents-api/runtime.openapi.yaml` | [Machine connection API](contracts/agents-api/machine-api.md) | | Core–Sandbox Provider | `services/core/internal/sandbox/sandbox_provider.go` | [Sandbox Provider guide](docs/sandbox-provider.md) | diff --git a/Makefile b/Makefile index 1958607db..4d91c1ca8 100644 --- a/Makefile +++ b/Makefile @@ -32,21 +32,29 @@ sqlc-generate: SWAG ?= go run github.com/swaggo/swag/cmd/swag@$(SWAG_VERSION) -.PHONY: openapi +.PHONY: openapi check-openapi +OPENAPI_FLAGS ?= +check-openapi: + $(MAKE) openapi OPENAPI_FLAGS=--check + python3 scripts/generate-public-api.test.py + openapi: + python3 scripts/generate-public-api.py $(OPENAPI_FLAGS) @set -e; root="$${OAC_DEV_HOME:-$$HOME/.oac}/build"; mkdir -p "$$root"; \ output=$$(mktemp -d "$$root/core-openapi.XXXXXX"); trap 'rm -rf "$$output"' EXIT; \ + python3 scripts/generate-public-api.py $(OPENAPI_FLAGS) --swag-roots "$$output/roots.go"; \ $(SWAG) init \ - -g cmd/server/main.go --dir ./services/core,./contracts/agents-api/v1 \ + -g cmd/server/main.go --dir "./services/core,./contracts/agents-api/v1,$$output" \ --output "$$output" \ --outputTypes yaml --parseInternal; \ python3 scripts/patch-agents-openapi.py "$$output/swagger.yaml"; \ - go run ./scripts/openapi-split "$$output/swagger.yaml" contracts/agents-api/openapi.yaml contracts/agents-api/core.openapi.yaml contracts/agents-api/runtime.openapi.yaml + go run ./scripts/openapi-split $(OPENAPI_FLAGS) "$$output/swagger.yaml" "$$output/extensions.json" contracts/agents-api/core.openapi.yaml contracts/agents-api/runtime.openapi.yaml; \ + python3 scripts/generate-public-api.py $(OPENAPI_FLAGS) --extensions "$$output/extensions.json" check-sqlc: python3 scripts/check-sqlc.py -check-go: +check-go: check-openapi go test ./apps/daemon/... ./internal/... ./contracts/agents-api/... ./scripts/openapi-split -count=1 .PHONY: check-runtime-contract diff --git a/contracts/agents-api/core.openapi.yaml b/contracts/agents-api/core.openapi.yaml index 9a74d1381..fb65920bd 100644 --- a/contracts/agents-api/core.openapi.yaml +++ b/contracts/agents-api/core.openapi.yaml @@ -1458,6 +1458,10 @@ definitions: service_tier: enum: - auto + - default + - flex + - priority + - fast type: string text: $ref: '#/definitions/v1.TextConfig' @@ -1466,13 +1470,13 @@ definitions: type: object type: array x_agents_core: - allOf: - - $ref: '#/definitions/v1.AgentsCore' - x-nullable: true + $ref: '#/definitions/v1.AgentsCore' required: - id + - instructions - model - multi_agent + - name - reasoning - service_tier - text @@ -1481,8 +1485,6 @@ definitions: v1.AgentDeleted: properties: deleted: - enum: - - true type: boolean id: type: string @@ -1546,8 +1548,8 @@ definitions: x-nullable: true type: enum: - - static_bearer - mcp_oauth + - static_bearer type: string required: - mcp_server_url @@ -1588,7 +1590,9 @@ definitions: type: string required: - data + - first_id - has_more + - last_id - object type: object v1.EnvironmentInstallation: @@ -1684,6 +1688,7 @@ definitions: - created_at - files - id + - name - network - object - packages @@ -1726,7 +1731,9 @@ definitions: type: string required: - data + - first_id - has_more + - last_id - object type: object v1.ExecutionHarnessConfigSelection: @@ -1794,7 +1801,9 @@ definitions: v1.Item: properties: action: - $ref: '#/definitions/v1.WebSearchAction' + allOf: + - $ref: '#/definitions/v1.WebSearchAction' + x-nullable: true agent_id: type: string arguments: {} @@ -1808,18 +1817,25 @@ definitions: type: array cwd: type: string + x-nullable: true duration_ms: type: integer - error: {} + x-nullable: true + error: + x-nullable: true exit_code: type: integer + x-nullable: true id: type: string + x-nullable: true model: type: string + x-nullable: true name: type: string - output: {} + output: + x-nullable: true phase: enum: - commentary @@ -1828,6 +1844,7 @@ definitions: x-nullable: true reasoning_effort: type: string + x-nullable: true recipient_agent_id: type: string recipient_agent_ids: @@ -1847,9 +1864,10 @@ definitions: enum: - in_progress - completed - - failed - incomplete + - failed type: string + x-nullable: true summary: items: $ref: '#/definitions/v1.SummaryText' @@ -1859,13 +1877,13 @@ definitions: type: enum: - message - - command_execution - - mcp_call + - reasoning - function_call - function_call_output - - web_search_call - - reasoning - agent_message + - mcp_call + - web_search_call + - command_execution - create_subagent_call - send_subagent_input_call - resume_subagent_call @@ -1889,8 +1907,8 @@ definitions: type: enum: - input_text - - output_text - input_image + - output_text - encrypted_content type: string required: @@ -1916,7 +1934,9 @@ definitions: type: string required: - data + - first_id - has_more + - last_id - object type: object v1.ModelConfigurationInput: @@ -1997,6 +2017,7 @@ definitions: x-nullable: true required: - enabled + - max_concurrent_subagents type: object v1.OAuthCredentialRefresh: properties: @@ -2014,6 +2035,8 @@ definitions: $ref: '#/definitions/v1.OAuthEndpointAuth' required: - client_id + - resource + - scope - token_endpoint - token_endpoint_auth type: object @@ -2038,9 +2061,21 @@ definitions: v1.Reasoning: properties: effort: + enum: + - none + - minimal + - low + - medium + - high + - xhigh + - max type: string x-nullable: true summary: + enum: + - concise + - detailed + - auto type: string x-nullable: true type: object @@ -2560,15 +2595,15 @@ definitions: updated_at: type: integer x_agents_core: - allOf: - - $ref: '#/definitions/v1.SavedAgentCore' - x-nullable: true + $ref: '#/definitions/v1.SavedAgentCore' required: - created_at - id + - instructions - metadata - model - multi_agent + - name - object - reasoning - service_tier @@ -2609,7 +2644,9 @@ definitions: type: string required: - data + - first_id - has_more + - last_id - object type: object v1.SavedAgentText: @@ -2686,12 +2723,14 @@ definitions: - agent - created_at - environment + - error - id - last_active_at - metadata - object - required_actions - status + - usage - vault_ids type: object v1.SessionArtifact: @@ -2759,7 +2798,9 @@ definitions: type: string required: - data + - first_id - has_more + - last_id - object type: object v1.SessionCore: @@ -2811,8 +2852,8 @@ definitions: type: enum: - none - - self_hosted - openai_hosted + - self_hosted type: string workspace_directory: type: string @@ -2868,7 +2909,9 @@ definitions: type: string required: - data + - first_id - has_more + - last_id - object type: object v1.Skill: @@ -2933,7 +2976,9 @@ definitions: type: string required: - data + - first_id - has_more + - last_id - object type: object v1.SkillVersion: @@ -3001,19 +3046,19 @@ definitions: type: string required: - data + - first_id - has_more + - last_id - object type: object v1.SourceFile: properties: bytes: - minimum: 0 type: integer created_at: type: integer expires_at: type: integer - x-nullable: true filename: type: string id: @@ -3024,15 +3069,23 @@ definitions: type: string purpose: enum: + - assistants + - assistants_output + - batch + - batch_output + - fine-tune + - fine-tune-results + - vision - user_data type: string status: enum: + - uploaded - processed + - error type: string status_details: type: string - x-nullable: true required: - bytes - created_at @@ -3065,19 +3118,17 @@ definitions: type: array first_id: type: string - x-nullable: true has_more: type: boolean last_id: type: string - x-nullable: true object: - enum: - - list type: string required: - data + - first_id - has_more + - last_id - object type: object v1.SummaryText: @@ -3179,11 +3230,16 @@ definitions: x-nullable: true required: - agent_id + - completed_at - created_at + - error - id - object - session_id + - started_at - status + - subagent_id + - usage type: object v1.TurnError: properties: @@ -3232,7 +3288,9 @@ definitions: type: string required: - data + - first_id - has_more + - last_id - object type: object v1.Vault: @@ -3256,6 +3314,7 @@ definitions: - created_at - id - metadata + - name - object type: object v1.VaultDeleted: @@ -3293,19 +3352,24 @@ definitions: type: string required: - data + - first_id - has_more + - last_id - object type: object v1.WebSearchAction: properties: pattern: type: string + x-nullable: true queries: items: type: string type: array + x-nullable: true query: type: string + x-nullable: true type: enum: - search @@ -3315,6 +3379,7 @@ definitions: type: string url: type: string + x-nullable: true required: - type type: object diff --git a/contracts/agents-api/go-bindings.json b/contracts/agents-api/go-bindings.json new file mode 100644 index 000000000..176a7d1c7 --- /dev/null +++ b/contracts/agents-api/go-bindings.json @@ -0,0 +1,642 @@ +{ + "APIError": { + "sources": ["#/components/schemas/Error"], + "fields": { + "code": {"type": "*string"} + }, + "order": ["message", "type", "code", "param"] + }, + "Agent": { + "sources": ["#/components/schemas/SessionAgentResource"], + "fields": { + "x_agents_core": {"type": "*AgentsCore"}, + "reasoning": {"type": "Reasoning"}, + "text": {"type": "TextConfig"} + }, + "order": ["x_agents_core", "id", "instructions", "model", "multi_agent", "name", "reasoning", "service_tier", "text", "tools"] + }, + "AgentContent": { + "sources": ["#/components/schemas/AgentContentResource"], + "order": ["type", "text", "encrypted_content"] + }, + "AgentDeleted": { + "sources": ["#/components/schemas/DeletedAgentResource"], + "order": ["id", "object", "deleted"] + }, + "AgentMessageItem": { + "sources": ["#/components/schemas/AgentMessageItemResource"], + "order": ["id", "turn_id", "type", "sender_agent_id", "recipient_agent_id", "content"] + }, + "CreateAgentRequest": { + "sources": ["#/components/schemas/CreateAgentParams"], + "fields": { + "x_agents_core": {"type": "*SavedAgentCoreInput"}, + "model": {"type": "*string"}, + "metadata": {"type": "map[string]*string"}, + "reasoning": {"type": "*Reasoning"}, + "text": {"type": "*SavedAgentTextInput"} + }, + "order": ["x_agents_core", "model", "name", "instructions", "metadata", "multi_agent", "reasoning", "service_tier", "text", "tools"] + }, + "CreateCredentialRequest": { + "sources": ["#/components/schemas/CreateVaultCredentialParams"], + "fields": { + "name": {"type": "*string"}, + "auth": {"type": "*CredentialAuthInput"} + }, + "order": ["name", "auth"] + }, + "CreateEventsRequest": { + "sources": ["#/components/schemas/CreateSessionEventsParams"], + "order": ["events"] + }, + "CreateSessionRequest": { + "sources": ["#/components/schemas/CreateAgentSessionParams"], + "fields": { + "x_agents_core": {"type": "*SessionExecutionInput"}, + "environment": {"type": "*Environment"}, + "input": {"type": "any"}, + "stream": {"type": "bool"} + }, + "order": ["x_agents_core", "agent", "agent_id", "environment", "input", "metadata", "stream", "vault_ids"] + }, + "CreateSubagentCallItem": { + "sources": ["#/components/schemas/CreateSubagentCallItemResource"], + "order": ["id", "turn_id", "type", "status", "agent_id", "content", "model", "reasoning_effort"] + }, + "CreateVaultRequest": { + "sources": ["#/components/schemas/CreateVaultParams"], + "fields": { + "metadata": {"type": "map[string]*string"} + }, + "order": ["name", "metadata"] + }, + "Credential": { + "sources": ["#/components/schemas/VaultCredentialResource"], + "order": ["id", "vault_id", "name", "object", "auth", "created_at", "updated_at"] + }, + "CredentialAuth": { + "sources": ["#/components/schemas/VaultCredentialAuthResource"], + "fields": { + "expires_at": {"omit": false}, + "refresh": {"type": "*OAuthCredentialRefresh", "omit": false} + }, + "order": ["type", "mcp_server_url", "expires_at", "refresh"] + }, + "CredentialAuthInput": { + "sources": ["#/components/schemas/CreateVaultCredentialAuthParam"], + "fields": { + "mcp_server_url": {"type": "*string"}, + "refresh": {"type": "*OAuthCredentialRefreshInput"} + }, + "order": ["type", "mcp_server_url", "token", "access_token", "expires_at", "refresh"] + }, + "CredentialAuthReplacement": { + "sources": ["#/components/schemas/RotateVaultCredentialAuthParam"], + "fields": { + "expires_at": {"type": "json.RawMessage"}, + "refresh": {"type": "*OAuthCredentialRefreshReplacement"} + }, + "order": ["type", "token", "access_token", "expires_at", "refresh"] + }, + "CredentialDeleted": { + "sources": ["#/components/schemas/DeletedVaultCredentialResource"], + "order": ["id", "deleted", "object"] + }, + "CredentialList": { + "sources": ["#/components/schemas/VaultCredentialListResource"], + "order": ["object", "data", "has_more", "first_id", "last_id"] + }, + "Environment": { + "sources": ["#/components/schemas/EnvironmentParam"], + "fields": { + "packages": {"type": "*EnvironmentPackages"}, + "files": {"type": "[]json.RawMessage"}, + "environment_template_id": {"type": "string"}, + "workspace_directory": {"type": "string"}, + "network": {"type": "*EnvironmentNetworkInput"} + }, + "order": ["plugins", "skills", "env", "setup_commands", "packages", "files", "environment_template_id", "type", "workspace_directory", "capability_directories", "network"] + }, + "EnvironmentConnectionAction": { + "sources": ["#/components/schemas/SessionRequiredActionResourceEnvironmentConnection"], + "order": ["environment_id", "type"] + }, + "EnvironmentFile": { + "sources": ["#/components/schemas/EnvironmentFileResource"], + "order": ["environment_id", "object", "path", "size_bytes"] + }, + "EnvironmentFileCreateRequest": { + "sources": ["#/components/schemas/HostedEnvironmentFileParam"], + "fields": { + "path": {"type": "*string"} + }, + "order": ["type", "data", "file_id", "path"] + }, + "EnvironmentFileList": { + "sources": ["#/components/schemas/EnvironmentFileListResource"], + "order": ["object", "data", "next", "has_more"] + }, + "EnvironmentInfo": { + "sources": ["#/components/schemas/PublicEnvironmentResource"], + "order": ["id", "object", "type", "status", "files", "plugins", "skills"] + }, + "EnvironmentNetwork": { + "sources": ["#/components/schemas/NetworkPolicyResource"], + "order": ["access", "allowed_domains"] + }, + "EnvironmentNetworkInput": { + "sources": ["#/components/schemas/NetworkPolicyParam"], + "order": ["access", "allowed_domains"] + }, + "EnvironmentPackages": { + "exclude": ["system"], + "sources": ["#/components/schemas/EnvironmentPackagesParam"], + "fields": { + "npm": {"omit": false}, + "python": {"omit": false} + }, + "order": ["npm", "python"] + }, + "EnvironmentPackagesInput": { + "exclude": ["system"], + "sources": ["#/components/schemas/EnvironmentPackagesParam"], + "order": ["npm", "python"] + }, + "EnvironmentPackagesResponse": { + "sources": ["#/components/schemas/EnvironmentPackagesResource"], + "order": ["npm", "python", "system"] + }, + "EnvironmentTemplate": { + "sources": ["#/components/schemas/EnvironmentTemplateResource"], + "order": ["id", "object", "name", "created_at", "updated_at", "capability_directories", "network", "packages", "files", "plugins", "skills"] + }, + "EnvironmentTemplateDeleted": { + "sources": ["#/components/schemas/DeletedEnvironmentTemplateResource"], + "order": ["id", "object", "deleted"] + }, + "EnvironmentTemplateList": { + "sources": ["#/components/schemas/EnvironmentTemplateListResource"], + "order": ["object", "data", "has_more", "first_id", "last_id"] + }, + "EnvironmentTemplateRequest": { + "sources": ["#/components/schemas/CreateEnvironmentTemplateParams"], + "fields": { + "network": {"type": "*EnvironmentNetworkInput"}, + "files": {"type": "[]json.RawMessage"}, + "packages": {"type": "*EnvironmentPackagesInput"} + }, + "order": ["name", "network", "capability_directories", "env", "files", "packages", "plugins", "skills", "setup_commands"] + }, + "ErrorResponse": { + "sources": ["#/components/schemas/ErrorResponse-2"], + "fields": {"error": {"type": "APIError"}}, + "order": ["error"] + }, + "FunctionCallAction": { + "sources": ["#/components/schemas/SessionRequiredActionResourceFunctionCall"], + "fields": { + "arguments": {"type": "any"} + }, + "order": ["arguments", "call_id", "name", "turn_id", "type"] + }, + "FunctionToolInput": { + "sources": ["#/components/schemas/AgentToolConfigParamFunction"], + "fields": { + "name": {"type": "*string"}, + "description": {"type": "*string"}, + "parameters": {"type": "json.RawMessage"}, + "defer_loading": {"type": "json.RawMessage"} + }, + "order": ["type", "name", "description", "parameters", "defer_loading"] + }, + "InlineAgent": { + "sources": ["#/components/schemas/SessionAgentConfigParam"], + "fields": { + "x_agents_core": {"type": "*AgentsCore"}, + "reasoning": {"type": "*Reasoning"}, + "text": {"type": "*SavedAgentTextInput"} + }, + "order": ["x_agents_core", "model", "instructions", "multi_agent", "reasoning", "service_tier", "text", "tools"] + }, + "InputContent": { + "sources": ["#/components/schemas/InputContentParam"], + "order": ["type", "text", "image_url"] + }, + "InputMessage": { + "sources": ["#/components/schemas/InputMessageParam"], + "fields": { + "type": {"type": "string"} + }, + "order": ["type", "role", "content"] + }, + "InputTokenDetails": { + "sources": ["#/components/schemas/InputTokensDetailsResource"], + "order": ["cached_tokens"] + }, + "Item": { + "sources": ["#/components/schemas/SessionTurnItemResource"], + "fields": { + "id": {"type": "string"}, + "status": {"type": "string", "omit": false}, + "role": {"type": "string"}, + "phase": {"type": "string"}, + "content": {"type": "[]ItemContent"}, + "command": {"type": "string"}, + "name": {"type": "string"}, + "call_id": {"type": "string"}, + "server_label": {"type": "string"}, + "arguments": {"type": "any"}, + "output": {"type": "any"}, + "error": {"type": "any"}, + "action": {"type": "*WebSearchAction"}, + "agent_id": {"type": "string"}, + "sender_agent_id": {"type": "string"}, + "recipient_agent_id": {"type": "string"} + }, + "order": ["id", "turn_id", "type", "status", "role", "phase", "content", "command", "cwd", "duration_ms", "exit_code", "name", "call_id", "server_label", "arguments", "output", "error", "action", "agent_id", "sender_agent_id", "recipient_agent_id", "recipient_agent_ids", "model", "reasoning_effort", "summary"] + }, + "ItemContent": { + "sources": ["#/components/schemas/MessageContentResource", "#/components/schemas/EncryptedContentResource"], + "fields": { + "image_url": {"type": "string"} + }, + "order": ["type", "text", "image_url", "encrypted_content"] + }, + "ItemList": { + "sources": ["#/components/schemas/SessionItemListResource"], + "order": ["object", "first_id", "last_id", "data", "has_more"] + }, + "MCPHTTPTransport": { + "sources": ["#/components/schemas/PersistedMcpTransportConfigParamHttp"], + "fields": { + "headers": {"type": "*map[string]string"} + }, + "order": ["type", "server_url", "headers"] + }, + "MCPTool": { + "sources": ["#/components/schemas/AgentToolResourceMcp"], + "fields": { + "transport": {"type": "MCPHTTPTransport"}, + "allowed_tools": {"type": "*[]string"} + }, + "order": ["type", "server_label", "transport", "allowed_tools", "connection_origin", "credential_id", "request_metadata", "required"] + }, + "MCPToolInput": { + "sources": ["#/components/schemas/AgentToolConfigParamMcp"], + "fields": { + "server_label": {"type": "*string"}, + "allowed_tools": {"type": "json.RawMessage", "omit": false}, + "connection_origin": {"omit": false}, + "credential_id": {"omit": false}, + "request_metadata": {"type": "json.RawMessage", "omit": false}, + "required": {"type": "json.RawMessage", "omit": false} + }, + "order": ["type", "server_label", "transport", "allowed_tools", "connection_origin", "credential_id", "request_metadata", "required"] + }, + "MultiAgentConfig": { + "sources": ["#/components/schemas/MultiAgentConfigResource"], + "fields": { + "max_concurrent_subagents": {"type": "*int"} + }, + "order": ["enabled", "max_concurrent_subagents"] + }, + "OAuthCredentialRefresh": { + "sources": ["#/components/schemas/McpOauthRefreshResource"], + "order": ["client_id", "token_endpoint", "token_endpoint_auth", "resource", "scope"] + }, + "OAuthCredentialRefreshInput": { + "sources": ["#/components/schemas/CreateMcpOauthRefreshParam"], + "fields": { + "client_id": {"type": "*string"}, + "refresh_token": {"type": "*string"}, + "token_endpoint": {"type": "*string"}, + "token_endpoint_auth": {"type": "*OAuthEndpointAuthInput"} + }, + "order": ["client_id", "refresh_token", "token_endpoint", "token_endpoint_auth", "resource", "scope"] + }, + "OAuthCredentialRefreshReplacement": { + "sources": ["#/components/schemas/RotateMcpOauthRefreshParam"], + "fields": { + "scope": {"type": "json.RawMessage"}, + "token_endpoint_auth": {"type": "*OAuthEndpointAuthReplacement"} + }, + "order": ["refresh_token", "scope", "token_endpoint_auth"] + }, + "OAuthEndpointAuth": { + "sources": ["#/components/schemas/McpOauthTokenEndpointAuthResource"], + "order": ["type"] + }, + "OAuthEndpointAuthInput": { + "sources": ["#/components/schemas/CreateMcpOauthTokenEndpointAuthParam"], + "order": ["type", "client_secret"] + }, + "OAuthEndpointAuthReplacement": { + "sources": ["#/components/schemas/RotateMcpOauthTokenEndpointAuthParam"], + "order": ["type", "client_secret"] + }, + "OutputTokenDetails": { + "sources": ["#/components/schemas/OutputTokensDetailsResource"], + "order": ["reasoning_tokens"] + }, + "Reasoning": { + "sources": ["#/components/schemas/ReasoningParam"], + "order": ["effort", "summary"] + }, + "ReasoningItem": { + "sources": ["#/components/schemas/ReasoningItemResource"], + "order": ["id", "turn_id", "type", "status", "summary"] + }, + "RequiredAction": { + "sources": ["#/components/schemas/SessionRequiredActionResource"], + "fields": { + "arguments": {"type": "any"}, + "call_id": {"type": "string"}, + "name": {"type": "string"}, + "turn_id": {"type": "string"}, + "environment_id": {"type": "string"} + }, + "order": ["type", "arguments", "call_id", "name", "turn_id", "environment_id"] + }, + "SavedAgent": { + "sources": ["#/components/schemas/AgentResource"], + "embed": {"SavedAgentConfiguration": ["x_agents_core", "model", "name", "instructions", "multi_agent", "reasoning", "service_tier", "text", "tools"]}, + "order": ["id", "object", "metadata", "created_at", "updated_at"] + }, + "SavedAgentConfiguration": { + "sources": ["#/components/schemas/AgentResource"], + "fields": { + "x_agents_core": {"type": "*SavedAgentCore"}, + "reasoning": {"type": "Reasoning"} + }, + "exclude": ["id", "object", "created_at", "updated_at", "metadata"], + "order": ["x_agents_core", "model", "name", "instructions", "multi_agent", "reasoning", "service_tier", "text", "tools"] + }, + "SavedAgentList": { + "sources": ["#/components/schemas/AgentListResource"], + "order": ["object", "data", "has_more", "first_id", "last_id"] + }, + "SavedAgentText": { + "sources": ["#/components/schemas/TextResource"], + "order": ["format", "verbosity"] + }, + "SavedAgentTextFormat": { + "sources": ["#/components/schemas/TextFormatResource"], + "fields": { + "schema": {"type": "json.RawMessage"} + }, + "order": ["type", "schema"] + }, + "SavedAgentTextInput": { + "sources": ["#/components/schemas/TextParam"], + "order": ["format", "verbosity"] + }, + "SendSubagentInputCallItem": { + "sources": ["#/components/schemas/SendSubagentInputCallItemResource"], + "order": ["id", "turn_id", "type", "status", "sender_agent_id", "recipient_agent_id", "content"] + }, + "Session": { + "sources": ["#/components/schemas/SessionResource"], + "fields": { + "x_agents_core": {"type": "*SessionCore"}, + "usage": {"type": "*TokenUsage"} + }, + "order": ["x_agents_core", "id", "agent", "created_at", "environment", "error", "last_active_at", "metadata", "object", "required_actions", "status", "usage", "vault_ids"] + }, + "SessionArtifact": { + "sources": ["#/components/schemas/SessionArtifactResource"], + "order": ["id", "created_at", "environment_id", "object", "path", "session_id", "size_bytes", "turn_id"] + }, + "SessionArtifactDeleted": { + "sources": ["#/components/schemas/DeletedSessionArtifactResource"], + "order": ["id", "object", "deleted"] + }, + "SessionArtifactList": { + "sources": ["#/components/schemas/SessionArtifactListResource"], + "order": ["object", "first_id", "last_id", "data", "has_more"] + }, + "SessionDeleted": { + "sources": ["#/components/schemas/DeletedSessionResource"], + "order": ["id", "deleted", "object"] + }, + "SessionEnvironment": { + "sources": ["#/components/schemas/EnvironmentResource"], + "fields": { + "id": {"type": "string"}, + "capability_directories": {"type": "*[]string"}, + "remote_url": {"type": "string"}, + "workspace_directory": {"type": "string"}, + "files": {"type": "*[]json.RawMessage"}, + "plugins": {"type": "*[]json.RawMessage"}, + "skills": {"type": "*[]json.RawMessage"} + }, + "order": ["type", "id", "capability_directories", "remote_url", "workspace_directory", "network", "packages", "files", "plugins", "skills"] + }, + "SessionEnvironmentState": { + "sources": ["#/components/schemas/SessionEnvironmentStateResource"], + "fields": { + "error": {"type": "*StreamError"} + }, + "order": ["id", "type", "status", "error"] + }, + "SessionEvent": { + "sources": ["#/components/schemas/SessionEvent"], + "fields": { + "subagent": {"type": "*Subagent"}, + "session_id": {"type": "string"}, + "turn_id": {"type": "string"}, + "session": {"type": "*Session"}, + "turn": {"type": "*Turn"}, + "item": {"type": "*Item"}, + "item_id": {"type": "string"}, + "output_index": {"type": "*int32"}, + "content_index": {"type": "*int"}, + "part": {"type": "*ItemContent"}, + "usage": {"type": "*TokenUsage"} + }, + "order": ["subagent", "type", "event_id", "session_id", "turn_id", "session", "turn", "item", "item_id", "output_index", "content_index", "part", "delta", "text", "error", "environment", "usage"] + }, + "SessionInput": { + "sources": ["#/components/schemas/SessionInputParam"], + "fields": { + "call_id": {"type": "string"}, + "turn_id": {"type": "string"}, + "error": {"type": "json.RawMessage"}, + "output": {"type": "any"} + }, + "order": ["type", "input", "call_id", "turn_id", "success", "error", "output"] + }, + "SessionList": { + "sources": ["#/components/schemas/SessionListResource"], + "order": ["object", "first_id", "last_id", "data", "has_more"] + }, + "Skill": { + "sources": ["#/components/schemas/SkillResource"], + "order": ["id", "object", "created_at", "name", "description", "default_version", "latest_version"] + }, + "SkillDeleted": { + "sources": ["#/components/schemas/DeletedSkillResource"], + "order": ["id", "object", "deleted"] + }, + "SkillList": { + "sources": ["#/components/schemas/SkillListResource"], + "order": ["object", "data", "first_id", "last_id", "has_more"] + }, + "SkillUpdateRequest": { + "sources": ["#/components/schemas/SetDefaultSkillVersionBody"], + "order": ["default_version"] + }, + "SkillVersion": { + "sources": ["#/components/schemas/SkillVersionResource"], + "order": ["id", "object", "created_at", "skill_id", "version", "name", "description"] + }, + "SkillVersionDeleted": { + "sources": ["#/components/schemas/DeletedSkillVersionResource"], + "order": ["id", "object", "version", "deleted"] + }, + "SkillVersionList": { + "sources": ["#/components/schemas/SkillVersionListResource"], + "order": ["object", "data", "first_id", "last_id", "has_more"] + }, + "SourceFile": { + "sources": ["#/components/schemas/OpenAIFile"], + "fields": { + "expires_at": {"omit": false}, + "status_details": {"omit": false} + }, + "order": ["id", "object", "bytes", "created_at", "filename", "purpose", "status", "expires_at", "status_details"] + }, + "SourceFileDeleted": { + "sources": ["#/components/schemas/DeleteFileResponse"], + "order": ["id", "object", "deleted"] + }, + "SourceFileList": { + "sources": ["#/components/schemas/ListFilesResponse"], + "fields": { + "first_id": {"type": "*string"}, + "last_id": {"type": "*string"} + }, + "order": ["object", "data", "has_more", "first_id", "last_id"] + }, + "StreamError": { + "sources": ["#/components/schemas/SessionErrorResource"], + "fields": { + "code": {"type": "string"}, + "param": {"omit": true} + }, + "order": ["code", "type", "message", "param"] + }, + "Subagent": { + "sources": ["#/components/schemas/SubagentResource"], + "order": ["id", "object", "session_id", "parent_agent_id", "opened_at", "closed_at", "name", "instructions", "status"] + }, + "SubagentControlCallItem": { + "sources": ["#/components/schemas/ResumeSubagentCallItemResource", "#/components/schemas/InterruptSubagentCallItemResource", "#/components/schemas/CloseSubagentCallItemResource"], + "order": ["id", "turn_id", "type", "status", "sender_agent_id", "recipient_agent_id"] + }, + "SubagentList": { + "sources": ["#/paths/~1agents~1sessions~1{session_id}~1subagents/get/responses/200/content/application~1json/schema"], + "order": ["object", "first_id", "last_id", "data", "has_more"] + }, + "SummaryText": { + "sources": ["#/components/schemas/SummaryTextResource"], + "order": ["type", "text"] + }, + "TextConfig": { + "sources": ["#/components/schemas/TextResource"], + "order": ["format", "verbosity"], + "fields": { + "format": {"type": "TextFormat"} + } + }, + "TextConfigInput": { + "sources": ["#/components/schemas/TextParam"], + "fields": { + "format": {"type": "*TextFormat"} + }, + "order": ["format", "verbosity"] + }, + "TextFormat": { + "sources": ["#/components/schemas/TextFormatResource"], + "fields": { + "schema": {"type": "json.RawMessage"} + }, + "order": ["type", "schema"] + }, + "TokenUsage": { + "sources": ["#/components/schemas/TokenUsageResource"], + "order": ["input_tokens", "input_tokens_details", "output_tokens", "output_tokens_details", "total_tokens"] + }, + "Turn": { + "sources": ["#/components/schemas/TurnResource"], + "fields": { + "error": {"type": "*TurnError"}, + "usage": {"type": "*TokenUsage"} + }, + "order": ["id", "agent_id", "subagent_id", "session_id", "object", "status", "created_at", "started_at", "completed_at", "error", "usage"] + }, + "TurnError": { + "sources": ["#/components/schemas/SessionTurnErrorResource"], + "order": ["code", "message"] + }, + "TurnList": { + "sources": ["#/components/schemas/SessionTurnListResource"], + "order": ["object", "first_id", "last_id", "data", "has_more"] + }, + "UpdateAgentRequest": { + "sources": ["#/components/schemas/UpdateAgentParams"], + "fields": { + "x_agents_core": {"type": "*SavedAgentCoreInput"}, + "metadata": {"type": "map[string]*string"}, + "reasoning": {"type": "*Reasoning"}, + "text": {"type": "*SavedAgentTextInput"} + }, + "order": ["x_agents_core", "model", "name", "instructions", "metadata", "multi_agent", "reasoning", "service_tier", "text", "tools"] + }, + "UpdateCredentialRequest": { + "sources": ["#/components/schemas/RotateVaultCredentialParams"], + "fields": { + "auth": {"type": "*CredentialAuthReplacement"} + }, + "order": ["auth"] + }, + "UpdateSessionRequest": { + "sources": ["#/components/schemas/UpdateAgentSessionParams"], + "fields": { + "metadata": {"omit": false} + }, + "order": ["metadata"] + }, + "Vault": { + "sources": ["#/components/schemas/VaultResource"], + "order": ["id", "object", "created_at", "name", "metadata"] + }, + "VaultDeleted": { + "sources": ["#/components/schemas/DeletedVaultResource"], + "order": ["id", "deleted", "object"] + }, + "VaultList": { + "sources": ["#/components/schemas/VaultListResource"], + "order": ["object", "data", "has_more", "first_id", "last_id"] + }, + "WaitForSubagentsCallItem": { + "sources": ["#/components/schemas/WaitForSubagentsCallItemResource"], + "order": ["id", "turn_id", "type", "status", "sender_agent_id", "recipient_agent_ids"] + }, + "WebSearchAction": { + "marshal_union": true, + "sources": ["#/components/schemas/WebSearchActionResource"], + "order": ["type", "query", "queries", "url", "pattern"] + }, + "reasoningResponse": { + "sources": ["#/components/schemas/ReasoningResource"], + "order": ["effort", "summary"] + }, + "sessionError": { + "sources": ["#/components/schemas/SessionErrorResource"], + "fields": { + "code": {"type": "string"} + }, + "order": ["code", "type", "message", "param"] + } +} diff --git a/contracts/agents-api/index.md b/contracts/agents-api/index.md index be6bed469..87dd67793 100644 --- a/contracts/agents-api/index.md +++ b/contracts/agents-api/index.md @@ -9,10 +9,18 @@ Core targets the complete OpenAI Agents API as pinned below ([public API rule](h | File | Contents | | --- | --- | | [upstream.json](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/contracts/agents-api/upstream.json) | The pin: [openai-python](https://github.com/openai/openai-python/tree/d7c41efee1b0802b79f3f88a678ef2052b06e9ce/src/openai/resources/beta/agents) 3.13.0 at commit `d7c41ef`, resources under `beta/agents`, Beta header `agents=v1` | -| [upstream-routes.json](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/contracts/agents-api/upstream-routes.json), [upstream-fields.json](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/contracts/agents-api/upstream-fields.json) | The 58 method and path pairs and their official fields: 42 operations under `beta/agents`, 5 Files and 11 Skills operations. `scripts/extract-agents-api-upstream.py` extracts them from the pinned SDK; run it with that SDK installed | -| [openapi.yaml](./openapi.yaml) | Core's public schema, generated by `make openapi` from the route annotations in `services/core/internal/api/` and the wire types in [`v1/`](https://github.com/MiniMax-AI/OpenAgentCore/tree/main/contracts/agents-api/v1) | +| [upstream/openapi.json](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/contracts/agents-api/upstream/openapi.json) | Unmodified official OpenAPI 3.1 at commit `046a2a0f325bf11f97966f2729219f27281ba71e`, published on 2026-09-10. Its 58 Agents, Vaults, Files and Skills operations match the pinned SDK route set. `upstream.json` records the SHA-256 checksum | +| [upstream-routes.json](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/contracts/agents-api/upstream-routes.json) | The normalized method/path inventory generated from the official schema | +| [openapi.yaml](./openapi.yaml) | The official public contract with Core's `x_agents_core` extension on Agent and Session request/response objects | +| [go-bindings.json](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/contracts/agents-api/go-bindings.json) | Go names, field representations, encoding order and stored projections; it does not define official field membership, enums or constraints | -Contract tests hold Core to the pin: the router and `openapi.yaml` serve exactly the pinned routes (`services/core/internal/api/routing_test.go`, `v1/upstream_contract_test.go`), every query parameter and field is official, and Core-only fields sit only inside `x_agents_core` on Agents and Sessions. Swagger 2.0 cannot express string-or-array unions, so `openapi.yaml` leaves Session `input` and function-result `output` unconstrained; the pinned types and Core's validation define them. Operations and fields newer than the pin wait for a protocol upgrade. +Run `make openapi` to regenerate the public Go types, route inventory and all three OpenAPI documents. `scripts/generate-public-api.py` reads the checked-in, checksum-verified official source without network access. It selects Agents, Vaults, Files and Skills and follows their schema references, preserving union types, nullability, required fields and constraints. Core's extension types in `v1/` remain authored in Go and are added to the public schema during generation. The internal `/core/v1` and `/api/v1` documents come from handler annotations. `make check-openapi` checks freshness and the generator; it also runs through `make check-go`. + +The public contract is the official API plus Core extensions. Standard fields are generated into `v1/official.gen.go`; `go-bindings.json` controls their Go representation where existing storage or custom JSON encoding requires it. Selected discriminated unions also generate JSON serializers to retain required nullable fields for each variant. Other union serializers, request admission and state transitions remain implementation code. Contract tests verify that the public schema preserves the official definitions, extensions remain in `x_agents_core`, and all documents match registered routes. Official-client and raw HTTP tests verify behavior. Schema generation does not qualify an unimplemented feature; the gaps below still apply. Upstream upgrades update the OpenAPI and SDK pins together after comparison and compatibility tests. + +The official source and existing service have these recorded differences: Agents authentication errors can return a null `code`; empty Files pages return null `first_id` and `last_id`; File resources can return null `expires_at` and `status_details`. The source declares those fields non-null. The official-client response validator allows null only for these named fields and otherwise validates OpenAPI 3.1 response schemas. Files and Skills operations omit error responses in the source, so those error bodies use the upstream shared `ErrorResponse` schema. [Wire semantics](./wire-semantics.md) and raw HTTP tests qualify service behavior; the published schema retains the official definitions. + +Go input projections exclude `packages.system` to preserve its explicit rejection, recorded below. Generation does not enable an unsupported operation or change stored setup validation. Evidence for a status comes from the pinned official SDK and raw HTTP against the running service, as [CONTRIBUTING](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/CONTRIBUTING.md#compatibility-evidence) requires. diff --git a/contracts/agents-api/openapi.yaml b/contracts/agents-api/openapi.yaml index 64c942b2e..1885da9ed 100644 --- a/contracts/agents-api/openapi.yaml +++ b/contracts/agents-api/openapi.yaml @@ -1,5429 +1,19444 @@ -basePath: /v1 -definitions: - v1.APIError: - properties: - code: - type: string - x-nullable: true - message: - type: string - param: - type: string - x-nullable: true - type: - type: string - required: - - message - - type - type: object - v1.Agent: - properties: - id: - type: string - instructions: - type: string - x-nullable: true - model: - type: string - multi_agent: - $ref: '#/definitions/v1.MultiAgentConfig' - name: - type: string - x-nullable: true - reasoning: - $ref: '#/definitions/v1.Reasoning' - service_tier: - enum: - - auto - type: string - text: - $ref: '#/definitions/v1.TextConfig' - tools: - items: - type: object - type: array - x_agents_core: - allOf: - - $ref: '#/definitions/v1.AgentsCore' - x-nullable: true - required: - - id - - model - - multi_agent - - reasoning - - service_tier - - text - - tools - type: object - v1.AgentContent: - properties: - encrypted_content: - type: string - text: - type: string - type: - enum: - - output_text - - encrypted_content - type: string - required: - - type - type: object - v1.AgentDeleted: - properties: - deleted: - enum: - - true - type: boolean - id: - type: string - object: - enum: - - agent.deleted - type: string - required: - - deleted - - id - - object - type: object - v1.AgentsCore: - properties: - harness: - enum: - - claude_sdk - - codex - - mcode - type: string - harness_config: - type: object - type: object - v1.CreateAgentRequest: - properties: - instructions: - type: string - x-nullable: true - metadata: - additionalProperties: - type: string - type: object - x-nullable: true - model: - type: string - multi_agent: - type: object - x-nullable: true - name: - maxLength: 128 - type: string - x-nullable: true - reasoning: - allOf: - - $ref: '#/definitions/v1.Reasoning' - x-nullable: true - service_tier: - enum: - - auto - - default - - flex - - priority - - fast - type: string - x-nullable: true - text: - allOf: - - $ref: '#/definitions/v1.SavedAgentTextInput' - x-nullable: true - tools: - items: - type: object - type: array - x-nullable: true - x_agents_core: - allOf: - - $ref: '#/definitions/v1.SavedAgentCoreInput' - x-nullable: true - required: - - model - type: object - v1.CreateCredentialRequest: - properties: - auth: - $ref: '#/definitions/v1.CredentialAuthInput' - name: - type: string - required: - - auth - - name - type: object - v1.CreateEventsRequest: - properties: - events: - items: - $ref: '#/definitions/v1.SessionInput' - type: array - required: - - events - type: object - v1.CreateSessionRequest: - properties: - agent: - $ref: '#/definitions/v1.InlineAgent' - agent_id: - type: string - environment: - $ref: '#/definitions/v1.Environment' - input: - description: |- - Input accepts a string or an ordered array of user InputMessage objects. - Required for none and streamed creation outside self_hosted; otherwise optional. - x-nullable: true - metadata: - additionalProperties: - type: string - type: object - x-nullable: true - stream: - default: false - type: boolean - vault_ids: - items: - type: string - type: array - x_agents_core: - $ref: '#/definitions/v1.SessionExecutionInput' - required: - - environment - type: object - v1.CreateVaultRequest: - properties: - metadata: - additionalProperties: - type: string - type: object - x-nullable: true - name: - type: string - type: object - v1.Credential: - properties: - auth: - $ref: '#/definitions/v1.CredentialAuth' - created_at: - type: integer - id: - type: string - name: - type: string - object: - enum: - - vault.credential - type: string - updated_at: - type: integer - vault_id: - type: string - required: - - auth - - created_at - - id - - name - - object - - updated_at - - vault_id - type: object - v1.CredentialAuth: - properties: - expires_at: - type: string - x-nullable: true - mcp_server_url: - type: string - refresh: - allOf: - - $ref: '#/definitions/v1.OAuthCredentialRefresh' - x-nullable: true - type: - enum: - - static_bearer - - mcp_oauth - type: string - required: - - mcp_server_url - - type - type: object - v1.CredentialAuthInput: - properties: - access_token: - minLength: 1 - type: string - expires_at: - type: string - x-nullable: true - mcp_server_url: - type: string - refresh: - allOf: - - $ref: '#/definitions/v1.OAuthCredentialRefreshInput' - x-nullable: true - token: - minLength: 1 - type: string - type: - enum: - - static_bearer - - mcp_oauth - type: string - required: - - mcp_server_url - - type - type: object - v1.CredentialAuthReplacement: - properties: - access_token: - minLength: 1 - type: string - x-nullable: true - expires_at: - type: string - x-nullable: true - refresh: - allOf: - - $ref: '#/definitions/v1.OAuthCredentialRefreshReplacement' - x-nullable: true - token: - minLength: 1 - type: string - type: - enum: - - static_bearer - - mcp_oauth - type: string - required: - - type - type: object - v1.CredentialDeleted: - properties: - deleted: - type: boolean - id: - type: string - object: - enum: - - vault.credential.deleted - type: string - required: - - deleted - - id - - object - type: object - v1.CredentialList: - properties: - data: - items: - $ref: '#/definitions/v1.Credential' - type: array - first_id: - type: string - x-nullable: true - has_more: - type: boolean - last_id: - type: string - x-nullable: true - object: - enum: - - list - type: string - required: - - data - - has_more - - object - type: object - v1.Environment: - properties: - capability_directories: - items: - type: string - type: array - x-nullable: true - env: - additionalProperties: - type: string - type: object - x-nullable: true - environment_template_id: - type: string - files: - items: - type: object - type: array - x-nullable: true - network: - allOf: - - $ref: '#/definitions/v1.EnvironmentNetworkInput' - x-nullable: true - packages: - allOf: - - $ref: '#/definitions/v1.EnvironmentPackages' - x-nullable: true - plugins: - items: - type: object - type: array - x-nullable: true - setup_commands: - items: - type: object - type: array - x-nullable: true - skills: - items: - type: object - type: array - x-nullable: true - type: - enum: - - none - - self_hosted - - openai_hosted - type: string - workspace_directory: - type: string - required: - - type - type: object - v1.EnvironmentFile: - properties: - environment_id: - type: string - object: - enum: - - agent.environment.file - type: string - path: - type: string - size_bytes: - minimum: 0 - type: integer - required: - - environment_id - - object - - path - - size_bytes - type: object - v1.EnvironmentFileCreateRequest: - properties: - data: - type: string - file_id: - type: string - path: - type: string - type: - enum: - - inline - - file_id - type: string - required: - - path - - type - type: object - v1.EnvironmentFileList: - properties: - data: - items: - $ref: '#/definitions/v1.EnvironmentFile' - type: array - has_more: - type: boolean - next: - type: string - x-nullable: true - object: - enum: - - page - type: string - required: - - data - - has_more - - object - type: object - v1.EnvironmentInfo: - properties: - files: - items: - type: object - type: array - id: - type: string - object: - enum: - - agent.environment - type: string - plugins: - items: - type: object - type: array - skills: - items: - type: object - type: array - status: - enum: - - pending - - connected - - disconnected - - expired - - failed - type: string - type: - enum: - - openai_hosted - - self_hosted - type: string - required: - - files - - id - - object - - plugins - - skills - - status - - type - type: object - v1.EnvironmentInstallation: - properties: - commands: - additionalProperties: - type: string - type: object - expires_at: - type: integer - message: - type: string - status: - enum: - - available - - unavailable - type: string - version: - type: string - type: object - v1.EnvironmentNetwork: - properties: - access: - enum: - - enabled - - disabled - - restricted - type: string - allowed_domains: - items: - type: string - type: array - required: - - access - - allowed_domains - type: object - v1.EnvironmentNetworkInput: - properties: - access: - enum: - - enabled - - disabled - - restricted - type: string - allowed_domains: - items: - type: string - type: array - x-nullable: true - required: - - access - type: object - v1.EnvironmentPackages: - properties: - npm: - items: - type: string - type: array - python: - items: - type: string - type: array - required: - - npm - - python - type: object - v1.EnvironmentPackagesInput: - properties: - npm: - items: - type: string - type: array - x-nullable: true - python: - items: - type: string - type: array - x-nullable: true - type: object - v1.EnvironmentPackagesResponse: - properties: - npm: - items: - type: string - type: array - python: - items: - type: string - type: array - system: - items: - type: string - type: array - required: - - npm - - python - - system - type: object - v1.EnvironmentTemplate: - properties: - capability_directories: - items: - type: string - type: array - created_at: - type: integer - files: - items: - type: object - type: array - id: - type: string - name: - type: string - x-nullable: true - network: - $ref: '#/definitions/v1.EnvironmentNetwork' - object: - enum: - - agent.environment.template - type: string - packages: - $ref: '#/definitions/v1.EnvironmentPackagesResponse' - plugins: - items: - type: object - type: array - skills: - items: - type: object - type: array - updated_at: - type: integer - required: - - capability_directories - - created_at - - files - - id - - network - - object - - packages - - plugins - - skills - - updated_at - type: object - v1.EnvironmentTemplateDeleted: - properties: - deleted: - type: boolean - id: - type: string - object: - enum: - - agent.environment.template.deleted - type: string - required: - - deleted - - id - - object - type: object - v1.EnvironmentTemplateList: - properties: - data: - items: - $ref: '#/definitions/v1.EnvironmentTemplate' - type: array - first_id: - type: string - x-nullable: true - has_more: - type: boolean - last_id: - type: string - x-nullable: true - object: - enum: - - list - type: string - required: - - data - - has_more - - object - type: object - v1.EnvironmentTemplateRequest: - properties: - capability_directories: - items: - type: string - type: array - x-nullable: true - env: - additionalProperties: - type: string - type: object - x-nullable: true - files: - items: - type: object - type: array - x-nullable: true - name: - type: string - x-nullable: true - network: - allOf: - - $ref: '#/definitions/v1.EnvironmentNetworkInput' - x-nullable: true - packages: - allOf: - - $ref: '#/definitions/v1.EnvironmentPackagesInput' - x-nullable: true - plugins: - items: - type: object - type: array - x-nullable: true - setup_commands: - items: - type: object - type: array - x-nullable: true - skills: - items: - type: object - type: array - x-nullable: true - type: object - v1.ErrorResponse: - properties: - error: - $ref: '#/definitions/v1.APIError' - required: - - error - type: object - v1.InlineAgent: - properties: - instructions: - type: string - x-nullable: true - model: - type: string - multi_agent: - type: object - x-nullable: true - reasoning: - allOf: - - $ref: '#/definitions/v1.Reasoning' - x-nullable: true - service_tier: - enum: - - auto - - default - - flex - - priority - - fast - type: string - x-nullable: true - text: - allOf: - - $ref: '#/definitions/v1.SavedAgentTextInput' - x-nullable: true - tools: - items: - type: object - type: array - x-nullable: true - x_agents_core: - allOf: - - $ref: '#/definitions/v1.AgentsCore' - x-nullable: true - type: object - v1.InputContent: - properties: - image_url: - type: string - text: - type: string - type: - enum: - - input_text - - input_image - type: string - required: - - type - type: object - v1.InputMessage: - properties: - content: - items: - $ref: '#/definitions/v1.InputContent' - type: array - role: - enum: - - user - type: string - type: - enum: - - message - type: string - required: - - content - - role - type: object - v1.InputTokenDetails: - properties: - cached_tokens: - type: integer - required: - - cached_tokens - type: object - v1.Item: - properties: - action: - $ref: '#/definitions/v1.WebSearchAction' - agent_id: - type: string - arguments: {} - call_id: - type: string - command: - type: string - content: - items: - $ref: '#/definitions/v1.ItemContent' - type: array - cwd: - type: string - duration_ms: - type: integer - error: {} - exit_code: - type: integer - id: - type: string - model: - type: string - name: - type: string - output: {} - phase: - enum: - - commentary - - final_answer - type: string - x-nullable: true - reasoning_effort: - type: string - recipient_agent_id: - type: string - recipient_agent_ids: - items: - type: string - type: array - role: - enum: - - user - - assistant - type: string - sender_agent_id: - type: string - server_label: - type: string - status: - enum: - - in_progress - - completed - - failed - - incomplete - type: string - summary: - items: - $ref: '#/definitions/v1.SummaryText' - type: array - turn_id: - type: string - type: - enum: - - message - - command_execution - - mcp_call - - function_call - - function_call_output - - web_search_call - - reasoning - - agent_message - - create_subagent_call - - send_subagent_input_call - - resume_subagent_call - - wait_for_subagents_call - - interrupt_subagent_call - - close_subagent_call - type: string - required: - - id - - turn_id - - type - type: object - v1.ItemContent: - properties: - encrypted_content: - type: string - image_url: - type: string - text: - type: string - type: - enum: - - input_text - - output_text - - input_image - - encrypted_content - type: string - required: - - type - type: object - v1.ItemList: - properties: - data: - items: - $ref: '#/definitions/v1.Item' - type: array - first_id: - type: string - x-nullable: true - has_more: - type: boolean - last_id: - type: string - x-nullable: true - object: - enum: - - list - type: string - required: - - data - - has_more - - object - type: object - v1.ModelProviderInput: - properties: - api_key: - type: string - base_url: - type: string - context_window: - type: integer - max_output_tokens: - type: integer - protocol: - enum: - - anthropic - - responses - - chat_completions - type: string - required: - - api_key - - base_url - - protocol - type: object - v1.ModelProviderView: - properties: - api_key_configured: - type: boolean - base_url: - type: string - context_window: - type: integer - max_output_tokens: - type: integer - protocol: - enum: - - anthropic - - responses - - chat_completions - type: string - required: - - api_key_configured - - base_url - - protocol - type: object - v1.MultiAgentConfig: - properties: - enabled: - type: boolean - max_concurrent_subagents: - type: integer - x-nullable: true - required: - - enabled - type: object - v1.OAuthCredentialRefresh: - properties: - client_id: - type: string - resource: - type: string - x-nullable: true - scope: - type: string - x-nullable: true - token_endpoint: - type: string - token_endpoint_auth: - $ref: '#/definitions/v1.OAuthEndpointAuth' - required: - - client_id - - token_endpoint - - token_endpoint_auth - type: object - v1.OAuthCredentialRefreshInput: - properties: - client_id: - type: string - refresh_token: - type: string - resource: - type: string - x-nullable: true - scope: - type: string - x-nullable: true - token_endpoint: - type: string - token_endpoint_auth: - $ref: '#/definitions/v1.OAuthEndpointAuthInput' - required: - - client_id - - refresh_token - - token_endpoint - - token_endpoint_auth - type: object - v1.OAuthCredentialRefreshReplacement: - properties: - refresh_token: - type: string - x-nullable: true - scope: - type: string - x-nullable: true - token_endpoint_auth: - allOf: - - $ref: '#/definitions/v1.OAuthEndpointAuthReplacement' - x-nullable: true - type: object - v1.OAuthEndpointAuth: - properties: - type: - enum: - - none - - client_secret_basic - - client_secret_post - type: string - required: - - type - type: object - v1.OAuthEndpointAuthInput: - properties: - client_secret: - type: string - type: - enum: - - none - - client_secret_basic - - client_secret_post - type: string - required: - - type - type: object - v1.OAuthEndpointAuthReplacement: - properties: - client_secret: - type: string - x-nullable: true - type: - enum: - - client_secret_basic - - client_secret_post - type: string - required: - - type - type: object - v1.OutputTokenDetails: - properties: - reasoning_tokens: - type: integer - required: - - reasoning_tokens - type: object - v1.Reasoning: - properties: - effort: - type: string - x-nullable: true - summary: - type: string - x-nullable: true - type: object - v1.RequiredAction: - properties: - arguments: {} - call_id: - type: string - environment_id: - type: string - name: - type: string - turn_id: - type: string - type: - enum: - - function_call - - environment_connection - type: string - required: - - type - type: object - v1.SavedAgent: - properties: - created_at: - type: integer - id: - type: string - instructions: - type: string - x-nullable: true - metadata: - additionalProperties: - type: string - type: object - model: - type: string - multi_agent: - $ref: '#/definitions/v1.MultiAgentConfig' - name: - type: string - x-nullable: true - object: - enum: - - agent - type: string - reasoning: - $ref: '#/definitions/v1.Reasoning' - service_tier: - enum: - - auto - - default - - flex - - priority - - fast - type: string - text: - $ref: '#/definitions/v1.SavedAgentText' - tools: - items: - type: object - type: array - updated_at: - type: integer - x_agents_core: - allOf: - - $ref: '#/definitions/v1.SavedAgentCore' - x-nullable: true - required: - - created_at - - id - - metadata - - model - - multi_agent - - object - - reasoning - - service_tier - - text - - tools - - updated_at - type: object - v1.SavedAgentCore: - properties: - harness: - enum: - - claude_sdk - - codex - - mcode - type: string - harness_config: - type: object - model_provider: - $ref: '#/definitions/v1.ModelProviderView' - type: object - v1.SavedAgentCoreInput: - properties: - harness: - enum: - - claude_sdk - - codex - - mcode - type: string - harness_config: - type: object - model_provider: - allOf: - - $ref: '#/definitions/v1.ModelProviderInput' - x-nullable: true - type: object - v1.SavedAgentList: - properties: - data: - items: - $ref: '#/definitions/v1.SavedAgent' - type: array - first_id: - type: string - x-nullable: true - has_more: - type: boolean - last_id: - type: string - x-nullable: true - object: - enum: - - list - type: string - required: - - data - - has_more - - object - type: object - v1.SavedAgentText: - properties: - format: - $ref: '#/definitions/v1.SavedAgentTextFormat' - verbosity: - enum: - - low - - medium - - high - type: string - required: - - format - - verbosity - type: object - v1.SavedAgentTextFormat: - properties: - schema: - type: object - type: - enum: - - text - - json_schema - type: string - required: - - type - type: object - v1.SavedAgentTextInput: - properties: - format: - type: object - x-nullable: true - verbosity: - enum: - - low - - medium - - high - type: string - x-nullable: true - type: object - v1.Session: - properties: - agent: - $ref: '#/definitions/v1.Agent' - created_at: - type: integer - environment: - $ref: '#/definitions/v1.SessionEnvironment' - error: - type: string - x-nullable: true - id: - type: string - last_active_at: - type: integer - metadata: - additionalProperties: - type: string - type: object - object: - enum: - - agent.session - type: string - required_actions: - items: - $ref: '#/definitions/v1.RequiredAction' - type: array - status: - enum: - - idle - - in_progress - - requires_action - - failed - type: string - usage: - allOf: - - $ref: '#/definitions/v1.TokenUsage' - x-nullable: true - vault_ids: - items: - type: string - type: array - x_agents_core: - $ref: '#/definitions/v1.SessionCore' - required: - - agent - - created_at - - environment - - id - - last_active_at - - metadata - - object - - required_actions - - status - - vault_ids - type: object - v1.SessionArtifact: - properties: - created_at: - type: integer - environment_id: - type: string - id: - type: string - object: - enum: - - agent.session.artifact - type: string - path: - type: string - session_id: - type: string - size_bytes: - type: integer - turn_id: - type: string - required: - - created_at - - environment_id - - id - - object - - path - - session_id - - size_bytes - - turn_id - type: object - v1.SessionArtifactDeleted: - properties: - deleted: - type: boolean - id: - type: string - object: - enum: - - agent.session.artifact.deleted - type: string - required: - - deleted - - id - - object - type: object - v1.SessionArtifactList: - properties: - data: - items: - $ref: '#/definitions/v1.SessionArtifact' - type: array - first_id: - type: string - x-nullable: true - has_more: - type: boolean - last_id: - type: string - x-nullable: true - object: - enum: - - list - type: string - required: - - data - - has_more - - object - type: object - v1.SessionCore: - properties: - installation: - $ref: '#/definitions/v1.EnvironmentInstallation' - type: object - v1.SessionDeleted: - properties: - deleted: - type: boolean - id: - type: string - object: - enum: - - agent.session.deleted - type: string - required: - - deleted - - id - - object - type: object - v1.SessionEnvironment: - properties: - capability_directories: - items: - type: string - type: array - files: - items: - type: object - type: array - id: - type: string - network: - $ref: '#/definitions/v1.EnvironmentNetwork' - packages: - $ref: '#/definitions/v1.EnvironmentPackagesResponse' - plugins: - items: - type: object - type: array - remote_url: - type: string - skills: - items: - type: object - type: array - type: - enum: - - none - - self_hosted - - openai_hosted - type: string - workspace_directory: - type: string - required: - - type - type: object - v1.SessionEnvironmentState: - properties: - error: - allOf: - - $ref: '#/definitions/v1.StreamError' - x-nullable: true - id: - type: string - status: - enum: - - pending - - ready - - connected - - disconnected - - failed - type: string - type: - type: string - required: - - id - - status - - type - type: object - v1.SessionEvent: - properties: - content_index: - type: integer - delta: - type: string - environment: - $ref: '#/definitions/v1.SessionEnvironmentState' - error: - $ref: '#/definitions/v1.StreamError' - event_id: - type: string - item: - $ref: '#/definitions/v1.Item' - item_id: - type: string - output_index: - type: integer - x-nullable: true - part: - $ref: '#/definitions/v1.ItemContent' - session: - $ref: '#/definitions/v1.Session' - session_id: - type: string - subagent: - $ref: '#/definitions/v1.Subagent' - text: - type: string - turn: - $ref: '#/definitions/v1.Turn' - turn_id: - type: string - type: - type: string - usage: - allOf: - - $ref: '#/definitions/v1.TokenUsage' - description: |- - Usage is present only on terminal Turn events, where it mirrors the Turn - snapshot and is null when unknown. Other events omit it. - x-nullable: true - required: - - event_id - - type - type: object - v1.SessionExecutionInput: - properties: - environment: - description: Environment supplies placement-independent preparation through - the Core extension. - type: object - harness_config: - type: object - model_provider: - $ref: '#/definitions/v1.ModelProviderInput' - type: object - v1.SessionInput: - properties: - call_id: - type: string - error: - type: string - x-nullable: true - input: - items: - $ref: '#/definitions/v1.InputMessage' - type: array - output: - x-nullable: true - success: - type: boolean - turn_id: - type: string - type: - enum: - - agent.session.input.message - - agent.session.input.cancel - - agent.session.input.tool_result - type: string - required: - - type - type: object - v1.SessionList: - properties: - data: - items: - $ref: '#/definitions/v1.Session' - type: array - first_id: - type: string - x-nullable: true - has_more: - type: boolean - last_id: - type: string - x-nullable: true - object: - enum: - - list - type: string - required: - - data - - has_more - - object - type: object - v1.Skill: - properties: - created_at: - type: integer - default_version: - type: string - description: - type: string - id: - type: string - latest_version: - type: string - name: - type: string - object: - enum: - - skill - type: string - required: - - created_at - - default_version - - description - - id - - latest_version - - name - - object - type: object - v1.SkillDeleted: - properties: - deleted: - type: boolean - id: - type: string - object: - enum: - - skill.deleted - type: string - required: - - deleted - - id - - object - type: object - v1.SkillList: - properties: - data: - items: - $ref: '#/definitions/v1.Skill' - type: array - first_id: - type: string - x-nullable: true - has_more: - type: boolean - last_id: - type: string - x-nullable: true - object: - enum: - - list - type: string - required: - - data - - has_more - - object - type: object - v1.SkillUpdateRequest: - properties: - default_version: - type: string - required: - - default_version - type: object - v1.SkillVersion: - properties: - created_at: - type: integer - description: - type: string - id: - type: string - name: - type: string - object: - enum: - - skill.version - type: string - skill_id: - type: string - version: - type: string - required: - - created_at - - description - - id - - name - - object - - skill_id - - version - type: object - v1.SkillVersionDeleted: - properties: - deleted: - type: boolean - id: - type: string - object: - enum: - - skill.version.deleted - type: string - version: - type: string - required: - - deleted - - id - - object - - version - type: object - v1.SkillVersionList: - properties: - data: - items: - $ref: '#/definitions/v1.SkillVersion' - type: array - first_id: - type: string - x-nullable: true - has_more: - type: boolean - last_id: - type: string - x-nullable: true - object: - enum: - - list - type: string - required: - - data - - has_more - - object - type: object - v1.SourceFile: - properties: - bytes: - minimum: 0 - type: integer - created_at: - type: integer - expires_at: - type: integer - x-nullable: true - filename: - type: string - id: - type: string - object: - enum: - - file - type: string - purpose: - enum: - - user_data - type: string - status: - enum: - - processed - type: string - status_details: - type: string - x-nullable: true - required: - - bytes - - created_at - - filename - - id - - object - - purpose - - status - type: object - v1.SourceFileDeleted: - properties: - deleted: - type: boolean - id: - type: string - object: - enum: - - file - type: string - required: - - deleted - - id - - object - type: object - v1.SourceFileList: - properties: - data: - items: - $ref: '#/definitions/v1.SourceFile' - type: array - first_id: - type: string - x-nullable: true - has_more: - type: boolean - last_id: - type: string - x-nullable: true - object: - enum: - - list - type: string - required: - - data - - has_more - - object - type: object - v1.StreamError: - properties: - code: - type: string - message: - type: string - param: - description: |- - Param is the pinned SessionError field. An error SessionEvent always - carries it, null when unset; Environment state errors and Core's own - stream_interrupted frame omit it. - type: string - x-nullable: true - type: - type: string - type: object - v1.Subagent: - properties: - closed_at: - type: integer - x-nullable: true - id: - type: string - instructions: - items: - $ref: '#/definitions/v1.AgentContent' - type: array - x-nullable: true - name: - type: string - x-nullable: true - object: - enum: - - agent.session.subagent - type: string - opened_at: - type: integer - parent_agent_id: - type: string - session_id: - type: string - status: - enum: - - active - - closed - type: string - required: - - id - - object - - opened_at - - parent_agent_id - - session_id - - status - type: object - v1.SubagentList: - properties: - data: - items: - $ref: '#/definitions/v1.Subagent' - type: array - first_id: - type: string - x-nullable: true - has_more: - type: boolean - last_id: - type: string - x-nullable: true - object: - enum: - - list - type: string - required: - - data - - has_more - - object - type: object - v1.SummaryText: - properties: - text: - type: string - type: - enum: - - summary_text - type: string - required: - - text - - type - type: object - v1.TextConfig: - properties: - format: - $ref: '#/definitions/v1.TextFormat' - verbosity: - enum: - - low - - medium - - high - type: string - required: - - format - - verbosity - type: object - v1.TextFormat: - properties: - schema: - type: object - type: - enum: - - text - - json_schema - type: string - required: - - type - type: object - v1.TokenUsage: - properties: - input_tokens: - type: integer - input_tokens_details: - $ref: '#/definitions/v1.InputTokenDetails' - output_tokens: - type: integer - output_tokens_details: - $ref: '#/definitions/v1.OutputTokenDetails' - total_tokens: - type: integer - required: - - input_tokens - - input_tokens_details - - output_tokens - - output_tokens_details - - total_tokens - type: object - v1.Turn: - properties: - agent_id: - type: string - completed_at: - type: integer - x-nullable: true - created_at: - type: integer - error: - allOf: - - $ref: '#/definitions/v1.TurnError' - x-nullable: true - id: - type: string - object: - enum: - - agent.session.turn - type: string - session_id: - type: string - started_at: - type: integer - x-nullable: true - status: - enum: - - queued - - in_progress - - waiting - - completed - - failed - - cancelled - type: string - subagent_id: - type: string - x-nullable: true - usage: - allOf: - - $ref: '#/definitions/v1.TokenUsage' - x-nullable: true - required: - - agent_id - - created_at - - id - - object - - session_id - - status - type: object - v1.TurnError: - properties: - code: - enum: - - context_length_exceeded - - session_budget_exceeded - - usage_limit_exceeded - - 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 - type: string - message: - type: string - required: - - code - - message - type: object - v1.TurnList: - properties: - data: - items: - $ref: '#/definitions/v1.Turn' - type: array - first_id: - type: string - x-nullable: true - has_more: - type: boolean - last_id: - type: string - x-nullable: true - object: - enum: - - list - type: string - required: - - data - - has_more - - object - type: object - v1.UpdateAgentRequest: - properties: - instructions: - type: string - x-nullable: true - metadata: - additionalProperties: - type: string - type: object - x-nullable: true - model: - type: string - multi_agent: - type: object - x-nullable: true - name: - maxLength: 128 - type: string - x-nullable: true - reasoning: - allOf: - - $ref: '#/definitions/v1.Reasoning' - x-nullable: true - service_tier: - enum: - - auto - - default - - flex - - priority - - fast - type: string - x-nullable: true - text: - allOf: - - $ref: '#/definitions/v1.SavedAgentTextInput' - x-nullable: true - tools: - items: - type: object - type: array - x-nullable: true - x_agents_core: - allOf: - - $ref: '#/definitions/v1.SavedAgentCoreInput' - x-nullable: true - type: object - v1.UpdateCredentialRequest: - properties: - auth: - $ref: '#/definitions/v1.CredentialAuthReplacement' - required: - - auth - type: object - v1.UpdateSessionRequest: - properties: - metadata: - additionalProperties: - type: string - type: object - x-nullable: true - required: - - metadata - type: object - v1.Vault: - properties: - created_at: - type: integer - id: - type: string - metadata: - additionalProperties: - type: string - type: object - name: - type: string - x-nullable: true - object: - enum: - - vault - type: string - required: - - created_at - - id - - metadata - - object - type: object - v1.VaultDeleted: - properties: - deleted: - type: boolean - id: - type: string - object: - enum: - - vault.deleted - type: string - required: - - deleted - - id - - object - type: object - v1.VaultList: - properties: - data: - items: - $ref: '#/definitions/v1.Vault' - type: array - first_id: - type: string - x-nullable: true - has_more: - type: boolean - last_id: - type: string - x-nullable: true - object: - enum: - - list - type: string - required: - - data - - has_more - - object - type: object - v1.WebSearchAction: - properties: - pattern: - type: string - queries: - items: - type: string - type: array - query: - type: string - type: - enum: - - search - - open_page - - find_in_page - - other - type: string - url: - type: string - required: - - type - type: object -info: - contact: {} - description: Supported single-Agent execution resources from the pinned openai-python - beta/agents contract. Bearer keys bind an execution principal to one project; - optional OpenAI-Organization and OpenAI-Project headers must match that binding. - license: - name: Apache 2.0 - url: https://www.apache.org/licenses/LICENSE-2.0.html - title: OpenAgentCore Agents API - version: "1" -paths: - /agents: - get: - description: Lists only the authenticated tenant's saved Agents, independently - of Sessions. Limit 0 is treated as 1 and larger limits as 100, as observed - on the hosted service. The local default is 20; exact upstream default/cap - and empty cursor fields remain unverified. An unknown, malformed or foreign - after cursor returns not found. - parameters: - - description: agents=v1 - in: header - name: OpenAI-Beta - required: true - type: string - - description: Last Agent ID from the previous page - in: query - name: after - type: string - - default: 20 - description: Page size; 0 is treated as 1 and values above 100 as 100 - in: query - minimum: 0 - name: limit - type: integer - - default: desc - description: Creation order; omit for descending, explicit empty values are - invalid - enum: - - asc - - desc - in: query - name: order - type: string - produces: - - application/json - responses: - "200": - description: OK - schema: - $ref: '#/definitions/v1.SavedAgentList' - "400": - description: Bad Request - schema: - $ref: '#/definitions/v1.ErrorResponse' - "401": - description: Unauthorized - schema: - $ref: '#/definitions/v1.ErrorResponse' - "404": - description: Not Found - schema: - $ref: '#/definitions/v1.ErrorResponse' - "500": - description: Internal Server Error - schema: - $ref: '#/definitions/v1.ErrorResponse' - security: - - BearerAuth: [] - summary: List reusable Agents - tags: - - Agents - post: - consumes: - - application/json - description: 'Persists configuration independently of execution. Names over - 128 characters and metadata outside 16 string pairs with 64-character keys - and 512-character values return invalid_request_error with the official param; - U+0000 in stored strings is rejected as a local storage limit. As on every - Agents API JSON route, a non-JSON Content-Type, invalid UTF-8, malformed JSON, - a repeated key at any depth or a non-object root returns invalid_request_error - with a null param and the official message before other checks; an empty or - null body is {}. Missing, unknown, wrongly typed or unsupported enum members - of the pinned configuration shapes (tools, text, reasoning, service_tier, - multi_agent) return invalid_request_error with the JSON path as param; duplicate - function names, repeated web_search or tool_search and non-object schema root - types return it with a null param. Supports model/name/instructions/metadata, - explicit reasoning and service tiers, multi_agent, text/json_schema, function/tool_search/programmatic_tool_calling/web_search - and HTTP MCP with nullable credential_id, service origin (omitted or null - on HTTP transport is saved as service) and boolean required defaulting to - false. Saving credential_id grants no access: Session admission checks attached - Vault ownership and destination. MCP allowed_tools preserves null versus empty; - saved HTTP transport includes empty headers. Model-derived reasoning defaults, - other MCP variants and public retry conformance remain incomplete. web_search - saves every pinned mode: omitted or null mode is saved as live and omitted - or null context_size as medium; allowed_domains preserves null versus empty - and a present location, including {}, includes all four keys with null for - omitted ones, as observed officially (req_db41d2f6261b4abfb69465eafe719ab5, - req_165d53b88445490b9146d8272c54134d). Session execution accepts only explicit - disabled web_search and disabled programmatic_tool_calling through qualified - Runtime controls; saved enabled forms reject at Session admission. Session - execution admits only its supported configuration subset.' - parameters: - - description: agents=v1 - in: header - name: OpenAI-Beta - required: true - type: string - - description: Reusable Agent configuration - in: body - name: body - required: true - schema: - $ref: '#/definitions/v1.CreateAgentRequest' - produces: - - application/json - responses: - "201": - description: Created - schema: - $ref: '#/definitions/v1.SavedAgent' - "400": - description: Bad Request - schema: - $ref: '#/definitions/v1.ErrorResponse' - "401": - description: Unauthorized - schema: - $ref: '#/definitions/v1.ErrorResponse' - "413": - description: Request Entity Too Large - schema: - $ref: '#/definitions/v1.ErrorResponse' - "500": - description: Internal Server Error - schema: - $ref: '#/definitions/v1.ErrorResponse' - security: - - BearerAuth: [] - summary: Create a reusable Agent - tags: - - Agents - /agents/{agent_id}: - delete: - description: Deletes only the authenticated tenant's saved configuration. Existing - Session snapshots, history and recorded creation retry identities remain independent. - Missing and repeated deletion locally return404; exact hosted error and in-flight - creation/deletion semantics remain unverified. - parameters: - - description: agents=v1 - in: header - name: OpenAI-Beta - required: true - type: string - - description: Agent ID - in: path - name: agent_id - required: true - type: string - produces: - - application/json - responses: - "200": - description: OK - schema: - $ref: '#/definitions/v1.AgentDeleted' - "400": - description: Bad Request - schema: - $ref: '#/definitions/v1.ErrorResponse' - "401": - description: Unauthorized - schema: - $ref: '#/definitions/v1.ErrorResponse' - "404": - description: Not Found - schema: - $ref: '#/definitions/v1.ErrorResponse' - "413": - description: Request Entity Too Large - schema: - $ref: '#/definitions/v1.ErrorResponse' - "500": - description: Internal Server Error - schema: - $ref: '#/definitions/v1.ErrorResponse' - security: - - BearerAuth: [] - summary: Delete a reusable Agent - tags: - - Agents - get: - description: Reads the saved resource owned by the authenticated tenant, independently - of execution Sessions. - parameters: - - description: agents=v1 - in: header - name: OpenAI-Beta - required: true - type: string - - description: Agent ID - in: path - name: agent_id - required: true - type: string - produces: - - application/json - responses: - "200": - description: OK - schema: - $ref: '#/definitions/v1.SavedAgent' - "400": - description: Bad Request - schema: - $ref: '#/definitions/v1.ErrorResponse' - "401": - description: Unauthorized - schema: - $ref: '#/definitions/v1.ErrorResponse' - "404": - description: Not Found - schema: - $ref: '#/definitions/v1.ErrorResponse' - "500": - description: Internal Server Error - schema: - $ref: '#/definitions/v1.ErrorResponse' - security: - - BearerAuth: [] - summary: Retrieve a reusable Agent - tags: - - Agents - post: - consumes: - - application/json - description: Preserves omitted fields and replaces supplied fields using shared - saved-configuration validation. Null name/instructions clear; null or empty - metadata clears all pairs. Name, metadata and configuration validation errors - return invalid_request_error with the official param, using the Agent create - rules before the Agent lookup. Existing Session snapshots are unchanged. Empty - updates advance updated_at without changing saved fields. Nested replacement/null - defaults, model-derived reasoning and exact hosted error behavior remain incompletely - verified. - parameters: - - description: agents=v1 - in: header - name: OpenAI-Beta - required: true - type: string - - description: Agent ID - in: path - name: agent_id - required: true - type: string - - description: Supplied reusable Agent fields - in: body - name: body - required: true - schema: - $ref: '#/definitions/v1.UpdateAgentRequest' - produces: - - application/json - responses: - "200": - description: OK - schema: - $ref: '#/definitions/v1.SavedAgent' - "400": - description: Bad Request - schema: - $ref: '#/definitions/v1.ErrorResponse' - "401": - description: Unauthorized - schema: - $ref: '#/definitions/v1.ErrorResponse' - "404": - description: Not Found - schema: - $ref: '#/definitions/v1.ErrorResponse' - "413": - description: Request Entity Too Large - schema: - $ref: '#/definitions/v1.ErrorResponse' - "500": - description: Internal Server Error - schema: - $ref: '#/definitions/v1.ErrorResponse' - security: - - BearerAuth: [] - summary: Update a reusable Agent - tags: - - Agents - /agents/environments/{environment_id}: - get: - description: Returns durable connection status and safe installed metadata for - supported self_hosted and basic openai_hosted profiles. Initial files expose - frozen safe metadata without content; Plugin/Skill entries expose only safe - configured installation metadata. Capability-directory discoveries are not - added to those arrays. Unsupported installation configurations remain implementation - gaps. This read does not prepare execution, start compute or require an enabled - execution worker. Session deletion removes the associated Environment from - public reads; project-shared read authorization is unchanged. Connection status - does not prove native readiness or process quiescence. - parameters: - - description: agents=v1 - in: header - name: OpenAI-Beta - required: true - type: string - - description: Environment ID - in: path - name: environment_id - required: true - type: string - produces: - - application/json - responses: - "200": - description: OK - schema: - $ref: '#/definitions/v1.EnvironmentInfo' - "400": - description: Bad Request - schema: - $ref: '#/definitions/v1.ErrorResponse' - "401": - description: Unauthorized - schema: - $ref: '#/definitions/v1.ErrorResponse' - "404": - description: Not Found - schema: - $ref: '#/definitions/v1.ErrorResponse' - "500": - description: Internal Server Error - schema: - $ref: '#/definitions/v1.ErrorResponse' - security: - - BearerAuth: [] - summary: Retrieve an execution Environment - tags: - - Environments - /agents/environments/{environment_id}/files: - get: - description: Lists direct regular files in one authorized self_hosted or qualified - local workspace directory. Local paths use the public /workspace root and - must be in cleaned form. This partial implementation defaults to the workspace - root and limit 20; recursive scope and these defaults are not verified upstream - semantics. A missing path, a regular file or a symbolic link returns an empty - page; links are never followed. Daemons without a local workspace binding - use the Claude SDK adapter reader, which keeps 404 for a missing path and - 503 for a regular file or symbolic link. Well-formed unknown query keys are - ignored; malformed query encoding and a repeated supported key are rejected. - Sorts by case-sensitive path components, descending by default. Keep the same - path, order and limit when using page. Each page rereads the complete bounded - directory; changed file paths/sizes invalidate continuation locally with 400. - There is no snapshot guarantee. An openai_hosted Environment that has not - connected yet returns 400. Truncated or uncertain native results fail with - 503 without returning a partial page. This read never starts a Turn or admits - model input. Actual transport disconnect/reconnect events remain observable. - parameters: - - description: agents=v1 - in: header - name: OpenAI-Beta - required: true - type: string - - description: Environment ID - in: path - name: environment_id - required: true - type: string - - description: Absolute directory in cleaned form inside /workspace - in: query - name: path - type: string - - description: Maximum file count; local default 20 - in: query - maximum: 100 - minimum: 1 - name: limit - type: integer - - default: desc - description: Case-sensitive path-component order; omit for descending, explicit - empty values are invalid - enum: - - asc - - desc - in: query - name: order - type: string - - description: Opaque continuation token; keep path, order and limit unchanged - in: query - name: page - type: string - produces: - - application/json - responses: - "200": - description: OK - schema: - $ref: '#/definitions/v1.EnvironmentFileList' - "400": - description: Bad Request - schema: - $ref: '#/definitions/v1.ErrorResponse' - "401": - description: Unauthorized - schema: - $ref: '#/definitions/v1.ErrorResponse' - "404": - description: Not Found - schema: - $ref: '#/definitions/v1.ErrorResponse' - "500": - description: Internal Server Error - schema: - $ref: '#/definitions/v1.ErrorResponse' - "503": - description: Service Unavailable - schema: - $ref: '#/definitions/v1.ErrorResponse' - security: - - BearerAuth: [] - summary: List live Environment files - tags: - - Environments - post: - consumes: - - application/json - description: Uploads standard Base64 bytes to a file beneath /workspace in a - qualified local Environment and returns 201. Accepts inline bytes or a project-owned - source file_id through the same write path. Unknown body fields are rejected - with their name as param. Basic public hosted creation requires explicit managed - Runtime configuration; an openai_hosted Environment that has not connected - yet returns 400. Inline data is limited to 5 MiB decoded and a file_id copy - to 50 MiB. Missing parent directories are created with mode 0700 and the file - with mode 0600. An existing destination is never replaced; a directory, an - existing file or a path through a symlink or non-directory returns 400. Idle - writes exclude execution. Missing receipts return unavailable and retain a - durable mutation gate without automatic replay. Error/timing parity with upstream - remains unverified. - parameters: - - description: agents=v1 - in: header - name: OpenAI-Beta - required: true - type: string - - description: Environment ID - in: path - name: environment_id - required: true - type: string - - description: Inline bytes or source file ID and absolute workspace path - in: body - name: request - required: true - schema: - $ref: '#/definitions/v1.EnvironmentFileCreateRequest' - produces: - - application/json - responses: - "201": - description: Created - schema: - $ref: '#/definitions/v1.EnvironmentFile' - "400": - description: Bad Request - schema: - $ref: '#/definitions/v1.ErrorResponse' - "401": - description: Unauthorized - schema: - $ref: '#/definitions/v1.ErrorResponse' - "404": - description: Not Found - schema: - $ref: '#/definitions/v1.ErrorResponse' - "409": - description: Conflict - schema: - $ref: '#/definitions/v1.ErrorResponse' - "413": - description: Request Entity Too Large - schema: - $ref: '#/definitions/v1.ErrorResponse' - "500": - description: Internal Server Error - schema: - $ref: '#/definitions/v1.ErrorResponse' - "503": - description: Service Unavailable - schema: - $ref: '#/definitions/v1.ErrorResponse' - security: - - BearerAuth: [] - summary: Create an Environment file from inline bytes or a source file - tags: - - Environments - /agents/environments/templates: - get: - description: Lists tenant-owned safe template metadata in creation order with - ID tie-breaking. Defaults to limit 20 and descending order; limit 0 is treated - as 1 and larger limits as 100. Foreign, missing and malformed cursors return - the same not found error. Concurrent-page and exact hosted error behavior - remain unverified. - parameters: - - description: agents=v1 - in: header - name: OpenAI-Beta - required: true - type: string - - description: Previous Template ID - in: query - name: after - type: string - - default: 20 - description: Page size; 0 is treated as 1 and values above 100 as 100 - in: query - minimum: 0 - name: limit - type: integer - - default: desc - description: Creation order; omit for descending, explicit empty values are - invalid - enum: - - asc - - desc - in: query - name: order - type: string - produces: - - application/json - responses: - "200": - description: OK - schema: - $ref: '#/definitions/v1.EnvironmentTemplateList' - "400": - description: Bad Request - schema: - $ref: '#/definitions/v1.ErrorResponse' - "401": - description: Unauthorized - schema: - $ref: '#/definitions/v1.ErrorResponse' - "404": - description: Not Found - schema: - $ref: '#/definitions/v1.ErrorResponse' - "500": - description: Internal Server Error - schema: - $ref: '#/definitions/v1.ErrorResponse' - security: - - BearerAuth: [] - summary: List Environment Templates - tags: - - Environment Templates - post: - consumes: - - application/json - description: Saves tenant-owned hosted configuration. Supports nullable name, - enabled/disabled or exact-domain restricted network, initial inline/file_id - files, confidential env, ordered setup_commands, npm/Python packages inline/referenced - Skill ZIPs, Plugin ZIPs and workspace-contained capability directories. Omitted/null - network defaults to enabled. Restricted network requires 1–100 exact ASCII - hostnames; other host forms and populated unsupported installations are rejected - before persistence without echoing input. Network policy rejections return - invalid_request_error with a null param. System dependencies must be preinstalled - in the sandbox image or template, or on the host machine; packages.system - is rejected. No compute is allocated. Exact hosted error/retry semantics remain - unverified. - parameters: - - description: agents=v1 - in: header - name: OpenAI-Beta - required: true - type: string - - description: Reusable configuration - in: body - name: body - required: true - schema: - $ref: '#/definitions/v1.EnvironmentTemplateRequest' - produces: - - application/json - responses: - "201": - description: Created - schema: - $ref: '#/definitions/v1.EnvironmentTemplate' - "400": - description: Bad Request - schema: - $ref: '#/definitions/v1.ErrorResponse' - "401": - description: Unauthorized - schema: - $ref: '#/definitions/v1.ErrorResponse' - "413": - description: Request Entity Too Large - schema: - $ref: '#/definitions/v1.ErrorResponse' - "500": - description: Internal Server Error - schema: - $ref: '#/definitions/v1.ErrorResponse' - security: - - BearerAuth: [] - summary: Create an Environment Template - tags: - - Environment Templates - /agents/environments/templates/{environment_template_id}: - delete: - description: Deletes the tenant-owned reusable configuration without changing - or deleting existing Sessions and their frozen configuration. - parameters: - - description: agents=v1 - in: header - name: OpenAI-Beta - required: true - type: string - - description: Template ID - in: path - name: environment_template_id - required: true - type: string - produces: - - application/json - responses: - "200": - description: OK - schema: - $ref: '#/definitions/v1.EnvironmentTemplateDeleted' - "400": - description: Bad Request - schema: - $ref: '#/definitions/v1.ErrorResponse' - "401": - description: Unauthorized - schema: - $ref: '#/definitions/v1.ErrorResponse' - "404": - description: Not Found - schema: - $ref: '#/definitions/v1.ErrorResponse' - "500": - description: Internal Server Error - schema: - $ref: '#/definitions/v1.ErrorResponse' - security: - - BearerAuth: [] - summary: Delete an Environment Template - tags: - - Environment Templates - get: - description: Returns safe tenant-owned configuration metadata without allocating - compute. Missing and foreign resources return the same not-found response. - parameters: - - description: agents=v1 - in: header - name: OpenAI-Beta - required: true - type: string - - description: Template ID - in: path - name: environment_template_id - required: true - type: string - produces: - - application/json - responses: - "200": - description: OK - schema: - $ref: '#/definitions/v1.EnvironmentTemplate' - "400": - description: Bad Request - schema: - $ref: '#/definitions/v1.ErrorResponse' - "401": - description: Unauthorized - schema: - $ref: '#/definitions/v1.ErrorResponse' - "404": - description: Not Found - schema: - $ref: '#/definitions/v1.ErrorResponse' - "500": - description: Internal Server Error - schema: - $ref: '#/definitions/v1.ErrorResponse' - security: - - BearerAuth: [] - summary: Retrieve an Environment Template - tags: - - Environment Templates - post: - consumes: - - application/json - description: Supplied fields replace atomically; omitted fields remain unchanged. - Null name clears and null network resets to the pinned enabled default. Existing - Session snapshots and creation retries remain unchanged. Initial files replace - as a list; null/empty clears. File data is encrypted separately and excluded - from response metadata. Skills replace as a list; null/empty clears. Skill - archives are encrypted separately and omitted from responses. Plugins and - capability directories replace as lists; null/empty clears. Plugin archives - are encrypted and omitted from responses. Capability directories are snapshotted - after setup. Environment MCP execution requires a qualified native transport - and runtime network policy. Empty updates advance updated_at without changing - saved fields or confidential contents. Network policy rejections return invalid_request_error - with a null param. - parameters: - - description: agents=v1 - in: header - name: OpenAI-Beta - required: true - type: string - - description: Template ID - in: path - name: environment_template_id - required: true - type: string - - description: Configuration replacements - in: body - name: body - required: true - schema: - $ref: '#/definitions/v1.EnvironmentTemplateRequest' - produces: - - application/json - responses: - "200": - description: OK - schema: - $ref: '#/definitions/v1.EnvironmentTemplate' - "400": - description: Bad Request - schema: - $ref: '#/definitions/v1.ErrorResponse' - "401": - description: Unauthorized - schema: - $ref: '#/definitions/v1.ErrorResponse' - "404": - description: Not Found - schema: - $ref: '#/definitions/v1.ErrorResponse' - "413": - description: Request Entity Too Large - schema: - $ref: '#/definitions/v1.ErrorResponse' - "500": - description: Internal Server Error - schema: - $ref: '#/definitions/v1.ErrorResponse' - security: - - BearerAuth: [] - summary: Update an Environment Template - tags: - - Environment Templates - /agents/sessions: - get: - description: Cursor and results are scoped to the authenticated execution tenant; - an unknown, malformed or foreign after cursor returns not found. Optional - agent_id matches the immutable root Agent ID, including inline Agents and - historical Sessions whose saved source was updated or deleted. Omission lists - all Agents. Returns the same Environment and pending-input activity projection - as Session retrieval, including self_hosted Sessions. - parameters: - - description: agents=v1 - in: header - name: OpenAI-Beta - required: true - type: string - - description: Root Agent ID whose Sessions to return - in: query - name: agent_id - type: string - - description: Last Session ID from the previous page - in: query - name: after - type: string - - default: 20 - description: Page size; 0 is treated as 1 and values above 100 as 100 - in: query - minimum: 0 - name: limit - type: integer - - default: desc - description: Creation order; omit for descending, explicit empty values are - invalid - enum: - - asc - - desc - in: query - name: order - type: string - produces: - - application/json - responses: - "200": - description: OK - schema: - $ref: '#/definitions/v1.SessionList' - "400": - description: Bad Request - schema: - $ref: '#/definitions/v1.ErrorResponse' - "401": - description: Unauthorized - schema: - $ref: '#/definitions/v1.ErrorResponse' - "404": - description: Not Found - schema: - $ref: '#/definitions/v1.ErrorResponse' - "500": - description: Internal Server Error - schema: - $ref: '#/definitions/v1.ErrorResponse' - security: - - BearerAuth: [] - summary: List execution Sessions - tags: - - Sessions - post: - consumes: - - application/json - description: 'The optional Core model_provider bundle resolves from the Session - override, saved Agent defaults, then, for openai_hosted and none, the deployment - default of the resolved harness; self_hosted never uses the deployment default - and none accepts only it. openai_hosted and self_hosted Sessions that resolve - no bundle return 400 model_provider_required with param x_agents_core.model_provider - before any write. Core encrypts and freezes the resolved bundle; later Agent - or deployment default edits and same-key retries cannot change it. Keys are - never returned. Supports inline configuration or a tenant-owned saved agent_id - with per-Session field replacements. Execution supports model/instructions, - text verbosity, non-deferred function tools, adapter-qualified multi_agent - with persisted Subagent reads, implicit reasoning, service tier auto and environment - type none, subject to the configured engine. Codex additionally supports HTTP - MCP with service origin (omitted or null on HTTP transport is saved as service), - native allowed_tools and boolean required defaulting to false. Session vault_ids - attach only project-owned Vaults; credential_id selects an attached static - bearer or OAuth credential for the exact HTTPS URL, while null/omission selects - a unique match or remains anonymous. Session reads, lists and event snapshots - show that implicitly selected credential ID in a null or omitted credential_id, - also after the credential is deleted; anonymous selections stay null and the - stored caller intent is unchanged. After the input requirement and before - any write, a credential_id without vault_ids, one outside the attached Vaults - (one message for missing, foreign and unattached IDs) or one for another server_url - returns 400 invalid_request_error, and several implicit matches return 409 - conflict_error. Missing decryption configuration fails dispatch without anonymous - fallback. Required initialization uses native startup before the first native - Turn, including cold resume, and requires a separately advertised capability; - exact hosted creation timing and error parity remain unverified. Explicit - environment-origin HTTP MCP is supported on managed and self-hosted workspaces - through the same Runtime bindings; native OAuth login remains unsupported. - The self_hosted profile uses a qualified native harness, a clean absolute - workspace_directory and optional absolute local capability_directories prepared - by Runtime, with optional non-deferred function tools and HTTP MCP using explicit - environment origin, optionally authenticated by the attached Vault rules. - Service-origin HTTP remains restricted to service-side environment:none. Remote - MCP and remote Bearer authentication each require separately advertised combination - support; old peers cannot receive unsupported work. Omitted/null capability_directories - use the empty-list default; self_hosted requires configured execution plus - executor registry. Claude SDK currently requires medium verbosity and object-root - function schemas. It supports anonymous or attached static-bearer service-origin - HTTP MCP on none with boolean required and separately advertised MCP/bearer/required - runtime support. Required servers must be connected before the first native - input is released; pending or failed startup rejects execution. The shared - Vault selection and immutable binding rules apply; unsupported native labels/tool - names reject before persistence. An attached Vault with no matching credential - may remain anonymous; missing keys or failed credential lookup/decryption - never fall back to anonymous execution. Omitted stream defaults to false; - stream and agent_id cannot be null. Metadata may be null; non-string values - and limit violations return invalid_request_error with a metadata or metadata. - param. The inline agent uses the Agent create configuration validation with - agent.-prefixed params, reported before the input requirement and saved-Agent - lookup; saved configurations with conflicting tools or schema roots reject - admission with the same errors, and execution limits keep unsupported_or_invalid_configuration. - Hosted network policy rejections return invalid_request_error with a null - param. Initial input accepts a string or ordered user-message array. Codex - and Claude SDK on none and qualified managed or self_hosted workspace profiles - also accept inline PNG/JPEG image content; other image combinations and remote - URLs are unsupported. None initial input atomically starts a Turn; self_hosted - initial input is reserved while returning its Environment connection target, - with execution deferred to native readiness and Session failure on initial - timeout. Initial input is required for none and for streamed creation outside - self_hosted. Omitted/null input remains valid for non-streaming hosted and - self_hosted creation. With stream=true, returns live Session events starting - with the committed creation snapshot and closes right after the first agent.session.idle - recorded when a Turn ends or an input reservation stops being pending, or - any agent.session.failed, without sending later events. A creation that admitted - nothing closes after the snapshot; a settlement that records no event closes - after events up to the cursor read with a settled Session projection. Required - actions keep it open; disconnect does not cancel execution. The GET events - stream remains live-only. New Sessions retain their authenticated creator; - all creation retries require the same typed subject, including across key - rotation. Saved-Agent retries and inline requests using Vault attachments - or credential references retain caller intent independently of later resource - changes; new hosted inline requests also freeze caller intent before deployment - defaults resolve; unrelated non-hosted inline retries preserve resolved/default - equivalences, and their resolved hash leaves out any deployment default. Provider - keys enter retry hashes only as fingerprints keyed by the credential key. - Unknown historical creators reject retries; known creators without recorded - intent retain resolved-snapshot retry rules. These conflict policies are local - and not verified hosted parity. A same-key stream=true retry of an existing - creation returns 201 with no events and closes at once; retry with stream=false - or use the GET events stream to recover. Claude SDK on none, Core-managed - Docker openai_hosted and self_hosted supports qualified object-root json_schema - output with medium verbosity, single-Agent execution and ordinary functions. - Hosted execution reuses native workspace tools and Files/Artifacts; Skills, - Plugins, capability directories, HTTP MCP, Subagent and tool_search combinations - remain unqualified, including inherited template contents. Other non-text - initial input remains unsupported. Basic Codex and Claude SDK openai_hosted - creation requires an explicitly configured managed provider. The Claude workspace - profile supports non-deferred function tools with text or successful inline - PNG/JPEG results alongside native workspace tools; explicit environment-origin - HTTP MCP uses the common Runtime path. MiniMax accepts public environment-origin - HTTP MCP only with null or omitted allowed_tools and required=false; even - an empty non-null allowlist rejects. Idle Sessions provision automatically; - initial provisioning has no caller connection action. Network defaults to - enabled; disabled and restricted policies reject before compute allocation - because the current Runtime cannot enforce them. The x_agents_core.environment - extension accepts common preparation fields for either hosted or self-hosted - placement: environment_template_id, files, env, packages, setup_commands, - skills, plugins and capability_directories. Duplicate fields in environment - and the extension reject. Confidential env, npm/Python packages and ordered - setup commands use the same Environment-owned initialization lifecycle; compute - allocation does not own preparation. Unknown side effects are not replayed - after disconnect or restart. System dependencies must be preinstalled in the - sandbox image or template, or on the host machine; packages.system is rejected. - Initial inline and tenant-owned file_id files freeze encrypted bytes before - provisioning, then install through the common Core lifecycle before native - execution or live Files access. With a template reference, omitted/null files, - env, packages and setup_commands inherit. Non-null files and command lists - replace; env overlays by key; each package manager inherits on omission/null - and otherwise replaces its list. Empty lists clear their selected field. Tenant-owned - environment_template_id references inherit omitted/null network and allow - only narrowing overrides. Inline hosted network:null retains the enabled default; - updating a Template with network:null resets its saved policy to enabled. - Core freezes effective configuration; template updates/deletion do not alter - Session snapshots or same-intent creation retries. Inline or tenant-owned - skill_reference Skills share initialization. Templates preserve default/latest/explicit - selectors; Session creation freezes concrete metadata and encrypted content - atomically. Skill, Plugin and capability-directory list omission/null inherit; - a non-null list replaces, including empty-list clearing. Omitted/null Skill - version selectors resolve the default version. Source deletion/default updates - cannot change committed Session Skill contents. Deferred function discovery - uses type-only tool_search and per-function defer_loading in the qualified - single-agent Claude function profile on none or a managed/user-owned workspace, - including qualified inline image messages and text results. Explicit web_search - mode disabled and programmatic_tool_calling enabled false use frozen common - Runtime controls. Enabled forms, including those saved on an Agent, remain - unqualified and reject before any write unless the Session replaces tools. - Omitted programmatic configuration preserves native behavior, a documented - difference from the official default-on behavior. Other combinations remain - unqualified; see the operation coverage.' - parameters: - - description: agents=v1 - in: header - name: OpenAI-Beta - required: true - type: string - - description: Creation retry key, up to 128 bytes - in: header - name: Idempotency-Key - type: string - - description: Session configuration - in: body - name: body - required: true - schema: - $ref: '#/definitions/v1.CreateSessionRequest' - produces: - - application/json - - text/event-stream - responses: - "201": - description: Created - schema: - $ref: '#/definitions/v1.Session' - "400": - description: Bad Request - schema: - $ref: '#/definitions/v1.ErrorResponse' - "401": - description: Unauthorized - schema: - $ref: '#/definitions/v1.ErrorResponse' - "404": - description: Not Found - schema: - $ref: '#/definitions/v1.ErrorResponse' - "409": - description: Conflict - schema: - $ref: '#/definitions/v1.ErrorResponse' - "413": - description: Request Entity Too Large - schema: - $ref: '#/definitions/v1.ErrorResponse' - "500": - description: Internal Server Error - schema: - $ref: '#/definitions/v1.ErrorResponse' - "503": - description: Service Unavailable - schema: - $ref: '#/definitions/v1.ErrorResponse' - security: - - BearerAuth: [] - summary: Create an execution Session - tags: - - Sessions - /agents/sessions/{session_id}: - delete: - description: Removes a durably idle or failed Session and its history from the - public API. A Session whose root Turn is queued, in progress or waiting (including - required actions) or whose input reservation is pending returns 409 conflict_error - and is left unchanged; cancel it and wait until it is idle before deleting. - Subagent child Turns and pending Environment file writes are not checked and - do not block deletion. Repeating the deletion of the caller's own deleted - Session returns the same confirmation; missing and foreign Sessions return - 404. Internal records and native history are retained pending separate physical - cleanup; overlapping stream timing remains unverified. - parameters: - - description: agents=v1 - in: header - name: OpenAI-Beta - required: true - type: string - - description: Session ID - in: path - name: session_id - required: true - type: string - produces: - - application/json - responses: - "200": - description: OK - schema: - $ref: '#/definitions/v1.SessionDeleted' - "400": - description: Bad Request - schema: - $ref: '#/definitions/v1.ErrorResponse' - "401": - description: Unauthorized - schema: - $ref: '#/definitions/v1.ErrorResponse' - "404": - description: Not Found - schema: - $ref: '#/definitions/v1.ErrorResponse' - "409": - description: Conflict - schema: - $ref: '#/definitions/v1.ErrorResponse' - "413": - description: Request Entity Too Large - schema: - $ref: '#/definitions/v1.ErrorResponse' - "500": - description: Internal Server Error - schema: - $ref: '#/definitions/v1.ErrorResponse' - security: - - BearerAuth: [] - summary: Delete an execution Session - tags: - - Sessions - get: - description: Returns supported none, self_hosted and basic openai_hosted Session - environments. Self-hosted pending input can require a caller connection before - a Turn exists. Hosted initial provisioning remains idle until a Turn starts; - connection observations are not native execution readiness. - parameters: - - description: agents=v1 - in: header - name: OpenAI-Beta - required: true - type: string - - description: Session ID - in: path - name: session_id - required: true - type: string - produces: - - application/json - responses: - "200": - description: OK - schema: - $ref: '#/definitions/v1.Session' - "400": - description: Bad Request - schema: - $ref: '#/definitions/v1.ErrorResponse' - "401": - description: Unauthorized - schema: - $ref: '#/definitions/v1.ErrorResponse' - "404": - description: Not Found - schema: - $ref: '#/definitions/v1.ErrorResponse' - "500": - description: Internal Server Error - schema: - $ref: '#/definitions/v1.ErrorResponse' - "503": - description: Service Unavailable - schema: - $ref: '#/definitions/v1.ErrorResponse' - security: - - BearerAuth: [] - summary: Retrieve an execution Session - tags: - - Sessions - post: - consumes: - - application/json - description: The metadata field is required in an update body. Send null or - {} to clear it, or supply an object to replace all pairs. Up to 16 string - pairs, with keys at most 64 characters and values at most 512 characters; - violations and non-string values return invalid_request_error with a metadata - or metadata. param. U+0000 is rejected as a local storage limit. Malformed, - missing and foreign Session IDs share the not-found response. Execution configuration - and activity are unchanged. Returns the same safe Environment and pending-input - activity projection as Session retrieval. - parameters: - - description: agents=v1 - in: header - name: OpenAI-Beta - required: true - type: string - - description: Session ID - in: path - name: session_id - required: true - type: string - - description: Session metadata - in: body - name: body - required: true - schema: - $ref: '#/definitions/v1.UpdateSessionRequest' - produces: - - application/json - responses: - "200": - description: OK - schema: - $ref: '#/definitions/v1.Session' - "400": - description: Bad Request - schema: - $ref: '#/definitions/v1.ErrorResponse' - "401": - description: Unauthorized - schema: - $ref: '#/definitions/v1.ErrorResponse' - "404": - description: Not Found - schema: - $ref: '#/definitions/v1.ErrorResponse' - "413": - description: Request Entity Too Large - schema: - $ref: '#/definitions/v1.ErrorResponse' - "500": - description: Internal Server Error - schema: - $ref: '#/definitions/v1.ErrorResponse' - "503": - description: Service Unavailable - schema: - $ref: '#/definitions/v1.ErrorResponse' - security: - - BearerAuth: [] - summary: Update execution Session metadata - tags: - - Sessions - /agents/sessions/{session_id}/artifacts: - get: - description: Lists published outputs independently of Environment availability. - Sorting uses publication time and ID. A later Turn publishes a path again - only when it is new, its bytes changed, or no Artifact remains for it. A malformed - environment_id matches nothing. An after value that is not an Artifact of - this Session, including a malformed one, returns 400 invalid_request_error - with the message "after is not a valid artifact ID". The local default page - size is 20; exact upstream defaults remain unverified. - parameters: - - description: agents=v1 - in: header - name: OpenAI-Beta - required: true - type: string - - description: Session ID - in: path - name: session_id - required: true - type: string - - description: Producing Environment ID; an unknown or malformed ID returns - an empty page - in: query - name: environment_id - type: string - - description: Last immutable artifact ID - in: query - name: after - type: string - - default: 20 - description: Page size - in: query - maximum: 100 - minimum: 1 - name: limit - type: integer - - default: desc - description: Publication order; omit for descending, explicit empty values - are invalid - enum: - - asc - - desc - in: query - name: order - type: string - produces: - - application/json - responses: - "200": - description: OK - schema: - $ref: '#/definitions/v1.SessionArtifactList' - "400": - description: Bad Request - schema: - $ref: '#/definitions/v1.ErrorResponse' - "401": - description: Unauthorized - schema: - $ref: '#/definitions/v1.ErrorResponse' - "404": - description: Not Found - schema: - $ref: '#/definitions/v1.ErrorResponse' - "500": - description: Internal Server Error - schema: - $ref: '#/definitions/v1.ErrorResponse' - "503": - description: Service Unavailable - schema: - $ref: '#/definitions/v1.ErrorResponse' - security: - - BearerAuth: [] - summary: List immutable Session artifacts - tags: - - Artifacts - /agents/sessions/{session_id}/artifacts/{artifact_id}: - delete: - description: Deletes the published copy without modifying its original workspace - file. Already admitted content reads may finish; later reads reject. - parameters: - - description: agents=v1 - in: header - name: OpenAI-Beta - required: true - type: string - - description: Session ID - in: path - name: session_id - required: true - type: string - - description: Artifact ID - in: path - name: artifact_id - required: true - type: string - produces: - - application/json - responses: - "200": - description: OK - schema: - $ref: '#/definitions/v1.SessionArtifactDeleted' - "400": - description: Bad Request - schema: - $ref: '#/definitions/v1.ErrorResponse' - "401": - description: Unauthorized - schema: - $ref: '#/definitions/v1.ErrorResponse' - "404": - description: Not Found - schema: - $ref: '#/definitions/v1.ErrorResponse' - "500": - description: Internal Server Error - schema: - $ref: '#/definitions/v1.ErrorResponse' - "503": - description: Service Unavailable - schema: - $ref: '#/definitions/v1.ErrorResponse' - security: - - BearerAuth: [] - summary: Delete a published artifact - tags: - - Artifacts - get: - parameters: - - description: agents=v1 - in: header - name: OpenAI-Beta - required: true - type: string - - description: Session ID - in: path - name: session_id - required: true - type: string - - description: Artifact ID - in: path - name: artifact_id - required: true - type: string - produces: - - application/json - responses: - "200": - description: OK - schema: - $ref: '#/definitions/v1.SessionArtifact' - "400": - description: Bad Request - schema: - $ref: '#/definitions/v1.ErrorResponse' - "401": - description: Unauthorized - schema: - $ref: '#/definitions/v1.ErrorResponse' - "404": - description: Not Found - schema: - $ref: '#/definitions/v1.ErrorResponse' - "500": - description: Internal Server Error - schema: - $ref: '#/definitions/v1.ErrorResponse' - "503": - description: Service Unavailable - schema: - $ref: '#/definitions/v1.ErrorResponse' - security: - - BearerAuth: [] - summary: Retrieve immutable artifact metadata - tags: - - Artifacts - /agents/sessions/{session_id}/artifacts/{artifact_id}/content: - get: - description: Streams stored bytes after tenant and Session authorization, including - after Environment expiration. Exact upstream headers and Range behavior remain - unverified. - parameters: - - description: agents=v1 - in: header - name: OpenAI-Beta - required: true - type: string - - description: Session ID - in: path - name: session_id - required: true - type: string - - description: Artifact ID - in: path - name: artifact_id - required: true - type: string - produces: - - application/octet-stream - responses: - "200": - description: OK - schema: - type: file - "400": - description: Bad Request - schema: - $ref: '#/definitions/v1.ErrorResponse' - "401": - description: Unauthorized - schema: - $ref: '#/definitions/v1.ErrorResponse' - "404": - description: Not Found - schema: - $ref: '#/definitions/v1.ErrorResponse' - "500": - description: Internal Server Error - schema: - $ref: '#/definitions/v1.ErrorResponse' - "503": - description: Service Unavailable - schema: - $ref: '#/definitions/v1.ErrorResponse' - security: - - BearerAuth: [] - summary: Download immutable artifact bytes - tags: - - Artifacts - /agents/sessions/{session_id}/events: - get: - description: |- - Live-only events, including command output fragments from capable Codex peers as agent.output.command_execution_output.delta with stable Item/output indexes. Native text conversion and output quotas apply; completion snapshots remain authoritative. Reconnect through Session, Turn and Items reads; missed events are not replayed. A lagging stream closes with an error when its bounded buffer is exceeded. When a hosted Environment fails to provision, the stream sends agent.session.environment.failed, an error event (environment_error/sandbox_error with the safe step and exit-status reason, never command output) and agent.session.failed, then ends. Session activity includes immutable pending-input connection actions before Turn creation; self_hosted environments use the same safe output as Session retrieval. - Active streams revalidate the original Project key every second before output; revocation, Project archival or authentication unavailability closes the stream. Authentication checks use a five-second timeout. - parameters: - - description: agents=v1 - in: header - name: OpenAI-Beta - required: true - type: string - - description: Session ID - in: path - name: session_id - required: true - type: string - produces: - - text/event-stream - responses: - "200": - description: OK - schema: - $ref: '#/definitions/v1.SessionEvent' - "400": - description: Bad Request - schema: - $ref: '#/definitions/v1.ErrorResponse' - "401": - description: Unauthorized - schema: - $ref: '#/definitions/v1.ErrorResponse' - "404": - description: Not Found - schema: - $ref: '#/definitions/v1.ErrorResponse' - "500": - description: Internal Server Error - schema: - $ref: '#/definitions/v1.ErrorResponse' - "503": - description: Service Unavailable - schema: - $ref: '#/definitions/v1.ErrorResponse' - security: - - BearerAuth: [] - summary: Stream live Session events - tags: - - Events - post: - consumes: - - application/json - description: An empty events array is a resource-authorized no-op; it creates - no execution retry identity, Turn, Item or input receipt. For environment - none, atomically accepts text messages, cancellation and function results. - Messages steer active work or start a queued Turn. Qualified Codex and Claude - SDK workspace profiles accept text and inline PNG/JPEG messages, independently - of managed or self_hosted ownership. Under the Session lock, matching retries - retain their original target; new active messages append to the current Turn, - while idle messages reserve work and wait up to the original five-minute connection/admission - deadline. Return 202 only after durable admission, without claiming native - application; active messages create no Turn or reservation. Cancellation-only - prepared-environment batches use existing durable cancellation admission and - return 202 without waiting for native exit; a new cancellation conflicts while - a pre-Turn reservation is pending. Homogeneous tool_result-only prepared-environment - batches reuse existing scoped result admission and application receipts without - creating a Turn or bypassing a pending reservation. Mixed prepared-environment - batches remain unsupported. HTTP expiry/cancellation use local 409 environment_input_expired/environment_input_cancelled - errors. New input on a Session whose hosted Environment failed to provision - returns the observed 409 conflict_error "the hosted environment failed to - provision"; input already waiting when it fails and expired Environments keep - the local 409 environment_unavailable. Input the Session cannot accept in - its current state, such as a result after cancellation or a batch while earlier - input is pending, and a result that differs from the call's saved result return - 409 with type and code conflict_error; reusing an Idempotency-Key with a different - batch returns the local 409 idempotency_conflict. Inside an owned Session, - a result for an unknown call or for a call of another Turn returns 400 invalid_request_error - and changes nothing; missing and foreign Sessions return 404. Losing execution - ownership returns 503. The response write deadline accommodates the admission - window for either prepared Environment, independently of new-hosted-admission - and executor URL settings. Disconnecting the waiting HTTP request does not - cancel retained work or restart its deadline. Retry keys identify the whole - ordered batch. Function output accepts text or ordered text/image parts subject - to engine support; Claude SDK accepts text results and, on none and qualified - workspace profiles, successful inline PNG/JPEG results, preserving ordered - content; error images and remote references reject before admission. Native - image resizing may change bytes. Runtime image-result support is checked only - for image-bearing delivery. Codex and Claude SDK on none and qualified managed - or self_hosted workspace profiles accept ordered inline PNG/JPEG image messages. - Other engines remain text-only; remote image URLs are unsupported. Image references - are retained unchanged without service-side downloads. - parameters: - - description: agents=v1 - in: header - name: OpenAI-Beta - required: true - type: string - - description: Retry key, up to 128 bytes - in: header - name: Idempotency-Key - type: string - - description: Session ID - in: path - name: session_id - required: true - type: string - - description: Ordered input events - in: body - name: body - required: true - schema: - $ref: '#/definitions/v1.CreateEventsRequest' - responses: - "202": - description: Accepted - "400": - description: Bad Request - schema: - $ref: '#/definitions/v1.ErrorResponse' - "401": - description: Unauthorized - schema: - $ref: '#/definitions/v1.ErrorResponse' - "404": - description: Not Found - schema: - $ref: '#/definitions/v1.ErrorResponse' - "409": - description: Conflict - schema: - $ref: '#/definitions/v1.ErrorResponse' - "413": - description: Request Entity Too Large - schema: - $ref: '#/definitions/v1.ErrorResponse' - "500": - description: Internal Server Error - schema: - $ref: '#/definitions/v1.ErrorResponse' - "503": - description: Service Unavailable - schema: - $ref: '#/definitions/v1.ErrorResponse' - security: - - BearerAuth: [] - summary: Submit Session input events - tags: - - Sessions - /agents/sessions/{session_id}/items: - get: - description: Returns supported message and tool Items in first-observation order. - Native engine fields are projected explicitly; unfinished Items on terminal - Turns are incomplete. Cursors are Items of the same tenant and Session. Any - other after value, including a malformed one, returns 400 invalid_request_error - with the message "Invalid session item ID in `after`". - parameters: - - description: agents=v1 - in: header - name: OpenAI-Beta - required: true - type: string - - description: Session ID - in: path - name: session_id - required: true - type: string - - description: Last Item ID from the previous page - in: query - name: after - type: string - - default: 20 - description: Page size; 0 is treated as 1 and values above 100 as 100 - in: query - minimum: 0 - name: limit - type: integer - - default: desc - description: Creation order; omit for descending, explicit empty values are - invalid - enum: - - asc - - desc - in: query - name: order - type: string - produces: - - application/json - responses: - "200": - description: OK - schema: - $ref: '#/definitions/v1.ItemList' - "400": - description: Bad Request - schema: - $ref: '#/definitions/v1.ErrorResponse' - "401": - description: Unauthorized - schema: - $ref: '#/definitions/v1.ErrorResponse' - "404": - description: Not Found - schema: - $ref: '#/definitions/v1.ErrorResponse' - "500": - description: Internal Server Error - schema: - $ref: '#/definitions/v1.ErrorResponse' - security: - - BearerAuth: [] - summary: List persisted execution Items - tags: - - Items - /agents/sessions/{session_id}/subagents: - get: - description: Includes nested and closed Subagents. Cursors are Subagents of - the same tenant and Session. Any other after value, including a malformed - one, returns 400 invalid_request_error with the message "Invalid resource - ID in `after`". A limit outside 1–100 is rejected. - parameters: - - description: agents=v1 - in: header - name: OpenAI-Beta - required: true - type: string - - description: Session ID - in: path - name: session_id - required: true - type: string - - description: Last Subagent ID from the previous page - in: query - name: after - type: string - - default: 20 - description: Page size - in: query - maximum: 100 - minimum: 1 - name: limit - type: integer - - default: desc - description: Resource order; omit for descending, explicit empty values are - invalid - enum: - - asc - - desc - in: query - name: order - type: string - produces: - - application/json - responses: - "200": - description: OK - schema: - $ref: '#/definitions/v1.SubagentList' - "400": - description: Bad Request - schema: - $ref: '#/definitions/v1.ErrorResponse' - "401": - description: Unauthorized - schema: - $ref: '#/definitions/v1.ErrorResponse' - "404": - description: Not Found - schema: - $ref: '#/definitions/v1.ErrorResponse' - "500": - description: Internal Server Error - schema: - $ref: '#/definitions/v1.ErrorResponse' - "503": - description: Service Unavailable - schema: - $ref: '#/definitions/v1.ErrorResponse' - security: - - BearerAuth: [] - summary: List Session Subagents - tags: - - Subagents - /agents/sessions/{session_id}/subagents/{subagent_id}: - get: - description: Returns this Session's persisted Subagent. Active includes idle - between Turns. Resuming preserves opened_at and clears closed_at. Unknown - or inaccessible parent scopes return not found. - parameters: - - description: agents=v1 - in: header - name: OpenAI-Beta - required: true - type: string - - description: Session ID - in: path - name: session_id - required: true - type: string - - description: Subagent ID - in: path - name: subagent_id - required: true - type: string - produces: - - application/json - responses: - "200": - description: OK - schema: - $ref: '#/definitions/v1.Subagent' - "400": - description: Bad Request - schema: - $ref: '#/definitions/v1.ErrorResponse' - "401": - description: Unauthorized - schema: - $ref: '#/definitions/v1.ErrorResponse' - "404": - description: Not Found - schema: - $ref: '#/definitions/v1.ErrorResponse' - "500": - description: Internal Server Error - schema: - $ref: '#/definitions/v1.ErrorResponse' - "503": - description: Service Unavailable - schema: - $ref: '#/definitions/v1.ErrorResponse' - security: - - BearerAuth: [] - summary: Retrieve a Session Subagent - tags: - - Subagents - /agents/sessions/{session_id}/subagents/{subagent_id}/items: - get: - description: Returns only this Subagent's own Items across all its Turns, not - its descendants' Items. Cursors are Items of the same tenant, Session and - Subagent. Any other after value, including a malformed one, returns 400 invalid_request_error - with the message "Invalid session item ID in `after`". - parameters: - - description: agents=v1 - in: header - name: OpenAI-Beta - required: true - type: string - - description: Session ID - in: path - name: session_id - required: true - type: string - - description: Subagent ID - in: path - name: subagent_id - required: true - type: string - - description: Last Item ID from the previous page - in: query - name: after - type: string - - default: 20 - description: Page size; 0 is treated as 1 and values above 100 as 100 - in: query - minimum: 0 - name: limit - type: integer - - default: desc - description: Resource order; omit for descending, explicit empty values are - invalid - enum: - - asc - - desc - in: query - name: order - type: string - produces: - - application/json - responses: - "200": - description: OK - schema: - $ref: '#/definitions/v1.ItemList' - "400": - description: Bad Request - schema: - $ref: '#/definitions/v1.ErrorResponse' - "401": - description: Unauthorized - schema: - $ref: '#/definitions/v1.ErrorResponse' - "404": - description: Not Found - schema: - $ref: '#/definitions/v1.ErrorResponse' - "500": - description: Internal Server Error - schema: - $ref: '#/definitions/v1.ErrorResponse' - "503": - description: Service Unavailable - schema: - $ref: '#/definitions/v1.ErrorResponse' - security: - - BearerAuth: [] - summary: List a Subagent's Items - tags: - - Subagents - /agents/sessions/{session_id}/subagents/{subagent_id}/turns: - get: - description: Includes this Subagent's Turns after resume, with the Session's - Agent ID as agent_id. Cursors are Turns of the same tenant, Session and Subagent. - Any other after value, including a malformed one, returns 400 invalid_request_error - with the message "Invalid resource ID in `after`". Missing recorded usage - remains null. A limit outside 1–100 is rejected. - parameters: - - description: agents=v1 - in: header - name: OpenAI-Beta - required: true - type: string - - description: Session ID - in: path - name: session_id - required: true - type: string - - description: Subagent ID - in: path - name: subagent_id - required: true - type: string - - description: Last Turn ID from the previous page - in: query - name: after - type: string - - default: 20 - description: Page size - in: query - maximum: 100 - minimum: 1 - name: limit - type: integer - - default: desc - description: Creation order; omit for descending, explicit empty values are - invalid - enum: - - asc - - desc - in: query - name: order - type: string - produces: - - application/json - responses: - "200": - description: OK - schema: - $ref: '#/definitions/v1.TurnList' - "400": - description: Bad Request - schema: - $ref: '#/definitions/v1.ErrorResponse' - "401": - description: Unauthorized - schema: - $ref: '#/definitions/v1.ErrorResponse' - "404": - description: Not Found - schema: - $ref: '#/definitions/v1.ErrorResponse' - "500": - description: Internal Server Error - schema: - $ref: '#/definitions/v1.ErrorResponse' - "503": - description: Service Unavailable - schema: - $ref: '#/definitions/v1.ErrorResponse' - security: - - BearerAuth: [] - summary: List a Subagent's Turns - tags: - - Subagents - /agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}: - get: - description: Returns a Turn owned by this Subagent. Its agent_id is the Session's - Agent ID and its subagent_id identifies the Subagent. Session Turn routes - do not return child Turns. Unknown or inaccessible parent scopes return not - found. - parameters: - - description: agents=v1 - in: header - name: OpenAI-Beta - required: true - type: string - - description: Session ID - in: path - name: session_id - required: true - type: string - - description: Subagent ID - in: path - name: subagent_id - required: true - type: string - - description: Turn ID - in: path - name: turn_id - required: true - type: string - produces: - - application/json - responses: - "200": - description: OK - schema: - $ref: '#/definitions/v1.Turn' - "400": - description: Bad Request - schema: - $ref: '#/definitions/v1.ErrorResponse' - "401": - description: Unauthorized - schema: - $ref: '#/definitions/v1.ErrorResponse' - "404": - description: Not Found - schema: - $ref: '#/definitions/v1.ErrorResponse' - "500": - description: Internal Server Error - schema: - $ref: '#/definitions/v1.ErrorResponse' - "503": - description: Service Unavailable - schema: - $ref: '#/definitions/v1.ErrorResponse' - security: - - BearerAuth: [] - summary: Retrieve a Subagent Turn - tags: - - Subagents - /agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}/items: - get: - description: Returns Items owned by this exact Subagent Turn. Cursors are Items - of the same tenant, Session, Subagent and Turn. Any other after value, including - a malformed one, returns 400 invalid_request_error with the message "Invalid - session item ID in `after`". - parameters: - - description: agents=v1 - in: header - name: OpenAI-Beta - required: true - type: string - - description: Session ID - in: path - name: session_id - required: true - type: string - - description: Subagent ID - in: path - name: subagent_id - required: true - type: string - - description: Turn ID - in: path - name: turn_id - required: true - type: string - - description: Last Item ID from the previous page - in: query - name: after - type: string - - default: 20 - description: Page size; 0 is treated as 1 and values above 100 as 100 - in: query - minimum: 0 - name: limit - type: integer - - default: desc - description: Resource order; omit for descending, explicit empty values are - invalid - enum: - - asc - - desc - in: query - name: order - type: string - produces: - - application/json - responses: - "200": - description: OK - schema: - $ref: '#/definitions/v1.ItemList' - "400": - description: Bad Request - schema: - $ref: '#/definitions/v1.ErrorResponse' - "401": - description: Unauthorized - schema: - $ref: '#/definitions/v1.ErrorResponse' - "404": - description: Not Found - schema: - $ref: '#/definitions/v1.ErrorResponse' - "500": - description: Internal Server Error - schema: - $ref: '#/definitions/v1.ErrorResponse' - "503": - description: Service Unavailable - schema: - $ref: '#/definitions/v1.ErrorResponse' - security: - - BearerAuth: [] - summary: List a Subagent Turn's Items - tags: - - Subagents - /agents/sessions/{session_id}/turns: - get: - description: Returns the Session's root Turns in creation order; Subagent Turns - are listed through the Subagent Turn routes. The cursor belongs to the same - Session and tenant; any other after value, including a malformed one or a - Subagent Turn ID, returns not found. Usage contains the latest recorded complete - token breakdown; missing measurements remain null. - parameters: - - description: agents=v1 - in: header - name: OpenAI-Beta - required: true - type: string - - description: Session ID - in: path - name: session_id - required: true - type: string - - description: Last Turn ID from the previous page - in: query - name: after - type: string - - default: 20 - description: Page size - in: query - maximum: 100 - minimum: 1 - name: limit - type: integer - - default: desc - description: Creation order; omit for descending, explicit empty values are - invalid - enum: - - asc - - desc - in: query - name: order - type: string - produces: - - application/json - responses: - "200": - description: OK - schema: - $ref: '#/definitions/v1.TurnList' - "400": - description: Bad Request - schema: - $ref: '#/definitions/v1.ErrorResponse' - "401": - description: Unauthorized - schema: - $ref: '#/definitions/v1.ErrorResponse' - "404": - description: Not Found - schema: - $ref: '#/definitions/v1.ErrorResponse' - "500": - description: Internal Server Error - schema: - $ref: '#/definitions/v1.ErrorResponse' - security: - - BearerAuth: [] - summary: List execution Turns - tags: - - Turns - /agents/sessions/{session_id}/turns/{turn_id}: - get: - description: Returns a root Turn of this Session. A Subagent Turn ID returns - the same not found error as a missing Turn; read it through the Subagent Turn - routes. - parameters: - - description: agents=v1 - in: header - name: OpenAI-Beta - required: true - type: string - - description: Session ID - in: path - name: session_id - required: true - type: string - - description: Turn ID - in: path - name: turn_id - required: true - type: string - produces: - - application/json - responses: - "200": - description: OK - schema: - $ref: '#/definitions/v1.Turn' - "400": - description: Bad Request - schema: - $ref: '#/definitions/v1.ErrorResponse' - "401": - description: Unauthorized - schema: - $ref: '#/definitions/v1.ErrorResponse' - "404": - description: Not Found - schema: - $ref: '#/definitions/v1.ErrorResponse' - "500": - description: Internal Server Error - schema: - $ref: '#/definitions/v1.ErrorResponse' - security: - - BearerAuth: [] - summary: Retrieve an execution Turn - tags: - - Turns - /files: - get: - description: Lists project-owned Files without reading their bodies. The limit - defaults to 10000 and must be 1–10000. Equal creation times use ID ordering. - Purpose validation precedes cursor lookup; current storage contains only user_data. - An explicit empty purpose is treated as omitted. Repeated purpose values remain - rejected. Hosted positive filtering, default order and concurrent-page behavior - remain unverified. No Beta header is required. - parameters: - - description: Last File ID from the previous page - in: query - name: after - type: string - - default: 10000 - description: Maximum page size, 1–10000 - in: query - maximum: 10000 - minimum: 1 - name: limit - type: integer - - default: desc - description: Creation order; omit for descending, explicit empty values are - invalid - enum: - - asc - - desc - in: query - name: order - type: string - - description: Only return Files with this purpose - in: query - name: purpose - type: string - produces: - - application/json - responses: - "200": - description: OK - schema: - $ref: '#/definitions/v1.SourceFileList' - "400": - description: Bad Request - schema: - $ref: '#/definitions/v1.ErrorResponse' - "401": - description: Unauthorized - schema: - $ref: '#/definitions/v1.ErrorResponse' - "404": - description: Not Found - schema: - $ref: '#/definitions/v1.ErrorResponse' - "500": - description: Internal Server Error - schema: - $ref: '#/definitions/v1.ErrorResponse' - "503": - description: Service Unavailable - schema: - $ref: '#/definitions/v1.ErrorResponse' - security: - - BearerAuth: [] - summary: List source files - tags: - - Files - post: - consumes: - - multipart/form-data - description: Accepts one multipart file and purpose=user_data in either order, - with a private 512 MiB content limit and 64 KiB envelope allowance. Commits - only after the entire request validates. The source is project-owned, independent - of Sessions and workspace copies. No Beta header is required. Other purposes, - expires_after, listing, resumable Uploads, quotas/rate-limit and complete - hosted error/status parity remain unsupported or unverified. - parameters: - - description: Source bytes - in: formData - name: file - required: true - type: file - - description: user_data - enum: - - user_data - in: formData - name: purpose - required: true - type: string - produces: - - application/json - responses: - "200": - description: OK - schema: - $ref: '#/definitions/v1.SourceFile' - "400": - description: Bad Request - schema: - $ref: '#/definitions/v1.ErrorResponse' - "401": - description: Unauthorized - schema: - $ref: '#/definitions/v1.ErrorResponse' - "413": - description: Request Entity Too Large - schema: - $ref: '#/definitions/v1.ErrorResponse' - "500": - description: Internal Server Error - schema: - $ref: '#/definitions/v1.ErrorResponse' - "503": - description: Service Unavailable - schema: - $ref: '#/definitions/v1.ErrorResponse' - security: - - BearerAuth: [] - summary: Upload a source file - tags: - - Files - /files/{file_id}: - delete: - description: Atomically deletes project-owned metadata and stored bytes. Already-admitted - reads or copies may finish. Workspace copies remain independent. Historical - WAL/backups are not erased. No Beta header is required; exact hosted concurrent - deletion/error semantics remain unverified. - parameters: - - description: Source file ID - in: path - name: file_id - required: true - type: string - produces: - - application/json - responses: - "200": - description: OK - schema: - $ref: '#/definitions/v1.SourceFileDeleted' - "400": - description: Bad Request - schema: - $ref: '#/definitions/v1.ErrorResponse' - "401": - description: Unauthorized - schema: - $ref: '#/definitions/v1.ErrorResponse' - "404": - description: Not Found - schema: - $ref: '#/definitions/v1.ErrorResponse' - "500": - description: Internal Server Error - schema: - $ref: '#/definitions/v1.ErrorResponse' - "503": - description: Service Unavailable - schema: - $ref: '#/definitions/v1.ErrorResponse' - security: - - BearerAuth: [] - summary: Delete a source file - tags: - - Files - get: - description: Returns immutable project-owned user_data file metadata. No Beta - header is required. Other purposes, expiration and full hosted status/error - semantics remain unimplemented or unverified. - parameters: - - description: Source file ID - in: path - name: file_id - required: true - type: string - produces: - - application/json - responses: - "200": - description: OK - schema: - $ref: '#/definitions/v1.SourceFile' - "400": - description: Bad Request - schema: - $ref: '#/definitions/v1.ErrorResponse' - "401": - description: Unauthorized - schema: - $ref: '#/definitions/v1.ErrorResponse' - "404": - description: Not Found - schema: - $ref: '#/definitions/v1.ErrorResponse' - "500": - description: Internal Server Error - schema: - $ref: '#/definitions/v1.ErrorResponse' - "503": - description: Service Unavailable - schema: - $ref: '#/definitions/v1.ErrorResponse' - security: - - BearerAuth: [] - summary: Retrieve source file metadata - tags: - - Files - /files/{file_id}/content: - get: - description: Resolves project-owned File metadata before enforcing download - policy. Public download of user_data Files returns 400; missing and foreign - Files return the same 404. Internal initial-file and workspace copies remain - available. No Beta header is required. - parameters: - - description: Source file ID - in: path - name: file_id - required: true - type: string - produces: - - application/json - responses: - "400": - description: Bad Request - schema: - $ref: '#/definitions/v1.ErrorResponse' - "401": - description: Unauthorized - schema: - $ref: '#/definitions/v1.ErrorResponse' - "404": - description: Not Found - schema: - $ref: '#/definitions/v1.ErrorResponse' - "500": - description: Internal Server Error - schema: - $ref: '#/definitions/v1.ErrorResponse' - "503": - description: Service Unavailable - schema: - $ref: '#/definitions/v1.ErrorResponse' - security: - - BearerAuth: [] - summary: Download source file bytes - tags: - - Files - /skills: - get: - description: Lists tenant-owned metadata in timestamp order. Default page size - 20, maximum 100. Limit 0 returns an empty page whose has_more reports whether - any Skill follows the cursor; exact hosted defaults remain unverified. - parameters: - - description: Skill resource cursor - in: query - name: after - type: string - - default: 20 - description: Page size; 0 returns an empty page - in: query - maximum: 100 - minimum: 0 - name: limit - type: integer - - description: Creation order; omit for descending, explicit empty values are - invalid - enum: - - asc - - desc - in: query - name: order - type: string - produces: - - application/json - responses: - "200": - description: OK - schema: - $ref: '#/definitions/v1.SkillList' - security: - - BearerAuth: [] - summary: List Skills - tags: - - Skills - post: - consumes: - - multipart/form-data - description: Accepts one ZIP in files or a directory in files[]. Applies the - qualified portable Skill bundle profile. No Beta header is required; full - hosted upload limits and activation extensions are not qualified. - parameters: - - description: Skill ZIP or directory files - in: formData - name: files - required: true - type: file - produces: - - application/json - responses: - "200": - description: OK - schema: - $ref: '#/definitions/v1.Skill' - security: - - BearerAuth: [] - summary: Upload a Skill - tags: - - Skills - /skills/{skill_id}: - delete: - description: Deletes tenant-owned source bundles. Existing Session installation - snapshots remain independent. - parameters: - - description: Skill ID - in: path - name: skill_id - required: true - type: string - produces: - - application/json - responses: - "200": - description: OK - schema: - $ref: '#/definitions/v1.SkillDeleted' - security: - - BearerAuth: [] - summary: Delete a Skill and its versions - tags: - - Skills - get: - description: Returns tenant-owned metadata without decrypting contents or starting - Runtime. No Beta header is required. - parameters: - - description: Skill ID - in: path - name: skill_id - required: true - type: string - produces: - - application/json - responses: - "200": - description: OK - schema: - $ref: '#/definitions/v1.Skill' - security: - - BearerAuth: [] - summary: Retrieve Skill metadata - tags: - - Skills - post: - consumes: - - application/json - description: Changes only the tenant-owned default pointer; immutable versions - and existing Session snapshots remain unchanged. - parameters: - - description: Skill ID - in: path - name: skill_id - required: true - type: string - - description: Default version - in: body - name: body - required: true - schema: - $ref: '#/definitions/v1.SkillUpdateRequest' - produces: - - application/json - responses: - "200": - description: OK - schema: - $ref: '#/definitions/v1.Skill' - security: - - BearerAuth: [] - summary: Update the default Skill version - tags: - - Skills - /skills/{skill_id}/content: - get: - description: Downloads an authorized ZIP using the default pointer when no concrete - version is supplied. Exact upstream unversioned selection, content headers - and range semantics remain unverified. - parameters: - - description: Skill ID - in: path - name: skill_id - required: true - type: string - produces: - - application/octet-stream - responses: - "200": - description: OK - schema: - type: file - security: - - BearerAuth: [] - summary: Download Skill content - tags: - - Skills - /skills/{skill_id}/versions: - get: - description: Orders by version number; after identifies a version resource, - not a version number. An after value that does not begin with skillver, or - a version of another Skill, returns 400 invalid_value with param after; a - missing version returns not found. No contents are decrypted. Limit 0 returns - an empty page whose has_more reports whether any version follows the cursor. - parameters: - - description: Skill ID - in: path - name: skill_id - required: true - type: string - - description: Version resource cursor - in: query - name: after - type: string - - default: 20 - description: Page size; 0 returns an empty page - in: query - maximum: 100 - minimum: 0 - name: limit - type: integer - - description: Version order; omit for descending, explicit empty values are - invalid - enum: - - asc - - desc - in: query - name: order - type: string - produces: - - application/json - responses: - "200": - description: OK - schema: - $ref: '#/definitions/v1.SkillVersionList' - security: - - BearerAuth: [] - summary: List Skill versions - tags: - - Skills - post: - consumes: - - multipart/form-data - parameters: - - description: Skill ID - in: path - name: skill_id - required: true - type: string - - description: Skill ZIP or directory files - in: formData - name: files - required: true - type: file - - description: Set as default - in: formData - name: default - type: boolean - produces: - - application/json - responses: - "200": - description: OK - schema: - $ref: '#/definitions/v1.SkillVersion' - security: - - BearerAuth: [] - summary: Upload an immutable Skill version - tags: - - Skills - /skills/{skill_id}/versions/{version}: - delete: - description: Deleting the only remaining version also deletes the Skill; existing - Session installation snapshots remain independent. The default version cannot - be deleted while other versions remain. Version numbers are never reused. - parameters: - - description: Skill ID - in: path - name: skill_id - required: true - type: string - - description: Concrete version number - in: path - name: version - required: true - type: string - produces: - - application/json - responses: - "200": - description: OK - schema: - $ref: '#/definitions/v1.SkillVersionDeleted' - security: - - BearerAuth: [] - summary: Delete a Skill version - tags: - - Skills - get: - parameters: - - description: Skill ID - in: path - name: skill_id - required: true - type: string - - description: Concrete version number - in: path - name: version - required: true - type: string - produces: - - application/json - responses: - "200": - description: OK - schema: - $ref: '#/definitions/v1.SkillVersion' - security: - - BearerAuth: [] - summary: Retrieve Skill version metadata - tags: - - Skills - /skills/{skill_id}/versions/{version}/content: - get: - parameters: - - description: Skill ID - in: path - name: skill_id - required: true - type: string - - description: Concrete version number - in: path - name: version - required: true - type: string - produces: - - application/octet-stream - responses: - "200": - description: OK - schema: - type: file - security: - - BearerAuth: [] - summary: Download immutable Skill version content - tags: - - Skills - /vaults: - get: - description: Lists project-owned Vaults independently of execution. An unknown, - malformed or foreign after cursor returns not found. Includes active and archived - records by default. Status accepts a scalar, the SDK's status[] array or both, - filtering by their union; a repeated scalar is rejected. Limits default to - 20 and clamp to 1–100. Equal creation times use ID ordering; exact hosted - errors and concurrent-page behavior remain unverified. Archive/delete lifecycle - is not implemented. - parameters: - - description: agents=v1 - in: header - name: OpenAI-Beta - required: true - type: string - - description: Last Vault ID from the previous page - in: query - name: after - type: string - - default: 20 - description: Requested page size, clamped to 1–100 - in: query - name: limit - type: integer - - default: desc - description: Creation order; omit for descending, explicit empty values are - invalid - enum: - - asc - - desc - in: query - name: order - type: string - - description: Scalar status filter - enum: - - active - - archived - in: query - name: status - type: string - - collectionFormat: multi - description: Array status filter; combined with status as a union - in: query - items: - enum: - - active - - archived - type: string - name: status[] - type: array - produces: - - application/json - responses: - "200": - description: OK - schema: - $ref: '#/definitions/v1.VaultList' - "400": - description: Bad Request - schema: - $ref: '#/definitions/v1.ErrorResponse' - "401": - description: Unauthorized - schema: - $ref: '#/definitions/v1.ErrorResponse' - "404": - description: Not Found - schema: - $ref: '#/definitions/v1.ErrorResponse' - "500": - description: Internal Server Error - schema: - $ref: '#/definitions/v1.ErrorResponse' - security: - - BearerAuth: [] - summary: List Vaults - tags: - - Vaults - post: - consumes: - - application/json - description: Creates a project-owned Vault independently of execution. Omitted - name stays null; a supplied string is trimmed and must contain 1–256 UTF-8 - bytes. Explicit null name is invalid. Omitted/null metadata becomes an empty - object; non-string values return invalid_request_error with a metadata. - param. Metadata has a local 64 KiB encoded storage bound. U+0000 in stored - strings is rejected as a local storage limit. Credentials, Session binding - and hosted error/retry parity remain incomplete. - parameters: - - description: agents=v1 - in: header - name: OpenAI-Beta - required: true - type: string - - description: Vault name and metadata - in: body - name: body - required: true - schema: - $ref: '#/definitions/v1.CreateVaultRequest' - produces: - - application/json - responses: - "201": - description: Created - schema: - $ref: '#/definitions/v1.Vault' - "400": - description: Bad Request - schema: - $ref: '#/definitions/v1.ErrorResponse' - "401": - description: Unauthorized - schema: - $ref: '#/definitions/v1.ErrorResponse' - "413": - description: Request Entity Too Large - schema: - $ref: '#/definitions/v1.ErrorResponse' - "500": - description: Internal Server Error - schema: - $ref: '#/definitions/v1.ErrorResponse' - security: - - BearerAuth: [] - summary: Create a Vault - tags: - - Vaults - /vaults/{vault_id}: - delete: - description: Atomically removes the authenticated project's Vault and all its - stored Credentials without an encryption key, decryption or external requests. - Existing Session snapshots, history and recorded retries retain their frozen - identities; subsequent credential lookups fail without reselection or anonymous - fallback. Already-resolved tokens and running Sessions are not revoked or - cancelled. Missing/repeated deletion locally returns 404. Exact hosted archive, - post-delete visibility and concurrent/error semantics remain unverified; physical - erasure from native history, WAL or backups is not established. - parameters: - - description: agents=v1 - in: header - name: OpenAI-Beta - required: true - type: string - - description: Vault ID - in: path - name: vault_id - required: true - type: string - produces: - - application/json - responses: - "200": - description: OK - schema: - $ref: '#/definitions/v1.VaultDeleted' - "400": - description: Bad Request - schema: - $ref: '#/definitions/v1.ErrorResponse' - "401": - description: Unauthorized - schema: - $ref: '#/definitions/v1.ErrorResponse' - "404": - description: Not Found - schema: - $ref: '#/definitions/v1.ErrorResponse' - "413": - description: Request Entity Too Large - schema: - $ref: '#/definitions/v1.ErrorResponse' - "500": - description: Internal Server Error - schema: - $ref: '#/definitions/v1.ErrorResponse' - security: - - BearerAuth: [] - summary: Delete a Vault and all its Credentials - tags: - - Vaults - get: - description: Reads a Vault owned by the authenticated project without resolving - credentials, Sessions or execution devices. Missing and foreign IDs share - the same not-found response; exact hosted error semantics remain unverified. - parameters: - - description: agents=v1 - in: header - name: OpenAI-Beta - required: true - type: string - - description: Vault ID - in: path - name: vault_id - required: true - type: string - produces: - - application/json - responses: - "200": - description: OK - schema: - $ref: '#/definitions/v1.Vault' - "400": - description: Bad Request - schema: - $ref: '#/definitions/v1.ErrorResponse' - "401": - description: Unauthorized - schema: - $ref: '#/definitions/v1.ErrorResponse' - "404": - description: Not Found - schema: - $ref: '#/definitions/v1.ErrorResponse' - "500": - description: Internal Server Error - schema: - $ref: '#/definitions/v1.ErrorResponse' - security: - - BearerAuth: [] - summary: Retrieve a Vault - tags: - - Vaults - /vaults/{vault_id}/credentials: - get: - description: Lists only metadata from the authenticated project's requested - Vault, without decryption or execution. An unknown, malformed or foreign after - cursor, including another Vault's Credential, returns not found. Includes - active and archived Credentials by default, independently of Vault status. - Status accepts a scalar, the SDK status[] array or both, filtering by their - union; a repeated scalar is rejected. Limits default to 20 and clamp to 1–100. - Equal creation times use ID ordering. Hosted errors, concurrent-page behavior - and archive/delete lifecycle remain unverified or unimplemented. - parameters: - - description: agents=v1 - in: header - name: OpenAI-Beta - required: true - type: string - - description: Vault ID - in: path - name: vault_id - required: true - type: string - - description: Last Credential ID from the previous page - in: query - name: after - type: string - - default: 20 - description: Requested page size, clamped to 1–100 - in: query - name: limit - type: integer - - default: desc - description: Creation order; omit for descending, explicit empty values are - invalid - enum: - - asc - - desc - in: query - name: order - type: string - - description: Scalar status filter - enum: - - active - - archived - in: query - name: status - type: string - - collectionFormat: multi - description: Array status filter; combined with status as a union - in: query - items: - enum: - - active - - archived - type: string - name: status[] - type: array - produces: - - application/json - responses: - "200": - description: OK - schema: - $ref: '#/definitions/v1.CredentialList' - "400": - description: Bad Request - schema: - $ref: '#/definitions/v1.ErrorResponse' - "401": - description: Unauthorized - schema: - $ref: '#/definitions/v1.ErrorResponse' - "404": - description: Not Found - schema: - $ref: '#/definitions/v1.ErrorResponse' - "500": - description: Internal Server Error - schema: - $ref: '#/definitions/v1.ErrorResponse' - security: - - BearerAuth: [] - summary: List safe Vault Credential metadata - tags: - - Credentials - post: - consumes: - - application/json - description: Stores static_bearer or mcp_oauth secrets as execution-owned authenticated - ciphertext without contacting any endpoint. Static bearer and OAuth access - tokens must be nonempty strings; their bytes are preserved. OAuth accepts - a required access token, nullable RFC3339 expiry and optional refresh configuration - with none, client_secret_basic or client_secret_post authentication. Required - name is trimmed to 1–256 UTF-8 bytes. Credential and token endpoints require - HTTPS without userinfo or fragments. Responses contain safe metadata only, - including explicit nullable OAuth expiry, refresh, resource and scope. Missing - encryption configuration returns local 503. External authorization and provider - revocation remain caller responsibilities; exact hosted error/default semantics - remain unverified. - parameters: - - description: agents=v1 - in: header - name: OpenAI-Beta - required: true - type: string - - description: Vault ID - in: path - name: vault_id - required: true - type: string - - description: Write-only credential authentication union - in: body - name: body - required: true - schema: - $ref: '#/definitions/v1.CreateCredentialRequest' - produces: - - application/json - responses: - "201": - description: Created - schema: - $ref: '#/definitions/v1.Credential' - "400": - description: Bad Request - schema: - $ref: '#/definitions/v1.ErrorResponse' - "401": - description: Unauthorized - schema: - $ref: '#/definitions/v1.ErrorResponse' - "404": - description: Not Found - schema: - $ref: '#/definitions/v1.ErrorResponse' - "413": - description: Request Entity Too Large - schema: - $ref: '#/definitions/v1.ErrorResponse' - "500": - description: Internal Server Error - schema: - $ref: '#/definitions/v1.ErrorResponse' - "503": - description: Service Unavailable - schema: - $ref: '#/definitions/v1.ErrorResponse' - security: - - BearerAuth: [] - summary: Create a Vault Credential - tags: - - Credentials - /vaults/{vault_id}/credentials/{credential_id}: - delete: - description: Removes one Credential and its encrypted token within the authenticated - project and owning Vault, without an encryption key or secret decryption. - Subsequent metadata reads, updates and dispatch lookups cannot use it. Existing - Session snapshots and history retain their frozen identities; already-resolved - tokens and running Sessions are not revoked or cancelled. This local policy - removes the row rather than defining archived lifecycle; missing/repeated - deletion returns 404. Exact hosted archive, post-delete visibility and retry/error - semantics remain unverified. Provider revocation and physical erasure from - native history, WAL or backups are separate concerns. - parameters: - - description: agents=v1 - in: header - name: OpenAI-Beta - required: true - type: string - - description: Vault ID - in: path - name: vault_id - required: true - type: string - - description: Credential ID - in: path - name: credential_id - required: true - type: string - produces: - - application/json - responses: - "200": - description: OK - schema: - $ref: '#/definitions/v1.CredentialDeleted' - "400": - description: Bad Request - schema: - $ref: '#/definitions/v1.ErrorResponse' - "401": - description: Unauthorized - schema: - $ref: '#/definitions/v1.ErrorResponse' - "404": - description: Not Found - schema: - $ref: '#/definitions/v1.ErrorResponse' - "413": - description: Request Entity Too Large - schema: - $ref: '#/definitions/v1.ErrorResponse' - "500": - description: Internal Server Error - schema: - $ref: '#/definitions/v1.ErrorResponse' - security: - - BearerAuth: [] - summary: Delete a Vault Credential - tags: - - Credentials - get: - description: Reads only non-secret metadata scoped to the authenticated project - and owning Vault. No token decryption, network request or execution is performed. - Unknown, foreign, wrong-Vault and malformed IDs use the same local not-found - response; hosted error parity remains unverified. - parameters: - - description: agents=v1 - in: header - name: OpenAI-Beta - required: true - type: string - - description: Vault ID - in: path - name: vault_id - required: true - type: string - - description: Credential ID - in: path - name: credential_id - required: true - type: string - produces: - - application/json - responses: - "200": - description: OK - schema: - $ref: '#/definitions/v1.Credential' - "400": - description: Bad Request - schema: - $ref: '#/definitions/v1.ErrorResponse' - "401": - description: Unauthorized - schema: - $ref: '#/definitions/v1.ErrorResponse' - "404": - description: Not Found - schema: - $ref: '#/definitions/v1.ErrorResponse' - "500": - description: Internal Server Error - schema: - $ref: '#/definitions/v1.ErrorResponse' - security: - - BearerAuth: [] - summary: Retrieve safe Vault Credential metadata - tags: - - Credentials - post: - consumes: - - application/json - description: Explicitly empty static bearer or OAuth access tokens and OAuth - patches without a mutable field are rejected before storage. Omitted OAuth - access tokens preserve the existing grant when expiry or refresh fields change. - Updates the existing static_bearer or mcp_oauth authentication method without - network requests. OAuth access_token omission/null retains the token; a new - token clears omitted expiry, explicit null clears expiry, and other omitted - fields remain unchanged. OAuth refresh patches cannot add configuration or - change client, endpoint, resource or authentication method; nullable token/client-secret - values retain stored secrets while explicit null scope clears scope. Whole-null - refresh and token_endpoint_auth retain existing configuration under local - policy. Identity, destination, creation time and Session bindings remain unchanged. - Responses expose safe metadata only. Already-dispatched work is not revoked; - provider revocation, storage-key rotation and exact hosted concurrent-update/error - semantics remain separate. - parameters: - - description: agents=v1 - in: header - name: OpenAI-Beta - required: true - type: string - - description: Vault ID - in: path - name: vault_id - required: true - type: string - - description: Credential ID - in: path - name: credential_id - required: true - type: string - - description: Write-only credential authentication replacement union - in: body - name: body - required: true - schema: - $ref: '#/definitions/v1.UpdateCredentialRequest' - produces: - - application/json - responses: - "200": - description: OK - schema: - $ref: '#/definitions/v1.Credential' - "400": - description: Bad Request - schema: - $ref: '#/definitions/v1.ErrorResponse' - "401": - description: Unauthorized - schema: - $ref: '#/definitions/v1.ErrorResponse' - "404": - description: Not Found - schema: - $ref: '#/definitions/v1.ErrorResponse' - "413": - description: Request Entity Too Large - schema: - $ref: '#/definitions/v1.ErrorResponse' - "500": - description: Internal Server Error - schema: - $ref: '#/definitions/v1.ErrorResponse' - "503": - description: Service Unavailable - schema: - $ref: '#/definitions/v1.ErrorResponse' - security: - - BearerAuth: [] - summary: Replace Vault Credential authentication secrets - tags: - - Credentials -schemes: -- http -- https -securityDefinitions: - BearerAuth: - in: header - name: Authorization - type: apiKey -swagger: "2.0" +{ + "openapi": "3.1.0", + "info": { + "title": "OpenAgentCore public API", + "version": "v1", + "description": "The pinned OpenAI Agents, Files and Skills API with x_agents_core extensions. See the coverage ledger for implementation qualification." + }, + "servers": [ + { + "url": "/v1" + } + ], + "security": [ + { + "ProjectKey": [] + } + ], + "tags": [ + { + "name": "Assistants", + "description": "Build Assistants that can call models and use tools." + }, + { + "name": "Audio", + "description": "Turn audio into text or text into audio." + }, + { + "name": "Chat", + "description": "Given a list of messages comprising a conversation, the model will return a response." + }, + { + "name": "Conversations", + "description": "Manage conversations and conversation items." + }, + { + "name": "Completions", + "description": "Given a prompt, the model will return one or more predicted completions, and can also return the probabilities of alternative tokens at each position." + }, + { + "name": "Embeddings", + "description": "Get a vector representation of a given input that can be easily consumed by machine learning models and algorithms." + }, + { + "name": "Evals", + "description": "Manage and run evals in the OpenAI platform." + }, + { + "name": "Fine-tuning", + "description": "Manage fine-tuning jobs to tailor a model to your specific training data." + }, + { + "name": "Graders", + "description": "Manage and run graders in the OpenAI platform." + }, + { + "name": "Batch", + "description": "Create large batches of API requests to run asynchronously." + }, + { + "name": "Files", + "description": "Files are used to upload documents that can be used with features like Assistants and Fine-tuning." + }, + { + "name": "Uploads", + "description": "Use Uploads to upload large files in multiple parts." + }, + { + "name": "Images", + "description": "Given a prompt and/or an input image, the model will generate a new image." + }, + { + "name": "Models", + "description": "List and describe the various models available in the API." + }, + { + "name": "Moderations", + "description": "Given text and/or image inputs, classifies if those inputs are potentially harmful." + }, + { + "name": "Audit Logs", + "description": "List user actions and configuration changes within this organization." + } + ], + "paths": { + "/files": { + "get": { + "operationId": "listFiles", + "tags": [ + "Files" + ], + "summary": "Returns a list of files.", + "parameters": [ + { + "in": "query", + "name": "purpose", + "required": false, + "schema": { + "type": "string" + }, + "description": "Only return files with the given purpose." + }, + { + "name": "limit", + "in": "query", + "description": "A limit on the number of objects to be returned. Limit can range between 1 and 10,000, and the default is 10,000.\n", + "required": false, + "schema": { + "type": "integer", + "default": 10000 + } + }, + { + "name": "order", + "in": "query", + "description": "Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order.\n", + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + } + }, + { + "name": "after", + "in": "query", + "description": "A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.\n", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListFilesResponse" + } + } + } + } + }, + "x-oaiMeta": { + "name": "List files", + "group": "files", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/files \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.files.list()\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const list = await openai.files.list();\n\n for await (const file of list) {\n console.log(file);\n }\n}\n\nmain();" + }, + "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"file-abc123\",\n \"object\": \"file\",\n \"bytes\": 175,\n \"created_at\": 1613677385,\n \"expires_at\": 1677614202,\n \"filename\": \"salesOverview.pdf\",\n \"purpose\": \"assistants\",\n },\n {\n \"id\": \"file-abc456\",\n \"object\": \"file\",\n \"bytes\": 140,\n \"created_at\": 1613779121,\n \"expires_at\": 1677614202,\n \"filename\": \"puppy.jsonl\",\n \"purpose\": \"fine-tune\",\n }\n ],\n \"first_id\": \"file-abc123\",\n \"last_id\": \"file-abc456\",\n \"has_more\": false\n}\n" + } + } + }, + "post": { + "operationId": "createFile", + "tags": [ + "Files" + ], + "summary": "Upload a file that can be used across various endpoints. Individual files\ncan be up to 512 MB, and each project can store up to 2.5 TB of files in\ntotal. There is no organization-wide storage limit. Uploads to this\nendpoint are rate-limited to 1,000 requests per minute per authenticated\nuser.\n\n- The Assistants API supports files up to 2 million tokens and of specific\n file types. See the [Assistants Tools guide](https://developers.openai.com/api/docs/guides/tools) for\n details.\n- The Fine-tuning API only supports `.jsonl` files. The input also has\n certain required formats for fine-tuning\n [chat](https://developers.openai.com/api/docs/guides/supervised-fine-tuning#formatting-your-data) or\n [completions](https://developers.openai.com/api/docs/guides/supervised-fine-tuning#formatting-your-data) models.\n- The Batch API only supports `.jsonl` files up to 200 MB in size. The input\n also has a specific required\n [format](https://developers.openai.com/api/docs/guides/batch#1-prepare-your-batch-file).\n- For Retrieval or `file_search` ingestion, upload files here first. If\n you need to attach multiple uploaded files to the same vector store, use\n [`/vector_stores/{vector_store_id}/file_batches`](https://developers.openai.com/api/reference/resources/vector_stores/subresources/file_batches/methods/create)\n instead of attaching them one by one. Vector store attachment has separate\n limits from file upload, including 2,000 attached files per minute per\n organization.\n\nPlease [contact us](https://help.openai.com/) if you need to increase these\nstorage limits.\n", + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "$ref": "#/components/schemas/CreateFileRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OpenAIFile" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Upload file", + "group": "files", + "description": "Uploads a file for later use across OpenAI APIs. Uploads to this endpoint are rate-limited to 1,000 requests per minute per authenticated user. For Retrieval or `file_search` ingestion, upload files here first. If you need to attach multiple uploaded files to the same vector store, use vector store file batches instead of attaching them one by one.\n", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/files \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -F purpose=\"fine-tune\" \\\n -F file=\"@mydata.jsonl\"\n -F expires_after[anchor]=\"created_at\"\n -F expires_after[seconds]=2592000\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.files.create(\n file=open(\"mydata.jsonl\", \"rb\"),\n purpose=\"fine-tune\",\n expires_after={\n \"anchor\": \"created_at\",\n \"seconds\": 2592000\n }\n)\n", + "javascript": "import fs from \"fs\";\nimport OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const file = await openai.files.create({\n file: fs.createReadStream(\"mydata.jsonl\"),\n purpose: \"fine-tune\",\n expires_after: {\n anchor: \"created_at\",\n seconds: 2592000\n }\n });\n\n console.log(file);\n}\n\nmain();" + }, + "response": "{\n \"id\": \"file-abc123\",\n \"object\": \"file\",\n \"bytes\": 120000,\n \"created_at\": 1677610602,\n \"expires_at\": 1677614202,\n \"filename\": \"mydata.jsonl\",\n \"purpose\": \"fine-tune\",\n}\n" + } + } + } + }, + "/files/{file_id}": { + "delete": { + "operationId": "deleteFile", + "tags": [ + "Files" + ], + "summary": "Delete a file and remove it from all vector stores.", + "parameters": [ + { + "in": "path", + "name": "file_id", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the file to use for this request." + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeleteFileResponse" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Delete file", + "group": "files", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/files/file-abc123 \\\n -X DELETE \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.files.delete(\"file-abc123\")\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const file = await openai.files.delete(\"file-abc123\");\n\n console.log(file);\n}\n\nmain();" + }, + "response": "{\n \"id\": \"file-abc123\",\n \"object\": \"file\",\n \"deleted\": true\n}\n" + } + } + }, + "get": { + "operationId": "retrieveFile", + "tags": [ + "Files" + ], + "summary": "Returns information about a specific file.", + "parameters": [ + { + "in": "path", + "name": "file_id", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the file to use for this request." + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OpenAIFile" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Retrieve file", + "group": "files", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/files/file-abc123 \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.files.retrieve(\"file-abc123\")\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const file = await openai.files.retrieve(\"file-abc123\");\n\n console.log(file);\n}\n\nmain();" + }, + "response": "{\n \"id\": \"file-abc123\",\n \"object\": \"file\",\n \"bytes\": 120000,\n \"created_at\": 1677610602,\n \"expires_at\": 1677614202,\n \"filename\": \"mydata.jsonl\",\n \"purpose\": \"fine-tune\",\n}\n" + } + } + } + }, + "/files/{file_id}/content": { + "get": { + "operationId": "downloadFile", + "tags": [ + "Files" + ], + "summary": "Returns a response containing the contents of the specified file.", + "parameters": [ + { + "in": "path", + "name": "file_id", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the file to use for this request." + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "string" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Retrieve file content", + "group": "files", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/files/file-abc123/content \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" > file.jsonl\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\ncontent = client.files.content(\"file-abc123\")\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const response = await openai.files.content(\"file-abc123\");\n const content = await response.text();\n\n console.log(content);\n}\n\nmain();\n" + } + } + } + } + }, + "/skills": { + "post": { + "tags": [ + "Skills" + ], + "summary": "Create a new skill.", + "operationId": "CreateSkill", + "parameters": [], + "requestBody": { + "content": { + "multipart/form-data": { + "schema": { + "$ref": "#/components/schemas/CreateSkillBody" + } + }, + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateSkillBody" + } + } + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SkillResource" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + } + }, + "get": { + "tags": [ + "Skills" + ], + "summary": "List all skills for the current project.", + "operationId": "ListSkills", + "parameters": [ + { + "name": "limit", + "in": "query", + "description": "Number of items to retrieve", + "required": false, + "schema": { + "type": "integer", + "minimum": 0, + "maximum": 100 + } + }, + { + "name": "order", + "in": "query", + "description": "Sort order of results by timestamp. Use `asc` for ascending order or `desc` for descending order.", + "required": false, + "schema": { + "$ref": "#/components/schemas/OrderEnum" + } + }, + { + "name": "after", + "in": "query", + "description": "Identifier for the last item from the previous pagination request", + "required": false, + "schema": { + "description": "Identifier for the last item from the previous pagination request", + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SkillListResource" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + } + } + }, + "/skills/{skill_id}": { + "delete": { + "tags": [ + "Skills" + ], + "summary": "Delete a skill by its ID.", + "operationId": "DeleteSkill", + "parameters": [ + { + "name": "skill_id", + "in": "path", + "description": "The identifier of the skill to delete.", + "required": true, + "schema": { + "example": "skill_123", + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeletedSkillResource" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + } + }, + "get": { + "tags": [ + "Skills" + ], + "summary": "Get a skill by its ID.", + "operationId": "GetSkill", + "parameters": [ + { + "name": "skill_id", + "in": "path", + "description": "The identifier of the skill to retrieve.", + "required": true, + "schema": { + "example": "skill_123", + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SkillResource" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + } + }, + "post": { + "tags": [ + "Skills" + ], + "summary": "Update the default version pointer for a skill.", + "operationId": "UpdateSkillDefaultVersion", + "parameters": [ + { + "name": "skill_id", + "in": "path", + "description": "The identifier of the skill.", + "required": true, + "schema": { + "example": "skill_123", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SetDefaultSkillVersionBody" + } + } + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SkillResource" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + } + } + }, + "/skills/{skill_id}/content": { + "get": { + "tags": [ + "Skills" + ], + "summary": "Download a skill zip bundle by its ID.", + "operationId": "GetSkillContent", + "parameters": [ + { + "name": "skill_id", + "in": "path", + "description": "The identifier of the skill to download.", + "required": true, + "schema": { + "example": "skill_123", + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The skill zip bundle.", + "content": { + "application/zip": { + "schema": { + "type": "string", + "format": "binary" + } + }, + "application/json": { + "schema": { + "type": "string" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + } + } + }, + "/skills/{skill_id}/versions": { + "post": { + "tags": [ + "Skills" + ], + "summary": "Create a new immutable skill version.", + "operationId": "CreateSkillVersion", + "parameters": [ + { + "name": "skill_id", + "in": "path", + "description": "The identifier of the skill to version.", + "required": true, + "schema": { + "example": "skill_123", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "multipart/form-data": { + "schema": { + "$ref": "#/components/schemas/CreateSkillVersionBody" + } + }, + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateSkillVersionBody" + } + } + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SkillVersionResource" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + } + }, + "get": { + "tags": [ + "Skills" + ], + "summary": "List skill versions for a skill.", + "operationId": "ListSkillVersions", + "parameters": [ + { + "name": "skill_id", + "in": "path", + "description": "The identifier of the skill.", + "required": true, + "schema": { + "example": "skill_123", + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "description": "Number of versions to retrieve.", + "required": false, + "schema": { + "type": "integer", + "minimum": 0, + "maximum": 100 + } + }, + { + "name": "order", + "in": "query", + "description": "Sort order of results by version number.", + "required": false, + "schema": { + "$ref": "#/components/schemas/OrderEnum" + } + }, + { + "name": "after", + "in": "query", + "description": "The skill version ID to start after.", + "required": false, + "schema": { + "example": "skillver_123", + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SkillVersionListResource" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + } + } + }, + "/skills/{skill_id}/versions/{version}": { + "get": { + "tags": [ + "Skills" + ], + "summary": "Get a specific skill version.", + "operationId": "GetSkillVersion", + "parameters": [ + { + "name": "skill_id", + "in": "path", + "description": "The identifier of the skill.", + "required": true, + "schema": { + "example": "skill_123", + "type": "string" + } + }, + { + "name": "version", + "in": "path", + "description": "The version number to retrieve.", + "required": true, + "schema": { + "description": "The version number to retrieve.", + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SkillVersionResource" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + } + }, + "delete": { + "tags": [ + "Skills" + ], + "summary": "Delete a skill version.", + "operationId": "DeleteSkillVersion", + "parameters": [ + { + "name": "skill_id", + "in": "path", + "description": "The identifier of the skill.", + "required": true, + "schema": { + "example": "skill_123", + "type": "string" + } + }, + { + "name": "version", + "in": "path", + "description": "The skill version number.", + "required": true, + "schema": { + "description": "The skill version number.", + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeletedSkillVersionResource" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + } + } + }, + "/skills/{skill_id}/versions/{version}/content": { + "get": { + "tags": [ + "Skills" + ], + "summary": "Download a skill version zip bundle.", + "operationId": "GetSkillVersionContent", + "parameters": [ + { + "name": "skill_id", + "in": "path", + "description": "The identifier of the skill.", + "required": true, + "schema": { + "example": "skill_123", + "type": "string" + } + }, + { + "name": "version", + "in": "path", + "description": "The skill version number.", + "required": true, + "schema": { + "description": "The skill version number.", + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The skill zip bundle.", + "content": { + "application/zip": { + "schema": { + "type": "string", + "format": "binary" + } + }, + "application/json": { + "schema": { + "type": "string" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + } + } + }, + "/agents/environments/{environment_id}": { + "get": { + "operationId": "retrieveAgentEnvironment", + "summary": "Retrieves an execution environment's connection status and safe installed metadata. See [environment lifecycle](https://developers.openai.com/api/docs/guides/agents-api/environments/lifecycle).", + "description": "Retrieves an execution environment's connection status and safe installed metadata.", + "tags": [ + "Agents" + ], + "parameters": [ + { + "name": "environment_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The ID of the environment." + }, + { + "name": "OpenAI-Beta", + "in": "header", + "required": true, + "schema": { + "type": "string", + "const": "agents=v1" + } + } + ], + "responses": { + "200": { + "description": "The requested environment.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PublicEnvironmentResource" + } + } + } + }, + "400": { + "description": "The request was invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "401": { + "description": "Authentication or project context was missing.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "404": { + "description": "The requested session or event was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "409": { + "description": "The request conflicted with the current session state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "500": { + "description": "An internal error occurred.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "503": { + "description": "The service is temporarily unavailable.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Retrieve an agent environment" + } + } + }, + "/agents/environments/{environment_id}/files": { + "get": { + "operationId": "listAgentEnvironmentFiles", + "summary": "Lists live files on a connected execution environment with optional directory filtering and opaque cursor pagination. See [environment files](https://developers.openai.com/api/docs/guides/agents-api/environments/files).", + "description": "Lists live files on a connected execution environment with optional directory filtering and opaque cursor pagination.", + "tags": [ + "Agents" + ], + "parameters": [ + { + "name": "environment_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The ID of the environment." + }, + { + "name": "path", + "in": "query", + "required": false, + "schema": { + "type": [ + "string", + "null" + ], + "minLength": 0, + "maxLength": 1048576 + }, + "description": "Restrict the listing to this absolute workspace directory." + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": [ + "integer", + "null" + ], + "format": "int64", + "minimum": 1, + "maximum": 100 + }, + "description": "The maximum number of files to return, between 1 and 100." + }, + { + "name": "order", + "in": "query", + "required": false, + "schema": { + "$ref": "#/components/schemas/ListOrderParam" + }, + "description": "Sort by case-sensitive path components. Defaults to descending." + }, + { + "name": "page", + "in": "query", + "required": false, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The opaque token from the previous page. Keep the same path, order, and limit." + }, + { + "name": "OpenAI-Beta", + "in": "header", + "required": true, + "schema": { + "type": "string", + "const": "agents=v1" + } + } + ], + "responses": { + "200": { + "description": "A page of live environment files.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EnvironmentFileListResource" + } + } + } + }, + "400": { + "description": "The request was invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "401": { + "description": "Authentication or project context was missing.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "404": { + "description": "The requested session or event was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "409": { + "description": "The request conflicted with the current session state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "500": { + "description": "An internal error occurred.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "503": { + "description": "The service is temporarily unavailable.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + } + }, + "x-oaiMeta": { + "name": "List agent environment files" + } + }, + "post": { + "operationId": "createAgentEnvironmentFile", + "summary": "Copies inline bytes or a Files API file into a connected execution environment. See [environment files](https://developers.openai.com/api/docs/guides/agents-api/environments/files).", + "description": "Copies inline bytes or a Files API file into a connected execution environment.", + "tags": [ + "Agents" + ], + "parameters": [ + { + "name": "environment_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The ID of the environment." + }, + { + "name": "OpenAI-Beta", + "in": "header", + "required": true, + "schema": { + "type": "string", + "const": "agents=v1" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HostedEnvironmentFileParam" + } + } + } + }, + "responses": { + "201": { + "description": "The created live environment file.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EnvironmentFileResource" + } + } + } + }, + "400": { + "description": "The request was invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "401": { + "description": "Authentication or project context was missing.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "404": { + "description": "The requested session or event was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "409": { + "description": "The request conflicted with the current session state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "500": { + "description": "An internal error occurred.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "503": { + "description": "The service is temporarily unavailable.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Create an agent environment file" + } + } + }, + "/agents/sessions/{session_id}/subagents": { + "get": { + "operationId": "listAgentSessionSubagents", + "summary": "Lists subagents in a session, including nested and closed subagents. See [subagent workflows](https://developers.openai.com/api/docs/guides/agents-api/multi-agent).", + "description": "Lists subagents in a session, including nested and closed subagents.", + "tags": [ + "Agents" + ], + "parameters": [ + { + "name": "session_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The ID of the session." + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 100, + "default": 20 + }, + "description": "The maximum number of resources to return, between 1 and 100. Defaults to 20." + }, + { + "name": "order", + "in": "query", + "required": false, + "schema": { + "$ref": "#/components/schemas/ListOrderParam", + "default": "desc" + }, + "description": "The order in which resources are returned. Defaults to `desc`." + }, + { + "name": "after", + "in": "query", + "required": false, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "Return resources after this resource ID in the selected order." + }, + { + "name": "OpenAI-Beta", + "in": "header", + "required": true, + "schema": { + "type": "string", + "const": "agents=v1" + } + } + ], + "responses": { + "200": { + "description": "The requested subagents.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "object": { + "type": "string", + "enum": [ + "list" + ], + "default": "list", + "x-stainless-const": true, + "description": "The object type, which is always `list`." + }, + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SubagentResource" + }, + "minItems": 0, + "maxItems": 2000, + "description": "The resources returned in this page, in the requested sort order." + }, + "first_id": { + "type": [ + "string", + "null" + ], + "minLength": 0, + "description": "The ID of the first resource in `data`, or `null` if the page is empty." + }, + "last_id": { + "type": [ + "string", + "null" + ], + "minLength": 0, + "description": "The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters." + }, + "has_more": { + "type": "boolean", + "description": "Whether there are more resources to retrieve after this page." + } + }, + "required": [ + "object", + "data", + "first_id", + "last_id", + "has_more" + ], + "additionalProperties": false, + "description": "A page of Agents API resources, with IDs for retrieving additional pages." + } + } + } + }, + "400": { + "description": "The request was invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "401": { + "description": "Authentication or project context was missing.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "403": { + "description": "The API key lacks the required Responses permission.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "404": { + "description": "The requested session or event was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "409": { + "description": "The request conflicted with the current session state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "500": { + "description": "An internal error occurred.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "503": { + "description": "The service is temporarily unavailable.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + } + }, + "x-oaiMeta": { + "name": "List session subagents" + } + } + }, + "/agents/sessions/{session_id}/subagents/{subagent_id}": { + "get": { + "operationId": "retrieveAgentSessionSubagent", + "summary": "Retrieves a subagent belonging to this session. See [subagent workflows](https://developers.openai.com/api/docs/guides/agents-api/multi-agent).", + "description": "Retrieves a subagent belonging to this session.", + "tags": [ + "Agents" + ], + "parameters": [ + { + "name": "session_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The ID of the session." + }, + { + "name": "subagent_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The ID of the subagent in this session." + }, + { + "name": "OpenAI-Beta", + "in": "header", + "required": true, + "schema": { + "type": "string", + "const": "agents=v1" + } + } + ], + "responses": { + "200": { + "description": "The requested subagent.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SubagentResource" + } + } + } + }, + "400": { + "description": "The request was invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "401": { + "description": "Authentication or project context was missing.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "403": { + "description": "The API key lacks the required Responses permission.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "404": { + "description": "The requested session or event was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "409": { + "description": "The request conflicted with the current session state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "500": { + "description": "An internal error occurred.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "503": { + "description": "The service is temporarily unavailable.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Retrieve a session subagent" + } + } + }, + "/agents/sessions/{session_id}/subagents/{subagent_id}/items": { + "get": { + "operationId": "listAgentSessionSubagentItems", + "summary": "Lists this subagent's own items across all of its turns. See [subagent workflows](https://developers.openai.com/api/docs/guides/agents-api/multi-agent).", + "description": "Lists this subagent's own items across all of its turns.", + "tags": [ + "Agents" + ], + "parameters": [ + { + "name": "session_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The ID of the session." + }, + { + "name": "subagent_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The ID of the subagent in this session." + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 100, + "default": 20 + }, + "description": "The maximum number of resources to return, between 1 and 100. Defaults to 20." + }, + { + "name": "order", + "in": "query", + "required": false, + "schema": { + "$ref": "#/components/schemas/ListOrderParam", + "default": "desc" + }, + "description": "The order in which resources are returned. Defaults to `desc`." + }, + { + "name": "after", + "in": "query", + "required": false, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "Return resources after this resource ID in the selected order." + }, + { + "name": "OpenAI-Beta", + "in": "header", + "required": true, + "schema": { + "type": "string", + "const": "agents=v1" + } + } + ], + "responses": { + "200": { + "description": "The requested subagent history.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SessionItemListResource" + } + } + } + }, + "400": { + "description": "The request was invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "401": { + "description": "Authentication or project context was missing.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "403": { + "description": "The API key lacks the required Responses permission.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "404": { + "description": "The requested session or event was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "409": { + "description": "The request conflicted with the current session state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "500": { + "description": "An internal error occurred.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "503": { + "description": "The service is temporarily unavailable.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + } + }, + "x-oaiMeta": { + "name": "List subagent items" + } + } + }, + "/agents/sessions/{session_id}/subagents/{subagent_id}/turns": { + "get": { + "operationId": "listAgentSessionSubagentTurns", + "summary": "Lists all turns of this subagent, including turns after a resume. See [subagent workflows](https://developers.openai.com/api/docs/guides/agents-api/multi-agent).", + "description": "Lists all turns of this subagent, including turns after a resume.", + "tags": [ + "Agents" + ], + "parameters": [ + { + "name": "session_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The ID of the session." + }, + { + "name": "subagent_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The ID of the subagent in this session." + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 100, + "default": 20 + }, + "description": "The maximum number of resources to return, between 1 and 100. Defaults to 20." + }, + { + "name": "order", + "in": "query", + "required": false, + "schema": { + "$ref": "#/components/schemas/ListOrderParam", + "default": "desc" + }, + "description": "The order in which resources are returned. Defaults to `desc`." + }, + { + "name": "after", + "in": "query", + "required": false, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "Return resources after this resource ID in the selected order." + }, + { + "name": "OpenAI-Beta", + "in": "header", + "required": true, + "schema": { + "type": "string", + "const": "agents=v1" + } + } + ], + "responses": { + "200": { + "description": "The requested subagent history.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SessionTurnListResource", + "description": "A page of turns from an agent session or subagent." + } + } + } + }, + "400": { + "description": "The request was invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "401": { + "description": "Authentication or project context was missing.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "403": { + "description": "The API key lacks the required Responses permission.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "404": { + "description": "The requested session or event was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "409": { + "description": "The request conflicted with the current session state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "500": { + "description": "An internal error occurred.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "503": { + "description": "The service is temporarily unavailable.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + } + }, + "x-oaiMeta": { + "name": "List subagent turns" + } + } + }, + "/agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}": { + "get": { + "operationId": "retrieveAgentSessionSubagentTurn", + "summary": "Retrieves a turn belonging to this subagent. See [subagent workflows](https://developers.openai.com/api/docs/guides/agents-api/multi-agent).", + "description": "Retrieves a turn belonging to this subagent.", + "tags": [ + "Agents" + ], + "parameters": [ + { + "name": "session_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The ID of the session." + }, + { + "name": "subagent_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The ID of the subagent in this session." + }, + { + "name": "turn_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The ID of a turn belonging to this subagent." + }, + { + "name": "OpenAI-Beta", + "in": "header", + "required": true, + "schema": { + "type": "string", + "const": "agents=v1" + } + } + ], + "responses": { + "200": { + "description": "The requested subagent history.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TurnResource" + } + } + } + }, + "400": { + "description": "The request was invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "401": { + "description": "Authentication or project context was missing.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "403": { + "description": "The API key lacks the required Responses permission.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "404": { + "description": "The requested session or event was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "409": { + "description": "The request conflicted with the current session state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "500": { + "description": "An internal error occurred.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "503": { + "description": "The service is temporarily unavailable.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Retrieve a subagent turn" + } + } + }, + "/agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}/items": { + "get": { + "operationId": "listAgentSessionSubagentTurnItems", + "summary": "Lists items belonging to one turn of this subagent. See [subagent workflows](https://developers.openai.com/api/docs/guides/agents-api/multi-agent).", + "description": "Lists items belonging to one turn of this subagent.", + "tags": [ + "Agents" + ], + "parameters": [ + { + "name": "session_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The ID of the session." + }, + { + "name": "subagent_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The ID of the subagent in this session." + }, + { + "name": "turn_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The ID of a turn belonging to this subagent." + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 100, + "default": 20 + }, + "description": "The maximum number of resources to return, between 1 and 100. Defaults to 20." + }, + { + "name": "order", + "in": "query", + "required": false, + "schema": { + "$ref": "#/components/schemas/ListOrderParam", + "default": "desc" + }, + "description": "The order in which resources are returned. Defaults to `desc`." + }, + { + "name": "after", + "in": "query", + "required": false, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "Return resources after this resource ID in the selected order." + }, + { + "name": "OpenAI-Beta", + "in": "header", + "required": true, + "schema": { + "type": "string", + "const": "agents=v1" + } + } + ], + "responses": { + "200": { + "description": "The requested subagent history.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SessionItemListResource" + } + } + } + }, + "400": { + "description": "The request was invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "401": { + "description": "Authentication or project context was missing.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "403": { + "description": "The API key lacks the required Responses permission.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "404": { + "description": "The requested session or event was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "409": { + "description": "The request conflicted with the current session state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "500": { + "description": "An internal error occurred.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "503": { + "description": "The service is temporarily unavailable.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + } + }, + "x-oaiMeta": { + "name": "List subagent turn items" + } + } + }, + "/agents": { + "get": { + "operationId": "listAgents", + "summary": "Lists reusable agents in the current project. See [agent configuration](https://developers.openai.com/api/docs/guides/agents-api/configuration).", + "description": "Lists reusable agents in the current project.", + "tags": [ + "Agents" + ], + "parameters": [ + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": [ + "integer", + "null" + ], + "format": "int64", + "minimum": 1 + }, + "description": "The maximum number of resources to return." + }, + { + "name": "order", + "in": "query", + "required": false, + "schema": { + "$ref": "#/components/schemas/ListOrderParam", + "default": "desc" + }, + "description": "The order in which resources are returned. Defaults to `desc`." + }, + { + "name": "after", + "in": "query", + "required": false, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "Return resources after this resource ID in the selected order." + }, + { + "name": "OpenAI-Beta", + "in": "header", + "required": true, + "schema": { + "type": "string", + "const": "agents=v1" + } + } + ], + "responses": { + "200": { + "description": "A page of agents.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentListResource", + "description": "A page of reusable agents." + } + } + } + }, + "400": { + "description": "The request was invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "401": { + "description": "Authentication or project context was missing.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "404": { + "description": "The requested session or event was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "409": { + "description": "The request conflicted with the current session state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "500": { + "description": "An internal error occurred.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "503": { + "description": "The service is temporarily unavailable.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + } + }, + "x-oaiMeta": { + "name": "List agents" + } + }, + "post": { + "operationId": "createAgent", + "summary": "Creates a reusable agent without storing credentials. See [agent configuration](https://developers.openai.com/api/docs/guides/agents-api/configuration).", + "description": "Creates a reusable agent without storing credentials.", + "tags": [ + "Agents" + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateAgentParams" + } + } + } + }, + "responses": { + "201": { + "description": "The created agent.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentResource" + } + } + } + }, + "400": { + "description": "The request was invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "401": { + "description": "Authentication or project context was missing.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "404": { + "description": "The requested session or event was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "409": { + "description": "The request conflicted with the current session state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "500": { + "description": "An internal error occurred.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "503": { + "description": "The service is temporarily unavailable.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Create an agent" + }, + "parameters": [ + { + "name": "OpenAI-Beta", + "in": "header", + "required": true, + "schema": { + "type": "string", + "const": "agents=v1" + } + } + ] + } + }, + "/agents/{agent_id}": { + "get": { + "operationId": "retrieveAgent", + "summary": "Retrieves a reusable agent by ID. See [agent configuration](https://developers.openai.com/api/docs/guides/agents-api/configuration).", + "description": "Retrieves a reusable agent by ID.", + "tags": [ + "Agents" + ], + "parameters": [ + { + "name": "agent_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The ID of the reusable agent." + }, + { + "name": "OpenAI-Beta", + "in": "header", + "required": true, + "schema": { + "type": "string", + "const": "agents=v1" + } + } + ], + "responses": { + "200": { + "description": "The requested agent.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentResource" + } + } + } + }, + "400": { + "description": "The request was invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "401": { + "description": "Authentication or project context was missing.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "404": { + "description": "The requested session or event was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "409": { + "description": "The request conflicted with the current session state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "500": { + "description": "An internal error occurred.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "503": { + "description": "The service is temporarily unavailable.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Retrieve an agent" + } + }, + "post": { + "operationId": "updateAgent", + "summary": "Updates a reusable agent. See [agent configuration](https://developers.openai.com/api/docs/guides/agents-api/configuration).", + "description": "Updates a reusable agent.", + "tags": [ + "Agents" + ], + "parameters": [ + { + "name": "agent_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The ID of the reusable agent." + }, + { + "name": "OpenAI-Beta", + "in": "header", + "required": true, + "schema": { + "type": "string", + "const": "agents=v1" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateAgentParams" + } + } + } + }, + "responses": { + "200": { + "description": "The updated agent.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentResource" + } + } + } + }, + "400": { + "description": "The request was invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "401": { + "description": "Authentication or project context was missing.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "404": { + "description": "The requested session or event was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "409": { + "description": "The request conflicted with the current session state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "500": { + "description": "An internal error occurred.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "503": { + "description": "The service is temporarily unavailable.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Update an agent" + } + }, + "delete": { + "operationId": "deleteAgent", + "summary": "Deletes a reusable agent. See [agent configuration](https://developers.openai.com/api/docs/guides/agents-api/configuration).", + "description": "Deletes a reusable agent.", + "tags": [ + "Agents" + ], + "parameters": [ + { + "name": "agent_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The ID of the reusable agent." + }, + { + "name": "OpenAI-Beta", + "in": "header", + "required": true, + "schema": { + "type": "string", + "const": "agents=v1" + } + } + ], + "responses": { + "200": { + "description": "The deleted agent.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeletedAgentResource" + } + } + } + }, + "400": { + "description": "The request was invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "401": { + "description": "Authentication or project context was missing.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "404": { + "description": "The requested session or event was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "409": { + "description": "The request conflicted with the current session state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "500": { + "description": "An internal error occurred.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "503": { + "description": "The service is temporarily unavailable.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Delete an agent" + } + } + }, + "/agents/environments/templates": { + "get": { + "operationId": "listAgentEnvironmentTemplates", + "summary": "Lists reusable environment templates without returning confidential values. See [reusing a hosted setup](https://developers.openai.com/api/docs/guides/agents-api/tools#reuse-a-hosted-plugin-setup).", + "description": "Lists reusable environment templates without returning confidential values.", + "tags": [ + "Agents" + ], + "parameters": [ + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 100, + "default": 20 + }, + "description": "The maximum number of resources to return, between 1 and 100. Defaults to 20." + }, + { + "name": "order", + "in": "query", + "required": false, + "schema": { + "$ref": "#/components/schemas/ListOrderParam", + "default": "desc" + }, + "description": "The order in which resources are returned. Defaults to `desc`." + }, + { + "name": "after", + "in": "query", + "required": false, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "Return resources after this resource ID in the selected order." + }, + { + "name": "OpenAI-Beta", + "in": "header", + "required": true, + "schema": { + "type": "string", + "const": "agents=v1" + } + } + ], + "responses": { + "200": { + "description": "A page of environment templates.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EnvironmentTemplateListResource", + "description": "A page of reusable environment templates." + } + } + } + }, + "400": { + "description": "The request was invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "401": { + "description": "Authentication or project context was missing.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "403": { + "description": "The API key lacks the required management permission.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "404": { + "description": "The requested environment definition was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "500": { + "description": "An internal error occurred.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "503": { + "description": "The service is temporarily unavailable.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + } + }, + "x-oaiMeta": { + "name": "List agent environment templates" + } + }, + "post": { + "operationId": "createAgentEnvironmentTemplate", + "summary": "Creates reusable environment configuration without returning confidential setup commands or environment values. See [reusing a hosted setup](https://developers.openai.com/api/docs/guides/agents-api/tools#reuse-a-hosted-plugin-setup).", + "description": "Creates reusable environment configuration without returning confidential setup commands or environment values.", + "tags": [ + "Agents" + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateEnvironmentTemplateParams" + } + } + } + }, + "responses": { + "201": { + "description": "The created environment template.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EnvironmentTemplateResource" + } + } + } + }, + "400": { + "description": "The request was invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "401": { + "description": "Authentication or project context was missing.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "403": { + "description": "The API key lacks the required management permission.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "404": { + "description": "The requested environment definition was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "500": { + "description": "An internal error occurred.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "503": { + "description": "The service is temporarily unavailable.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Create an agent environment template" + }, + "parameters": [ + { + "name": "OpenAI-Beta", + "in": "header", + "required": true, + "schema": { + "type": "string", + "const": "agents=v1" + } + } + ] + } + }, + "/agents/environments/templates/{environment_template_id}": { + "get": { + "operationId": "retrieveAgentEnvironmentTemplate", + "summary": "Retrieves reusable environment configuration without returning confidential values. See [reusing a hosted setup](https://developers.openai.com/api/docs/guides/agents-api/tools#reuse-a-hosted-plugin-setup).", + "description": "Retrieves reusable environment configuration without returning confidential values.", + "tags": [ + "Agents" + ], + "parameters": [ + { + "name": "environment_template_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The ID of the reusable environment template." + }, + { + "name": "OpenAI-Beta", + "in": "header", + "required": true, + "schema": { + "type": "string", + "const": "agents=v1" + } + } + ], + "responses": { + "200": { + "description": "The requested environment template.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EnvironmentTemplateResource" + } + } + } + }, + "400": { + "description": "The request was invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "401": { + "description": "Authentication or project context was missing.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "403": { + "description": "The API key lacks the required management permission.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "404": { + "description": "The requested environment definition was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "500": { + "description": "An internal error occurred.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "503": { + "description": "The service is temporarily unavailable.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Retrieve an agent environment template" + } + }, + "post": { + "operationId": "updateAgentEnvironmentTemplate", + "summary": "Updates reusable environment configuration without returning confidential values. See [reusing a hosted setup](https://developers.openai.com/api/docs/guides/agents-api/tools#reuse-a-hosted-plugin-setup).", + "description": "Updates reusable environment configuration without returning confidential values.", + "tags": [ + "Agents" + ], + "parameters": [ + { + "name": "environment_template_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The ID of the reusable environment template." + }, + { + "name": "OpenAI-Beta", + "in": "header", + "required": true, + "schema": { + "type": "string", + "const": "agents=v1" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateEnvironmentTemplateParams" + } + } + } + }, + "responses": { + "200": { + "description": "The updated environment template.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EnvironmentTemplateResource" + } + } + } + }, + "400": { + "description": "The request was invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "401": { + "description": "Authentication or project context was missing.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "403": { + "description": "The API key lacks the required management permission.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "404": { + "description": "The requested environment definition was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "409": { + "description": "The request conflicted with the current environment state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "500": { + "description": "An internal error occurred.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "503": { + "description": "The service is temporarily unavailable.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Update an agent environment template" + } + }, + "delete": { + "operationId": "deleteAgentEnvironmentTemplate", + "summary": "Deletes reusable environment configuration and all confidential template inputs. See [reusing a hosted setup](https://developers.openai.com/api/docs/guides/agents-api/tools#reuse-a-hosted-plugin-setup).", + "description": "Deletes reusable environment configuration and all confidential template inputs.", + "tags": [ + "Agents" + ], + "parameters": [ + { + "name": "environment_template_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The ID of the reusable environment template." + }, + { + "name": "OpenAI-Beta", + "in": "header", + "required": true, + "schema": { + "type": "string", + "const": "agents=v1" + } + } + ], + "responses": { + "200": { + "description": "The deleted environment template.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeletedEnvironmentTemplateResource" + } + } + } + }, + "400": { + "description": "The request was invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "401": { + "description": "Authentication or project context was missing.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "403": { + "description": "The API key lacks the required management permission.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "404": { + "description": "The requested environment definition was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "409": { + "description": "The request conflicted with the current environment state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "500": { + "description": "An internal error occurred.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "503": { + "description": "The service is temporarily unavailable.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Delete an agent environment template" + } + } + }, + "/agents/sessions": { + "get": { + "operationId": "listAgentSessions", + "summary": "Lists managed agent sessions using ID-based pagination and the requested sort order. See [managing sessions](https://developers.openai.com/api/docs/guides/agents-api/sessions/manage).", + "description": "Lists managed agent sessions using ID-based pagination and the requested sort order.", + "tags": [ + "Agents" + ], + "parameters": [ + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": [ + "integer", + "null" + ], + "format": "int64", + "minimum": 1 + }, + "description": "The maximum number of resources to return." + }, + { + "name": "order", + "in": "query", + "required": false, + "schema": { + "$ref": "#/components/schemas/ListOrderParam", + "default": "desc" + }, + "description": "Sort order by the `created_at` timestamp. Use `asc` for ascending order or `desc` for descending order. Defaults to `desc`." + }, + { + "name": "agent_id", + "in": "query", + "required": false, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "Only return sessions whose root agent has this ID. Omit to return sessions for all agents." + }, + { + "name": "after", + "in": "query", + "required": false, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "Return resources after this resource ID in the selected order." + }, + { + "name": "OpenAI-Beta", + "in": "header", + "required": true, + "schema": { + "type": "string", + "const": "agents=v1" + } + } + ], + "responses": { + "200": { + "description": "A page of sessions.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SessionListResource", + "description": "A paginated list of sessions." + } + } + } + }, + "400": { + "description": "The request was invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "401": { + "description": "Authentication or project context was missing.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "403": { + "description": "The API key lacks the required Responses permission.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "404": { + "description": "The requested session or event was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "409": { + "description": "The request conflicted with the current session state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "500": { + "description": "An internal error occurred.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "503": { + "description": "The service is temporarily unavailable.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + } + }, + "x-oaiMeta": { + "name": "List agent sessions" + } + }, + "post": { + "operationId": "createAgentSession", + "summary": "Creates a managed agent session, optionally submits initial input, and returns the session or streams its events when stream is true. See [running sessions](https://developers.openai.com/api/docs/guides/agents-api/sessions).", + "description": "Creates a managed agent session, optionally submits initial input, and returns the session or streams its events when stream is true.", + "tags": [ + "Agents" + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateAgentSessionParams" + } + } + } + }, + "responses": { + "201": { + "description": "The created session or its event stream.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SessionResource" + } + }, + "text/event-stream": { + "schema": { + "$ref": "#/components/schemas/SessionEvent" + } + } + } + }, + "400": { + "description": "The request was invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "401": { + "description": "Authentication or project context was missing.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "403": { + "description": "The API key lacks the required Responses permission.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "404": { + "description": "The requested session or event was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "409": { + "description": "The request conflicted with the current session state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "500": { + "description": "An internal error occurred.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "503": { + "description": "The service is temporarily unavailable.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + } + }, + "x-oai-streaming": { + "request_field": "stream", + "response_status_code": 201 + }, + "x-oaiMeta": { + "name": "Create an agent session" + }, + "parameters": [ + { + "name": "OpenAI-Beta", + "in": "header", + "required": true, + "schema": { + "type": "string", + "const": "agents=v1" + } + } + ] + } + }, + "/agents/sessions/{session_id}": { + "get": { + "operationId": "retrieveAgentSession", + "summary": "Retrieves the current state of a managed agent session. See [managing sessions](https://developers.openai.com/api/docs/guides/agents-api/sessions/manage).", + "description": "Retrieves the current state of a managed agent session.", + "tags": [ + "Agents" + ], + "parameters": [ + { + "name": "session_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The ID of the session." + }, + { + "name": "OpenAI-Beta", + "in": "header", + "required": true, + "schema": { + "type": "string", + "const": "agents=v1" + } + } + ], + "responses": { + "200": { + "description": "The requested session.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SessionResource" + } + } + } + }, + "400": { + "description": "The request was invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "401": { + "description": "Authentication or project context was missing.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "403": { + "description": "The API key lacks the required Responses permission.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "404": { + "description": "The requested session or event was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "409": { + "description": "The request conflicted with the current session state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "500": { + "description": "An internal error occurred.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "503": { + "description": "The service is temporarily unavailable.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Retrieve an agent session" + } + }, + "post": { + "operationId": "updateAgentSession", + "summary": "Updates session metadata. Omitted fields are unchanged. See [managing sessions](https://developers.openai.com/api/docs/guides/agents-api/sessions/manage).", + "description": "Updates session metadata. Omitted fields are unchanged.", + "tags": [ + "Agents" + ], + "parameters": [ + { + "name": "session_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The ID of the session." + }, + { + "name": "OpenAI-Beta", + "in": "header", + "required": true, + "schema": { + "type": "string", + "const": "agents=v1" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateAgentSessionParams" + } + } + } + }, + "responses": { + "200": { + "description": "The updated session.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SessionResource" + } + } + } + }, + "400": { + "description": "The request was invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "401": { + "description": "Authentication or project context was missing.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "403": { + "description": "The API key lacks the required Responses permission.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "404": { + "description": "The requested session or event was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "409": { + "description": "The request conflicted with the current session state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "500": { + "description": "An internal error occurred.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "503": { + "description": "The service is temporarily unavailable.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Update an agent session" + } + }, + "delete": { + "operationId": "deleteAgentSession", + "summary": "Removes a managed agent session from the public API and returns a deletion confirmation. Physical cleanup may continue asynchronously. See [managing sessions](https://developers.openai.com/api/docs/guides/agents-api/sessions/manage).", + "description": "Removes a managed agent session from the public API and returns a deletion confirmation. Physical cleanup may continue asynchronously.", + "tags": [ + "Agents" + ], + "parameters": [ + { + "name": "session_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The ID of the session." + }, + { + "name": "OpenAI-Beta", + "in": "header", + "required": true, + "schema": { + "type": "string", + "const": "agents=v1" + } + } + ], + "responses": { + "200": { + "description": "The deleted session.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeletedSessionResource" + } + } + } + }, + "400": { + "description": "The request was invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "401": { + "description": "Authentication or project context was missing.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "403": { + "description": "The API key lacks the required Responses permission.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "404": { + "description": "The requested session or event was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "409": { + "description": "The request conflicted with the current session state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "500": { + "description": "An internal error occurred.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "503": { + "description": "The service is temporarily unavailable.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Delete an agent session" + } + } + }, + "/agents/sessions/{session_id}/artifacts": { + "get": { + "operationId": "listAgentSessionArtifacts", + "summary": "Lists immutable artifacts published by completed hosted session turns. See [session artifacts](https://developers.openai.com/api/docs/guides/agents-api/environments/files#openai-hosted-artifacts).", + "description": "Lists immutable artifacts published by completed hosted session turns.", + "tags": [ + "Agents" + ], + "parameters": [ + { + "name": "session_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The ID of the session." + }, + { + "name": "order", + "in": "query", + "required": false, + "schema": { + "$ref": "#/components/schemas/ListOrderParam" + }, + "description": "Sort by creation time and ID. Defaults to descending." + }, + { + "name": "environment_id", + "in": "query", + "required": false, + "schema": { + "type": [ + "string", + "null" + ], + "minLength": 0, + "maxLength": 1048576 + }, + "description": "Restrict the listing to artifacts produced by this environment." + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": [ + "integer", + "null" + ], + "format": "int64", + "minimum": 1, + "maximum": 100 + }, + "description": "The maximum number of artifacts to return, between 1 and 100." + }, + { + "name": "after", + "in": "query", + "required": false, + "schema": { + "type": [ + "string", + "null" + ], + "minLength": 0, + "maxLength": 1048576 + }, + "description": "Return artifacts after this immutable artifact ID." + }, + { + "name": "OpenAI-Beta", + "in": "header", + "required": true, + "schema": { + "type": "string", + "const": "agents=v1" + } + } + ], + "responses": { + "200": { + "description": "A page of durable session artifacts.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SessionArtifactListResource", + "description": "A page of durable artifacts published by a session." + } + } + } + }, + "400": { + "description": "The request was invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "401": { + "description": "Authentication or project context was missing.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "403": { + "description": "The API key lacks the required Responses permission.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "404": { + "description": "The requested session or event was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "409": { + "description": "The request conflicted with the current session state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "500": { + "description": "An internal error occurred.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "503": { + "description": "The service is temporarily unavailable.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + } + }, + "x-oaiMeta": { + "name": "List agent session artifacts" + } + } + }, + "/agents/sessions/{session_id}/artifacts/{artifact_id}": { + "get": { + "operationId": "retrieveAgentSessionArtifact", + "summary": "Retrieves immutable metadata for one durable session artifact. See [session artifacts](https://developers.openai.com/api/docs/guides/agents-api/environments/files#openai-hosted-artifacts).", + "description": "Retrieves immutable metadata for one durable session artifact.", + "tags": [ + "Agents" + ], + "parameters": [ + { + "name": "session_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The ID of the session that owns the artifact." + }, + { + "name": "artifact_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The immutable session artifact ID." + }, + { + "name": "OpenAI-Beta", + "in": "header", + "required": true, + "schema": { + "type": "string", + "const": "agents=v1" + } + } + ], + "responses": { + "200": { + "description": "The requested session artifact.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SessionArtifactResource" + } + } + } + }, + "400": { + "description": "The request was invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "401": { + "description": "Authentication or project context was missing.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "403": { + "description": "The API key lacks the required Responses permission.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "404": { + "description": "The requested session or event was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "409": { + "description": "The request conflicted with the current session state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "500": { + "description": "An internal error occurred.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "503": { + "description": "The service is temporarily unavailable.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Retrieve an agent session artifact" + } + }, + "delete": { + "operationId": "deleteAgentSessionArtifact", + "summary": "Deletes an immutable session artifact without deleting its live environment file or original Files API object. See [session artifacts](https://developers.openai.com/api/docs/guides/agents-api/environments/files#openai-hosted-artifacts).", + "description": "Deletes an immutable session artifact without deleting its live environment file or original Files API object.", + "tags": [ + "Agents" + ], + "parameters": [ + { + "name": "session_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The ID of the session that owns the artifact." + }, + { + "name": "artifact_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The immutable session artifact ID." + }, + { + "name": "OpenAI-Beta", + "in": "header", + "required": true, + "schema": { + "type": "string", + "const": "agents=v1" + } + } + ], + "responses": { + "200": { + "description": "The deleted session artifact.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeletedSessionArtifactResource" + } + } + } + }, + "400": { + "description": "The request was invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "401": { + "description": "Authentication or project context was missing.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "403": { + "description": "The API key lacks the required Responses permission.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "404": { + "description": "The requested session or event was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "409": { + "description": "The request conflicted with the current session state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "500": { + "description": "An internal error occurred.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "503": { + "description": "The service is temporarily unavailable.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Delete an agent session artifact" + } + } + }, + "/agents/sessions/{session_id}/artifacts/{artifact_id}/content": { + "get": { + "operationId": "retrieveAgentSessionArtifactContent", + "summary": "Downloads immutable session artifact bytes after the execution environment expires. See [session artifacts](https://developers.openai.com/api/docs/guides/agents-api/environments/files#openai-hosted-artifacts).", + "description": "Downloads immutable session artifact bytes after the execution environment expires.", + "tags": [ + "Agents" + ], + "parameters": [ + { + "name": "session_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The ID of the session that owns the artifact." + }, + { + "name": "artifact_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The immutable session artifact ID." + }, + { + "name": "OpenAI-Beta", + "in": "header", + "required": true, + "schema": { + "type": "string", + "const": "agents=v1" + } + } + ], + "responses": { + "200": { + "description": "The immutable artifact contents.", + "content": { + "application/octet-stream": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "400": { + "description": "The request was invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "401": { + "description": "Authentication or project context was missing.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "403": { + "description": "The API key lacks the required Responses permission.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "404": { + "description": "The requested session or event was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "409": { + "description": "The request conflicted with the current session state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "500": { + "description": "An internal error occurred.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "503": { + "description": "The service is temporarily unavailable.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Retrieve agent session artifact content" + } + } + }, + "/agents/sessions/{session_id}/events": { + "get": { + "operationId": "listAgentSessionEvents", + "summary": "Streams live events for an agent session. See [session events](https://developers.openai.com/api/docs/guides/agents-api/sessions/events).", + "description": "Streams live events for an agent session.", + "tags": [ + "Agents" + ], + "parameters": [ + { + "name": "session_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The ID of the session." + }, + { + "name": "OpenAI-Beta", + "in": "header", + "required": true, + "schema": { + "type": "string", + "const": "agents=v1" + } + } + ], + "responses": { + "200": { + "description": "A live stream of session events.", + "content": { + "text/event-stream": { + "schema": { + "$ref": "#/components/schemas/SessionEvent" + } + } + } + }, + "400": { + "description": "The request was invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "401": { + "description": "Authentication or project context was missing.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "403": { + "description": "The API key lacks the required Responses permission.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "404": { + "description": "The requested session or event was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "409": { + "description": "The request conflicted with the current session state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "500": { + "description": "An internal error occurred.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "503": { + "description": "The service is temporarily unavailable.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + } + }, + "x-oai-streaming": { + "request_field": null, + "response_status_code": 200 + }, + "x-oaiMeta": { + "name": "Stream agent session events" + } + }, + "post": { + "operationId": "createAgentSessionEvents", + "summary": "Submits message, cancellation, or tool-result events to a managed agent session. See [session events](https://developers.openai.com/api/docs/guides/agents-api/sessions/events).", + "description": "Submits message, cancellation, or tool-result events to a managed agent session.", + "tags": [ + "Agents" + ], + "parameters": [ + { + "name": "session_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The ID of the session." + }, + { + "name": "Idempotency-Key", + "in": "header", + "required": false, + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 256 + }, + "description": "An optional client-generated key that makes retries of submitted messages idempotent." + }, + { + "name": "OpenAI-Beta", + "in": "header", + "required": true, + "schema": { + "type": "string", + "const": "agents=v1" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateSessionEventsParams" + } + } + } + }, + "responses": { + "202": { + "description": "The events were accepted." + }, + "400": { + "description": "The request was invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "401": { + "description": "Authentication or project context was missing.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "403": { + "description": "The API key lacks the required Responses permission.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "404": { + "description": "The requested session or event was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "409": { + "description": "The request conflicted with the current session state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "500": { + "description": "An internal error occurred.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "503": { + "description": "The service is temporarily unavailable.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Create agent session input events" + } + } + }, + "/agents/sessions/{session_id}/items": { + "get": { + "operationId": "listAgentSessionItems", + "summary": "Lists items produced by the session's root agent, including its interactions with subagents. Each subagent has its own item history. See [inspecting agent output](https://developers.openai.com/api/docs/guides/agents-api/observability).", + "description": "Lists items produced by the session's root agent, including its interactions with subagents. Each subagent has its own item history.", + "tags": [ + "Agents" + ], + "parameters": [ + { + "name": "session_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The ID of the session." + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 100, + "default": 20 + }, + "description": "The maximum number of resources to return, between 1 and 100. Defaults to 20." + }, + { + "name": "order", + "in": "query", + "required": false, + "schema": { + "$ref": "#/components/schemas/ListOrderParam", + "default": "desc" + }, + "description": "The order in which resources are returned. Defaults to `desc`." + }, + { + "name": "after", + "in": "query", + "required": false, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "Return resources after this resource ID in the selected order." + }, + { + "name": "OpenAI-Beta", + "in": "header", + "required": true, + "schema": { + "type": "string", + "const": "agents=v1" + } + } + ], + "responses": { + "200": { + "description": "A page of session items.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SessionItemListResource" + } + } + } + }, + "400": { + "description": "The request was invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "401": { + "description": "Authentication or project context was missing.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "403": { + "description": "The API key lacks the required Responses permission.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "404": { + "description": "The requested session or event was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "409": { + "description": "The request conflicted with the current session state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "500": { + "description": "An internal error occurred.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "503": { + "description": "The service is temporarily unavailable.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + } + }, + "x-oaiMeta": { + "name": "List agent session items" + } + } + }, + "/agents/sessions/{session_id}/turns": { + "get": { + "operationId": "listAgentSessionTurns", + "summary": "Lists turns by creation time and turn ID. The after cursor is exclusive in the selected order. See [session turns](https://developers.openai.com/api/docs/guides/agents-api/sessions/manage#inspect-session-turns).", + "description": "Lists turns by creation time and turn ID. The after cursor is exclusive in the selected order.", + "tags": [ + "Agents" + ], + "parameters": [ + { + "name": "session_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The ID of the session." + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 100, + "default": 20 + }, + "description": "The maximum number of resources to return, between 1 and 100. Defaults to 20." + }, + { + "name": "order", + "in": "query", + "required": false, + "schema": { + "$ref": "#/components/schemas/ListOrderParam", + "default": "desc" + }, + "description": "The order in which resources are returned. Defaults to `desc`." + }, + { + "name": "after", + "in": "query", + "required": false, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "Return resources after this resource ID in the selected order." + }, + { + "name": "OpenAI-Beta", + "in": "header", + "required": true, + "schema": { + "type": "string", + "const": "agents=v1" + } + } + ], + "responses": { + "200": { + "description": "A page of session turns.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SessionTurnListResource", + "description": "A page of turns from an agent session or subagent." + } + } + } + }, + "400": { + "description": "The request was invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "401": { + "description": "Authentication or project context was missing.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "404": { + "description": "The requested session or event was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "409": { + "description": "The request conflicted with the current session state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "500": { + "description": "An internal error occurred.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "503": { + "description": "The service is temporarily unavailable.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + } + }, + "x-oaiMeta": { + "name": "List agent session turns" + } + } + }, + "/agents/sessions/{session_id}/turns/{turn_id}": { + "get": { + "operationId": "retrieveAgentSessionTurn", + "summary": "Retrieves a turn's current status, timestamps, usage, and error. Returns 404 if the turn does not belong to the session. See [session turns](https://developers.openai.com/api/docs/guides/agents-api/sessions/manage#inspect-session-turns).", + "description": "Retrieves a turn's current status, timestamps, usage, and error. Returns 404 if the turn does not belong to the session.", + "tags": [ + "Agents" + ], + "parameters": [ + { + "name": "session_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The ID of the session that owns the turn." + }, + { + "name": "turn_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The ID of the turn." + }, + { + "name": "OpenAI-Beta", + "in": "header", + "required": true, + "schema": { + "type": "string", + "const": "agents=v1" + } + } + ], + "responses": { + "200": { + "description": "The requested turn.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TurnResource" + } + } + } + }, + "400": { + "description": "The request was invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "401": { + "description": "Authentication or project context was missing.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "404": { + "description": "The requested session or event was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "409": { + "description": "The request conflicted with the current session state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "500": { + "description": "An internal error occurred.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "503": { + "description": "The service is temporarily unavailable.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Retrieve an agent session turn" + } + } + }, + "/vaults": { + "get": { + "operationId": "listVaults", + "summary": "Lists vaults using ID-based pagination. See [vaults](https://developers.openai.com/api/docs/guides/agents-api/tools/vaults).", + "description": "Lists vaults using ID-based pagination.", + "tags": [ + "Vaults" + ], + "parameters": [ + { + "name": "order", + "in": "query", + "required": false, + "schema": { + "$ref": "#/components/schemas/ListOrderParam", + "default": "desc" + }, + "description": "Sort order by the `created_at` timestamp. Use `asc` for ascending order or `desc` for descending order. Defaults to `desc`." + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": [ + "integer", + "null" + ], + "format": "int64", + "minimum": 0 + }, + "description": "The maximum number of resources to return. Defaults to 20. Values are clamped between 1 and 100." + }, + { + "name": "status", + "in": "query", + "required": false, + "schema": { + "$ref": "#/components/schemas/VaultStatusFilterParam" + }, + "description": "Filter by one status or a list, such as `status=active` or `status[]=active&status[]=archived`. Both statuses are included by default." + }, + { + "name": "after", + "in": "query", + "required": false, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "Return resources after this resource ID in the selected order." + }, + { + "name": "OpenAI-Beta", + "in": "header", + "required": true, + "schema": { + "type": "string", + "const": "agents=v1" + } + } + ], + "responses": { + "200": { + "description": "A page of vaults.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/VaultListResource", + "description": "A page of vaults." + } + } + } + }, + "400": { + "description": "The request was invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "401": { + "description": "Authentication or project context was missing.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "403": { + "description": "The API key lacks the required management permission.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "404": { + "description": "The requested vault or credential was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "409": { + "description": "The request conflicted with the current vault state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "500": { + "description": "An internal error occurred.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "503": { + "description": "The service is temporarily unavailable.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + } + }, + "x-oaiMeta": { + "name": "List vaults" + } + }, + "post": { + "operationId": "createVault", + "summary": "Creates a vault for the current project. See [vaults](https://developers.openai.com/api/docs/guides/agents-api/tools/vaults).", + "description": "Creates a vault for the current project.", + "tags": [ + "Vaults" + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateVaultParams" + } + } + } + }, + "responses": { + "201": { + "description": "The created vault.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/VaultResource" + } + } + } + }, + "400": { + "description": "The request was invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "401": { + "description": "Authentication or project context was missing.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "403": { + "description": "The API key lacks the required management permission.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "404": { + "description": "The requested vault or credential was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "409": { + "description": "The request conflicted with the current vault state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "500": { + "description": "An internal error occurred.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "503": { + "description": "The service is temporarily unavailable.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Create a vault" + }, + "parameters": [ + { + "name": "OpenAI-Beta", + "in": "header", + "required": true, + "schema": { + "type": "string", + "const": "agents=v1" + } + } + ] + } + }, + "/vaults/{vault_id}": { + "get": { + "operationId": "retrieveVault", + "summary": "Retrieves a vault by its ID. See [vaults](https://developers.openai.com/api/docs/guides/agents-api/tools/vaults).", + "description": "Retrieves a vault by its ID.", + "tags": [ + "Vaults" + ], + "parameters": [ + { + "name": "vault_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The ID of the vault." + }, + { + "name": "OpenAI-Beta", + "in": "header", + "required": true, + "schema": { + "type": "string", + "const": "agents=v1" + } + } + ], + "responses": { + "200": { + "description": "The requested vault.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/VaultResource" + } + } + } + }, + "400": { + "description": "The request was invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "401": { + "description": "Authentication or project context was missing.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "403": { + "description": "The API key lacks the required management permission.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "404": { + "description": "The requested vault or credential was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "409": { + "description": "The request conflicted with the current vault state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "500": { + "description": "An internal error occurred.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "503": { + "description": "The service is temporarily unavailable.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Retrieve a vault" + } + }, + "delete": { + "operationId": "deleteVault", + "summary": "Deletes a vault and all its credentials. See [vaults](https://developers.openai.com/api/docs/guides/agents-api/tools/vaults).", + "description": "Deletes a vault and all its credentials.", + "tags": [ + "Vaults" + ], + "parameters": [ + { + "name": "vault_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The ID of the vault." + }, + { + "name": "OpenAI-Beta", + "in": "header", + "required": true, + "schema": { + "type": "string", + "const": "agents=v1" + } + } + ], + "responses": { + "200": { + "description": "The deleted vault.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeletedVaultResource" + } + } + } + }, + "400": { + "description": "The request was invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "401": { + "description": "Authentication or project context was missing.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "403": { + "description": "The API key lacks the required management permission.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "404": { + "description": "The requested vault or credential was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "409": { + "description": "The request conflicted with the current vault state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "500": { + "description": "An internal error occurred.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "503": { + "description": "The service is temporarily unavailable.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Delete a vault" + } + } + }, + "/vaults/{vault_id}/credentials": { + "get": { + "operationId": "listVaultCredentials", + "summary": "Lists a vault's credentials using ID-based pagination without returning secret values. See [vaults](https://developers.openai.com/api/docs/guides/agents-api/tools/vaults).", + "description": "Lists a vault's credentials using ID-based pagination without returning secret values.", + "tags": [ + "Vaults" + ], + "parameters": [ + { + "name": "vault_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The ID of the vault." + }, + { + "name": "order", + "in": "query", + "required": false, + "schema": { + "$ref": "#/components/schemas/ListOrderParam", + "default": "desc" + }, + "description": "Sort order by the `created_at` timestamp. Use `asc` for ascending order or `desc` for descending order. Defaults to `desc`." + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": [ + "integer", + "null" + ], + "format": "int64", + "minimum": 0 + }, + "description": "The maximum number of resources to return. Defaults to 20. Values are clamped between 1 and 100." + }, + { + "name": "status", + "in": "query", + "required": false, + "schema": { + "$ref": "#/components/schemas/VaultStatusFilterParam" + }, + "description": "Filter by one status or a list, such as `status=active` or `status[]=active&status[]=archived`. Both statuses are included by default." + }, + { + "name": "after", + "in": "query", + "required": false, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "Return resources after this resource ID in the selected order." + }, + { + "name": "OpenAI-Beta", + "in": "header", + "required": true, + "schema": { + "type": "string", + "const": "agents=v1" + } + } + ], + "responses": { + "200": { + "description": "A page of vault credentials.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/VaultCredentialListResource", + "description": "A page of credentials in a vault." + } + } + } + }, + "400": { + "description": "The request was invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "401": { + "description": "Authentication or project context was missing.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "403": { + "description": "The API key lacks the required management permission.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "404": { + "description": "The requested vault or credential was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "409": { + "description": "The request conflicted with the current vault state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "500": { + "description": "An internal error occurred.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "503": { + "description": "The service is temporarily unavailable.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + } + }, + "x-oaiMeta": { + "name": "List vault credentials" + } + }, + "post": { + "operationId": "createVaultCredential", + "summary": "Creates a vault credential. Secret values are write-only and are never returned. See [vaults](https://developers.openai.com/api/docs/guides/agents-api/tools/vaults).", + "description": "Creates a vault credential. Secret values are write-only and are never returned.", + "tags": [ + "Vaults" + ], + "parameters": [ + { + "name": "vault_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The ID of the vault." + }, + { + "name": "OpenAI-Beta", + "in": "header", + "required": true, + "schema": { + "type": "string", + "const": "agents=v1" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateVaultCredentialParams" + } + } + } + }, + "responses": { + "201": { + "description": "The created vault credential without secret values.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/VaultCredentialResource" + } + } + } + }, + "400": { + "description": "The request was invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "401": { + "description": "Authentication or project context was missing.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "403": { + "description": "The API key lacks the required management permission.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "404": { + "description": "The requested vault or credential was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "409": { + "description": "The request conflicted with the current vault state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "500": { + "description": "An internal error occurred.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "503": { + "description": "The service is temporarily unavailable.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Create a vault credential" + } + } + }, + "/vaults/{vault_id}/credentials/{credential_id}": { + "get": { + "operationId": "retrieveVaultCredential", + "summary": "Retrieves vault credential metadata without returning secret values. See [vaults](https://developers.openai.com/api/docs/guides/agents-api/tools/vaults).", + "description": "Retrieves vault credential metadata without returning secret values.", + "tags": [ + "Vaults" + ], + "parameters": [ + { + "name": "vault_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The ID of the vault." + }, + { + "name": "credential_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The ID of the vault credential." + }, + { + "name": "OpenAI-Beta", + "in": "header", + "required": true, + "schema": { + "type": "string", + "const": "agents=v1" + } + } + ], + "responses": { + "200": { + "description": "The requested vault credential without secret values.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/VaultCredentialResource" + } + } + } + }, + "400": { + "description": "The request was invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "401": { + "description": "Authentication or project context was missing.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "403": { + "description": "The API key lacks the required management permission.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "404": { + "description": "The requested vault or credential was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "409": { + "description": "The request conflicted with the current vault state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "500": { + "description": "An internal error occurred.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "503": { + "description": "The service is temporarily unavailable.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Retrieve a vault credential" + } + }, + "post": { + "operationId": "rotateVaultCredential", + "summary": "Rotates a vault credential's write-only secret and returns only credential metadata. See [vaults](https://developers.openai.com/api/docs/guides/agents-api/tools/vaults).", + "description": "Rotates a vault credential's write-only secret and returns only credential metadata.", + "tags": [ + "Vaults" + ], + "parameters": [ + { + "name": "vault_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The ID of the vault." + }, + { + "name": "credential_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The ID of the vault credential." + }, + { + "name": "OpenAI-Beta", + "in": "header", + "required": true, + "schema": { + "type": "string", + "const": "agents=v1" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RotateVaultCredentialParams" + } + } + } + }, + "responses": { + "200": { + "description": "The rotated vault credential without secret values.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/VaultCredentialResource" + } + } + } + }, + "400": { + "description": "The request was invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "401": { + "description": "Authentication or project context was missing.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "403": { + "description": "The API key lacks the required management permission.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "404": { + "description": "The requested vault or credential was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "409": { + "description": "The request conflicted with the current vault state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "500": { + "description": "An internal error occurred.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "503": { + "description": "The service is temporarily unavailable.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Rotate a vault credential" + } + }, + "delete": { + "operationId": "deleteVaultCredential", + "summary": "Deletes a vault credential. See [vaults](https://developers.openai.com/api/docs/guides/agents-api/tools/vaults).", + "description": "Deletes a vault credential.", + "tags": [ + "Vaults" + ], + "parameters": [ + { + "name": "vault_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The ID of the vault." + }, + { + "name": "credential_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "description": "The ID of the vault credential." + }, + { + "name": "OpenAI-Beta", + "in": "header", + "required": true, + "schema": { + "type": "string", + "const": "agents=v1" + } + } + ], + "responses": { + "200": { + "description": "The deleted vault credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeletedVaultCredentialResource" + } + } + } + }, + "400": { + "description": "The request was invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "401": { + "description": "Authentication or project context was missing.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "403": { + "description": "The API key lacks the required management permission.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "404": { + "description": "The requested vault or credential was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "409": { + "description": "The request conflicted with the current vault state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "500": { + "description": "An internal error occurred.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + }, + "503": { + "description": "The service is temporarily unavailable.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse-2" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Delete a vault credential" + } + } + } + }, + "webhooks": { + "batch_cancelled": { + "post": { + "description": "Sent when a batch has been cancelled.\n", + "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.\n", + "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.\n", + "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.\n", + "requestBody": { + "description": "The event payload sent by the API.", + "content": { + "application/json": { + "schema": { + "$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" + } + } + } + }, + "eval_run_canceled": { + "post": { + "description": "Sent when an eval run has been canceled.\n", + "requestBody": { + "description": "The event payload sent by the API.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebhookEvalRunCanceled" + } + } + } + }, + "responses": { + "200": { + "description": "Return a 200 status code to acknowledge receipt of the event. Non-200 \nstatus codes will be retried. \n" + } + } + } + }, + "eval_run_failed": { + "post": { + "description": "Sent when an eval run has failed.\n", + "requestBody": { + "description": "The event payload sent by the API.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebhookEvalRunFailed" + } + } + } + }, + "responses": { + "200": { + "description": "Return a 200 status code to acknowledge receipt of the event. Non-200 \nstatus codes will be retried. \n" + } + } + } + }, + "eval_run_succeeded": { + "post": { + "description": "Sent when an eval run has succeeded.\n", + "requestBody": { + "description": "The event payload sent by the API.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebhookEvalRunSucceeded" + } + } + } + }, + "responses": { + "200": { + "description": "Return a 200 status code to acknowledge receipt of the event. Non-200 \nstatus codes will be retried. \n" + } + } + } + }, + "fine_tuning_job_cancelled": { + "post": { + "description": "Sent when a fine-tuning job has been cancelled.\n", + "requestBody": { + "description": "The event payload sent by the API.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebhookFineTuningJobCancelled" + } + } + } + }, + "responses": { + "200": { + "description": "Return a 200 status code to acknowledge receipt of the event. Non-200 \nstatus codes will be retried. \n" + } + } + } + }, + "fine_tuning_job_failed": { + "post": { + "description": "Sent when a fine-tuning job has failed.\n", + "requestBody": { + "description": "The event payload sent by the API.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebhookFineTuningJobFailed" + } + } + } + }, + "responses": { + "200": { + "description": "Return a 200 status code to acknowledge receipt of the event. Non-200 \nstatus codes will be retried. \n" + } + } + } + }, + "fine_tuning_job_succeeded": { + "post": { + "description": "Sent when a fine-tuning job has succeeded.\n", + "requestBody": { + "description": "The event payload sent by the API.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebhookFineTuningJobSucceeded" + } + } + } + }, + "responses": { + "200": { + "description": "Return a 200 status code to acknowledge receipt of the event. Non-200 \nstatus codes will be retried. \n" + } + } + } + }, + "live_call_incoming": { + "post": { + "deprecated": true, + "description": "Deprecated: use `live.transport.incoming`. Retained only for existing subscriptions.\nSent when an incoming API SIP session is available for Live acceptance.\n", + "requestBody": { + "description": "The event payload sent by the API.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebhookLiveCallIncoming" + } + } + } + }, + "responses": { + "200": { + "description": "Return a 200 status code to acknowledge receipt of the event. Non-200\nstatus codes will be retried.\n" + } + } + } + }, + "live_transport_incoming": { + "post": { + "description": "Sent when an incoming API SIP session is available for Live acceptance.\n", + "requestBody": { + "description": "The event payload sent by the API.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebhookLiveTransportIncoming" + } + } + } + }, + "responses": { + "200": { + "description": "Return a 200 status code to acknowledge receipt of the event. Non-200\nstatus codes will be retried.\n" + } + } + } + }, + "realtime_call_incoming": { + "post": { + "description": "Sent when an incoming API SIP session is available for Realtime acceptance.\n", + "requestBody": { + "description": "The event payload sent by the API.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebhookRealtimeCallIncoming" + } + } + } + }, + "responses": { + "200": { + "description": "Return a 200 status code to acknowledge receipt of the event. Non-200\nstatus codes will be retried.\n" + } + } + } + }, + "response_cancelled": { + "post": { + "description": "Sent when a background response has been cancelled.\n", + "requestBody": { + "description": "The event payload sent by the API.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebhookResponseCancelled" + } + } + } + }, + "responses": { + "200": { + "description": "Return a 200 status code to acknowledge receipt of the event. Non-200 \nstatus codes will be retried.\n" + } + } + } + }, + "response_completed": { + "post": { + "description": "Sent when a background response has completed successfully.\n", + "requestBody": { + "description": "The event payload sent by the API.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebhookResponseCompleted" + } + } + } + }, + "responses": { + "200": { + "description": "Return a 200 status code to acknowledge receipt of the event. Non-200 \nstatus codes will be retried. \n" + } + } + } + }, + "response_failed": { + "post": { + "description": "Sent when a background response has failed.\n", + "requestBody": { + "description": "The event payload sent by the API.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebhookResponseFailed" + } + } + } + }, + "responses": { + "200": { + "description": "Return a 200 status code to acknowledge receipt of the event. Non-200 \nstatus codes will be retried.\n" + } + } + } + }, + "response_incomplete": { + "post": { + "description": "Sent when a background response is incomplete.\n", + "requestBody": { + "description": "The event payload sent by the API.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebhookResponseIncomplete" + } + } + } + }, + "responses": { + "200": { + "description": "Return a 200 status code to acknowledge receipt of the event. Non-200 \nstatus codes will be retried.\n" + } + } + } + }, + "safety_alert_created": { + "post": { + "description": "Sent when an approved safety alert is available for an API project.\nRetrieve the alert with a project API key granted `api.safety.alerts.read`.\n", + "requestBody": { + "description": "The event payload sent by the API.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebhookSafetyAlertCreated" + } + } + } + }, + "responses": { + "200": { + "description": "Return any 2xx status code to acknowledge receipt. A 410 Gone response also stops retries; other non-2xx responses are retried." + } + } + } + }, + "safety_org_alert_created": { + "post": { + "description": "Sent when an approved safety alert is available for an enterprise workspace.\nRetrieve the alert from `https://api.chatgpt.com/v1/safety/alerts/{id}` with\nan administrator API key for the workspace's backing organization granted\n`chatgpt.enterprise.safety_alerts.read`.\n", + "requestBody": { + "description": "The event payload sent by the API.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebhookSafetyOrgAlertCreated" + } + } + } + }, + "responses": { + "200": { + "description": "Return any 2xx status code to acknowledge receipt. A 410 Gone response also stops retries; other non-2xx responses are retried." + } + } + } + } + }, + "components": { + "schemas": { + "CreateFileRequest": { + "type": "object", + "additionalProperties": false, + "properties": { + "file": { + "description": "The File object (not file name) to be uploaded.\n", + "type": "string", + "format": "binary" + }, + "purpose": { + "description": "The intended purpose of the uploaded file. One of:\n- `assistants`: Used in the Assistants API\n- `batch`: Used in the Batch API\n- `fine-tune`: Used for fine-tuning\n- `vision`: Images used for vision fine-tuning\n- `user_data`: Flexible file type for any purpose\n- `evals`: Used for eval data sets\n", + "type": "string", + "enum": [ + "assistants", + "batch", + "fine-tune", + "vision", + "user_data", + "evals" + ] + }, + "expires_after": { + "$ref": "#/components/schemas/FileExpirationAfter" + } + }, + "required": [ + "file", + "purpose" + ] + }, + "DeleteFileResponse": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "object": { + "type": "string", + "enum": [ + "file" + ], + "x-stainless-const": true + }, + "deleted": { + "type": "boolean" + } + }, + "required": [ + "id", + "object", + "deleted" + ] + }, + "Error": { + "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/MisalignmentErrorDetailsResource" + } + }, + "required": [ + "type", + "message", + "param", + "code" + ] + }, + "ErrorResponse": { + "type": "object", + "properties": { + "error": { + "$ref": "#/components/schemas/Error" + } + }, + "required": [ + "error" + ] + }, + "FileExpirationAfter": { + "type": "object", + "title": "File expiration policy", + "description": "The expiration policy for a file. By default, files with `purpose=batch` expire after 30 days and all other files are persisted until they are manually deleted.", + "properties": { + "anchor": { + "description": "Anchor timestamp after which the expiration policy applies. Supported anchors: `created_at`.", + "type": "string", + "enum": [ + "created_at" + ], + "x-stainless-const": true + }, + "seconds": { + "description": "The number of seconds after the anchor time that the file will expire. Must be between 3600 (1 hour) and 2592000 (30 days).", + "type": "integer", + "format": "int64", + "minimum": 3600, + "maximum": 2592000 + } + }, + "required": [ + "anchor", + "seconds" + ] + }, + "ListFilesResponse": { + "type": "object", + "properties": { + "object": { + "type": "string", + "example": "list" + }, + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/OpenAIFile" + } + }, + "first_id": { + "type": "string", + "example": "file-abc123" + }, + "last_id": { + "type": "string", + "example": "file-abc456" + }, + "has_more": { + "type": "boolean", + "example": false + } + }, + "required": [ + "object", + "data", + "first_id", + "last_id", + "has_more" + ] + }, + "OpenAIFile": { + "title": "OpenAIFile", + "description": "The `File` object represents a document that has been uploaded to OpenAI.", + "properties": { + "id": { + "type": "string", + "description": "The file identifier, which can be referenced in the API endpoints." + }, + "bytes": { + "type": "integer", + "description": "The size of the file, in bytes." + }, + "created_at": { + "type": "integer", + "format": "unixtime", + "description": "The Unix timestamp (in seconds) for when the file was created." + }, + "expires_at": { + "type": "integer", + "format": "unixtime", + "description": "The Unix timestamp (in seconds) for when the file will expire." + }, + "filename": { + "type": "string", + "description": "The name of the file." + }, + "object": { + "type": "string", + "description": "The object type, which is always `file`.", + "enum": [ + "file" + ], + "x-stainless-const": true + }, + "purpose": { + "type": "string", + "description": "The intended purpose of the file. Supported values are `assistants`, `assistants_output`, `batch`, `batch_output`, `fine-tune`, `fine-tune-results`, `vision`, and `user_data`.", + "enum": [ + "assistants", + "assistants_output", + "batch", + "batch_output", + "fine-tune", + "fine-tune-results", + "vision", + "user_data" + ] + }, + "status": { + "type": "string", + "deprecated": true, + "description": "Deprecated. The current status of the file, which can be either `uploaded`, `processed`, or `error`.", + "enum": [ + "uploaded", + "processed", + "error" + ] + }, + "status_details": { + "type": "string", + "deprecated": true, + "description": "Deprecated. For details on why a fine-tuning training file failed validation, see the `error` field on `fine_tuning.job`." + } + }, + "required": [ + "id", + "object", + "bytes", + "created_at", + "filename", + "purpose", + "status" + ], + "x-oaiMeta": { + "name": "The file object", + "example": "{\n \"id\": \"file-abc123\",\n \"object\": \"file\",\n \"bytes\": 120000,\n \"created_at\": 1677610602,\n \"expires_at\": 1680202602,\n \"filename\": \"salesOverview.pdf\",\n \"purpose\": \"assistants\",\n}\n" + } + }, + "_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": [] + }, + "OrderEnum": { + "type": "string", + "enum": [ + "asc", + "desc" + ] + }, + "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": { + "type": "string", + "enum": [ + "list" + ], + "description": "The type of object returned, must be `list`.", + "default": "list", + "x-stainless-const": true + }, + "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": { + "oneOf": [ + { + "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", + "required": [ + "files" + ], + "title": "Create skill request", + "description": "Uploads a skill either as a directory (multipart `files[]`) or as a single zip file." + }, + "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": { + "type": "string", + "enum": [ + "list" + ], + "description": "The type of object returned, must be `list`.", + "default": "list", + "x-stainless-const": true + }, + "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": { + "oneOf": [ + { + "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", + "required": [ + "files" + ], + "title": "Create skill version request", + "description": "Uploads a new immutable version of a skill." + }, + "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" + ] + }, + "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": { + "oneOf": [ + { + "$ref": "#/components/schemas/HostedEnvironmentFileResourceFileId" + }, + { + "$ref": "#/components/schemas/HostedEnvironmentFileResourceInline" + } + ], + "discriminator": { + "propertyName": "type", + "mapping": { + "file_id": "#/components/schemas/HostedEnvironmentFileResourceFileId", + "inline": "#/components/schemas/HostedEnvironmentFileResourceInline" + } + }, + "x-oai-discriminator-values": [ + "file_id", + "inline" + ], + "description": "Metadata for a file materialized in an OpenAI-hosted execution environment." + }, + "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": { + "oneOf": [ + { + "$ref": "#/components/schemas/HostedSkillResourceSkillReference" + }, + { + "$ref": "#/components/schemas/HostedSkillResourceInline" + } + ], + "discriminator": { + "propertyName": "type", + "mapping": { + "skill_reference": "#/components/schemas/HostedSkillResourceSkillReference", + "inline": "#/components/schemas/HostedSkillResourceInline" + } + }, + "x-oai-discriminator-values": [ + "skill_reference", + "inline" + ], + "description": "A skill installed in an OpenAI-hosted environment." + }, + "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": { + "oneOf": [ + { + "$ref": "#/components/schemas/HostedPluginResourceInline" + } + ], + "discriminator": { + "propertyName": "type", + "mapping": { + "inline": "#/components/schemas/HostedPluginResourceInline" + } + }, + "x-oai-discriminator-values": [ + "inline" + ], + "description": "A plugin installed in an OpenAI-hosted environment." + }, + "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": { + "oneOf": [ + { + "$ref": "#/components/schemas/HostedEnvironmentFileParamFileId" + }, + { + "$ref": "#/components/schemas/HostedEnvironmentFileParamInline" + } + ], + "discriminator": { + "propertyName": "type", + "mapping": { + "file_id": "#/components/schemas/HostedEnvironmentFileParamFileId", + "inline": "#/components/schemas/HostedEnvironmentFileParamInline" + } + }, + "x-oai-discriminator-values": [ + "file_id", + "inline" + ], + "description": "A file materialized in an OpenAI-hosted execution environment." + }, + "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": { + "oneOf": [ + { + "$ref": "#/components/schemas/OutputTextResource" + }, + { + "$ref": "#/components/schemas/EncryptedContentResource" + } + ], + "discriminator": { + "propertyName": "type", + "mapping": { + "output_text": "#/components/schemas/OutputTextResource", + "encrypted_content": "#/components/schemas/EncryptedContentResource" + } + }, + "x-oai-discriminator-values": [ + "output_text", + "encrypted_content" + ], + "description": "A plaintext or encrypted content part exchanged between agents." + }, + "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": { + "oneOf": [ + { + "$ref": "#/components/schemas/MessageContentResourceInputText" + }, + { + "$ref": "#/components/schemas/MessageContentResourceInputImage" + }, + { + "$ref": "#/components/schemas/MessageContentResourceOutputText" + } + ], + "discriminator": { + "propertyName": "type", + "mapping": { + "input_text": "#/components/schemas/MessageContentResourceInputText", + "input_image": "#/components/schemas/MessageContentResourceInputImage", + "output_text": "#/components/schemas/MessageContentResourceOutputText" + } + }, + "x-oai-discriminator-values": [ + "input_text", + "input_image", + "output_text" + ], + "description": "A content part in a session message." + }, + "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": { + "oneOf": [ + { + "$ref": "#/components/schemas/InputContentResourceInputText" + }, + { + "$ref": "#/components/schemas/InputContentResourceInputImage" + } + ], + "discriminator": { + "propertyName": "type", + "mapping": { + "input_text": "#/components/schemas/InputContentResourceInputText", + "input_image": "#/components/schemas/InputContentResourceInputImage" + } + }, + "x-oai-discriminator-values": [ + "input_text", + "input_image" + ], + "description": "User-provided content recorded in a session item." + }, + "FunctionCallOutputResource": { + "oneOf": [ + { + "type": "string", + "minLength": 0 + }, + { + "type": "array", + "items": { + "$ref": "#/components/schemas/InputContentResource" + }, + "minItems": 0, + "maxItems": 2000 + } + ], + "description": "The text or model-input content supplied as a function result." + }, + "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": { + "oneOf": [ + { + "$ref": "#/components/schemas/WebSearchActionResourceSearch" + }, + { + "$ref": "#/components/schemas/WebSearchActionResourceOpenPage" + }, + { + "$ref": "#/components/schemas/WebSearchActionResourceFindInPage" + }, + { + "$ref": "#/components/schemas/WebSearchActionResourceOther" + } + ], + "discriminator": { + "propertyName": "type", + "mapping": { + "search": "#/components/schemas/WebSearchActionResourceSearch", + "open_page": "#/components/schemas/WebSearchActionResourceOpenPage", + "find_in_page": "#/components/schemas/WebSearchActionResourceFindInPage", + "other": "#/components/schemas/WebSearchActionResourceOther" + } + }, + "x-oai-discriminator-values": [ + "search", + "open_page", + "find_in_page", + "other" + ], + "description": "An action performed by the web search tool." + }, + "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": { + "oneOf": [ + { + "$ref": "#/components/schemas/MessageItemResource" + }, + { + "$ref": "#/components/schemas/ReasoningItemResource" + }, + { + "$ref": "#/components/schemas/FunctionCallItemResource" + }, + { + "$ref": "#/components/schemas/FunctionCallOutputItemResource" + }, + { + "$ref": "#/components/schemas/AgentMessageItemResource" + }, + { + "$ref": "#/components/schemas/McpCallItemResource" + }, + { + "$ref": "#/components/schemas/WebSearchCallItemResource" + }, + { + "$ref": "#/components/schemas/CommandExecutionItemResource" + }, + { + "$ref": "#/components/schemas/CreateSubagentCallItemResource" + }, + { + "$ref": "#/components/schemas/SendSubagentInputCallItemResource" + }, + { + "$ref": "#/components/schemas/ResumeSubagentCallItemResource" + }, + { + "$ref": "#/components/schemas/WaitForSubagentsCallItemResource" + }, + { + "$ref": "#/components/schemas/InterruptSubagentCallItemResource" + }, + { + "$ref": "#/components/schemas/CloseSubagentCallItemResource" + } + ], + "discriminator": { + "propertyName": "type", + "mapping": { + "message": "#/components/schemas/MessageItemResource", + "reasoning": "#/components/schemas/ReasoningItemResource", + "function_call": "#/components/schemas/FunctionCallItemResource", + "function_call_output": "#/components/schemas/FunctionCallOutputItemResource", + "agent_message": "#/components/schemas/AgentMessageItemResource", + "mcp_call": "#/components/schemas/McpCallItemResource", + "web_search_call": "#/components/schemas/WebSearchCallItemResource", + "command_execution": "#/components/schemas/CommandExecutionItemResource", + "interrupt_subagent_call": "#/components/schemas/InterruptSubagentCallItemResource", + "create_subagent_call": "#/components/schemas/CreateSubagentCallItemResource", + "send_subagent_input_call": "#/components/schemas/SendSubagentInputCallItemResource", + "resume_subagent_call": "#/components/schemas/ResumeSubagentCallItemResource", + "wait_for_subagents_call": "#/components/schemas/WaitForSubagentsCallItemResource", + "close_subagent_call": "#/components/schemas/CloseSubagentCallItemResource" + } + }, + "x-oai-discriminator-values": [ + "message", + "reasoning", + "function_call", + "function_call_output", + "agent_message", + "mcp_call", + "web_search_call", + "command_execution", + "create_subagent_call", + "send_subagent_input_call", + "resume_subagent_call", + "wait_for_subagents_call", + "interrupt_subagent_call", + "close_subagent_call" + ], + "description": "An item associated with a session turn." + }, + "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", + "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 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": { + "oneOf": [ + { + "$ref": "#/components/schemas/TextFormatResourceText" + }, + { + "$ref": "#/components/schemas/TextFormatResourceJsonSchema" + } + ], + "discriminator": { + "propertyName": "type", + "mapping": { + "text": "#/components/schemas/TextFormatResourceText", + "json_schema": "#/components/schemas/TextFormatResourceJsonSchema" + } + }, + "x-oai-discriminator-values": [ + "text", + "json_schema" + ], + "description": "The effective output format for generated text." + }, + "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": { + "oneOf": [ + { + "$ref": "#/components/schemas/PersistedMcpTransportResourceHttp" + }, + { + "$ref": "#/components/schemas/PersistedMcpTransportResourceStdio" + } + ], + "discriminator": { + "propertyName": "type", + "mapping": { + "http": "#/components/schemas/PersistedMcpTransportResourceHttp", + "stdio": "#/components/schemas/PersistedMcpTransportResourceStdio" + } + }, + "x-oai-discriminator-values": [ + "http", + "stdio" + ], + "description": "A credential-free transport used to connect to an MCP server." + }, + "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": { + "oneOf": [ + { + "$ref": "#/components/schemas/PersistedAgentToolResourceFunction" + }, + { + "$ref": "#/components/schemas/PersistedAgentToolResourceToolSearch" + }, + { + "$ref": "#/components/schemas/PersistedAgentToolResourceProgrammaticToolCalling" + }, + { + "$ref": "#/components/schemas/PersistedAgentToolResourceMcp" + }, + { + "$ref": "#/components/schemas/PersistedAgentToolResourceWebSearch" + } + ], + "discriminator": { + "propertyName": "type", + "mapping": { + "function": "#/components/schemas/PersistedAgentToolResourceFunction", + "tool_search": "#/components/schemas/PersistedAgentToolResourceToolSearch", + "programmatic_tool_calling": "#/components/schemas/PersistedAgentToolResourceProgrammaticToolCalling", + "mcp": "#/components/schemas/PersistedAgentToolResourceMcp", + "web_search": "#/components/schemas/PersistedAgentToolResourceWebSearch" + } + }, + "x-oai-discriminator-values": [ + "function", + "tool_search", + "programmatic_tool_calling", + "mcp", + "web_search" + ], + "description": "A credential-free tool available to a reusable agent." + }, + "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." + }, + "x_agents_core": { + "anyOf": [ + { + "$ref": "#/components/schemas/v1.SavedAgentCore" + }, + { + "type": "null" + } + ] + } + }, + "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": { + "oneOf": [ + { + "$ref": "#/components/schemas/TextFormatParamText" + }, + { + "$ref": "#/components/schemas/TextFormatParamJsonSchema" + } + ], + "discriminator": { + "propertyName": "type", + "mapping": { + "text": "#/components/schemas/TextFormatParamText", + "json_schema": "#/components/schemas/TextFormatParamJsonSchema" + } + }, + "x-oai-discriminator-values": [ + "text", + "json_schema" + ], + "description": "The output format for generated text." + }, + "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", + "properties": { + "type": { + "type": "string", + "enum": [ + "programmatic_tool_calling" + ], + "default": "programmatic_tool_calling", + "x-stainless-const": true, + "description": "The type of the object. Always `programmatic_tool_calling`." + }, + "enabled": { + "type": "boolean", + "default": true, + "description": "Whether tools can be called from model-generated code. Defaults to `true`." + } + }, + "required": [ + "type" + ], + "additionalProperties": false, + "description": "Enables calling tools from model-generated code." + }, + "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", + "properties": { + "type": { + "type": "string", + "enum": [ + "stdio" + ], + "default": "stdio", + "x-stainless-const": true, + "description": "The type of the object. Always `stdio`." + }, + "command": { + "type": "string", + "minLength": 0, + "maxLength": 1048576, + "description": "The command used to start the MCP server." + }, + "args": { + "type": [ + "array", + "null" + ], + "items": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "minItems": 0, + "maxItems": 16384, + "description": "Arguments passed to the MCP server command." + }, + "cwd": { + "type": "string", + "minLength": 0, + "maxLength": 1048576, + "description": "The working directory used to start the MCP server." + }, + "env_vars": { + "type": [ + "array", + "null" + ], + "items": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "minItems": 0, + "maxItems": 16384, + "description": "Environment variable names to inherit from the selected execution environment." + } + }, + "required": [ + "type", + "command", + "cwd" + ], + "additionalProperties": false, + "description": "Starts an MCP server as a local process." + }, + "PersistedMcpTransportConfigParam": { + "oneOf": [ + { + "$ref": "#/components/schemas/PersistedMcpTransportConfigParamHttp" + }, + { + "$ref": "#/components/schemas/PersistedMcpTransportConfigParamStdio" + } + ], + "discriminator": { + "propertyName": "type", + "mapping": { + "http": "#/components/schemas/PersistedMcpTransportConfigParamHttp", + "stdio": "#/components/schemas/PersistedMcpTransportConfigParamStdio" + } + }, + "x-oai-discriminator-values": [ + "http", + "stdio" + ], + "description": "A credential-free transport used to connect to an MCP server." + }, + "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", + "properties": { + "type": { + "type": "string", + "enum": [ + "web_search" + ], + "default": "web_search", + "x-stainless-const": true, + "description": "The type of the object. Always `web_search`." + }, + "mode": { + "anyOf": [ + { + "$ref": "#/components/schemas/WebSearchModeParam" + }, + { + "type": "null" + } + ], + "description": "The source used for web search results. Defaults to `live`." + }, + "context_size": { + "anyOf": [ + { + "$ref": "#/components/schemas/WebSearchContextSizeParam" + }, + { + "type": "null" + } + ], + "description": "The amount of search context made available to the model. Defaults to `medium`." + }, + "allowed_domains": { + "type": [ + "array", + "null" + ], + "items": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "minItems": 0, + "maxItems": 16384, + "description": "Domains the search may include." + }, + "location": { + "anyOf": [ + { + "$ref": "#/components/schemas/WebSearchLocationParam" + }, + { + "type": "null" + } + ], + "description": "Approximate location used to localize search results." + } + }, + "required": [ + "type" + ], + "additionalProperties": false, + "description": "Web search." + }, + "PersistedAgentToolConfigParam": { + "oneOf": [ + { + "$ref": "#/components/schemas/PersistedAgentToolConfigParamFunction" + }, + { + "$ref": "#/components/schemas/PersistedAgentToolConfigParamToolSearch" + }, + { + "$ref": "#/components/schemas/PersistedAgentToolConfigParamProgrammaticToolCalling" + }, + { + "$ref": "#/components/schemas/PersistedAgentToolConfigParamMcp" + }, + { + "$ref": "#/components/schemas/PersistedAgentToolConfigParamWebSearch" + } + ], + "discriminator": { + "propertyName": "type", + "mapping": { + "function": "#/components/schemas/PersistedAgentToolConfigParamFunction", + "tool_search": "#/components/schemas/PersistedAgentToolConfigParamToolSearch", + "programmatic_tool_calling": "#/components/schemas/PersistedAgentToolConfigParamProgrammaticToolCalling", + "mcp": "#/components/schemas/PersistedAgentToolConfigParamMcp", + "web_search": "#/components/schemas/PersistedAgentToolConfigParamWebSearch" + } + }, + "x-oai-discriminator-values": [ + "function", + "tool_search", + "programmatic_tool_calling", + "mcp", + "web_search" + ], + "description": "A tool that can be stored on a reusable agent without session credentials." + }, + "MultiAgentConfigCurrentParam": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether subagent tools are enabled." + }, + "max_concurrent_subagents": { + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 4294967295, + "description": "Maximum number of subagents that may run concurrently. Defaults to 6." + } + }, + "required": [ + "enabled" + ], + "additionalProperties": false, + "description": "Explicit configuration for creating and coordinating subagents." + }, + "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." + }, + "x_agents_core": { + "anyOf": [ + { + "$ref": "#/components/schemas/v1.SavedAgentCoreInput" + }, + { + "type": "null" + } + ] + } + }, + "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": { + "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." + }, + "x_agents_core": { + "anyOf": [ + { + "$ref": "#/components/schemas/v1.SavedAgentCoreInput" + }, + { + "type": "null" + } + ] + } + }, + "additionalProperties": false, + "description": "Fields to replace on an existing reusable agent." + }, + "DeletedAgentResource": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 0, + "description": "The ID of the deleted agent." + }, + "object": { + "type": "string", + "enum": [ + "agent.deleted" + ], + "default": "agent.deleted", + "x-stainless-const": true, + "description": "The object type. Always `agent.deleted`." + }, + "deleted": { + "type": "boolean", + "description": "Whether the agent was deleted. Always `true`." + } + }, + "required": [ + "id", + "object", + "deleted" + ], + "additionalProperties": false, + "description": "A deleted reusable agent." + }, + "EnvironmentPackagesResource": { + "type": "object", + "properties": { + "python": { + "type": "array", + "items": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "minItems": 0, + "maxItems": 16384, + "description": "Python packages installed in the environment." + }, + "system": { + "type": "array", + "items": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "minItems": 0, + "maxItems": 16384, + "description": "System packages installed in the environment." + }, + "npm": { + "type": "array", + "items": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "minItems": 0, + "maxItems": 16384, + "description": "npm packages installed globally in the environment." + } + }, + "required": [ + "python", + "system", + "npm" + ], + "additionalProperties": false, + "description": "Packages installed in an OpenAI-hosted environment." + }, + "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": { + "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", + "properties": { + "type": { + "type": "string", + "enum": [ + "skill_reference" + ], + "default": "skill_reference", + "x-stainless-const": true, + "description": "The type of the object. Always `skill_reference`." + }, + "skill_id": { + "type": "string", + "minLength": 0, + "description": "The referenced skill ID." + }, + "version": { + "type": [ + "string", + "null" + ], + "minLength": 0, + "description": "The requested version selector, including `latest`." + } + }, + "required": [ + "type", + "skill_id", + "version" + ], + "additionalProperties": false, + "description": "A skill resolved afresh from the Skills API whenever a session starts." + }, + "HostedTemplateSkillResourceInline": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "inline" + ], + "default": "inline", + "x-stainless-const": true, + "description": "The type of the object. Always `inline`." + }, + "name": { + "type": "string", + "minLength": 0, + "description": "The skill name declared in `SKILL.md`." + }, + "description": { + "type": "string", + "minLength": 0, + "description": "The skill description declared in `SKILL.md`." + } + }, + "required": [ + "type", + "name", + "description" + ], + "additionalProperties": false, + "description": "Safe metadata for an inline skill archive." + }, + "HostedTemplateSkillResource": { + "oneOf": [ + { + "$ref": "#/components/schemas/HostedTemplateSkillResourceSkillReference" + }, + { + "$ref": "#/components/schemas/HostedTemplateSkillResourceInline" + } + ], + "discriminator": { + "propertyName": "type", + "mapping": { + "skill_reference": "#/components/schemas/HostedTemplateSkillResourceSkillReference", + "inline": "#/components/schemas/HostedTemplateSkillResourceInline" + } + }, + "x-oai-discriminator-values": [ + "skill_reference", + "inline" + ], + "description": "Safe metadata for a skill configured by an environment template." + }, + "HostedTemplateFileResourceFileId": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "file_id" + ], + "default": "file_id", + "x-stainless-const": true, + "description": "The type of the object. Always `file_id`." + }, + "file_id": { + "type": "string", + "minLength": 0, + "description": "The ID of the uploaded file." + }, + "path": { + "type": "string", + "minLength": 0, + "description": "The file's absolute path inside the environment." + } + }, + "required": [ + "type", + "file_id", + "path" + ], + "additionalProperties": false, + "description": "A project-scoped Files API reference resolved separately for each session." + }, + "HostedTemplateFileResourceInline": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "inline" + ], + "default": "inline", + "x-stainless-const": true, + "description": "The type of the object. Always `inline`." + }, + "path": { + "type": "string", + "minLength": 0, + "description": "The file's absolute path inside the environment." + }, + "size_bytes": { + "type": "integer", + "format": "int64", + "minimum": 0, + "description": "The decoded size of the inline file in bytes." + } + }, + "required": [ + "type", + "path", + "size_bytes" + ], + "additionalProperties": false, + "description": "Metadata for confidential inline file contents." + }, + "HostedTemplateFileResource": { + "oneOf": [ + { + "$ref": "#/components/schemas/HostedTemplateFileResourceFileId" + }, + { + "$ref": "#/components/schemas/HostedTemplateFileResourceInline" + } + ], + "discriminator": { + "propertyName": "type", + "mapping": { + "file_id": "#/components/schemas/HostedTemplateFileResourceFileId", + "inline": "#/components/schemas/HostedTemplateFileResourceInline" + } + }, + "x-oai-discriminator-values": [ + "file_id", + "inline" + ], + "description": "Safe metadata for a file configured by an environment template." + }, + "EnvironmentTemplateResource": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 0, + "description": "The ID of the reusable environment template." + }, + "name": { + "type": [ + "string", + "null" + ], + "minLength": 0, + "description": "An optional human-readable display name for the template." + }, + "object": { + "type": "string", + "enum": [ + "agent.environment.template" + ], + "default": "agent.environment.template", + "x-stainless-const": true, + "description": "The object type. Always `agent.environment.template`." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "The Unix timestamp, in seconds, when the template was created." + }, + "updated_at": { + "type": "integer", + "format": "int64", + "description": "The Unix timestamp, in seconds, when the template was last updated." + }, + "packages": { + "$ref": "#/components/schemas/EnvironmentPackagesResource", + "description": "Packages installed in each fresh OpenAI-hosted environment." + }, + "network": { + "$ref": "#/components/schemas/NetworkPolicyResource", + "description": "Runtime network access for each OpenAI-hosted environment." + }, + "capability_directories": { + "type": "array", + "items": { + "type": "string", + "minLength": 0 + }, + "minItems": 0, + "maxItems": 2000, + "description": "Directories that expose capabilities to the agent." + }, + "skills": { + "type": "array", + "items": { + "$ref": "#/components/schemas/HostedTemplateSkillResource" + }, + "minItems": 0, + "maxItems": 200, + "description": "Safe skill metadata, preserving unresolved version selectors." + }, + "plugins": { + "type": "array", + "items": { + "$ref": "#/components/schemas/HostedPluginResource" + }, + "minItems": 0, + "maxItems": 32, + "description": "Safe plugin metadata, excluding inline archive contents." + }, + "files": { + "type": "array", + "items": { + "$ref": "#/components/schemas/HostedTemplateFileResource" + }, + "minItems": 0, + "maxItems": 50, + "description": "Safe file metadata, excluding contents and session-scoped file IDs." + } + }, + "required": [ + "id", + "name", + "object", + "created_at", + "updated_at", + "packages", + "network", + "capability_directories", + "skills", + "plugins", + "files" + ], + "additionalProperties": false, + "description": "Reusable configuration that provisions a fresh OpenAI-hosted environment for each session." + }, + "EnvironmentTemplateListResource": { + "type": "object", + "properties": { + "object": { + "type": "string", + "enum": [ + "list" + ], + "default": "list", + "x-stainless-const": true, + "description": "The object type, which is always `list`." + }, + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/EnvironmentTemplateResource" + }, + "minItems": 0, + "maxItems": 2000, + "description": "The resources returned in this page, in the requested sort order." + }, + "first_id": { + "type": [ + "string", + "null" + ], + "minLength": 0, + "description": "The ID of the first resource in `data`, or `null` if the page is empty." + }, + "last_id": { + "type": [ + "string", + "null" + ], + "minLength": 0, + "description": "The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters." + }, + "has_more": { + "type": "boolean", + "description": "Whether there are more resources to retrieve after this page." + } + }, + "required": [ + "object", + "data", + "first_id", + "last_id", + "has_more" + ], + "additionalProperties": false, + "description": "A page of Agents API resources, with IDs for retrieving additional pages." + }, + "EnvironmentPackagesParam": { + "type": "object", + "properties": { + "python": { + "type": [ + "array", + "null" + ], + "items": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "minItems": 0, + "maxItems": 16384, + "description": "Python packages to install. Defaults to an empty list." + }, + "system": { + "type": [ + "array", + "null" + ], + "items": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "minItems": 0, + "maxItems": 16384, + "description": "System packages to install. Defaults to an empty list." + }, + "npm": { + "type": [ + "array", + "null" + ], + "items": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "minItems": 0, + "maxItems": 16384, + "description": "npm packages to install globally. Defaults to an empty list." + } + }, + "additionalProperties": false, + "description": "Packages to install in an OpenAI-hosted environment." + }, + "SetupCommandParam": { + "type": "object", + "properties": { + "command": { + "type": "string", + "minLength": 0, + "maxLength": 65536, + "description": "The shell command to execute." + }, + "cwd": { + "type": [ + "string", + "null" + ], + "minLength": 0, + "maxLength": 4096, + "description": "The absolute working directory. Defaults to `/workspace`." + } + }, + "required": [ + "command" + ], + "additionalProperties": false, + "description": "A confidential setup command executed before the hosted agent starts." + }, + "NetworkAccessParam": { + "type": "string", + "enum": [ + "enabled", + "disabled", + "restricted" + ], + "x-enumDescriptions": [ + "Allows unrestricted network access, matching an omitted network policy.", + "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": [ + "access" + ], + "additionalProperties": false, + "description": "Network access for an OpenAI-hosted environment." + }, + "HostedSkillParamSkillReference": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "skill_reference" + ], + "default": "skill_reference", + "x-stainless-const": true, + "description": "The type of the object. Always `skill_reference`." + }, + "skill_id": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "description": "The ID of the skill created through `/v1/skills`." + }, + "version": { + "type": [ + "string", + "null" + ], + "minLength": 0, + "maxLength": 1048576, + "description": "The skill version, a positive integer or `latest`; omission selects the default." + } + }, + "required": [ + "type", + "skill_id" + ], + "additionalProperties": false, + "description": "References a skill uploaded through the Skills API." + }, + "InlineCapabilitySourceParamBase64": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "base64" + ], + "default": "base64", + "x-stainless-const": true, + "description": "The type of the object. Always `base64`." + }, + "media_type": { + "type": "string", + "enum": [ + "application/zip" + ], + "default": "application/zip", + "x-stainless-const": true, + "x-enumDescriptions": [ + "A ZIP archive." + ], + "description": "The archive media type, always `application/zip`." + }, + "data": { + "type": "string", + "minLength": 1, + "maxLength": 70254592, + "description": "Standard-base64 encoded ZIP archive bytes." + } + }, + "required": [ + "type", + "media_type", + "data" + ], + "additionalProperties": false, + "description": "Provides ZIP bytes encoded with standard base64." + }, + "InlineCapabilitySourceParam": { + "oneOf": [ + { + "$ref": "#/components/schemas/InlineCapabilitySourceParamBase64" + } + ], + "discriminator": { + "propertyName": "type", + "mapping": { + "base64": "#/components/schemas/InlineCapabilitySourceParamBase64" + } + }, + "x-oai-discriminator-values": [ + "base64" + ], + "description": "The encoded ZIP archive for an inline skill or plugin." + }, + "HostedSkillParamInline": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "inline" + ], + "default": "inline", + "x-stainless-const": true, + "description": "The type of the object. Always `inline`." + }, + "name": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "description": "The skill name declared in `SKILL.md`." + }, + "description": { + "type": "string", + "minLength": 0, + "maxLength": 1048576, + "description": "The skill description declared in `SKILL.md`." + }, + "source": { + "$ref": "#/components/schemas/InlineCapabilitySourceParam", + "description": "The inline ZIP archive." + } + }, + "required": [ + "type", + "name", + "description", + "source" + ], + "additionalProperties": false, + "description": "Supplies a skill ZIP directly in the session request." + }, + "HostedSkillParam": { + "oneOf": [ + { + "$ref": "#/components/schemas/HostedSkillParamSkillReference" + }, + { + "$ref": "#/components/schemas/HostedSkillParamInline" + } + ], + "discriminator": { + "propertyName": "type", + "mapping": { + "skill_reference": "#/components/schemas/HostedSkillParamSkillReference", + "inline": "#/components/schemas/HostedSkillParamInline" + } + }, + "x-oai-discriminator-values": [ + "skill_reference", + "inline" + ], + "description": "A skill installed in an OpenAI-hosted environment." + }, + "HostedPluginParamInline": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "inline" + ], + "default": "inline", + "x-stainless-const": true, + "description": "The type of the object. Always `inline`." + }, + "name": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "description": "The plugin name declared in `.codex-plugin/plugin.json`." + }, + "description": { + "type": "string", + "minLength": 0, + "maxLength": 1048576, + "description": "The plugin description declared in `.codex-plugin/plugin.json`." + }, + "source": { + "$ref": "#/components/schemas/InlineCapabilitySourceParam", + "description": "The inline ZIP archive." + } + }, + "required": [ + "type", + "name", + "description", + "source" + ], + "additionalProperties": false, + "description": "Supplies a plugin ZIP directly in the session request." + }, + "HostedPluginParam": { + "oneOf": [ + { + "$ref": "#/components/schemas/HostedPluginParamInline" + } + ], + "discriminator": { + "propertyName": "type", + "mapping": { + "inline": "#/components/schemas/HostedPluginParamInline" + } + }, + "x-oai-discriminator-values": [ + "inline" + ], + "description": "A plugin installed in an OpenAI-hosted environment." + }, + "CreateEnvironmentTemplateParams": { + "type": "object", + "properties": { + "packages": { + "anyOf": [ + { + "$ref": "#/components/schemas/EnvironmentPackagesParam" + }, + { + "type": "null" + } + ], + "description": "Packages to install in the environment. Defaults to empty package lists." + }, + "setup_commands": { + "type": [ + "array", + "null" + ], + "items": { + "$ref": "#/components/schemas/SetupCommandParam" + }, + "minItems": 0, + "maxItems": 16, + "description": "Ordered, confidential setup commands. Command bodies are never returned." + }, + "network": { + "anyOf": [ + { + "$ref": "#/components/schemas/NetworkPolicyParam" + }, + { + "type": "null" + } + ], + "description": "Network access policy for the environment. Defaults to enabled." + }, + "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", + "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." + }, + "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", + "enum": [ + "agent.environment.template.deleted" + ], + "default": "agent.environment.template.deleted", + "x-stainless-const": true, + "description": "The object type. Always `agent.environment.template.deleted`." + }, + "deleted": { + "type": "boolean", + "description": "Whether the environment template was deleted. Always `true`." + } + }, + "required": [ + "id", + "object", + "deleted" + ], + "additionalProperties": false, + "description": "A deleted reusable environment template." + }, + "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", + "properties": { + "type": { + "type": "string", + "enum": [ + "function_call" + ], + "default": "function_call", + "x-stainless-const": true, + "description": "The type of the object. Always `function_call`." + }, + "turn_id": { + "type": "string", + "minLength": 0, + "description": "The ID of the turn that requested the function call." + }, + "call_id": { + "type": "string", + "minLength": 0, + "description": "The ID to include when submitting the function result." + }, + "name": { + "type": "string", + "minLength": 0, + "description": "The function name." + }, + "arguments": { + "description": "The arguments supplied by the model." + } + }, + "required": [ + "type", + "turn_id", + "call_id", + "name", + "arguments" + ], + "additionalProperties": false, + "description": "Run a function tool and submit its result." + }, + "SessionRequiredActionResourceEnvironmentConnection": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "environment_connection" + ], + "default": "environment_connection", + "x-stainless-const": true, + "description": "The type of the object. Always `environment_connection`." + }, + "environment_id": { + "type": "string", + "minLength": 0, + "description": "The ID of the environment to reconnect." + } + }, + "required": [ + "type", + "environment_id" + ], + "additionalProperties": false, + "description": "Reconnect a session environment." + }, + "SessionRequiredActionResource": { + "oneOf": [ + { + "$ref": "#/components/schemas/SessionRequiredActionResourceFunctionCall" + }, + { + "$ref": "#/components/schemas/SessionRequiredActionResourceEnvironmentConnection" + } + ], + "discriminator": { + "propertyName": "type", + "mapping": { + "function_call": "#/components/schemas/SessionRequiredActionResourceFunctionCall", + "environment_connection": "#/components/schemas/SessionRequiredActionResourceEnvironmentConnection" + } + }, + "x-oai-discriminator-values": [ + "function_call", + "environment_connection" + ], + "description": "An action that must be completed before a session can continue." + }, + "AgentToolResourceFunction": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "function" + ], + "default": "function", + "x-stainless-const": true, + "description": "The type of the object. Always `function`." + }, + "name": { + "type": "string", + "minLength": 0, + "description": "The name of the function." + }, + "description": { + "type": "string", + "minLength": 0, + "description": "A description of what the function does." + }, + "parameters": { + "type": "object", + "additionalProperties": {}, + "propertyNames": { + "type": "string", + "minLength": 0 + }, + "minProperties": 0, + "description": "A JSON Schema object describing the function's arguments." + }, + "defer_loading": { + "type": "boolean", + "description": "Whether the function is deferred and discovered through tool search." + } + }, + "required": [ + "type", + "name", + "description", + "parameters", + "defer_loading" + ], + "additionalProperties": false, + "description": "A function defined by the application." + }, + "AgentToolResourceProgrammaticToolCalling": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "programmatic_tool_calling" + ], + "default": "programmatic_tool_calling", + "x-stainless-const": true, + "description": "The type of the object. Always `programmatic_tool_calling`." + }, + "enabled": { + "type": "boolean", + "description": "Whether tools can be called from model-generated code." + } + }, + "required": [ + "type", + "enabled" + ], + "additionalProperties": false, + "description": "Enables calling tools from model-generated code." + }, + "McpTransportResourceHttp": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "http" + ], + "default": "http", + "x-stainless-const": true, + "description": "The type of the object. Always `http`." + }, + "server_url": { + "type": "string", + "minLength": 0, + "description": "The URL of the MCP server." + } + }, + "required": [ + "type", + "server_url" + ], + "additionalProperties": false, + "description": "Connects to an MCP server over HTTP." + }, + "McpTransportResourceStdio": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "stdio" + ], + "default": "stdio", + "x-stainless-const": true, + "description": "The type of the object. Always `stdio`." + }, + "command": { + "type": "string", + "minLength": 0, + "description": "The command used to start the MCP server." + }, + "args": { + "type": "array", + "items": { + "type": "string", + "minLength": 0 + }, + "minItems": 0, + "maxItems": 2000, + "description": "Arguments passed to the MCP server command." + }, + "cwd": { + "type": "string", + "minLength": 0, + "description": "The working directory used to start the MCP server." + }, + "env_vars": { + "type": "array", + "items": { + "type": "string", + "minLength": 0 + }, + "minItems": 0, + "maxItems": 2000, + "description": "Environment variable names inherited from the execution environment." + } + }, + "required": [ + "type", + "command", + "args", + "cwd", + "env_vars" + ], + "additionalProperties": false, + "description": "Starts an MCP server as a local process." + }, + "McpTransportResource": { + "oneOf": [ + { + "$ref": "#/components/schemas/McpTransportResourceHttp" + }, + { + "$ref": "#/components/schemas/McpTransportResourceStdio" + } + ], + "discriminator": { + "propertyName": "type", + "mapping": { + "http": "#/components/schemas/McpTransportResourceHttp", + "stdio": "#/components/schemas/McpTransportResourceStdio" + } + }, + "x-oai-discriminator-values": [ + "http", + "stdio" + ], + "description": "The transport used to connect to an MCP server." + }, + "AgentToolResourceMcp": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "mcp" + ], + "default": "mcp", + "x-stainless-const": true, + "description": "The type of the object. Always `mcp`." + }, + "server_label": { + "type": "string", + "minLength": 0, + "description": "A label used to identify the MCP server in tool calls." + }, + "credential_id": { + "type": [ + "string", + "null" + ], + "minLength": 0, + "description": "The attached vault credential selected for this MCP server, if any. Optional when exactly one attached credential matches the server URL." + }, + "transport": { + "$ref": "#/components/schemas/McpTransportResource", + "description": "The transport used to connect to the MCP server." + }, + "request_metadata": { + "type": "object", + "additionalProperties": {}, + "propertyNames": { + "type": "string", + "minLength": 0 + }, + "minProperties": 0, + "description": "Metadata included with requests to this MCP server." + }, + "allowed_tools": { + "type": [ + "array", + "null" + ], + "items": { + "type": "string", + "minLength": 0 + }, + "minItems": 0, + "maxItems": 2000, + "description": "The MCP tools the agent may call." + }, + "required": { + "type": "boolean", + "description": "Whether this MCP server must initialize before the first turn." + }, + "connection_origin": { + "$ref": "#/components/schemas/McpConnectionOriginResource", + "description": "Where outbound MCP HTTP connections originate." + } + }, + "required": [ + "type", + "server_label", + "credential_id", + "transport", + "request_metadata", + "allowed_tools", + "required", + "connection_origin" + ], + "additionalProperties": false, + "description": "Tools provided by a remote MCP server." + }, + "AgentToolResourceWebSearch": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "web_search" + ], + "default": "web_search", + "x-stainless-const": true, + "description": "The type of the object. Always `web_search`." + }, + "mode": { + "$ref": "#/components/schemas/WebSearchModeResource", + "description": "The source used for web search results." + }, + "context_size": { + "$ref": "#/components/schemas/WebSearchContextSizeResource", + "description": "The amount of search context made available to the model. Defaults to `medium`." + }, + "allowed_domains": { + "type": [ + "array", + "null" + ], + "items": { + "type": "string", + "minLength": 0 + }, + "minItems": 0, + "maxItems": 2000, + "description": "Allowed search domains, or `null` when the search is unrestricted." + }, + "location": { + "anyOf": [ + { + "$ref": "#/components/schemas/WebSearchLocationResource" + }, + { + "type": "null" + } + ], + "description": "Approximate location used to localize search results, if provided." + } + }, + "required": [ + "type", + "mode", + "context_size", + "allowed_domains", + "location" + ], + "additionalProperties": false, + "description": "Web search." + }, + "AgentToolResource": { + "oneOf": [ + { + "$ref": "#/components/schemas/AgentToolResourceFunction" + }, + { + "$ref": "#/components/schemas/AgentToolResourceProgrammaticToolCalling" + }, + { + "$ref": "#/components/schemas/AgentToolResourceMcp" + }, + { + "$ref": "#/components/schemas/AgentToolResourceWebSearch" + } + ], + "discriminator": { + "propertyName": "type", + "mapping": { + "function": "#/components/schemas/AgentToolResourceFunction", + "programmatic_tool_calling": "#/components/schemas/AgentToolResourceProgrammaticToolCalling", + "mcp": "#/components/schemas/AgentToolResourceMcp", + "web_search": "#/components/schemas/AgentToolResourceWebSearch" + } + }, + "x-oai-discriminator-values": [ + "function", + "programmatic_tool_calling", + "mcp", + "web_search" + ], + "description": "A tool available to the agent." + }, + "SessionAgentResource": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 0, + "description": "The ID of the agent." + }, + "name": { + "type": [ + "string", + "null" + ], + "minLength": 0, + "description": "The reusable agent's name when the session was created, or null if no name was saved. Later changes to the agent's name do not affect this value." + }, + "model": { + "type": "string", + "minLength": 0, + "description": "The model used by the agent." + }, + "reasoning": { + "$ref": "#/components/schemas/ReasoningResource", + "description": "The agent's reasoning configuration." + }, + "text": { + "$ref": "#/components/schemas/TextResource", + "description": "Configuration for text generated by the agent." + }, + "service_tier": { + "$ref": "#/components/schemas/ServiceTierResource", + "description": "The effective service-tier policy for model requests. Defaults to `auto`." + }, + "instructions": { + "type": [ + "string", + "null" + ], + "minLength": 0, + "description": "Custom instructions appended to the agent's default base instructions." + }, + "tools": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AgentToolResource" + }, + "minItems": 0, + "maxItems": 2000, + "description": "Tools available to the agent." + }, + "multi_agent": { + "$ref": "#/components/schemas/MultiAgentConfigResource", + "description": "Configuration for creating and coordinating subagents." + }, + "x_agents_core": { + "anyOf": [ + { + "$ref": "#/components/schemas/v1.AgentsCore" + }, + { + "type": "null" + } + ] + } + }, + "required": [ + "id", + "name", + "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": [ + "none" + ], + "default": "none", + "x-stainless-const": true, + "description": "The type of the object. Always `none`." + } + }, + "required": [ + "type" + ], + "additionalProperties": false, + "description": "The session talks to CCA without selecting or provisioning an execution environment." + }, + "EnvironmentResourceOpenaiHosted": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "openai_hosted" + ], + "default": "openai_hosted", + "x-stainless-const": true, + "description": "The type of the object. Always `openai_hosted`." + }, + "id": { + "type": "string", + "minLength": 0, + "description": "The public ID of the environment." + }, + "packages": { + "$ref": "#/components/schemas/EnvironmentPackagesResource", + "description": "Packages installed in the environment." + }, + "network": { + "$ref": "#/components/schemas/NetworkPolicyResource", + "description": "The effective network access policy for the environment." + }, + "capability_directories": { + "type": "array", + "items": { + "type": "string", + "minLength": 0 + }, + "minItems": 0, + "maxItems": 2000, + "description": "Directories that contain capabilities exposed to the agent." + }, + "skills": { + "type": "array", + "items": { + "$ref": "#/components/schemas/HostedSkillResource" + }, + "minItems": 0, + "maxItems": 2000, + "description": "Skills installed in the environment, excluding their archive contents." + }, + "plugins": { + "type": "array", + "items": { + "$ref": "#/components/schemas/HostedPluginResource" + }, + "minItems": 0, + "maxItems": 2000, + "description": "Plugins installed in the environment, excluding their archive contents." + }, + "files": { + "type": "array", + "items": { + "$ref": "#/components/schemas/HostedEnvironmentFileResource" + }, + "minItems": 0, + "maxItems": 50, + "description": "Files available in the environment, excluding their contents." + } + }, + "required": [ + "type", + "id", + "packages", + "network", + "capability_directories", + "skills", + "plugins", + "files" + ], + "additionalProperties": false, + "description": "An environment hosted by OpenAI." + }, + "EnvironmentResourceSelfHosted": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "self_hosted" + ], + "default": "self_hosted", + "x-stainless-const": true, + "description": "The type of the object. Always `self_hosted`." + }, + "remote_url": { + "type": "string", + "minLength": 0, + "description": "Pass this URL unchanged to `codex exec-server --remote` when connecting this environment." + }, + "id": { + "type": "string", + "minLength": 0, + "description": "The public ID of the environment." + }, + "workspace_directory": { + "type": "string", + "minLength": 0, + "description": "The absolute project directory inside the environment. Defaults to `/workspace`." + }, + "capability_directories": { + "type": "array", + "items": { + "type": "string", + "minLength": 0 + }, + "minItems": 0, + "maxItems": 2000, + "description": "Directories that contain capabilities exposed to the agent." + } + }, + "required": [ + "type", + "remote_url", + "id", + "workspace_directory", + "capability_directories" + ], + "additionalProperties": false, + "description": "An environment hosted by the application." + }, + "EnvironmentResource": { + "oneOf": [ + { + "$ref": "#/components/schemas/EnvironmentResourceNone" + }, + { + "$ref": "#/components/schemas/EnvironmentResourceOpenaiHosted" + }, + { + "$ref": "#/components/schemas/EnvironmentResourceSelfHosted" + } + ], + "discriminator": { + "propertyName": "type", + "mapping": { + "none": "#/components/schemas/EnvironmentResourceNone", + "openai_hosted": "#/components/schemas/EnvironmentResourceOpenaiHosted", + "self_hosted": "#/components/schemas/EnvironmentResourceSelfHosted" + } + }, + "x-oai-discriminator-values": [ + "none", + "openai_hosted", + "self_hosted" + ], + "description": "The execution environment for a session." + }, + "SessionResource": { + "type": "object", + "properties": { + "metadata": { + "type": "object", + "additionalProperties": { + "type": "string", + "minLength": 0 + }, + "propertyNames": { + "type": "string", + "minLength": 0 + }, + "minProperties": 0, + "description": "Custom string key-value pairs attached to the session." + }, + "id": { + "type": "string", + "minLength": 0, + "description": "The ID of the session." + }, + "object": { + "type": "string", + "enum": [ + "agent.session" + ], + "default": "agent.session", + "x-stainless-const": true, + "description": "The object type. Always `agent.session`." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "The Unix timestamp, in seconds, when the session was created." + }, + "last_active_at": { + "type": "integer", + "format": "int64", + "description": "The Unix timestamp, in seconds, when the session was last active." + }, + "status": { + "$ref": "#/components/schemas/SessionStatusResource", + "description": "The current status of the session." + }, + "required_actions": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SessionRequiredActionResource" + }, + "minItems": 0, + "maxItems": 2000, + "description": "Actions that must be completed before the session can continue." + }, + "error": { + "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" + }, + { + "type": "null" + } + ], + "description": "Best-effort token usage for the session, or null if unknown. Recorded usage may change." + }, + "x_agents_core": { + "anyOf": [ + { + "$ref": "#/components/schemas/v1.SessionCore" + }, + { + "type": "null" + } + ] + } + }, + "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": [ + "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": [ + "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." + }, + "AgentToolConfigParamToolSearch": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "tool_search" + ], + "default": "tool_search", + "x-stainless-const": true, + "description": "The type of the object. Always `tool_search`." + } + }, + "required": [ + "type" + ], + "additionalProperties": false, + "description": "Discovers deferred function tools and loads them into the model context." + }, + "AgentToolConfigParamProgrammaticToolCalling": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "programmatic_tool_calling" + ], + "default": "programmatic_tool_calling", + "x-stainless-const": true, + "description": "The type of the object. Always `programmatic_tool_calling`." + }, + "enabled": { + "type": "boolean", + "default": true, + "description": "Whether tools can be called from model-generated code. Defaults to `true`." + } + }, + "required": [ + "type" + ], + "additionalProperties": false, + "description": "Enables calling tools from model-generated code." + }, + "McpTransportConfigParamHttp": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "http" + ], + "default": "http", + "x-stainless-const": true, + "description": "The type of the object. Always `http`." + }, + "server_url": { + "type": "string", + "minLength": 0, + "maxLength": 1048576, + "description": "The URL of the MCP server." + }, + "authorization": { + "type": [ + "string", + "null" + ], + "minLength": 0, + "maxLength": 1048576, + "description": "The authorization value sent to the MCP server, if any." + }, + "headers": { + "type": [ + "object", + "null" + ], + "additionalProperties": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "propertyNames": { + "type": "string", + "minLength": 1, + "maxLength": 256 + }, + "minProperties": 0, + "maxProperties": 1024, + "description": "Additional HTTP headers sent to the MCP server." + } + }, + "required": [ + "type", + "server_url" + ], + "additionalProperties": false, + "description": "Connects to an MCP server over HTTP." + }, + "McpTransportConfigParamStdio": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "stdio" + ], + "default": "stdio", + "x-stainless-const": true, + "description": "The type of the object. Always `stdio`." + }, + "command": { + "type": "string", + "minLength": 0, + "maxLength": 1048576, + "description": "The command used to start the MCP server." + }, + "args": { + "type": [ + "array", + "null" + ], + "items": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "minItems": 0, + "maxItems": 16384, + "description": "Arguments passed to the MCP server command." + }, + "cwd": { + "type": "string", + "minLength": 0, + "maxLength": 1048576, + "description": "The working directory used to start the MCP server." + }, + "env": { + "type": [ + "object", + "null" + ], + "additionalProperties": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "propertyNames": { + "type": "string", + "minLength": 1, + "maxLength": 256 + }, + "minProperties": 0, + "maxProperties": 1024, + "description": "Environment variables set for the MCP server process." + }, + "env_vars": { + "type": [ + "array", + "null" + ], + "items": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "minItems": 0, + "maxItems": 16384, + "description": "Environment variable names to inherit from the selected execution environment." + } + }, + "required": [ + "type", + "command", + "cwd" + ], + "additionalProperties": false, + "description": "Starts an MCP server as a local process." + }, + "McpTransportConfigParam": { + "oneOf": [ + { + "$ref": "#/components/schemas/McpTransportConfigParamHttp" + }, + { + "$ref": "#/components/schemas/McpTransportConfigParamStdio" + } + ], + "discriminator": { + "propertyName": "type", + "mapping": { + "http": "#/components/schemas/McpTransportConfigParamHttp", + "stdio": "#/components/schemas/McpTransportConfigParamStdio" + } + }, + "x-oai-discriminator-values": [ + "http", + "stdio" + ], + "description": "The transport used to connect to an MCP server." + }, + "AgentToolConfigParamMcp": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "mcp" + ], + "default": "mcp", + "x-stainless-const": true, + "description": "The type of the object. Always `mcp`." + }, + "server_label": { + "type": "string", + "minLength": 0, + "maxLength": 1048576, + "description": "A label used to identify the MCP server in tool calls." + }, + "credential_id": { + "type": [ + "string", + "null" + ], + "minLength": 0, + "maxLength": 1048576, + "description": "The attached vault credential used to authenticate this MCP server. Optional when exactly one attached credential matches the server URL." + }, + "transport": { + "$ref": "#/components/schemas/McpTransportConfigParam", + "description": "The transport used to connect to the MCP server." + }, + "request_metadata": { + "type": [ + "object", + "null" + ], + "additionalProperties": {}, + "propertyNames": { + "type": "string", + "minLength": 1, + "maxLength": 256 + }, + "minProperties": 0, + "maxProperties": 1024, + "description": "Metadata included with requests to this MCP server." + }, + "allowed_tools": { + "type": [ + "array", + "null" + ], + "items": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "minItems": 0, + "maxItems": 16384, + "description": "The MCP tools the agent may call. All server tools are allowed when omitted." + }, + "required": { + "type": "boolean", + "default": false, + "description": "Whether this MCP server must initialize before the first turn. Defaults to `false`." + }, + "connection_origin": { + "anyOf": [ + { + "$ref": "#/components/schemas/McpConnectionOriginParam" + }, + { + "type": "null" + } + ], + "description": "Selects where outbound MCP HTTP connections originate. Omitted or `service` uses the Managed Agents service network; `environment` uses the session's selected environment." + } + }, + "required": [ + "type", + "server_label", + "transport" + ], + "additionalProperties": false, + "description": "Tools provided by a remote MCP server." + }, + "AgentToolConfigParamWebSearch": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "web_search" + ], + "default": "web_search", + "x-stainless-const": true, + "description": "The type of the object. Always `web_search`." + }, + "mode": { + "anyOf": [ + { + "$ref": "#/components/schemas/WebSearchModeParam" + }, + { + "type": "null" + } + ], + "description": "The source used for web search results. Defaults to `live`." + }, + "context_size": { + "anyOf": [ + { + "$ref": "#/components/schemas/WebSearchContextSizeParam" + }, + { + "type": "null" + } + ], + "description": "The amount of search context made available to the model. Defaults to `medium`." + }, + "allowed_domains": { + "type": [ + "array", + "null" + ], + "items": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "minItems": 0, + "maxItems": 16384, + "description": "Domains the search may include." + }, + "location": { + "anyOf": [ + { + "$ref": "#/components/schemas/WebSearchLocationParam" + }, + { + "type": "null" + } + ], + "description": "Approximate location used to localize search results." + } + }, + "required": [ + "type" + ], + "additionalProperties": false, + "description": "Web search." + }, + "AgentToolConfigParam": { + "oneOf": [ + { + "$ref": "#/components/schemas/AgentToolConfigParamFunction" + }, + { + "$ref": "#/components/schemas/AgentToolConfigParamToolSearch" + }, + { + "$ref": "#/components/schemas/AgentToolConfigParamProgrammaticToolCalling" + }, + { + "$ref": "#/components/schemas/AgentToolConfigParamMcp" + }, + { + "$ref": "#/components/schemas/AgentToolConfigParamWebSearch" + } + ], + "discriminator": { + "propertyName": "type", + "mapping": { + "function": "#/components/schemas/AgentToolConfigParamFunction", + "tool_search": "#/components/schemas/AgentToolConfigParamToolSearch", + "programmatic_tool_calling": "#/components/schemas/AgentToolConfigParamProgrammaticToolCalling", + "mcp": "#/components/schemas/AgentToolConfigParamMcp", + "web_search": "#/components/schemas/AgentToolConfigParamWebSearch" + } + }, + "x-oai-discriminator-values": [ + "function", + "tool_search", + "programmatic_tool_calling", + "mcp", + "web_search" + ], + "description": "A tool available to the agent." + }, + "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." + }, + "x_agents_core": { + "anyOf": [ + { + "$ref": "#/components/schemas/v1.AgentsCore" + }, + { + "type": "null" + } + ] + } + }, + "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": [ + "none" + ], + "default": "none", + "x-stainless-const": true, + "description": "The type of the object. Always `none`." + } + }, + "required": [ + "type" + ], + "additionalProperties": false, + "description": "Runs the agent without an execution environment." + }, + "EnvironmentParamOpenaiHosted": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "openai_hosted" + ], + "default": "openai_hosted", + "x-stainless-const": true, + "description": "The type of the object. Always `openai_hosted`." + }, + "packages": { + "anyOf": [ + { + "$ref": "#/components/schemas/EnvironmentPackagesParam" + }, + { + "type": "null" + } + ], + "description": "Packages to install in the environment. Defaults to empty package lists." + }, + "setup_commands": { + "type": [ + "array", + "null" + ], + "items": { + "$ref": "#/components/schemas/SetupCommandParam" + }, + "minItems": 0, + "maxItems": 16, + "description": "Ordered, confidential setup commands. Command bodies are never returned." + }, + "network": { + "anyOf": [ + { + "$ref": "#/components/schemas/NetworkPolicyParam" + }, + { + "type": "null" + } + ], + "description": "Network access policy for the environment. Defaults to enabled." + }, + "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", + "properties": { + "type": { + "type": "string", + "enum": [ + "self_hosted" + ], + "default": "self_hosted", + "x-stainless-const": true, + "description": "The type of the object. Always `self_hosted`." + }, + "workspace_directory": { + "type": "string", + "minLength": 0, + "maxLength": 1048576, + "description": "Absolute project directory inside the self-hosted environment." + }, + "capability_directories": { + "type": [ + "array", + "null" + ], + "items": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "minItems": 0, + "maxItems": 16384, + "description": "Directories that contain capabilities exposed to the agent. Defaults to an empty list." + } + }, + "required": [ + "type", + "workspace_directory" + ], + "additionalProperties": false, + "description": "An application-hosted environment configured inline." + }, + "EnvironmentParam": { + "oneOf": [ + { + "$ref": "#/components/schemas/EnvironmentParamNone" + }, + { + "$ref": "#/components/schemas/EnvironmentParamOpenaiHosted" + }, + { + "$ref": "#/components/schemas/EnvironmentParamSelfHosted" + } + ], + "discriminator": { + "propertyName": "type", + "mapping": { + "none": "#/components/schemas/EnvironmentParamNone", + "openai_hosted": "#/components/schemas/EnvironmentParamOpenaiHosted", + "self_hosted": "#/components/schemas/EnvironmentParamSelfHosted" + } + }, + "x-oai-discriminator-values": [ + "none", + "openai_hosted", + "self_hosted" + ], + "description": "The execution environment and optional reusable template for a session." + }, + "InputContentParamInputText": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "input_text" + ], + "default": "input_text", + "x-stainless-const": true, + "description": "The type of the object. Always `input_text`." + }, + "text": { + "type": "string", + "minLength": 0, + "maxLength": 1048576, + "description": "The text sent to the model." + } + }, + "required": [ + "type", + "text" + ], + "additionalProperties": false, + "description": "Text input to the model." + }, + "InputContentParamInputImage": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "input_image" + ], + "default": "input_image", + "x-stainless-const": true, + "description": "The type of the object. Always `input_image`." + }, + "image_url": { + "type": "string", + "minLength": 0, + "maxLength": 1048576, + "description": "The URL of the image sent to the model." + } + }, + "required": [ + "type", + "image_url" + ], + "additionalProperties": false, + "description": "Image input to the model." + }, + "InputContentParam": { + "oneOf": [ + { + "$ref": "#/components/schemas/InputContentParamInputText" + }, + { + "$ref": "#/components/schemas/InputContentParamInputImage" + } + ], + "discriminator": { + "propertyName": "type", + "mapping": { + "input_text": "#/components/schemas/InputContentParamInputText", + "input_image": "#/components/schemas/InputContentParamInputImage" + } + }, + "x-oai-discriminator-values": [ + "input_text", + "input_image" + ], + "description": "Content included in an input message." + }, + "InputMessageParam": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "message" + ], + "default": "message", + "x-stainless-const": true, + "description": "The type of the input item. Always `message`." + }, + "role": { + "type": "string", + "enum": [ + "user" + ], + "default": "user", + "x-stainless-const": true, + "description": "The role of the message author. Always `user`." + }, + "content": { + "type": "array", + "items": { + "$ref": "#/components/schemas/InputContentParam" + }, + "minItems": 0, + "maxItems": 16384, + "description": "The content of the message." + } + }, + "required": [ + "role", + "content" + ], + "additionalProperties": false, + "description": "A user message submitted to a session." + }, + "CreateSessionInputParam": { + "oneOf": [ + { + "type": "string", + "minLength": 1, + "maxLength": 1048576 + }, + { + "type": "array", + "items": { + "$ref": "#/components/schemas/InputMessageParam" + }, + "minItems": 0, + "maxItems": 16384 + } + ], + "description": "Initial input submitted when creating a session." + }, + "CreateAgentSessionParams": { + "type": "object", + "properties": { + "metadata": { + "type": [ + "object", + "null" + ], + "additionalProperties": { + "type": "string", + "minLength": 0, + "maxLength": 512 + }, + "propertyNames": { + "type": "string", + "minLength": 1, + "maxLength": 64 + }, + "minProperties": 0, + "maxProperties": 16, + "description": "Up to 16 string key-value pairs, with keys up to 64 and values up to 512 characters. Omission or null defaults to an empty map." + }, + "agent": { + "$ref": "#/components/schemas/SessionAgentConfigParam", + "description": "Agent configuration. With `agent_id`, supplied fields override the saved agent for this session. Without `agent_id`, `model` is required." + }, + "agent_id": { + "type": "string", + "minLength": 0, + "maxLength": 64, + "description": "The ID of a saved reusable agent. Omit `agent` to use its configuration unchanged." + }, + "environment": { + "$ref": "#/components/schemas/EnvironmentParam", + "description": "An inline execution environment or a reference to an environment template." + }, + "vault_ids": { + "type": [ + "array", + "null" + ], + "items": { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + "minItems": 0, + "maxItems": 16384, + "description": "The IDs of vaults made available to the session." + }, + "input": { + "anyOf": [ + { + "$ref": "#/components/schemas/CreateSessionInputParam" + }, + { + "type": "null" + } + ], + "description": "Initial input to submit when the session is created. A string is shorthand for a single user message. Required when `environment.type` is `none`, or when `stream` is `true` for an environment that is not `self_hosted`; optional for self-hosted and non-streaming execution environments." + }, + "stream": { + "type": "boolean", + "default": false, + "description": "Whether to stream session events as server-sent events. Defaults to `false`." + }, + "x_agents_core": { + "anyOf": [ + { + "$ref": "#/components/schemas/v1.SessionExecutionInput" + }, + { + "type": "null" + } + ] + } + }, + "required": [ + "environment" + ], + "additionalProperties": false, + "description": "Parameters for creating a Managed Agents session." + }, + "SessionErrorResource": { + "type": "object", + "properties": { + "type": { + "type": "string", + "minLength": 0, + "description": "The error type." + }, + "code": { + "type": [ + "string", + "null" + ], + "minLength": 0, + "description": "The machine-readable error code, if any." + }, + "message": { + "type": "string", + "minLength": 0, + "description": "A customer-safe explanation of the error." + }, + "param": { + "type": [ + "string", + "null" + ], + "minLength": 0, + "description": "The request parameter associated with the error, if any." + } + }, + "required": [ + "type", + "code", + "message", + "param" + ], + "additionalProperties": false, + "description": "An error payload with the same public fields as Responses API streaming errors." + }, + "SessionEventError": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "error" + ], + "default": "error", + "x-stainless-const": true, + "description": "The type of the object. Always `error`." + }, + "event_id": { + "type": "string", + "minLength": 0, + "description": "The unique ID of the event." + }, + "session_id": { + "type": "string", + "minLength": 0, + "description": "The ID of the session associated with the event." + }, + "error": { + "$ref": "#/components/schemas/SessionErrorResource", + "description": "The error that occurred." + } + }, + "required": [ + "type", + "event_id", + "session_id", + "error" + ], + "additionalProperties": false, + "description": "Emitted when a turn or session fails.", + "x-oaiMeta": { + "example": { + "type": "error", + "event_id": "event_123", + "session_id": "sess_123", + "error": { + "type": "server_error", + "code": null, + "message": "The session failed due to an internal server error.", + "param": null + } + } + } + }, + "SessionEnvironmentStatusResource": { + "type": "string", + "enum": [ + "pending", + "ready", + "connected", + "disconnected", + "failed" + ], + "x-enumDescriptions": [ + "The environment is being prepared.", + "The environment is ready to connect.", + "The environment is connected.", + "The environment is disconnected.", + "The environment failed to connect." + ], + "description": "The connection status of a session environment." + }, + "SessionEnvironmentErrorResource": { + "type": "object", + "properties": { + "type": { + "type": "string", + "minLength": 0, + "description": "The error type." + }, + "code": { + "type": "string", + "minLength": 0, + "description": "A machine-readable error code." + }, + "message": { + "type": "string", + "minLength": 0, + "description": "A human-readable error message." + } + }, + "required": [ + "type", + "code", + "message" + ], + "additionalProperties": false, + "description": "An error reported while preparing a session environment." + }, + "SessionEnvironmentStateResource": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 0, + "description": "The public ID of the environment." + }, + "type": { + "type": "string", + "minLength": 0, + "description": "The environment type." + }, + "status": { + "$ref": "#/components/schemas/SessionEnvironmentStatusResource", + "description": "The environment's connection status." + }, + "error": { + "anyOf": [ + { + "$ref": "#/components/schemas/SessionEnvironmentErrorResource" + }, + { + "type": "null" + } + ], + "description": "The error reported while preparing the environment, if any." + } + }, + "required": [ + "id", + "type", + "status", + "error" + ], + "additionalProperties": false, + "description": "The current state of a session environment." + }, + "SessionEventAgentSessionEnvironmentReady": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "agent.session.environment.ready" + ], + "default": "agent.session.environment.ready", + "x-stainless-const": true, + "description": "The type of the object. Always `agent.session.environment.ready`." + }, + "event_id": { + "type": "string", + "minLength": 0, + "description": "The unique ID of the event." + }, + "session_id": { + "type": "string", + "minLength": 0, + "description": "The ID of the session associated with the event." + }, + "turn_id": { + "type": [ + "string", + "null" + ], + "minLength": 0, + "description": "The ID of the turn associated with the event, when applicable." + }, + "environment": { + "$ref": "#/components/schemas/SessionEnvironmentStateResource", + "description": "The current environment state." + } + }, + "required": [ + "type", + "event_id", + "session_id", + "turn_id", + "environment" + ], + "additionalProperties": false, + "description": "Emitted when a hosted session environment is ready to connect." + }, + "SessionEventAgentOutputCommandExecutionOutputDelta": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "agent.output.command_execution_output.delta" + ], + "default": "agent.output.command_execution_output.delta", + "x-stainless-const": true, + "description": "The type of the object. Always `agent.output.command_execution_output.delta`." + }, + "event_id": { + "type": "string", + "minLength": 0, + "description": "The unique ID of the event." + }, + "session_id": { + "type": "string", + "minLength": 0, + "description": "The ID of the session associated with the event." + }, + "turn_id": { + "type": [ + "string", + "null" + ], + "minLength": 0, + "description": "The ID of the turn associated with the event, when applicable." + }, + "item_id": { + "type": "string", + "minLength": 0, + "description": "The ID of the command execution item." + }, + "output_index": { + "type": "integer", + "format": "int64", + "minimum": 0, + "maximum": 4294967295, + "description": "The index of the item in the turn output." + }, + "delta": { + "type": "string", + "minLength": 0, + "description": "The output text that was appended." + } + }, + "required": [ + "type", + "event_id", + "session_id", + "turn_id", + "item_id", + "output_index", + "delta" + ], + "additionalProperties": false, + "description": "Emitted when command execution produces an output delta." + }, + "SessionEventAgentSessionCreated": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "agent.session.created" + ], + "default": "agent.session.created", + "x-stainless-const": true, + "description": "The type of the object. Always `agent.session.created`." + }, + "event_id": { + "type": "string", + "minLength": 0, + "description": "The unique ID of the event." + }, + "session": { + "$ref": "#/components/schemas/SessionResource", + "description": "The session that was created." + } + }, + "required": [ + "type", + "event_id", + "session" + ], + "additionalProperties": false, + "description": "Emitted when a session is created." + }, + "SessionEventAgentSessionTurnCreated": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "agent.session.turn.created" + ], + "default": "agent.session.turn.created", + "x-stainless-const": true, + "description": "The type of the object. Always `agent.session.turn.created`." + }, + "event_id": { + "type": "string", + "minLength": 0, + "description": "The unique ID of the event." + }, + "session_id": { + "type": "string", + "minLength": 0, + "description": "The ID of the session associated with the event." + }, + "turn_id": { + "type": "string", + "minLength": 0, + "description": "The ID of the turn associated with the event." + }, + "turn": { + "$ref": "#/components/schemas/TurnResource", + "description": "The turn at the time it was created." + } + }, + "required": [ + "type", + "event_id", + "session_id", + "turn_id", + "turn" + ], + "additionalProperties": false, + "description": "Emitted when a turn is created." + }, + "SessionEventAgentSessionTurnInProgress": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "agent.session.turn.in_progress" + ], + "default": "agent.session.turn.in_progress", + "x-stainless-const": true, + "description": "The type of the object. Always `agent.session.turn.in_progress`." + }, + "event_id": { + "type": "string", + "minLength": 0, + "description": "The unique ID of the event." + }, + "session_id": { + "type": "string", + "minLength": 0, + "description": "The ID of the session associated with the event." + }, + "turn_id": { + "type": "string", + "minLength": 0, + "description": "The ID of the turn associated with the event." + }, + "turn": { + "$ref": "#/components/schemas/TurnResource", + "description": "The turn at the time it started running." + } + }, + "required": [ + "type", + "event_id", + "session_id", + "turn_id", + "turn" + ], + "additionalProperties": false, + "description": "Emitted when a turn starts running." + }, + "SessionEventAgentSessionTurnCompleted": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "agent.session.turn.completed" + ], + "default": "agent.session.turn.completed", + "x-stainless-const": true, + "description": "The type of the object. Always `agent.session.turn.completed`." + }, + "event_id": { + "type": "string", + "minLength": 0, + "description": "The unique ID of the event." + }, + "session_id": { + "type": "string", + "minLength": 0, + "description": "The ID of the session associated with the event." + }, + "turn_id": { + "type": "string", + "minLength": 0, + "description": "The ID of the turn associated with the event." + }, + "turn": { + "$ref": "#/components/schemas/TurnResource", + "description": "The completed turn." + }, + "usage": { + "anyOf": [ + { + "$ref": "#/components/schemas/TokenUsageResource" + }, + { + "type": "null" + } + ], + "description": "Token usage by the root agent during the turn, when available." + } + }, + "required": [ + "type", + "event_id", + "session_id", + "turn_id", + "turn", + "usage" + ], + "additionalProperties": false, + "description": "Emitted when a turn completes." + }, + "SessionEventAgentSessionTurnFailed": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "agent.session.turn.failed" + ], + "default": "agent.session.turn.failed", + "x-stainless-const": true, + "description": "The type of the object. Always `agent.session.turn.failed`." + }, + "event_id": { + "type": "string", + "minLength": 0, + "description": "The unique ID of the event." + }, + "session_id": { + "type": "string", + "minLength": 0, + "description": "The ID of the session associated with the event." + }, + "turn_id": { + "type": "string", + "minLength": 0, + "description": "The ID of the turn associated with the event." + }, + "turn": { + "$ref": "#/components/schemas/TurnResource", + "description": "The failed turn." + }, + "usage": { + "anyOf": [ + { + "$ref": "#/components/schemas/TokenUsageResource" + }, + { + "type": "null" + } + ], + "description": "Token usage by the root agent during the turn, when available." + } + }, + "required": [ + "type", + "event_id", + "session_id", + "turn_id", + "turn", + "usage" + ], + "additionalProperties": false, + "description": "Emitted when a turn fails." + }, + "SessionEventAgentSessionTurnCancelled": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "agent.session.turn.cancelled" + ], + "default": "agent.session.turn.cancelled", + "x-stainless-const": true, + "description": "The type of the object. Always `agent.session.turn.cancelled`." + }, + "event_id": { + "type": "string", + "minLength": 0, + "description": "The unique ID of the event." + }, + "session_id": { + "type": "string", + "minLength": 0, + "description": "The ID of the session associated with the event." + }, + "turn_id": { + "type": "string", + "minLength": 0, + "description": "The ID of the turn associated with the event." + }, + "turn": { + "$ref": "#/components/schemas/TurnResource", + "description": "The cancelled turn." + }, + "usage": { + "anyOf": [ + { + "$ref": "#/components/schemas/TokenUsageResource" + }, + { + "type": "null" + } + ], + "description": "Token usage by the root agent during the turn, when available." + } + }, + "required": [ + "type", + "event_id", + "session_id", + "turn_id", + "turn", + "usage" + ], + "additionalProperties": false, + "description": "Emitted when a turn is cancelled." + }, + "SessionEventAgentSessionTurnItemAdded": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "agent.session.turn.item.added" + ], + "default": "agent.session.turn.item.added", + "x-stainless-const": true, + "description": "The type of the object. Always `agent.session.turn.item.added`." + }, + "event_id": { + "type": "string", + "minLength": 0, + "description": "The unique ID of the event." + }, + "session_id": { + "type": "string", + "minLength": 0, + "description": "The ID of the session associated with the event." + }, + "turn_id": { + "type": [ + "string", + "null" + ], + "minLength": 0, + "description": "The ID of the turn associated with the event, when applicable." + }, + "output_index": { + "type": [ + "integer", + "null" + ], + "format": "int64", + "minimum": 0, + "maximum": 4294967295, + "description": "The index of the item in the turn output, when the item is agent output." + }, + "item": { + "$ref": "#/components/schemas/SessionTurnItemResource", + "description": "The item that was added." + } + }, + "required": [ + "type", + "event_id", + "session_id", + "turn_id", + "output_index", + "item" + ], + "additionalProperties": false, + "description": "Emitted when an item is added to a turn." + }, + "SessionEventAgentSessionIdle": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "agent.session.idle" + ], + "default": "agent.session.idle", + "x-stainless-const": true, + "description": "The type of the object. Always `agent.session.idle`." + }, + "event_id": { + "type": "string", + "minLength": 0, + "description": "The unique ID of the event." + }, + "session": { + "$ref": "#/components/schemas/SessionResource", + "description": "The session that became idle." + } + }, + "required": [ + "type", + "event_id", + "session" + ], + "additionalProperties": false, + "description": "Emitted when a session becomes idle." + }, + "SessionEventAgentSessionInProgress": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "agent.session.in_progress" + ], + "default": "agent.session.in_progress", + "x-stainless-const": true, + "description": "The type of the object. Always `agent.session.in_progress`." + }, + "event_id": { + "type": "string", + "minLength": 0, + "description": "The unique ID of the event." + }, + "session": { + "$ref": "#/components/schemas/SessionResource", + "description": "The session that started processing." + } + }, + "required": [ + "type", + "event_id", + "session" + ], + "additionalProperties": false, + "description": "Emitted when a session starts processing a turn." + }, + "SessionEventAgentSessionRequiresAction": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "agent.session.requires_action" + ], + "default": "agent.session.requires_action", + "x-stainless-const": true, + "description": "The type of the object. Always `agent.session.requires_action`." + }, + "event_id": { + "type": "string", + "minLength": 0, + "description": "The unique ID of the event." + }, + "session": { + "$ref": "#/components/schemas/SessionResource", + "description": "The session and its current required actions." + } + }, + "required": [ + "type", + "event_id", + "session" + ], + "additionalProperties": false, + "description": "Emitted when a session is waiting for one or more required actions." + }, + "SessionEventAgentSessionFailed": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "agent.session.failed" + ], + "default": "agent.session.failed", + "x-stainless-const": true, + "description": "The type of the object. Always `agent.session.failed`." + }, + "event_id": { + "type": "string", + "minLength": 0, + "description": "The unique ID of the event." + }, + "session": { + "$ref": "#/components/schemas/SessionResource", + "description": "The failed session." + } + }, + "required": [ + "type", + "event_id", + "session" + ], + "additionalProperties": false, + "description": "Emitted when a session fails." + }, + "SessionEventAgentSessionEnvironmentPending": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "agent.session.environment.pending" + ], + "default": "agent.session.environment.pending", + "x-stainless-const": true, + "description": "The type of the object. Always `agent.session.environment.pending`." + }, + "event_id": { + "type": "string", + "minLength": 0, + "description": "The unique ID of the event." + }, + "session_id": { + "type": "string", + "minLength": 0, + "description": "The ID of the session associated with the event." + }, + "turn_id": { + "type": [ + "string", + "null" + ], + "minLength": 0, + "description": "The ID of the turn associated with the event, when applicable." + }, + "environment": { + "$ref": "#/components/schemas/SessionEnvironmentStateResource", + "description": "The current environment state." + } + }, + "required": [ + "type", + "event_id", + "session_id", + "turn_id", + "environment" + ], + "additionalProperties": false, + "description": "Emitted while a session environment is being prepared." + }, + "SessionEventAgentSessionEnvironmentConnected": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "agent.session.environment.connected" + ], + "default": "agent.session.environment.connected", + "x-stainless-const": true, + "description": "The type of the object. Always `agent.session.environment.connected`." + }, + "event_id": { + "type": "string", + "minLength": 0, + "description": "The unique ID of the event." + }, + "session_id": { + "type": "string", + "minLength": 0, + "description": "The ID of the session associated with the event." + }, + "turn_id": { + "type": [ + "string", + "null" + ], + "minLength": 0, + "description": "The ID of the turn associated with the event, when applicable." + }, + "environment": { + "$ref": "#/components/schemas/SessionEnvironmentStateResource", + "description": "The current environment state." + } + }, + "required": [ + "type", + "event_id", + "session_id", + "turn_id", + "environment" + ], + "additionalProperties": false, + "description": "Emitted when a session environment connects." + }, + "SessionEventAgentSessionEnvironmentDisconnected": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "agent.session.environment.disconnected" + ], + "default": "agent.session.environment.disconnected", + "x-stainless-const": true, + "description": "The type of the object. Always `agent.session.environment.disconnected`." + }, + "event_id": { + "type": "string", + "minLength": 0, + "description": "The unique ID of the event." + }, + "session_id": { + "type": "string", + "minLength": 0, + "description": "The ID of the session associated with the event." + }, + "turn_id": { + "type": [ + "string", + "null" + ], + "minLength": 0, + "description": "The ID of the turn associated with the event, when applicable." + }, + "environment": { + "$ref": "#/components/schemas/SessionEnvironmentStateResource", + "description": "The current environment state." + } + }, + "required": [ + "type", + "event_id", + "session_id", + "turn_id", + "environment" + ], + "additionalProperties": false, + "description": "Emitted when a session environment disconnects." + }, + "SessionEventAgentSessionEnvironmentFailed": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "agent.session.environment.failed" + ], + "default": "agent.session.environment.failed", + "x-stainless-const": true, + "description": "The type of the object. Always `agent.session.environment.failed`." + }, + "event_id": { + "type": "string", + "minLength": 0, + "description": "The unique ID of the event." + }, + "session_id": { + "type": "string", + "minLength": 0, + "description": "The ID of the session associated with the event." + }, + "turn_id": { + "type": [ + "string", + "null" + ], + "minLength": 0, + "description": "The ID of the turn associated with the event, when applicable." + }, + "environment": { + "$ref": "#/components/schemas/SessionEnvironmentStateResource", + "description": "The current environment state." + } + }, + "required": [ + "type", + "event_id", + "session_id", + "turn_id", + "environment" + ], + "additionalProperties": false, + "description": "Emitted when a session environment fails." + }, + "SessionEventAgentSessionSubagentCreated": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "agent.session.subagent.created" + ], + "default": "agent.session.subagent.created", + "x-stainless-const": true, + "description": "The type of the object. Always `agent.session.subagent.created`." + }, + "event_id": { + "type": "string", + "minLength": 0, + "description": "The unique ID of the event." + }, + "subagent": { + "$ref": "#/components/schemas/SubagentResource", + "description": "The subagent that was created." + } + }, + "required": [ + "type", + "event_id", + "subagent" + ], + "additionalProperties": false, + "description": "Emitted when a subagent is created." + }, + "SessionEventAgentSessionSubagentActive": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "agent.session.subagent.active" + ], + "default": "agent.session.subagent.active", + "x-stainless-const": true, + "description": "The type of the object. Always `agent.session.subagent.active`." + }, + "event_id": { + "type": "string", + "minLength": 0, + "description": "The unique ID of the event." + }, + "subagent": { + "$ref": "#/components/schemas/SubagentResource", + "description": "The subagent that resumed." + } + }, + "required": [ + "type", + "event_id", + "subagent" + ], + "additionalProperties": false, + "description": "Emitted when a closed subagent successfully resumes." + }, + "SessionEventAgentSessionSubagentClosed": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "agent.session.subagent.closed" + ], + "default": "agent.session.subagent.closed", + "x-stainless-const": true, + "description": "The type of the object. Always `agent.session.subagent.closed`." + }, + "event_id": { + "type": "string", + "minLength": 0, + "description": "The unique ID of the event." + }, + "subagent": { + "$ref": "#/components/schemas/SubagentResource", + "description": "The subagent that was closed." + } + }, + "required": [ + "type", + "event_id", + "subagent" + ], + "additionalProperties": false, + "description": "Emitted when a subagent is closed." + }, + "AssistantMessageItemResource": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "message" + ], + "default": "message", + "x-stainless-const": true, + "description": "The item type. Always `message`." + }, + "id": { + "type": "string", + "minLength": 0, + "description": "The ID of the message." + }, + "turn_id": { + "type": "string", + "minLength": 0, + "description": "The ID of the turn that contains this item." + }, + "role": { + "type": "string", + "enum": [ + "assistant" + ], + "default": "assistant", + "x-stainless-const": true, + "description": "The role of the message author. Always `assistant`." + }, + "status": { + "$ref": "#/components/schemas/OutputItemStatusResource", + "description": "The status of the message." + }, + "content": { + "type": "array", + "items": { + "$ref": "#/components/schemas/OutputTextResource" + }, + "minItems": 0, + "maxItems": 2000, + "description": "The content of the message." + }, + "phase": { + "anyOf": [ + { + "$ref": "#/components/schemas/MessagePhaseResource" + }, + { + "type": "null" + } + ], + "description": "The phase of the assistant message." + } + }, + "required": [ + "type", + "id", + "turn_id", + "role", + "status", + "content", + "phase" + ], + "additionalProperties": false, + "description": "An assistant message produced by the agent." + }, + "AgentOutputItemResource": { + "oneOf": [ + { + "$ref": "#/components/schemas/AssistantMessageItemResource" + }, + { + "$ref": "#/components/schemas/ReasoningItemResource" + }, + { + "$ref": "#/components/schemas/FunctionCallItemResource" + }, + { + "$ref": "#/components/schemas/McpCallItemResource" + }, + { + "$ref": "#/components/schemas/WebSearchCallItemResource" + }, + { + "$ref": "#/components/schemas/CommandExecutionItemResource" + }, + { + "$ref": "#/components/schemas/CreateSubagentCallItemResource" + }, + { + "$ref": "#/components/schemas/SendSubagentInputCallItemResource" + }, + { + "$ref": "#/components/schemas/ResumeSubagentCallItemResource" + }, + { + "$ref": "#/components/schemas/WaitForSubagentsCallItemResource" + }, + { + "$ref": "#/components/schemas/InterruptSubagentCallItemResource" + }, + { + "$ref": "#/components/schemas/CloseSubagentCallItemResource" + } + ], + "discriminator": { + "propertyName": "type", + "mapping": { + "message": "#/components/schemas/AssistantMessageItemResource", + "reasoning": "#/components/schemas/ReasoningItemResource", + "function_call": "#/components/schemas/FunctionCallItemResource", + "mcp_call": "#/components/schemas/McpCallItemResource", + "web_search_call": "#/components/schemas/WebSearchCallItemResource", + "command_execution": "#/components/schemas/CommandExecutionItemResource", + "interrupt_subagent_call": "#/components/schemas/InterruptSubagentCallItemResource", + "create_subagent_call": "#/components/schemas/CreateSubagentCallItemResource", + "send_subagent_input_call": "#/components/schemas/SendSubagentInputCallItemResource", + "resume_subagent_call": "#/components/schemas/ResumeSubagentCallItemResource", + "wait_for_subagents_call": "#/components/schemas/WaitForSubagentsCallItemResource", + "close_subagent_call": "#/components/schemas/CloseSubagentCallItemResource" + } + }, + "x-oai-discriminator-values": [ + "message", + "reasoning", + "function_call", + "mcp_call", + "web_search_call", + "command_execution", + "create_subagent_call", + "send_subagent_input_call", + "resume_subagent_call", + "wait_for_subagents_call", + "interrupt_subagent_call", + "close_subagent_call" + ], + "description": "An output item produced by an agent." + }, + "SessionEventAgentSessionTurnItemDone": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "agent.session.turn.item.done" + ], + "default": "agent.session.turn.item.done", + "x-stainless-const": true, + "description": "The type of the object. Always `agent.session.turn.item.done`." + }, + "event_id": { + "type": "string", + "minLength": 0, + "description": "The unique ID of the event." + }, + "session_id": { + "type": "string", + "minLength": 0, + "description": "The ID of the session associated with the event." + }, + "turn_id": { + "type": [ + "string", + "null" + ], + "minLength": 0, + "description": "The ID of the turn associated with the event, when applicable." + }, + "output_index": { + "type": "integer", + "format": "int64", + "minimum": 0, + "maximum": 4294967295, + "description": "The index of the output item in the turn output." + }, + "item": { + "$ref": "#/components/schemas/AgentOutputItemResource", + "description": "The completed output item." + } + }, + "required": [ + "type", + "event_id", + "session_id", + "turn_id", + "output_index", + "item" + ], + "additionalProperties": false, + "description": "Emitted when an output item is complete." + }, + "SessionEventAgentSessionTurnContentPartAdded": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "agent.session.turn.content_part.added" + ], + "default": "agent.session.turn.content_part.added", + "x-stainless-const": true, + "description": "The type of the object. Always `agent.session.turn.content_part.added`." + }, + "event_id": { + "type": "string", + "minLength": 0, + "description": "The unique ID of the event." + }, + "session_id": { + "type": "string", + "minLength": 0, + "description": "The ID of the session associated with the event." + }, + "turn_id": { + "type": [ + "string", + "null" + ], + "minLength": 0, + "description": "The ID of the turn associated with the event, when applicable." + }, + "item_id": { + "type": "string", + "minLength": 0, + "description": "The ID of the message item." + }, + "output_index": { + "type": "integer", + "format": "int64", + "minimum": 0, + "maximum": 4294967295, + "description": "The index of the item in the turn output." + }, + "content_index": { + "type": "integer", + "format": "int64", + "minimum": 0, + "maximum": 4294967295, + "description": "The index of the content part in the message." + }, + "part": { + "$ref": "#/components/schemas/OutputTextResource", + "description": "The initial content part." + } + }, + "required": [ + "type", + "event_id", + "session_id", + "turn_id", + "item_id", + "output_index", + "content_index", + "part" + ], + "additionalProperties": false, + "description": "Emitted when an output text content part is added." + }, + "SessionEventAgentSessionTurnContentPartDone": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "agent.session.turn.content_part.done" + ], + "default": "agent.session.turn.content_part.done", + "x-stainless-const": true, + "description": "The type of the object. Always `agent.session.turn.content_part.done`." + }, + "event_id": { + "type": "string", + "minLength": 0, + "description": "The unique ID of the event." + }, + "session_id": { + "type": "string", + "minLength": 0, + "description": "The ID of the session associated with the event." + }, + "turn_id": { + "type": [ + "string", + "null" + ], + "minLength": 0, + "description": "The ID of the turn associated with the event, when applicable." + }, + "item_id": { + "type": "string", + "minLength": 0, + "description": "The ID of the message item." + }, + "output_index": { + "type": "integer", + "format": "int64", + "minimum": 0, + "maximum": 4294967295, + "description": "The index of the item in the turn output." + }, + "content_index": { + "type": "integer", + "format": "int64", + "minimum": 0, + "maximum": 4294967295, + "description": "The index of the content part in the message." + }, + "part": { + "$ref": "#/components/schemas/OutputTextResource", + "description": "The completed content part." + } + }, + "required": [ + "type", + "event_id", + "session_id", + "turn_id", + "item_id", + "output_index", + "content_index", + "part" + ], + "additionalProperties": false, + "description": "Emitted when an output content part is complete." + }, + "SessionEventAgentSessionTurnOutputTextDelta": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "agent.session.turn.output_text.delta" + ], + "default": "agent.session.turn.output_text.delta", + "x-stainless-const": true, + "description": "The type of the object. Always `agent.session.turn.output_text.delta`." + }, + "event_id": { + "type": "string", + "minLength": 0, + "description": "The unique ID of the event." + }, + "session_id": { + "type": "string", + "minLength": 0, + "description": "The ID of the session associated with the event." + }, + "turn_id": { + "type": [ + "string", + "null" + ], + "minLength": 0, + "description": "The ID of the turn associated with the event, when applicable." + }, + "item_id": { + "type": "string", + "minLength": 0, + "description": "The ID of the message item." + }, + "output_index": { + "type": "integer", + "format": "int64", + "minimum": 0, + "maximum": 4294967295, + "description": "The index of the item in the turn output." + }, + "content_index": { + "type": "integer", + "format": "int64", + "minimum": 0, + "maximum": 4294967295, + "description": "The index of the content part in the message." + }, + "delta": { + "type": "string", + "minLength": 0, + "description": "The text that was appended." + } + }, + "required": [ + "type", + "event_id", + "session_id", + "turn_id", + "item_id", + "output_index", + "content_index", + "delta" + ], + "additionalProperties": false, + "description": "Emitted when text is appended to an output text content part." + }, + "SessionEventAgentSessionTurnOutputTextDone": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "agent.session.turn.output_text.done" + ], + "default": "agent.session.turn.output_text.done", + "x-stainless-const": true, + "description": "The type of the object. Always `agent.session.turn.output_text.done`." + }, + "event_id": { + "type": "string", + "minLength": 0, + "description": "The unique ID of the event." + }, + "session_id": { + "type": "string", + "minLength": 0, + "description": "The ID of the session associated with the event." + }, + "turn_id": { + "type": [ + "string", + "null" + ], + "minLength": 0, + "description": "The ID of the turn associated with the event, when applicable." + }, + "item_id": { + "type": "string", + "minLength": 0, + "description": "The ID of the message item." + }, + "output_index": { + "type": "integer", + "format": "int64", + "minimum": 0, + "maximum": 4294967295, + "description": "The index of the item in the turn output." + }, + "content_index": { + "type": "integer", + "format": "int64", + "minimum": 0, + "maximum": 4294967295, + "description": "The index of the content part in the message." + }, + "text": { + "type": "string", + "minLength": 0, + "description": "The complete output text." + } + }, + "required": [ + "type", + "event_id", + "session_id", + "turn_id", + "item_id", + "output_index", + "content_index", + "text" + ], + "additionalProperties": false, + "description": "Emitted when an output text content part is complete." + }, + "SessionEventAgentSessionTurnReasoningSummaryPartAdded": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "agent.session.turn.reasoning_summary_part.added" + ], + "default": "agent.session.turn.reasoning_summary_part.added", + "x-stainless-const": true, + "description": "The type of the object. Always `agent.session.turn.reasoning_summary_part.added`." + }, + "event_id": { + "type": "string", + "minLength": 0, + "description": "The unique ID of the event." + }, + "session_id": { + "type": "string", + "minLength": 0, + "description": "The ID of the session associated with the event." + }, + "turn_id": { + "type": [ + "string", + "null" + ], + "minLength": 0, + "description": "The ID of the turn associated with the event, when applicable." + }, + "item_id": { + "type": "string", + "minLength": 0, + "description": "The ID of the reasoning item." + }, + "output_index": { + "type": "integer", + "format": "int64", + "minimum": 0, + "maximum": 4294967295, + "description": "The index of the item in the turn output." + }, + "summary_index": { + "type": "integer", + "format": "int64", + "minimum": 0, + "maximum": 4294967295, + "description": "The index of the summary content part." + }, + "part": { + "$ref": "#/components/schemas/SummaryTextResource", + "description": "The initial summary part." + } + }, + "required": [ + "type", + "event_id", + "session_id", + "turn_id", + "item_id", + "output_index", + "summary_index", + "part" + ], + "additionalProperties": false, + "description": "Emitted when a reasoning summary content part is added." + }, + "SessionEventAgentSessionTurnReasoningSummaryPartDone": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "agent.session.turn.reasoning_summary_part.done" + ], + "default": "agent.session.turn.reasoning_summary_part.done", + "x-stainless-const": true, + "description": "The type of the object. Always `agent.session.turn.reasoning_summary_part.done`." + }, + "event_id": { + "type": "string", + "minLength": 0, + "description": "The unique ID of the event." + }, + "session_id": { + "type": "string", + "minLength": 0, + "description": "The ID of the session associated with the event." + }, + "turn_id": { + "type": [ + "string", + "null" + ], + "minLength": 0, + "description": "The ID of the turn associated with the event, when applicable." + }, + "item_id": { + "type": "string", + "minLength": 0, + "description": "The ID of the reasoning item." + }, + "output_index": { + "type": "integer", + "format": "int64", + "minimum": 0, + "maximum": 4294967295, + "description": "The index of the item in the turn output." + }, + "summary_index": { + "type": "integer", + "format": "int64", + "minimum": 0, + "maximum": 4294967295, + "description": "The index of the summary part." + }, + "part": { + "$ref": "#/components/schemas/SummaryTextResource", + "description": "The completed summary part." + }, + "status": { + "type": [ + "string", + "null" + ], + "enum": [ + "incomplete", + null + ], + "description": "Present as `incomplete` when summary generation was interrupted.", + "x-stainless-const": true + } + }, + "required": [ + "type", + "event_id", + "session_id", + "turn_id", + "item_id", + "output_index", + "summary_index", + "part", + "status" + ], + "additionalProperties": false, + "description": "Emitted when a reasoning summary part is complete." + }, + "SessionEventAgentSessionTurnReasoningSummaryTextDelta": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "agent.session.turn.reasoning_summary_text.delta" + ], + "default": "agent.session.turn.reasoning_summary_text.delta", + "x-stainless-const": true, + "description": "The type of the object. Always `agent.session.turn.reasoning_summary_text.delta`." + }, + "event_id": { + "type": "string", + "minLength": 0, + "description": "The unique ID of the event." + }, + "session_id": { + "type": "string", + "minLength": 0, + "description": "The ID of the session associated with the event." + }, + "turn_id": { + "type": [ + "string", + "null" + ], + "minLength": 0, + "description": "The ID of the turn associated with the event, when applicable." + }, + "item_id": { + "type": "string", + "minLength": 0, + "description": "The ID of the reasoning item." + }, + "output_index": { + "type": "integer", + "format": "int64", + "minimum": 0, + "maximum": 4294967295, + "description": "The index of the item in the turn output." + }, + "summary_index": { + "type": "integer", + "format": "int64", + "minimum": 0, + "maximum": 4294967295, + "description": "The index of the summary content part." + }, + "delta": { + "type": "string", + "minLength": 0, + "description": "The summary text that was appended." + } + }, + "required": [ + "type", + "event_id", + "session_id", + "turn_id", + "item_id", + "output_index", + "summary_index", + "delta" + ], + "additionalProperties": false, + "description": "Emitted when text is appended to a reasoning summary." + }, + "SessionEventAgentSessionTurnReasoningSummaryTextDone": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "agent.session.turn.reasoning_summary_text.done" + ], + "default": "agent.session.turn.reasoning_summary_text.done", + "x-stainless-const": true, + "description": "The type of the object. Always `agent.session.turn.reasoning_summary_text.done`." + }, + "event_id": { + "type": "string", + "minLength": 0, + "description": "The unique ID of the event." + }, + "session_id": { + "type": "string", + "minLength": 0, + "description": "The ID of the session associated with the event." + }, + "turn_id": { + "type": [ + "string", + "null" + ], + "minLength": 0, + "description": "The ID of the turn associated with the event, when applicable." + }, + "item_id": { + "type": "string", + "minLength": 0, + "description": "The ID of the reasoning item." + }, + "output_index": { + "type": "integer", + "format": "int64", + "minimum": 0, + "maximum": 4294967295, + "description": "The index of the item in the turn output." + }, + "summary_index": { + "type": "integer", + "format": "int64", + "minimum": 0, + "maximum": 4294967295, + "description": "The index of the summary content part." + }, + "text": { + "type": "string", + "minLength": 0, + "description": "The complete reasoning summary text." + } + }, + "required": [ + "type", + "event_id", + "session_id", + "turn_id", + "item_id", + "output_index", + "summary_index", + "text" + ], + "additionalProperties": false, + "description": "Emitted when a reasoning summary content part is complete." + }, + "SessionEvent": { + "oneOf": [ + { + "$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" + } + ], + "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" + } + }, + "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" + ], + "description": "An event emitted by a Managed Agents session." + }, + "UpdateAgentSessionParams": { + "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": "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", + "properties": { + "id": { + "type": "string", + "minLength": 0, + "description": "The ID of the deleted session." + }, + "object": { + "type": "string", + "enum": [ + "agent.session.deleted" + ], + "default": "agent.session.deleted", + "x-stainless-const": true, + "description": "The object type. Always `agent.session.deleted`." + }, + "deleted": { + "type": "boolean", + "description": "Whether the session has been removed from the public API. Always `true`. Physical cleanup may still be in progress." + } + }, + "required": [ + "id", + "object", + "deleted" + ], + "additionalProperties": false, + "description": "A Managed Agents session removed from the public API. Physical cleanup may continue asynchronously." + }, + "SessionArtifactResource": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 0, + "description": "The immutable artifact ID." + }, + "object": { + "type": "string", + "enum": [ + "agent.session.artifact" + ], + "default": "agent.session.artifact", + "x-stainless-const": true, + "description": "The object type. Always `agent.session.artifact`." + }, + "session_id": { + "type": "string", + "minLength": 0, + "description": "The ID of the session that owns the artifact." + }, + "environment_id": { + "type": "string", + "minLength": 0, + "description": "The ID of the environment that produced the artifact." + }, + "turn_id": { + "type": "string", + "minLength": 0, + "description": "The ID of the completed turn that published the artifact." + }, + "path": { + "type": "string", + "minLength": 0, + "description": "The original absolute file path in the execution environment." + }, + "size_bytes": { + "type": "integer", + "format": "int64", + "minimum": 0, + "description": "The immutable artifact size in bytes." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "The Unix timestamp, in seconds, when the artifact was published." + } + }, + "required": [ + "id", + "object", + "session_id", + "environment_id", + "turn_id", + "path", + "size_bytes", + "created_at" + ], + "additionalProperties": false, + "description": "An immutable file published by a completed hosted session turn." + }, + "SessionArtifactListResource": { + "type": "object", + "properties": { + "object": { + "type": "string", + "enum": [ + "list" + ], + "default": "list", + "x-stainless-const": true, + "description": "The object type, which is always `list`." + }, + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SessionArtifactResource" + }, + "minItems": 0, + "maxItems": 2000, + "description": "The resources returned in this page, in the requested sort order." + }, + "first_id": { + "type": [ + "string", + "null" + ], + "minLength": 0, + "description": "The ID of the first resource in `data`, or `null` if the page is empty." + }, + "last_id": { + "type": [ + "string", + "null" + ], + "minLength": 0, + "description": "The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters." + }, + "has_more": { + "type": "boolean", + "description": "Whether there are more resources to retrieve after this page." + } + }, + "required": [ + "object", + "data", + "first_id", + "last_id", + "has_more" + ], + "additionalProperties": false, + "description": "A page of Agents API resources, with IDs for retrieving additional pages." + }, + "DeletedSessionArtifactResource": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 0, + "description": "The ID of the deleted session artifact." + }, + "object": { + "type": "string", + "enum": [ + "agent.session.artifact.deleted" + ], + "default": "agent.session.artifact.deleted", + "x-stainless-const": true, + "description": "The object type. Always `agent.session.artifact.deleted`." + }, + "deleted": { + "type": "boolean", + "description": "Whether the session artifact was deleted. Always `true`." + } + }, + "required": [ + "id", + "object", + "deleted" + ], + "additionalProperties": false, + "description": "Confirmation that an immutable session artifact was deleted." + }, + "SessionInputParamAgentSessionInputMessage": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "agent.session.input.message" + ], + "default": "agent.session.input.message", + "x-stainless-const": true, + "description": "The type of the object. Always `agent.session.input.message`." + }, + "input": { + "type": "array", + "items": { + "$ref": "#/components/schemas/InputMessageParam" + }, + "minItems": 0, + "maxItems": 16384, + "description": "The user messages to add to the session." + } + }, + "required": [ + "type", + "input" + ], + "additionalProperties": false, + "description": "Adds one or more user messages and starts a turn." + }, + "SessionInputParamAgentSessionInputCancel": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "agent.session.input.cancel" + ], + "default": "agent.session.input.cancel", + "x-stainless-const": true, + "description": "The type of the object. Always `agent.session.input.cancel`." + } + }, + "required": [ + "type" + ], + "additionalProperties": false, + "description": "Cancels the session's active turn." + }, + "FunctionCallOutputParam": { + "oneOf": [ + { + "type": "string", + "minLength": 0, + "maxLength": 1048576 + }, + { + "type": "array", + "items": { + "$ref": "#/components/schemas/InputContentParam" + }, + "minItems": 0, + "maxItems": 16384 + } + ], + "description": "A function result represented as text or supported model-input content." + }, + "SessionInputParamAgentSessionInputToolResult": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "agent.session.input.tool_result" + ], + "default": "agent.session.input.tool_result", + "x-stainless-const": true, + "description": "The type of the object. Always `agent.session.input.tool_result`." + }, + "turn_id": { + "type": "string", + "minLength": 0, + "maxLength": 1048576, + "description": "The ID of the turn that requested the function call." + }, + "call_id": { + "type": "string", + "minLength": 0, + "maxLength": 1048576, + "description": "The ID of the function call." + }, + "success": { + "type": "boolean", + "description": "Whether the function call succeeded." + }, + "output": { + "anyOf": [ + { + "$ref": "#/components/schemas/FunctionCallOutputParam" + }, + { + "type": "null" + } + ], + "description": "The function result when the call succeeded." + }, + "error": { + "type": [ + "string", + "null" + ], + "minLength": 0, + "maxLength": 1048576, + "description": "The error message when the call failed." + } + }, + "required": [ + "type", + "turn_id", + "call_id", + "success" + ], + "additionalProperties": false, + "description": "Submits the result of a function call." + }, + "SessionInputParam": { + "oneOf": [ + { + "$ref": "#/components/schemas/SessionInputParamAgentSessionInputMessage" + }, + { + "$ref": "#/components/schemas/SessionInputParamAgentSessionInputCancel" + }, + { + "$ref": "#/components/schemas/SessionInputParamAgentSessionInputToolResult" + } + ], + "discriminator": { + "propertyName": "type", + "mapping": { + "agent.session.input.message": "#/components/schemas/SessionInputParamAgentSessionInputMessage", + "agent.session.input.cancel": "#/components/schemas/SessionInputParamAgentSessionInputCancel", + "agent.session.input.tool_result": "#/components/schemas/SessionInputParamAgentSessionInputToolResult" + } + }, + "x-oai-discriminator-values": [ + "agent.session.input.message", + "agent.session.input.cancel", + "agent.session.input.tool_result" + ], + "description": "Input submitted to an existing session." + }, + "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": [ + "active", + "archived" + ], + "description": "Whether a vault or credential is active or archived." + }, + "VaultStatusFilterParam": { + "oneOf": [ + { + "$ref": "#/components/schemas/VaultStatusParam" + }, + { + "type": "array", + "items": { + "$ref": "#/components/schemas/VaultStatusParam" + }, + "minItems": 0, + "maxItems": 16384 + } + ], + "description": "One or more lifecycle statuses to include when listing vaults or credentials." + }, + "VaultResource": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 0, + "description": "The ID of the vault." + }, + "object": { + "type": "string", + "enum": [ + "vault" + ], + "default": "vault", + "x-stainless-const": true, + "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": [ + "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", + "items": { + "$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", + "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`." + } + }, + "required": [ + "id", + "object", + "deleted" + ], + "additionalProperties": false, + "description": "Confirmation that a vault was deleted." + }, + "McpOauthTokenEndpointAuthResourceNone": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "none" + ], + "default": "none", + "x-stainless-const": true, + "description": "The type of the object. Always `none`." + } + }, + "required": [ + "type" + ], + "additionalProperties": false, + "description": "Sends the client ID without a client secret." + }, + "McpOauthTokenEndpointAuthResourceClientSecretBasic": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "client_secret_basic" + ], + "default": "client_secret_basic", + "x-stainless-const": true, + "description": "The type of the object. Always `client_secret_basic`." + } + }, + "required": [ + "type" + ], + "additionalProperties": false, + "description": "Sends the client ID and secret using HTTP Basic authentication." + }, + "McpOauthTokenEndpointAuthResourceClientSecretPost": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "client_secret_post" + ], + "default": "client_secret_post", + "x-stainless-const": true, + "description": "The type of the object. Always `client_secret_post`." + } + }, + "required": [ + "type" + ], + "additionalProperties": false, + "description": "Sends the client ID and secret in the token request body." + }, + "McpOauthTokenEndpointAuthResource": { + "oneOf": [ + { + "$ref": "#/components/schemas/McpOauthTokenEndpointAuthResourceNone" + }, + { + "$ref": "#/components/schemas/McpOauthTokenEndpointAuthResourceClientSecretBasic" + }, + { + "$ref": "#/components/schemas/McpOauthTokenEndpointAuthResourceClientSecretPost" + } + ], + "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" + ], + "description": "The client authentication method used for OAuth token refresh." + }, + "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": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "mcp_oauth" + ], + "default": "mcp_oauth", + "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": { + "type": [ + "string", + "null" + ], + "minLength": 0, + "description": "When the OAuth access token expires, as an RFC 3339 timestamp, if known." + }, + "refresh": { + "anyOf": [ + { + "$ref": "#/components/schemas/McpOauthRefreshResource" + }, + { + "type": "null" + } + ], + "description": "Public refresh metadata without refresh tokens or OAuth client secrets." + } + }, + "required": [ + "type", + "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": { + "type": { + "type": "string", + "enum": [ + "static_bearer" + ], + "default": "static_bearer", + "x-stainless-const": true, + "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." + }, + "VaultCredentialAuthResource": { + "oneOf": [ + { + "$ref": "#/components/schemas/VaultCredentialAuthResourceMcpOauth" + }, + { + "$ref": "#/components/schemas/VaultCredentialAuthResourceStaticBearer" + } + ], + "discriminator": { + "propertyName": "type", + "mapping": { + "mcp_oauth": "#/components/schemas/VaultCredentialAuthResourceMcpOauth", + "static_bearer": "#/components/schemas/VaultCredentialAuthResourceStaticBearer" + } + }, + "x-oai-discriminator-values": [ + "mcp_oauth", + "static_bearer" + ], + "description": "The MCP server and authentication configuration of a vault credential, excluding secrets." + }, + "VaultCredentialResource": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 0, + "description": "The ID of the credential." + }, + "object": { + "type": "string", + "enum": [ + "vault.credential" + ], + "default": "vault.credential", + "x-stainless-const": true, + "description": "The object type. Always `vault.credential`." + }, + "vault_id": { + "type": "string", + "minLength": 0, + "description": "The ID of the vault containing this credential." + }, + "name": { + "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": { + "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", + "properties": { + "type": { + "type": "string", + "enum": [ + "none" + ], + "default": "none", + "x-stainless-const": true, + "description": "The type of the object. Always `none`." + } + }, + "required": [ + "type" + ], + "additionalProperties": false, + "description": "Sends the client ID without a client secret." + }, + "CreateMcpOauthTokenEndpointAuthParamClientSecretBasic": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "client_secret_basic" + ], + "default": "client_secret_basic", + "x-stainless-const": true, + "description": "The type of the object. Always `client_secret_basic`." + }, + "client_secret": { + "type": "string", + "minLength": 0, + "maxLength": 1048576, + "description": "The OAuth client secret to store. Never returned in credential resources." + } + }, + "required": [ + "type", + "client_secret" + ], + "additionalProperties": false, + "description": "Sends the client ID and secret using HTTP Basic authentication." + }, + "CreateMcpOauthTokenEndpointAuthParamClientSecretPost": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "client_secret_post" + ], + "default": "client_secret_post", + "x-stainless-const": true, + "description": "The type of the object. Always `client_secret_post`." + }, + "client_secret": { + "type": "string", + "minLength": 0, + "maxLength": 1048576, + "description": "The OAuth client secret to store. Never returned in credential resources." + } + }, + "required": [ + "type", + "client_secret" + ], + "additionalProperties": false, + "description": "Sends the client ID and secret in the token request body." + }, + "CreateMcpOauthTokenEndpointAuthParam": { + "oneOf": [ + { + "$ref": "#/components/schemas/CreateMcpOauthTokenEndpointAuthParamNone" + }, + { + "$ref": "#/components/schemas/CreateMcpOauthTokenEndpointAuthParamClientSecretBasic" + }, + { + "$ref": "#/components/schemas/CreateMcpOauthTokenEndpointAuthParamClientSecretPost" + } + ], + "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" + ], + "description": "Client authentication credentials for OAuth token refresh." + }, + "CreateMcpOauthRefreshParam": { + "type": "object", + "properties": { + "token_endpoint": { + "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": { + "type": "string", + "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": [ + "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": [ + "mcp_oauth" + ], + "default": "mcp_oauth", + "x-stainless-const": true, + "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/CreateMcpOauthRefreshParam" + }, + { + "type": "null" + } + ], + "description": "Optional refresh configuration for an HTTPS OAuth token endpoint." + } + }, + "required": [ + "type", + "mcp_server_url", + "access_token" + ], + "additionalProperties": false, + "description": "An OAuth credential for an HTTPS MCP destination." + }, + "CreateVaultCredentialAuthParamStaticBearer": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "static_bearer" + ], + "default": "static_bearer", + "x-stainless-const": true, + "description": "The type of the object. Always `static_bearer`." + }, + "mcp_server_url": { + "type": "string", + "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", + "mcp_server_url", + "token" + ], + "additionalProperties": false, + "description": "A bearer token for an MCP server, without automatic OAuth refresh." + }, + "CreateVaultCredentialAuthParam": { + "oneOf": [ + { + "$ref": "#/components/schemas/CreateVaultCredentialAuthParamMcpOauth" + }, + { + "$ref": "#/components/schemas/CreateVaultCredentialAuthParamStaticBearer" + } + ], + "discriminator": { + "propertyName": "type", + "mapping": { + "mcp_oauth": "#/components/schemas/CreateVaultCredentialAuthParamMcpOauth", + "static_bearer": "#/components/schemas/CreateVaultCredentialAuthParamStaticBearer" + } + }, + "x-oai-discriminator-values": [ + "mcp_oauth", + "static_bearer" + ], + "description": "Authentication credentials for an MCP server used by agent tools." + }, + "CreateVaultCredentialParams": { + "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." + }, + "auth": { + "$ref": "#/components/schemas/CreateVaultCredentialAuthParam", + "description": "The authentication method and secret values to store for the MCP server." + } + }, + "required": [ + "auth", + "name" + ], + "additionalProperties": false, + "description": "Parameters for storing a credential that authorizes access to an MCP server." + }, + "RotateMcpOauthTokenEndpointAuthParamClientSecretBasic": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "client_secret_basic" + ], + "default": "client_secret_basic", + "x-stainless-const": true, + "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": [ + "type" + ], + "additionalProperties": false, + "description": "Updates credentials sent using HTTP Basic authentication." + }, + "RotateMcpOauthTokenEndpointAuthParamClientSecretPost": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "client_secret_post" + ], + "default": "client_secret_post", + "x-stainless-const": true, + "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" + ], + "additionalProperties": false, + "description": "Updates credentials sent in the token request body." + }, + "RotateMcpOauthTokenEndpointAuthParam": { + "oneOf": [ + { + "$ref": "#/components/schemas/RotateMcpOauthTokenEndpointAuthParamClientSecretBasic" + }, + { + "$ref": "#/components/schemas/RotateMcpOauthTokenEndpointAuthParamClientSecretPost" + } + ], + "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" + ], + "description": "Client-secret updates that preserve the credential's OAuth authentication method." + }, + "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": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "mcp_oauth" + ], + "default": "mcp_oauth", + "x-stainless-const": true, + "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/RotateMcpOauthRefreshParam" + }, + { + "type": "null" + } + ], + "description": "Optional write-only refresh-token and client-secret updates." + } + }, + "required": [ + "type" + ], + "additionalProperties": false, + "description": "Rotate an OAuth credential for an HTTPS MCP destination." + }, + "RotateVaultCredentialAuthParamStaticBearer": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "static_bearer" + ], + "default": "static_bearer", + "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." + } + }, + "required": [ + "type", + "token" + ], + "additionalProperties": false, + "description": "Replace the bearer token for the credential's MCP server." + }, + "RotateVaultCredentialAuthParam": { + "oneOf": [ + { + "$ref": "#/components/schemas/RotateVaultCredentialAuthParamMcpOauth" + }, + { + "$ref": "#/components/schemas/RotateVaultCredentialAuthParamStaticBearer" + } + ], + "discriminator": { + "propertyName": "type", + "mapping": { + "mcp_oauth": "#/components/schemas/RotateVaultCredentialAuthParamMcpOauth", + "static_bearer": "#/components/schemas/RotateVaultCredentialAuthParamStaticBearer" + } + }, + "x-oai-discriminator-values": [ + "mcp_oauth", + "static_bearer" + ], + "description": "Updates to a vault credential without changing its authentication method or MCP server." + }, + "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", + "properties": { + "id": { + "type": "string", + "minLength": 0, + "description": "The ID of the deleted credential." + }, + "object": { + "type": "string", + "enum": [ + "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": [ + "id", + "object", + "deleted" + ], + "additionalProperties": false, + "description": "Confirmation that a vault credential was deleted." + }, + "v1.AgentsCore": { + "properties": { + "harness": { + "enum": [ + "claude_sdk", + "codex", + "mcode" + ], + "type": "string" + }, + "harness_config": { + "type": "object" + } + }, + "type": "object" + }, + "v1.EnvironmentInstallation": { + "properties": { + "commands": { + "additionalProperties": { + "type": "string" + }, + "type": "object" + }, + "expires_at": { + "type": "integer" + }, + "message": { + "type": "string" + }, + "status": { + "enum": [ + "available", + "unavailable" + ], + "type": "string" + }, + "version": { + "type": "string" + } + }, + "type": "object" + }, + "v1.ModelProviderInput": { + "properties": { + "api_key": { + "type": "string" + }, + "base_url": { + "type": "string" + }, + "context_window": { + "type": "integer" + }, + "max_output_tokens": { + "type": "integer" + }, + "protocol": { + "enum": [ + "anthropic", + "responses", + "chat_completions" + ], + "type": "string" + } + }, + "required": [ + "api_key", + "base_url", + "protocol" + ], + "type": "object" + }, + "v1.ModelProviderView": { + "properties": { + "api_key_configured": { + "type": "boolean" + }, + "base_url": { + "type": "string" + }, + "context_window": { + "type": "integer" + }, + "max_output_tokens": { + "type": "integer" + }, + "protocol": { + "enum": [ + "anthropic", + "responses", + "chat_completions" + ], + "type": "string" + } + }, + "required": [ + "api_key_configured", + "base_url", + "protocol" + ], + "type": "object" + }, + "v1.SavedAgentCore": { + "properties": { + "harness": { + "enum": [ + "claude_sdk", + "codex", + "mcode" + ], + "type": "string" + }, + "harness_config": { + "type": "object" + }, + "model_provider": { + "$ref": "#/components/schemas/v1.ModelProviderView" + } + }, + "type": "object" + }, + "v1.SavedAgentCoreInput": { + "properties": { + "harness": { + "enum": [ + "claude_sdk", + "codex", + "mcode" + ], + "type": "string" + }, + "harness_config": { + "type": "object" + }, + "model_provider": { + "anyOf": [ + { + "allOf": [ + { + "$ref": "#/components/schemas/v1.ModelProviderInput" + } + ] + }, + { + "type": "null" + } + ] + } + }, + "type": "object" + }, + "v1.SessionCore": { + "properties": { + "installation": { + "$ref": "#/components/schemas/v1.EnvironmentInstallation" + } + }, + "type": "object" + }, + "v1.SessionExecutionInput": { + "properties": { + "environment": { + "description": "Environment supplies placement-independent preparation through the Core extension.", + "type": "object" + }, + "harness_config": { + "type": "object" + }, + "model_provider": { + "$ref": "#/components/schemas/v1.ModelProviderInput" + } + }, + "type": "object" + } + }, + "responses": { + "TooManyRequests": { + "description": "The request was rejected because a rate limit was exceeded.", + "headers": { + "Retry-After": { + "description": "The minimum number of seconds to wait before retrying. This header is returned when the server has computed a retry delay and may be omitted for 429 responses that require user action.", + "schema": { + "type": "integer", + "minimum": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + }, + "securitySchemes": { + "ProjectKey": { + "type": "http", + "scheme": "bearer", + "description": "OpenAgentCore Project API key." + } + } + }, + "x-oaiMeta": { + "navigationGroups": [ + { + "id": "responses", + "title": "Responses API" + }, + { + "id": "webhooks", + "title": "Webhooks" + }, + { + "id": "endpoints", + "title": "Platform APIs" + }, + { + "id": "vector_stores", + "title": "Vector stores" + }, + { + "id": "chatkit", + "title": "ChatKit", + "beta": true + }, + { + "id": "containers", + "title": "Containers" + }, + { + "id": "live", + "title": "Live (alpha)" + }, + { + "id": "realtime", + "title": "Realtime" + }, + { + "id": "chat", + "title": "Chat Completions" + }, + { + "id": "assistants", + "title": "Assistants", + "deprecated": true + }, + { + "id": "administration", + "title": "Administration" + }, + { + "id": "legacy", + "title": "Legacy" + } + ], + "groups": [ + { + "id": "responses-streaming", + "title": "Streaming events", + "description": "When you [create a Response](https://developers.openai.com/api/reference/resources/responses/methods/create) with\n`stream` set to `true`, the server will emit server-sent events to the\nclient as the Response is generated. This section contains the events that\nare emitted by the server.\n\n[Learn more about streaming responses](https://developers.openai.com/api/docs/guides/streaming-responses).\n", + "navigationGroup": "responses", + "sections": [ + { + "type": "object", + "key": "ResponseCreatedEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseInProgressEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseCompletedEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseFailedEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseIncompleteEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseOutputItemAddedEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseOutputItemDoneEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseContentPartAddedEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseContentPartDoneEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseTextDeltaEvent", + "path": "response/output_text/delta" + }, + { + "type": "object", + "key": "ResponseTextDoneEvent", + "path": "response/output_text/done" + }, + { + "type": "object", + "key": "ResponseRefusalDeltaEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseRefusalDoneEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseFunctionCallArgumentsDeltaEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseFunctionCallArgumentsDoneEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseFileSearchCallInProgressEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseFileSearchCallSearchingEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseFileSearchCallCompletedEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseWebSearchCallInProgressEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseWebSearchCallSearchingEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseWebSearchCallCompletedEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseReasoningSummaryPartAddedEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseReasoningSummaryPartDoneEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseReasoningSummaryTextDeltaEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseReasoningSummaryTextDoneEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseReasoningTextDeltaEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseReasoningTextDoneEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseImageGenCallCompletedEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseImageGenCallGeneratingEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseImageGenCallInProgressEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseImageGenCallPartialImageEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseMCPCallArgumentsDeltaEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseMCPCallArgumentsDoneEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseMCPCallCompletedEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseMCPCallFailedEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseMCPCallInProgressEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseMCPListToolsCompletedEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseMCPListToolsFailedEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseMCPListToolsInProgressEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseCodeInterpreterCallInProgressEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseCodeInterpreterCallInterpretingEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseCodeInterpreterCallCompletedEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseCodeInterpreterCallCodeDeltaEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseCodeInterpreterCallCodeDoneEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseOutputTextAnnotationAddedEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseQueuedEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseCustomToolCallInputDeltaEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseCustomToolCallInputDoneEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseErrorEvent", + "path": "" + } + ] + }, + { + "id": "responses-websocket-client-events", + "title": "Client events", + "description": "Events sent by the client over a Responses API WebSocket connection.\n", + "navigationGroup": "responses", + "sections": [ + { + "type": "object", + "key": "ResponsesClientEventResponseCreate", + "path": "" + }, + { + "type": "object", + "key": "ResponseSteerEvent", + "path": "" + } + ] + }, + { + "id": "responses-websocket-server-events", + "title": "Server events (WebSocket only)", + "description": "Events emitted only over a Responses API WebSocket connection.\n", + "navigationGroup": "responses", + "sections": [ + { + "type": "object", + "key": "ResponseSteerAcceptedEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseSteerPendingEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseSteerFailedEvent", + "path": "" + } + ] + }, + { + "id": "responses-websocket-shared-events", + "title": "Server events", + "description": "These events use the same payloads over WebSocket and\n[HTTP streaming](https://developers.openai.com/api/reference/resources/responses/streaming-events).\n", + "navigationGroup": "responses", + "sections": [ + { + "type": "object", + "key": "ResponseCreatedEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseInProgressEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseCompletedEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseFailedEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseIncompleteEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseOutputItemAddedEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseOutputItemDoneEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseContentPartAddedEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseContentPartDoneEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseTextDeltaEvent", + "path": "response/output_text/delta" + }, + { + "type": "object", + "key": "ResponseTextDoneEvent", + "path": "response/output_text/done" + }, + { + "type": "object", + "key": "ResponseRefusalDeltaEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseRefusalDoneEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseFunctionCallArgumentsDeltaEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseFunctionCallArgumentsDoneEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseFileSearchCallInProgressEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseFileSearchCallSearchingEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseFileSearchCallCompletedEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseWebSearchCallInProgressEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseWebSearchCallSearchingEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseWebSearchCallCompletedEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseReasoningSummaryPartAddedEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseReasoningSummaryPartDoneEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseReasoningSummaryTextDeltaEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseReasoningSummaryTextDoneEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseReasoningTextDeltaEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseReasoningTextDoneEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseImageGenCallCompletedEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseImageGenCallGeneratingEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseImageGenCallInProgressEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseImageGenCallPartialImageEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseMCPCallArgumentsDeltaEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseMCPCallArgumentsDoneEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseMCPCallCompletedEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseMCPCallFailedEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseMCPCallInProgressEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseMCPListToolsCompletedEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseMCPListToolsFailedEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseMCPListToolsInProgressEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseCodeInterpreterCallInProgressEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseCodeInterpreterCallInterpretingEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseCodeInterpreterCallCompletedEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseCodeInterpreterCallCodeDeltaEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseCodeInterpreterCallCodeDoneEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseOutputTextAnnotationAddedEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseQueuedEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseCustomToolCallInputDeltaEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseCustomToolCallInputDoneEvent", + "path": "" + }, + { + "type": "object", + "key": "ResponseErrorEvent", + "path": "" + } + ] + }, + { + "id": "safety-alerts", + "title": "Safety Alerts", + "description": "Retrieve approved safety alerts with an API key. Project keys require\n`api.safety.alerts.read` and can read alerts from their project.\n", + "navigationGroup": "endpoints", + "sections": [ + { + "type": "endpoint", + "key": "Getprojectsafetyalert", + "path": "retrieve" + }, + { + "type": "object", + "key": "SafetyAlertResource", + "path": "object" + } + ] + }, + { + "id": "webhook-events", + "title": "Webhook Events", + "description": "Webhooks are HTTP requests sent by OpenAI to a URL you specify when certain\nevents happen during the course of API usage.\n\n[Learn more about webhooks](https://developers.openai.com/api/docs/guides/webhooks).\n", + "navigationGroup": "webhooks", + "sections": [ + { + "type": "object", + "key": "WebhookResponseCompleted", + "path": "" + }, + { + "type": "object", + "key": "WebhookResponseCancelled", + "path": "" + }, + { + "type": "object", + "key": "WebhookResponseFailed", + "path": "" + }, + { + "type": "object", + "key": "WebhookResponseIncomplete", + "path": "" + }, + { + "type": "object", + "key": "WebhookBatchCompleted", + "path": "" + }, + { + "type": "object", + "key": "WebhookBatchCancelled", + "path": "" + }, + { + "type": "object", + "key": "WebhookBatchExpired", + "path": "" + }, + { + "type": "object", + "key": "WebhookBatchFailed", + "path": "" + }, + { + "type": "object", + "key": "WebhookFineTuningJobSucceeded", + "path": "" + }, + { + "type": "object", + "key": "WebhookFineTuningJobFailed", + "path": "" + }, + { + "type": "object", + "key": "WebhookFineTuningJobCancelled", + "path": "" + }, + { + "type": "object", + "key": "WebhookEvalRunSucceeded", + "path": "" + }, + { + "type": "object", + "key": "WebhookEvalRunFailed", + "path": "" + }, + { + "type": "object", + "key": "WebhookEvalRunCanceled", + "path": "" + }, + { + "type": "object", + "key": "WebhookRealtimeCallIncoming", + "path": "" + }, + { + "type": "object", + "key": "WebhookLiveCallIncoming", + "path": "" + }, + { + "type": "object", + "key": "WebhookLiveTransportIncoming", + "path": "" + }, + { + "type": "object", + "key": "WebhookSafetyAlertCreated", + "path": "" + }, + { + "type": "object", + "key": "WebhookSafetyOrgAlertCreated", + "path": "" + } + ] + }, + { + "id": "images-streaming", + "title": "Image Streaming", + "description": "Stream image generation and editing in real time with server-sent events.\n[Learn more about image streaming](https://developers.openai.com/api/docs/guides/image-generation).\n", + "navigationGroup": "endpoints", + "sections": [ + { + "type": "object", + "key": "ImageGenPartialImageEvent", + "path": "" + }, + { + "type": "object", + "key": "ImageGenCompletedEvent", + "path": "" + }, + { + "type": "object", + "key": "ImageEditPartialImageEvent", + "path": "" + }, + { + "type": "object", + "key": "ImageEditCompletedEvent", + "path": "" + } + ] + }, + { + "id": "realtime-client-events", + "title": "Client events", + "description": "These are events that the OpenAI Realtime WebSocket server will accept from the client.\n", + "navigationGroup": "realtime", + "sections": [ + { + "type": "object", + "key": "RealtimeClientEventSessionUpdate", + "path": "" + }, + { + "type": "object", + "key": "RealtimeClientEventInputAudioBufferAppend", + "path": "" + }, + { + "type": "object", + "key": "RealtimeClientEventInputAudioBufferCommit", + "path": "" + }, + { + "type": "object", + "key": "RealtimeClientEventInputAudioBufferClear", + "path": "" + }, + { + "type": "object", + "key": "RealtimeClientEventConversationItemCreate", + "path": "" + }, + { + "type": "object", + "key": "RealtimeClientEventConversationItemRetrieve", + "path": "" + }, + { + "type": "object", + "key": "RealtimeClientEventConversationItemTruncate", + "path": "" + }, + { + "type": "object", + "key": "RealtimeClientEventConversationItemDelete", + "path": "" + }, + { + "type": "object", + "key": "RealtimeClientEventResponseCreate", + "path": "" + }, + { + "type": "object", + "key": "RealtimeClientEventResponseCancel", + "path": "" + }, + { + "type": "object", + "key": "RealtimeClientEventOutputAudioBufferClear", + "path": "" + } + ] + }, + { + "id": "realtime-server-events", + "title": "Server events", + "description": "These are events emitted from the OpenAI Realtime WebSocket server to the client.\n", + "navigationGroup": "realtime", + "sections": [ + { + "type": "object", + "key": "RealtimeServerEventError", + "path": "" + }, + { + "type": "object", + "key": "RealtimeServerEventSessionCreated", + "path": "" + }, + { + "type": "object", + "key": "RealtimeServerEventSessionUpdated", + "path": "" + }, + { + "type": "object", + "key": "RealtimeServerEventConversationItemAdded", + "path": "" + }, + { + "type": "object", + "key": "RealtimeServerEventConversationItemDone", + "path": "" + }, + { + "type": "object", + "key": "RealtimeServerEventConversationItemRetrieved", + "path": "" + }, + { + "type": "object", + "key": "RealtimeServerEventConversationItemInputAudioTranscriptionCompleted", + "path": "" + }, + { + "type": "object", + "key": "RealtimeServerEventConversationItemInputAudioTranscriptionDelta", + "path": "" + }, + { + "type": "object", + "key": "RealtimeServerEventConversationItemInputAudioTranscriptionSegment", + "path": "" + }, + { + "type": "object", + "key": "RealtimeServerEventConversationItemInputAudioTranscriptionFailed", + "path": "" + }, + { + "type": "object", + "key": "RealtimeServerEventConversationItemTruncated", + "path": "" + }, + { + "type": "object", + "key": "RealtimeServerEventConversationItemDeleted", + "path": "" + }, + { + "type": "object", + "key": "RealtimeServerEventInputAudioBufferCommitted", + "path": "" + }, + { + "type": "object", + "key": "RealtimeServerEventInputAudioBufferDtmfEventReceived", + "path": "" + }, + { + "type": "object", + "key": "RealtimeServerEventInputAudioBufferCleared", + "path": "" + }, + { + "type": "object", + "key": "RealtimeServerEventInputAudioBufferSpeechStarted", + "path": "" + }, + { + "type": "object", + "key": "RealtimeServerEventInputAudioBufferSpeechStopped", + "path": "" + }, + { + "type": "object", + "key": "RealtimeServerEventInputAudioBufferTimeoutTriggered", + "path": "" + }, + { + "type": "object", + "key": "RealtimeServerEventOutputAudioBufferStarted", + "path": "" + }, + { + "type": "object", + "key": "RealtimeServerEventOutputAudioBufferStopped", + "path": "" + }, + { + "type": "object", + "key": "RealtimeServerEventOutputAudioBufferCleared", + "path": "" + }, + { + "type": "object", + "key": "RealtimeServerEventResponseCreated", + "path": "" + }, + { + "type": "object", + "key": "RealtimeServerEventResponseDone", + "path": "" + }, + { + "type": "object", + "key": "RealtimeServerEventResponseOutputItemAdded", + "path": "" + }, + { + "type": "object", + "key": "RealtimeServerEventResponseOutputItemDone", + "path": "" + }, + { + "type": "object", + "key": "RealtimeServerEventResponseContentPartAdded", + "path": "" + }, + { + "type": "object", + "key": "RealtimeServerEventResponseContentPartDone", + "path": "" + }, + { + "type": "object", + "key": "RealtimeServerEventResponseTextDelta", + "path": "" + }, + { + "type": "object", + "key": "RealtimeServerEventResponseTextDone", + "path": "" + }, + { + "type": "object", + "key": "RealtimeServerEventResponseAudioTranscriptDelta", + "path": "" + }, + { + "type": "object", + "key": "RealtimeServerEventResponseAudioTranscriptDone", + "path": "" + }, + { + "type": "object", + "key": "RealtimeServerEventResponseAudioDelta", + "path": "" + }, + { + "type": "object", + "key": "RealtimeServerEventResponseAudioDone", + "path": "" + }, + { + "type": "object", + "key": "RealtimeServerEventResponseFunctionCallArgumentsDelta", + "path": "" + }, + { + "type": "object", + "key": "RealtimeServerEventResponseFunctionCallArgumentsDone", + "path": "" + }, + { + "type": "object", + "key": "RealtimeServerEventResponseMCPCallArgumentsDelta", + "path": "" + }, + { + "type": "object", + "key": "RealtimeServerEventResponseMCPCallArgumentsDone", + "path": "" + }, + { + "type": "object", + "key": "RealtimeServerEventResponseMCPCallInProgress", + "path": "" + }, + { + "type": "object", + "key": "RealtimeServerEventResponseMCPCallCompleted", + "path": "" + }, + { + "type": "object", + "key": "RealtimeServerEventResponseMCPCallFailed", + "path": "" + }, + { + "type": "object", + "key": "RealtimeServerEventMCPListToolsInProgress", + "path": "" + }, + { + "type": "object", + "key": "RealtimeServerEventMCPListToolsCompleted", + "path": "" + }, + { + "type": "object", + "key": "RealtimeServerEventMCPListToolsFailed", + "path": "" + }, + { + "type": "object", + "key": "RealtimeServerEventRateLimitsUpdated", + "path": "" + } + ] + }, + { + "id": "realtime-translation-client-events", + "title": "Translation client events", + "description": "These are events that the OpenAI Realtime Translation WebSocket server will accept from the client.\n", + "navigationGroup": "realtime", + "sections": [ + { + "type": "object", + "key": "RealtimeTranslationClientEventSessionUpdate", + "path": "" + }, + { + "type": "object", + "key": "RealtimeTranslationClientEventInputAudioBufferAppend", + "path": "" + }, + { + "type": "object", + "key": "RealtimeTranslationClientEventSessionClose", + "path": "" + } + ] + }, + { + "id": "realtime-translation-server-events", + "title": "Translation server events", + "description": "These are events emitted from the OpenAI Realtime Translation WebSocket server to the client.\n", + "navigationGroup": "realtime", + "sections": [ + { + "type": "object", + "key": "RealtimeServerEventError", + "path": "" + }, + { + "type": "object", + "key": "RealtimeTranslationServerEventSessionCreated", + "path": "" + }, + { + "type": "object", + "key": "RealtimeTranslationServerEventSessionUpdated", + "path": "" + }, + { + "type": "object", + "key": "RealtimeTranslationServerEventSessionClosed", + "path": "" + }, + { + "type": "object", + "key": "RealtimeTranslationServerEventSessionInputTranscriptDelta", + "path": "" + }, + { + "type": "object", + "key": "RealtimeTranslationServerEventSessionOutputTranscriptDelta", + "path": "" + }, + { + "type": "object", + "key": "RealtimeTranslationServerEventSessionOutputAudioDelta", + "path": "" + } + ] + }, + { + "id": "chat-streaming", + "title": "Streaming", + "description": "Stream Chat Completions in real time. Receive chunks of completions\nreturned from the model using server-sent events.\n[Learn more](https://developers.openai.com/api/docs/guides/streaming-responses).\n", + "navigationGroup": "chat", + "sections": [ + { + "type": "object", + "key": "CreateChatCompletionStreamResponse", + "path": "streaming" + } + ] + }, + { + "id": "assistants-streaming", + "title": "Streaming", + "beta": true, + "description": "Stream the result of executing a Run or resuming a Run after submitting tool outputs.\nYou can stream events from the [Create Thread and Run](https://developers.openai.com/api/docs/assistants/migration),\n[Create Run](https://developers.openai.com/api/docs/assistants/migration), and [Submit Tool Outputs](https://developers.openai.com/api/docs/assistants/migration)\nendpoints by passing `\"stream\": true`. The response will be a [Server-Sent events](https://html.spec.whatwg.org/multipage/server-sent-events.html#server-sent-events) stream.\nOur Node and Python SDKs provide helpful utilities to make streaming easy. Reference the\n[Assistants API quickstart](https://developers.openai.com/api/docs/assistants/migration) to learn more.\n", + "navigationGroup": "assistants", + "sections": [ + { + "type": "object", + "key": "AssistantStreamEvent", + "path": "events" + } + ] + }, + { + "id": "realtime-beta-client-events", + "title": "Realtime Beta client events", + "description": "These are events that the OpenAI Realtime WebSocket server will accept from the client.\n", + "navigationGroup": "legacy", + "sections": [ + { + "type": "object", + "key": "RealtimeBetaClientEventSessionUpdate", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaClientEventInputAudioBufferAppend", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaClientEventInputAudioBufferCommit", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaClientEventInputAudioBufferClear", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaClientEventConversationItemCreate", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaClientEventConversationItemRetrieve", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaClientEventConversationItemTruncate", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaClientEventConversationItemDelete", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaClientEventResponseCreate", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaClientEventResponseCancel", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaClientEventTranscriptionSessionUpdate", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaClientEventOutputAudioBufferClear", + "path": "" + } + ] + }, + { + "id": "realtime-beta-server-events", + "title": "Realtime Beta server events", + "description": "These are events emitted from the OpenAI Realtime WebSocket server to the client.\n", + "navigationGroup": "legacy", + "sections": [ + { + "type": "object", + "key": "RealtimeBetaServerEventError", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaServerEventSessionCreated", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaServerEventSessionUpdated", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaServerEventTranscriptionSessionCreated", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaServerEventTranscriptionSessionUpdated", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaServerEventConversationItemCreated", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaServerEventConversationItemRetrieved", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaServerEventConversationItemInputAudioTranscriptionCompleted", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaServerEventConversationItemInputAudioTranscriptionDelta", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaServerEventConversationItemInputAudioTranscriptionSegment", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaServerEventConversationItemInputAudioTranscriptionFailed", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaServerEventConversationItemTruncated", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaServerEventConversationItemDeleted", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaServerEventInputAudioBufferCommitted", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaServerEventInputAudioBufferCleared", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaServerEventInputAudioBufferSpeechStarted", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaServerEventInputAudioBufferSpeechStopped", + "path": "" + }, + { + "type": "object", + "key": "RealtimeServerEventInputAudioBufferTimeoutTriggered", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaServerEventResponseCreated", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaServerEventResponseDone", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaServerEventResponseOutputItemAdded", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaServerEventResponseOutputItemDone", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaServerEventResponseContentPartAdded", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaServerEventResponseContentPartDone", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaServerEventResponseTextDelta", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaServerEventResponseTextDone", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaServerEventResponseAudioTranscriptDelta", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaServerEventResponseAudioTranscriptDone", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaServerEventResponseAudioDelta", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaServerEventResponseAudioDone", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaServerEventResponseFunctionCallArgumentsDelta", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaServerEventResponseFunctionCallArgumentsDone", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaServerEventResponseMCPCallArgumentsDelta", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaServerEventResponseMCPCallArgumentsDone", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaServerEventResponseMCPCallInProgress", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaServerEventResponseMCPCallCompleted", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaServerEventResponseMCPCallFailed", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaServerEventMCPListToolsInProgress", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaServerEventMCPListToolsCompleted", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaServerEventMCPListToolsFailed", + "path": "" + }, + { + "type": "object", + "key": "RealtimeBetaServerEventRateLimitsUpdated", + "path": "" + } + ] + }, + { + "id": "live-client-events", + "title": "Client events", + "description": "Initialize a primary WebSocket with session.start and wait for session.started before sending other events. WebRTC creation starts the session for you. Start with the [Live prompting guide](https://developers.openai.com/api/docs/guides/live-prompting) to design frontend instructions and delegation policy; see [backend prompting](https://developers.openai.com/api/docs/guides/live-delegation#start-with-your-existing-backend-prompt) for tools and business rules.", + "navigationGroup": "live", + "sections": [ + { + "type": "object", + "key": "LiveSessionStartEvent", + "path": "" + }, + { + "type": "object", + "key": "LiveForkSessionStartEvent", + "path": "" + }, + { + "type": "object", + "key": "LiveSessionUpdateParam", + "path": "" + }, + { + "type": "object", + "key": "LiveInputAudioAppendEvent", + "path": "" + }, + { + "type": "object", + "key": "LiveInputAudioMuteParam", + "path": "" + }, + { + "type": "object", + "key": "LiveInputAudioUnmuteParam", + "path": "" + }, + { + "type": "object", + "key": "LiveInstructionsAppendParam", + "path": "" + }, + { + "type": "object", + "key": "LiveThinkingAppendParam", + "path": "" + }, + { + "type": "object", + "key": "LiveCommentaryAppendParam", + "path": "" + }, + { + "type": "object", + "key": "LiveResponseItemCreateParam", + "path": "" + }, + { + "type": "object", + "key": "LiveResponseCreateParam", + "path": "" + }, + { + "type": "object", + "key": "LiveSessionCloseParam", + "path": "" + } + ] + }, + { + "id": "live-server-events", + "title": "Server events", + "description": "Live server events. Responses delegation lifecycle events arrive inside response.event, not as top-level response events. Start with the [Live prompting guide](https://developers.openai.com/api/docs/guides/live-prompting) to design frontend instructions and delegation policy; see [backend prompting](https://developers.openai.com/api/docs/guides/live-delegation#start-with-your-existing-backend-prompt) for tools and business rules.", + "navigationGroup": "live", + "sections": [ + { + "type": "object", + "key": "LiveSessionStarted", + "path": "" + }, + { + "type": "object", + "key": "LiveSessionUpdated", + "path": "" + }, + { + "type": "object", + "key": "LiveInputAudioMuted", + "path": "" + }, + { + "type": "object", + "key": "LiveInputAudioUnmuted", + "path": "" + }, + { + "type": "object", + "key": "LiveInstructionsAppended", + "path": "" + }, + { + "type": "object", + "key": "LiveThinkingAppended", + "path": "" + }, + { + "type": "object", + "key": "LiveCommentaryAppended", + "path": "" + }, + { + "type": "object", + "key": "LiveOutputAudioDelta", + "path": "" + }, + { + "type": "object", + "key": "LiveInputTranscriptDelta", + "path": "" + }, + { + "type": "object", + "key": "LiveOutputTranscriptDelta", + "path": "" + }, + { + "type": "object", + "key": "LiveDelegationCreated", + "path": "" + }, + { + "type": "object", + "key": "LiveResponseEvent", + "path": "" + }, + { + "type": "object", + "key": "LiveSessionUsageUpdated", + "path": "" + }, + { + "type": "object", + "key": "LiveSessionClosed", + "path": "" + }, + { + "type": "object", + "key": "LiveErrorEvent", + "path": "" + }, + { + "type": "object", + "key": "LiveInfoEvent", + "path": "" + } + ] + } + ] + } +} diff --git a/contracts/agents-api/runtime.openapi.yaml b/contracts/agents-api/runtime.openapi.yaml index fc109bc6f..8e1ac37a7 100644 --- a/contracts/agents-api/runtime.openapi.yaml +++ b/contracts/agents-api/runtime.openapi.yaml @@ -151,13 +151,17 @@ definitions: x-nullable: true message: type: string + misalignment: + type: object param: type: string x-nullable: true type: type: string required: + - code - message + - param - type type: object v1.ErrorResponse: diff --git a/contracts/agents-api/upstream-fields.json b/contracts/agents-api/upstream-fields.json deleted file mode 100644 index f1668c995..000000000 --- a/contracts/agents-api/upstream-fields.json +++ /dev/null @@ -1,2301 +0,0 @@ -{ - "sdk_version": "3.13.0", - "commit": "d7c41efee1b0802b79f3f88a678ef2052b06e9ce", - "generator": "scripts/extract-agents-api-upstream.py", - "operations": { - "DELETE /agents/environments/templates/{}": { - "request": [], - "query": [], - "response": [ - "beta.agents.environments.environment_template_deleted.EnvironmentTemplateDeleted" - ] - }, - "DELETE /agents/sessions/{}": { - "request": [], - "query": [], - "response": [ - "beta.agent_session_deleted.AgentSessionDeleted" - ] - }, - "DELETE /agents/sessions/{}/artifacts/{}": { - "request": [], - "query": [], - "response": [ - "beta.agents.sessions.session_artifact_deleted.SessionArtifactDeleted" - ] - }, - "DELETE /agents/{}": { - "request": [], - "query": [], - "response": [ - "beta.agent_deleted.AgentDeleted" - ] - }, - "DELETE /files/{}": { - "request": [], - "query": [], - "response": [ - "file_deleted.FileDeleted" - ] - }, - "DELETE /skills/{}": { - "request": [], - "query": [], - "response": [ - "deleted_skill.DeletedSkill" - ] - }, - "DELETE /skills/{}/versions/{}": { - "request": [], - "query": [], - "response": [ - "skills.deleted_skill_version.DeletedSkillVersion" - ] - }, - "DELETE /vaults/{}": { - "request": [], - "query": [], - "response": [ - "beta.agents.vault_deleted.VaultDeleted" - ] - }, - "DELETE /vaults/{}/credentials/{}": { - "request": [], - "query": [], - "response": [ - "beta.agents.vaults.credential_deleted.CredentialDeleted" - ] - }, - "GET /agents": { - "request": [], - "query": [ - "beta.agent_list_params.AgentListParams" - ], - "response": [ - "pagination.SyncCursorPage[beta.agent.Agent]" - ] - }, - "GET /agents/environments/templates": { - "request": [], - "query": [ - "beta.agents.environments.template_list_params.TemplateListParams" - ], - "response": [ - "pagination.SyncCursorPage[beta.agents.environments.environment_template.EnvironmentTemplate]" - ] - }, - "GET /agents/environments/templates/{}": { - "request": [], - "query": [], - "response": [ - "beta.agents.environments.environment_template.EnvironmentTemplate" - ] - }, - "GET /agents/environments/{}": { - "request": [], - "query": [], - "response": [ - "beta.agents.environment_info.EnvironmentInfo" - ] - }, - "GET /agents/environments/{}/files": { - "request": [], - "query": [ - "beta.agents.environments.file_list_params.FileListParams" - ], - "response": [ - "pagination.SyncTokenPage[beta.agents.environments.environment_file.EnvironmentFile]" - ] - }, - "GET /agents/sessions": { - "request": [], - "query": [ - "beta.agents.session_list_params.SessionListParams" - ], - "response": [ - "pagination.SyncCursorPage[beta.agent_session.AgentSession]" - ] - }, - "GET /agents/sessions/{}": { - "request": [], - "query": [], - "response": [ - "beta.agent_session.AgentSession" - ] - }, - "GET /agents/sessions/{}/artifacts": { - "request": [], - "query": [ - "beta.agents.sessions.artifact_list_params.ArtifactListParams" - ], - "response": [ - "pagination.SyncCursorPage[beta.agents.sessions.session_artifact.SessionArtifact]" - ] - }, - "GET /agents/sessions/{}/artifacts/{}": { - "request": [], - "query": [], - "response": [ - "beta.agents.sessions.session_artifact.SessionArtifact" - ] - }, - "GET /agents/sessions/{}/artifacts/{}/content": { - "request": [], - "query": [], - "response": [] - }, - "GET /agents/sessions/{}/events": { - "request": [], - "query": [], - "response": [ - "beta.agent_output_command_execution_output_delta_event.AgentOutputCommandExecutionOutputDeltaEvent", - "beta.agent_session_created_event.AgentSessionCreatedEvent", - "beta.agent_session_environment_connected_event.AgentSessionEnvironmentConnectedEvent", - "beta.agent_session_environment_disconnected_event.AgentSessionEnvironmentDisconnectedEvent", - "beta.agent_session_environment_failed_event.AgentSessionEnvironmentFailedEvent", - "beta.agent_session_environment_pending_event.AgentSessionEnvironmentPendingEvent", - "beta.agent_session_environment_ready_event.AgentSessionEnvironmentReadyEvent", - "beta.agent_session_error_event.AgentSessionErrorEvent", - "beta.agent_session_failed_event.AgentSessionFailedEvent", - "beta.agent_session_idle_event.AgentSessionIdleEvent", - "beta.agent_session_in_progress_event.AgentSessionInProgressEvent", - "beta.agent_session_requires_action_event.AgentSessionRequiresActionEvent", - "beta.agent_session_subagent_active_event.AgentSessionSubagentActiveEvent", - "beta.agent_session_subagent_closed_event.AgentSessionSubagentClosedEvent", - "beta.agent_session_subagent_created_event.AgentSessionSubagentCreatedEvent", - "beta.agent_session_turn_cancelled_event.AgentSessionTurnCancelledEvent", - "beta.agent_session_turn_completed_event.AgentSessionTurnCompletedEvent", - "beta.agent_session_turn_content_part_added_event.AgentSessionTurnContentPartAddedEvent", - "beta.agent_session_turn_content_part_done_event.AgentSessionTurnContentPartDoneEvent", - "beta.agent_session_turn_created_event.AgentSessionTurnCreatedEvent", - "beta.agent_session_turn_failed_event.AgentSessionTurnFailedEvent", - "beta.agent_session_turn_in_progress_event.AgentSessionTurnInProgressEvent", - "beta.agent_session_turn_item_added_event.AgentSessionTurnItemAddedEvent", - "beta.agent_session_turn_item_done_event.AgentSessionTurnItemDoneEvent", - "beta.agent_session_turn_output_text_delta_event.AgentSessionTurnOutputTextDeltaEvent", - "beta.agent_session_turn_output_text_done_event.AgentSessionTurnOutputTextDoneEvent", - "beta.agent_session_turn_reasoning_summary_part_added_event.AgentSessionTurnReasoningSummaryPartAddedEvent", - "beta.agent_session_turn_reasoning_summary_part_done_event.AgentSessionTurnReasoningSummaryPartDoneEvent", - "beta.agent_session_turn_reasoning_summary_text_delta_event.AgentSessionTurnReasoningSummaryTextDeltaEvent", - "beta.agent_session_turn_reasoning_summary_text_done_event.AgentSessionTurnReasoningSummaryTextDoneEvent" - ] - }, - "GET /agents/sessions/{}/items": { - "request": [], - "query": [ - "beta.agents.sessions.item_list_params.ItemListParams" - ], - "response": [ - "pagination.SyncCursorPage[beta.agent_close_subagent_call_item.AgentCloseSubagentCallItem | beta.agent_command_execution_item.AgentCommandExecutionItem | beta.agent_create_subagent_call_item.AgentCreateSubagentCallItem | beta.agent_function_call_item.AgentFunctionCallItem | beta.agent_interrupt_subagent_call_item.AgentInterruptSubagentCallItem | beta.agent_mcp_call_item.AgentMcpCallItem | beta.agent_reasoning_item.AgentReasoningItem | beta.agent_resume_subagent_call_item.AgentResumeSubagentCallItem | beta.agent_send_subagent_input_call_item.AgentSendSubagentInputCallItem | beta.agent_session_item.AgentMessageItemResource | beta.agent_session_item.FunctionCallOutputItemResource | beta.agent_session_message.AgentSessionMessage | beta.agent_wait_for_subagents_call_item.AgentWaitForSubagentsCallItem | beta.agent_web_search_call_item.AgentWebSearchCallItem]" - ] - }, - "GET /agents/sessions/{}/subagents": { - "request": [], - "query": [ - "beta.agents.sessions.subagent_list_params.SubagentListParams" - ], - "response": [ - "pagination.SyncCursorPage[beta.subagent.Subagent]" - ] - }, - "GET /agents/sessions/{}/subagents/{}": { - "request": [], - "query": [], - "response": [ - "beta.subagent.Subagent" - ] - }, - "GET /agents/sessions/{}/subagents/{}/items": { - "request": [], - "query": [ - "beta.agents.sessions.subagents.item_list_params.ItemListParams" - ], - "response": [ - "pagination.SyncCursorPage[beta.agent_close_subagent_call_item.AgentCloseSubagentCallItem | beta.agent_command_execution_item.AgentCommandExecutionItem | beta.agent_create_subagent_call_item.AgentCreateSubagentCallItem | beta.agent_function_call_item.AgentFunctionCallItem | beta.agent_interrupt_subagent_call_item.AgentInterruptSubagentCallItem | beta.agent_mcp_call_item.AgentMcpCallItem | beta.agent_reasoning_item.AgentReasoningItem | beta.agent_resume_subagent_call_item.AgentResumeSubagentCallItem | beta.agent_send_subagent_input_call_item.AgentSendSubagentInputCallItem | beta.agent_session_item.AgentMessageItemResource | beta.agent_session_item.FunctionCallOutputItemResource | beta.agent_session_message.AgentSessionMessage | beta.agent_wait_for_subagents_call_item.AgentWaitForSubagentsCallItem | beta.agent_web_search_call_item.AgentWebSearchCallItem]" - ] - }, - "GET /agents/sessions/{}/subagents/{}/turns": { - "request": [], - "query": [ - "beta.agents.sessions.subagents.turn_list_params.TurnListParams" - ], - "response": [ - "pagination.SyncCursorPage[beta.agents.sessions.turn.Turn]" - ] - }, - "GET /agents/sessions/{}/subagents/{}/turns/{}": { - "request": [], - "query": [], - "response": [ - "beta.agents.sessions.turn.Turn" - ] - }, - "GET /agents/sessions/{}/subagents/{}/turns/{}/items": { - "request": [], - "query": [ - "beta.agents.sessions.subagents.turns.item_list_params.ItemListParams" - ], - "response": [ - "pagination.SyncCursorPage[beta.agent_close_subagent_call_item.AgentCloseSubagentCallItem | beta.agent_command_execution_item.AgentCommandExecutionItem | beta.agent_create_subagent_call_item.AgentCreateSubagentCallItem | beta.agent_function_call_item.AgentFunctionCallItem | beta.agent_interrupt_subagent_call_item.AgentInterruptSubagentCallItem | beta.agent_mcp_call_item.AgentMcpCallItem | beta.agent_reasoning_item.AgentReasoningItem | beta.agent_resume_subagent_call_item.AgentResumeSubagentCallItem | beta.agent_send_subagent_input_call_item.AgentSendSubagentInputCallItem | beta.agent_session_item.AgentMessageItemResource | beta.agent_session_item.FunctionCallOutputItemResource | beta.agent_session_message.AgentSessionMessage | beta.agent_wait_for_subagents_call_item.AgentWaitForSubagentsCallItem | beta.agent_web_search_call_item.AgentWebSearchCallItem]" - ] - }, - "GET /agents/sessions/{}/turns": { - "request": [], - "query": [ - "beta.agents.sessions.turn_list_params.TurnListParams" - ], - "response": [ - "pagination.SyncCursorPage[beta.agents.sessions.turn.Turn]" - ] - }, - "GET /agents/sessions/{}/turns/{}": { - "request": [], - "query": [], - "response": [ - "beta.agents.sessions.turn.Turn" - ] - }, - "GET /agents/{}": { - "request": [], - "query": [], - "response": [ - "beta.agent.Agent" - ] - }, - "GET /files": { - "request": [], - "query": [ - "file_list_params.FileListParams" - ], - "response": [ - "pagination.SyncCursorPage[file_object.FileObject]" - ] - }, - "GET /files/{}": { - "request": [], - "query": [], - "response": [ - "file_object.FileObject" - ] - }, - "GET /files/{}/content": { - "request": [], - "query": [], - "response": [] - }, - "GET /skills": { - "request": [], - "query": [ - "skill_list_params.SkillListParams" - ], - "response": [ - "pagination.SyncCursorPage[skill.Skill]" - ] - }, - "GET /skills/{}": { - "request": [], - "query": [], - "response": [ - "skill.Skill" - ] - }, - "GET /skills/{}/content": { - "request": [], - "query": [], - "response": [] - }, - "GET /skills/{}/versions": { - "request": [], - "query": [ - "skills.version_list_params.VersionListParams" - ], - "response": [ - "pagination.SyncCursorPage[skills.skill_version.SkillVersion]" - ] - }, - "GET /skills/{}/versions/{}": { - "request": [], - "query": [], - "response": [ - "skills.skill_version.SkillVersion" - ] - }, - "GET /skills/{}/versions/{}/content": { - "request": [], - "query": [], - "response": [] - }, - "GET /vaults": { - "request": [], - "query": [ - "beta.agents.vault_list_params.VaultListParams" - ], - "response": [ - "pagination.SyncCursorPage[beta.agents.vault.Vault]" - ] - }, - "GET /vaults/{}": { - "request": [], - "query": [], - "response": [ - "beta.agents.vault.Vault" - ] - }, - "GET /vaults/{}/credentials": { - "request": [], - "query": [ - "beta.agents.vaults.credential_list_params.CredentialListParams" - ], - "response": [ - "pagination.SyncCursorPage[beta.agents.vaults.credential.Credential]" - ] - }, - "GET /vaults/{}/credentials/{}": { - "request": [], - "query": [], - "response": [ - "beta.agents.vaults.credential.Credential" - ] - }, - "POST /agents": { - "request": [ - "beta.agent_create_params.AgentCreateParams" - ], - "query": [], - "response": [ - "beta.agent.Agent" - ] - }, - "POST /agents/environments/templates": { - "request": [ - "beta.agents.environments.template_create_params.TemplateCreateParams" - ], - "query": [], - "response": [ - "beta.agents.environments.environment_template.EnvironmentTemplate" - ] - }, - "POST /agents/environments/templates/{}": { - "request": [ - "beta.agents.environments.template_update_params.TemplateUpdateParams" - ], - "query": [], - "response": [ - "beta.agents.environments.environment_template.EnvironmentTemplate" - ] - }, - "POST /agents/environments/{}/files": { - "request": [ - "beta.agents.environments.file_create_params.HostedEnvironmentFileParamFileID", - "beta.agents.environments.file_create_params.HostedEnvironmentFileParamInline" - ], - "query": [], - "response": [ - "beta.agents.environments.environment_file.EnvironmentFile" - ] - }, - "POST /agents/sessions": { - "request": [ - "beta.agents.session_create_params.SessionCreateParamsNonStreaming", - "beta.agents.session_create_params.SessionCreateParamsStreaming" - ], - "query": [], - "response": [ - "beta.agent_session.AgentSession" - ] - }, - "POST /agents/sessions/{}": { - "request": [ - "beta.agents.session_update_params.SessionUpdateParams" - ], - "query": [], - "response": [ - "beta.agent_session.AgentSession" - ] - }, - "POST /agents/sessions/{}/events": { - "request": [ - "beta.agents.sessions.event_create_params.EventCreateParams" - ], - "query": [], - "response": [] - }, - "POST /agents/{}": { - "request": [ - "beta.agent_update_params.AgentUpdateParams" - ], - "query": [], - "response": [ - "beta.agent.Agent" - ] - }, - "POST /files": { - "request": [ - "file_create_params.FileCreateParams" - ], - "query": [], - "response": [ - "file_object.FileObject" - ] - }, - "POST /skills": { - "request": [ - "skill_create_params.SkillCreateParams" - ], - "query": [], - "response": [ - "skill.Skill" - ] - }, - "POST /skills/{}": { - "request": [ - "skill_update_params.SkillUpdateParams" - ], - "query": [], - "response": [ - "skill.Skill" - ] - }, - "POST /skills/{}/versions": { - "request": [ - "skills.version_create_params.VersionCreateParams" - ], - "query": [], - "response": [ - "skills.skill_version.SkillVersion" - ] - }, - "POST /vaults": { - "request": [ - "beta.agents.vault_create_params.VaultCreateParams" - ], - "query": [], - "response": [ - "beta.agents.vault.Vault" - ] - }, - "POST /vaults/{}/credentials": { - "request": [ - "beta.agents.vaults.credential_create_params.CredentialCreateParams" - ], - "query": [], - "response": [ - "beta.agents.vaults.credential.Credential" - ] - }, - "POST /vaults/{}/credentials/{}": { - "request": [ - "beta.agents.vaults.credential_update_params.CredentialUpdateParams" - ], - "query": [], - "response": [ - "beta.agents.vaults.credential.Credential" - ] - } - }, - "types": { - "beta.agent.Agent": { - "created_at": [], - "id": [], - "instructions": [], - "metadata": [], - "model": [], - "multi_agent": [ - "beta.multi_agent_config.MultiAgentConfig" - ], - "name": [], - "object": [], - "reasoning": [ - "beta.agent_reasoning.AgentReasoning" - ], - "service_tier": [], - "text": [ - "beta.agent_text.AgentText" - ], - "tools": [ - "beta.persisted_agent_tool.PersistedAgentToolResourceFunction", - "beta.persisted_agent_tool.PersistedAgentToolResourceMcp", - "beta.persisted_agent_tool.PersistedAgentToolResourceProgrammaticToolCalling", - "beta.persisted_agent_tool.PersistedAgentToolResourceToolSearch", - "beta.persisted_agent_tool.PersistedAgentToolResourceWebSearch" - ], - "updated_at": [] - }, - "beta.agent_close_subagent_call_item.AgentCloseSubagentCallItem": { - "id": [], - "recipient_agent_id": [], - "sender_agent_id": [], - "status": [], - "turn_id": [], - "type": [] - }, - "beta.agent_command_execution_item.AgentCommandExecutionItem": { - "command": [], - "cwd": [], - "duration_ms": [], - "exit_code": [], - "id": [], - "output": [], - "status": [], - "turn_id": [], - "type": [] - }, - "beta.agent_content.EncryptedContentResource": { - "encrypted_content": [], - "type": [] - }, - "beta.agent_create_params.AgentCreateParams": { - "instructions": [], - "metadata": [], - "model": [], - "multi_agent": [ - "beta.multi_agent_config_param.MultiAgentConfigParam" - ], - "name": [], - "reasoning": [ - "beta.agent_reasoning_param.AgentReasoningParam" - ], - "service_tier": [], - "text": [ - "beta.agent_text_param.AgentTextParam" - ], - "tools": [ - "beta.persisted_agent_tool_param.PersistedAgentToolConfigParamFunction", - "beta.persisted_agent_tool_param.PersistedAgentToolConfigParamMcp", - "beta.persisted_agent_tool_param.PersistedAgentToolConfigParamProgrammaticToolCalling", - "beta.persisted_agent_tool_param.PersistedAgentToolConfigParamToolSearch", - "beta.persisted_agent_tool_param.PersistedAgentToolConfigParamWebSearch" - ] - }, - "beta.agent_create_subagent_call_item.AgentCreateSubagentCallItem": { - "agent_id": [], - "content": [ - "beta.agent_content.EncryptedContentResource", - "beta.output_text.OutputText" - ], - "id": [], - "model": [], - "reasoning_effort": [], - "status": [], - "turn_id": [], - "type": [] - }, - "beta.agent_deleted.AgentDeleted": { - "deleted": [], - "id": [], - "object": [] - }, - "beta.agent_function_call_item.AgentFunctionCallItem": { - "arguments": [], - "call_id": [], - "id": [], - "name": [], - "status": [], - "turn_id": [], - "type": [] - }, - "beta.agent_interrupt_subagent_call_item.AgentInterruptSubagentCallItem": { - "id": [], - "recipient_agent_id": [], - "sender_agent_id": [], - "status": [], - "turn_id": [], - "type": [] - }, - "beta.agent_list_params.AgentListParams": { - "after": [], - "limit": [], - "order": [] - }, - "beta.agent_mcp_call_item.AgentMcpCallItem": { - "arguments": [], - "error": [], - "id": [], - "name": [], - "output": [], - "server_label": [], - "status": [], - "turn_id": [], - "type": [] - }, - "beta.agent_output_command_execution_output_delta_event.AgentOutputCommandExecutionOutputDeltaEvent": { - "delta": [], - "event_id": [], - "item_id": [], - "output_index": [], - "session_id": [], - "turn_id": [], - "type": [] - }, - "beta.agent_reasoning.AgentReasoning": { - "effort": [], - "summary": [] - }, - "beta.agent_reasoning_item.AgentReasoningItem": { - "id": [], - "status": [], - "summary": [ - "beta.summary_text.SummaryText" - ], - "turn_id": [], - "type": [] - }, - "beta.agent_reasoning_param.AgentReasoningParam": { - "effort": [], - "summary": [] - }, - "beta.agent_resume_subagent_call_item.AgentResumeSubagentCallItem": { - "id": [], - "recipient_agent_id": [], - "sender_agent_id": [], - "status": [], - "turn_id": [], - "type": [] - }, - "beta.agent_send_subagent_input_call_item.AgentSendSubagentInputCallItem": { - "content": [ - "beta.agent_content.EncryptedContentResource", - "beta.output_text.OutputText" - ], - "id": [], - "recipient_agent_id": [], - "sender_agent_id": [], - "status": [], - "turn_id": [], - "type": [] - }, - "beta.agent_session.Agent": { - "id": [], - "instructions": [], - "model": [], - "multi_agent": [ - "beta.multi_agent_config.MultiAgentConfig" - ], - "name": [], - "reasoning": [ - "beta.agent_reasoning.AgentReasoning" - ], - "service_tier": [], - "text": [ - "beta.agent_text.AgentText" - ], - "tools": [ - "beta.agent_tool.AgentToolResourceFunction", - "beta.agent_tool.AgentToolResourceMcp", - "beta.agent_tool.AgentToolResourceProgrammaticToolCalling", - "beta.agent_tool.AgentToolResourceWebSearch" - ] - }, - "beta.agent_session.AgentSession": { - "agent": [ - "beta.agent_session.Agent" - ], - "created_at": [], - "environment": [ - "beta.environment.EnvironmentResourceNone", - "beta.environment.EnvironmentResourceOpenAIHosted", - "beta.environment.EnvironmentResourceSelfHosted" - ], - "error": [], - "id": [], - "last_active_at": [], - "metadata": [], - "object": [], - "required_actions": [ - "beta.agent_session.RequiredActionSessionRequiredActionResourceEnvironmentConnection", - "beta.agent_session.RequiredActionSessionRequiredActionResourceFunctionCall" - ], - "status": [], - "usage": [ - "beta.token_usage.TokenUsage" - ], - "vault_ids": [] - }, - "beta.agent_session.RequiredActionSessionRequiredActionResourceEnvironmentConnection": { - "environment_id": [], - "type": [] - }, - "beta.agent_session.RequiredActionSessionRequiredActionResourceFunctionCall": { - "arguments": [], - "call_id": [], - "name": [], - "turn_id": [], - "type": [] - }, - "beta.agent_session_assistant_message.AgentSessionAssistantMessage": { - "content": [ - "beta.output_text.OutputText" - ], - "id": [], - "phase": [], - "role": [], - "status": [], - "turn_id": [], - "type": [] - }, - "beta.agent_session_created_event.AgentSessionCreatedEvent": { - "event_id": [], - "session": [ - "beta.agent_session.AgentSession" - ], - "type": [] - }, - "beta.agent_session_deleted.AgentSessionDeleted": { - "deleted": [], - "id": [], - "object": [] - }, - "beta.agent_session_environment_connected_event.AgentSessionEnvironmentConnectedEvent": { - "environment": [ - "beta.agent_session_environment_state.AgentSessionEnvironmentState" - ], - "event_id": [], - "session_id": [], - "turn_id": [], - "type": [] - }, - "beta.agent_session_environment_disconnected_event.AgentSessionEnvironmentDisconnectedEvent": { - "environment": [ - "beta.agent_session_environment_state.AgentSessionEnvironmentState" - ], - "event_id": [], - "session_id": [], - "turn_id": [], - "type": [] - }, - "beta.agent_session_environment_failed_event.AgentSessionEnvironmentFailedEvent": { - "environment": [ - "beta.agent_session_environment_state.AgentSessionEnvironmentState" - ], - "event_id": [], - "session_id": [], - "turn_id": [], - "type": [] - }, - "beta.agent_session_environment_pending_event.AgentSessionEnvironmentPendingEvent": { - "environment": [ - "beta.agent_session_environment_state.AgentSessionEnvironmentState" - ], - "event_id": [], - "session_id": [], - "turn_id": [], - "type": [] - }, - "beta.agent_session_environment_ready_event.AgentSessionEnvironmentReadyEvent": { - "environment": [ - "beta.agent_session_environment_state.AgentSessionEnvironmentState" - ], - "event_id": [], - "session_id": [], - "turn_id": [], - "type": [] - }, - "beta.agent_session_environment_state.AgentSessionEnvironmentState": { - "error": [ - "beta.agent_session_environment_state.Error" - ], - "id": [], - "status": [], - "type": [] - }, - "beta.agent_session_environment_state.Error": { - "code": [], - "message": [], - "type": [] - }, - "beta.agent_session_error_event.AgentSessionErrorEvent": { - "error": [ - "beta.session_error.SessionError" - ], - "event_id": [], - "session_id": [], - "type": [] - }, - "beta.agent_session_failed_event.AgentSessionFailedEvent": { - "event_id": [], - "session": [ - "beta.agent_session.AgentSession" - ], - "type": [] - }, - "beta.agent_session_idle_event.AgentSessionIdleEvent": { - "event_id": [], - "session": [ - "beta.agent_session.AgentSession" - ], - "type": [] - }, - "beta.agent_session_in_progress_event.AgentSessionInProgressEvent": { - "event_id": [], - "session": [ - "beta.agent_session.AgentSession" - ], - "type": [] - }, - "beta.agent_session_input_message_param.AgentSessionInputMessageParam": { - "content": [ - "beta.input_content_param.InputContentParamInputImage", - "beta.input_content_param.InputContentParamInputText" - ], - "role": [], - "type": [] - }, - "beta.agent_session_input_param.SessionInputParamAgentSessionInputCancel": { - "type": [] - }, - "beta.agent_session_input_param.SessionInputParamAgentSessionInputMessage": { - "input": [ - "beta.agent_session_input_message_param.AgentSessionInputMessageParam" - ], - "type": [] - }, - "beta.agent_session_input_param.SessionInputParamAgentSessionInputToolResult": { - "call_id": [], - "error": [], - "output": [ - "beta.input_content_param.InputContentParamInputImage", - "beta.input_content_param.InputContentParamInputText" - ], - "success": [], - "turn_id": [], - "type": [] - }, - "beta.agent_session_item.AgentMessageItemResource": { - "content": [ - "beta.agent_content.EncryptedContentResource", - "beta.output_text.OutputText" - ], - "id": [], - "recipient_agent_id": [], - "sender_agent_id": [], - "turn_id": [], - "type": [] - }, - "beta.agent_session_item.FunctionCallOutputItemResource": { - "call_id": [], - "error": [], - "id": [], - "output": [ - "beta.input_content.InputContentResourceInputImage", - "beta.input_content.InputContentResourceInputText" - ], - "status": [], - "turn_id": [], - "type": [] - }, - "beta.agent_session_message.AgentSessionMessage": { - "content": [ - "beta.agent_session_message_content.MessageContentResourceInputImage", - "beta.agent_session_message_content.MessageContentResourceInputText", - "beta.agent_session_message_content.MessageContentResourceOutputText" - ], - "id": [], - "phase": [], - "role": [], - "status": [], - "turn_id": [], - "type": [] - }, - "beta.agent_session_message_content.MessageContentResourceInputImage": { - "image_url": [], - "type": [] - }, - "beta.agent_session_message_content.MessageContentResourceInputText": { - "text": [], - "type": [] - }, - "beta.agent_session_message_content.MessageContentResourceOutputText": { - "text": [], - "type": [] - }, - "beta.agent_session_requires_action_event.AgentSessionRequiresActionEvent": { - "event_id": [], - "session": [ - "beta.agent_session.AgentSession" - ], - "type": [] - }, - "beta.agent_session_subagent_active_event.AgentSessionSubagentActiveEvent": { - "event_id": [], - "subagent": [ - "beta.subagent.Subagent" - ], - "type": [] - }, - "beta.agent_session_subagent_closed_event.AgentSessionSubagentClosedEvent": { - "event_id": [], - "subagent": [ - "beta.subagent.Subagent" - ], - "type": [] - }, - "beta.agent_session_subagent_created_event.AgentSessionSubagentCreatedEvent": { - "event_id": [], - "subagent": [ - "beta.subagent.Subagent" - ], - "type": [] - }, - "beta.agent_session_turn_cancelled_event.AgentSessionTurnCancelledEvent": { - "event_id": [], - "session_id": [], - "turn": [ - "beta.agents.sessions.turn.Turn" - ], - "turn_id": [], - "type": [], - "usage": [ - "beta.token_usage.TokenUsage" - ] - }, - "beta.agent_session_turn_completed_event.AgentSessionTurnCompletedEvent": { - "event_id": [], - "session_id": [], - "turn": [ - "beta.agents.sessions.turn.Turn" - ], - "turn_id": [], - "type": [], - "usage": [ - "beta.token_usage.TokenUsage" - ] - }, - "beta.agent_session_turn_content_part_added_event.AgentSessionTurnContentPartAddedEvent": { - "content_index": [], - "event_id": [], - "item_id": [], - "output_index": [], - "part": [ - "beta.output_text.OutputText" - ], - "session_id": [], - "turn_id": [], - "type": [] - }, - "beta.agent_session_turn_content_part_done_event.AgentSessionTurnContentPartDoneEvent": { - "content_index": [], - "event_id": [], - "item_id": [], - "output_index": [], - "part": [ - "beta.output_text.OutputText" - ], - "session_id": [], - "turn_id": [], - "type": [] - }, - "beta.agent_session_turn_created_event.AgentSessionTurnCreatedEvent": { - "event_id": [], - "session_id": [], - "turn": [ - "beta.agents.sessions.turn.Turn" - ], - "turn_id": [], - "type": [] - }, - "beta.agent_session_turn_failed_event.AgentSessionTurnFailedEvent": { - "event_id": [], - "session_id": [], - "turn": [ - "beta.agents.sessions.turn.Turn" - ], - "turn_id": [], - "type": [], - "usage": [ - "beta.token_usage.TokenUsage" - ] - }, - "beta.agent_session_turn_in_progress_event.AgentSessionTurnInProgressEvent": { - "event_id": [], - "session_id": [], - "turn": [ - "beta.agents.sessions.turn.Turn" - ], - "turn_id": [], - "type": [] - }, - "beta.agent_session_turn_item_added_event.AgentSessionTurnItemAddedEvent": { - "event_id": [], - "item": [ - "beta.agent_close_subagent_call_item.AgentCloseSubagentCallItem", - "beta.agent_command_execution_item.AgentCommandExecutionItem", - "beta.agent_create_subagent_call_item.AgentCreateSubagentCallItem", - "beta.agent_function_call_item.AgentFunctionCallItem", - "beta.agent_interrupt_subagent_call_item.AgentInterruptSubagentCallItem", - "beta.agent_mcp_call_item.AgentMcpCallItem", - "beta.agent_reasoning_item.AgentReasoningItem", - "beta.agent_resume_subagent_call_item.AgentResumeSubagentCallItem", - "beta.agent_send_subagent_input_call_item.AgentSendSubagentInputCallItem", - "beta.agent_session_item.AgentMessageItemResource", - "beta.agent_session_item.FunctionCallOutputItemResource", - "beta.agent_session_message.AgentSessionMessage", - "beta.agent_wait_for_subagents_call_item.AgentWaitForSubagentsCallItem", - "beta.agent_web_search_call_item.AgentWebSearchCallItem" - ], - "output_index": [], - "session_id": [], - "turn_id": [], - "type": [] - }, - "beta.agent_session_turn_item_done_event.AgentSessionTurnItemDoneEvent": { - "event_id": [], - "item": [ - "beta.agent_close_subagent_call_item.AgentCloseSubagentCallItem", - "beta.agent_command_execution_item.AgentCommandExecutionItem", - "beta.agent_create_subagent_call_item.AgentCreateSubagentCallItem", - "beta.agent_function_call_item.AgentFunctionCallItem", - "beta.agent_interrupt_subagent_call_item.AgentInterruptSubagentCallItem", - "beta.agent_mcp_call_item.AgentMcpCallItem", - "beta.agent_reasoning_item.AgentReasoningItem", - "beta.agent_resume_subagent_call_item.AgentResumeSubagentCallItem", - "beta.agent_send_subagent_input_call_item.AgentSendSubagentInputCallItem", - "beta.agent_session_assistant_message.AgentSessionAssistantMessage", - "beta.agent_wait_for_subagents_call_item.AgentWaitForSubagentsCallItem", - "beta.agent_web_search_call_item.AgentWebSearchCallItem" - ], - "output_index": [], - "session_id": [], - "turn_id": [], - "type": [] - }, - "beta.agent_session_turn_output_text_delta_event.AgentSessionTurnOutputTextDeltaEvent": { - "content_index": [], - "delta": [], - "event_id": [], - "item_id": [], - "output_index": [], - "session_id": [], - "turn_id": [], - "type": [] - }, - "beta.agent_session_turn_output_text_done_event.AgentSessionTurnOutputTextDoneEvent": { - "content_index": [], - "event_id": [], - "item_id": [], - "output_index": [], - "session_id": [], - "text": [], - "turn_id": [], - "type": [] - }, - "beta.agent_session_turn_reasoning_summary_part_added_event.AgentSessionTurnReasoningSummaryPartAddedEvent": { - "event_id": [], - "item_id": [], - "output_index": [], - "part": [ - "beta.summary_text.SummaryText" - ], - "session_id": [], - "summary_index": [], - "turn_id": [], - "type": [] - }, - "beta.agent_session_turn_reasoning_summary_part_done_event.AgentSessionTurnReasoningSummaryPartDoneEvent": { - "event_id": [], - "item_id": [], - "output_index": [], - "part": [ - "beta.summary_text.SummaryText" - ], - "session_id": [], - "status": [], - "summary_index": [], - "turn_id": [], - "type": [] - }, - "beta.agent_session_turn_reasoning_summary_text_delta_event.AgentSessionTurnReasoningSummaryTextDeltaEvent": { - "delta": [], - "event_id": [], - "item_id": [], - "output_index": [], - "session_id": [], - "summary_index": [], - "turn_id": [], - "type": [] - }, - "beta.agent_session_turn_reasoning_summary_text_done_event.AgentSessionTurnReasoningSummaryTextDoneEvent": { - "event_id": [], - "item_id": [], - "output_index": [], - "session_id": [], - "summary_index": [], - "text": [], - "turn_id": [], - "type": [] - }, - "beta.agent_text.AgentText": { - "format": [ - "beta.text_format.TextFormatResourceJSONSchema", - "beta.text_format.TextFormatResourceText" - ], - "verbosity": [] - }, - "beta.agent_text_param.AgentTextParam": { - "format": [ - "beta.text_format_param.TextFormatParamJSONSchema", - "beta.text_format_param.TextFormatParamText" - ], - "verbosity": [] - }, - "beta.agent_tool.AgentToolResourceFunction": { - "defer_loading": [], - "description": [], - "name": [], - "parameters": [], - "type": [] - }, - "beta.agent_tool.AgentToolResourceMcp": { - "allowed_tools": [], - "connection_origin": [], - "credential_id": [], - "request_metadata": [], - "required": [], - "server_label": [], - "transport": [ - "beta.mcp_transport.McpTransportResourceHTTP", - "beta.mcp_transport.McpTransportResourceStdio" - ], - "type": [] - }, - "beta.agent_tool.AgentToolResourceProgrammaticToolCalling": { - "enabled": [], - "type": [] - }, - "beta.agent_tool.AgentToolResourceWebSearch": { - "allowed_domains": [], - "context_size": [], - "location": [ - "beta.agent_tool.AgentToolResourceWebSearchLocation" - ], - "mode": [], - "type": [] - }, - "beta.agent_tool.AgentToolResourceWebSearchLocation": { - "city": [], - "country": [], - "region": [], - "timezone": [] - }, - "beta.agent_tool_param.AgentToolConfigParamFunction": { - "defer_loading": [], - "description": [], - "name": [], - "parameters": [], - "type": [] - }, - "beta.agent_tool_param.AgentToolConfigParamMcp": { - "allowed_tools": [], - "connection_origin": [], - "credential_id": [], - "request_metadata": [], - "required": [], - "server_label": [], - "transport": [ - "beta.mcp_transport_param.McpTransportConfigParamHTTP", - "beta.mcp_transport_param.McpTransportConfigParamStdio" - ], - "type": [] - }, - "beta.agent_tool_param.AgentToolConfigParamProgrammaticToolCalling": { - "enabled": [], - "type": [] - }, - "beta.agent_tool_param.AgentToolConfigParamToolSearch": { - "type": [] - }, - "beta.agent_tool_param.AgentToolConfigParamWebSearch": { - "allowed_domains": [], - "context_size": [], - "location": [ - "beta.agent_tool_param.AgentToolConfigParamWebSearchLocation" - ], - "mode": [], - "type": [] - }, - "beta.agent_tool_param.AgentToolConfigParamWebSearchLocation": { - "city": [], - "country": [], - "region": [], - "timezone": [] - }, - "beta.agent_update_params.AgentUpdateParams": { - "instructions": [], - "metadata": [], - "model": [], - "multi_agent": [ - "beta.multi_agent_config_param.MultiAgentConfigParam" - ], - "name": [], - "reasoning": [ - "beta.agent_reasoning_param.AgentReasoningParam" - ], - "service_tier": [], - "text": [ - "beta.agent_text_param.AgentTextParam" - ], - "tools": [ - "beta.persisted_agent_tool_param.PersistedAgentToolConfigParamFunction", - "beta.persisted_agent_tool_param.PersistedAgentToolConfigParamMcp", - "beta.persisted_agent_tool_param.PersistedAgentToolConfigParamProgrammaticToolCalling", - "beta.persisted_agent_tool_param.PersistedAgentToolConfigParamToolSearch", - "beta.persisted_agent_tool_param.PersistedAgentToolConfigParamWebSearch" - ] - }, - "beta.agent_wait_for_subagents_call_item.AgentWaitForSubagentsCallItem": { - "id": [], - "recipient_agent_ids": [], - "sender_agent_id": [], - "status": [], - "turn_id": [], - "type": [] - }, - "beta.agent_web_search_call_item.AgentWebSearchCallItem": { - "action": [ - "beta.web_search_action.WebSearchActionResourceFindInPage", - "beta.web_search_action.WebSearchActionResourceOpenPage", - "beta.web_search_action.WebSearchActionResourceOther", - "beta.web_search_action.WebSearchActionResourceSearch" - ], - "id": [], - "status": [], - "turn_id": [], - "type": [] - }, - "beta.agents.environment_info.EnvironmentInfo": { - "files": [ - "beta.hosted_environment_file.HostedEnvironmentFileResourceInline", - "beta.hosted_environment_file_id.HostedEnvironmentFileID" - ], - "id": [], - "object": [], - "plugins": [ - "beta.hosted_plugin.HostedPlugin" - ], - "skills": [ - "beta.hosted_skill.HostedSkillResourceInline", - "beta.hosted_skill_reference.HostedSkillReference" - ], - "status": [], - "type": [] - }, - "beta.agents.environments.environment_file.EnvironmentFile": { - "environment_id": [], - "object": [], - "path": [], - "size_bytes": [] - }, - "beta.agents.environments.environment_template.EnvironmentTemplate": { - "capability_directories": [], - "created_at": [], - "files": [ - "beta.agents.environments.environment_template.FileHostedTemplateFileResourceFileID", - "beta.agents.environments.environment_template.FileHostedTemplateFileResourceInline" - ], - "id": [], - "name": [], - "network": [ - "beta.agents.environments.environment_template.Network" - ], - "object": [], - "packages": [ - "beta.agents.environments.environment_template.Packages" - ], - "plugins": [ - "beta.hosted_plugin.HostedPlugin" - ], - "skills": [ - "beta.agents.environments.environment_template.SkillHostedTemplateSkillResourceInline", - "beta.agents.environments.environment_template.SkillHostedTemplateSkillResourceSkillReference" - ], - "updated_at": [] - }, - "beta.agents.environments.environment_template.FileHostedTemplateFileResourceFileID": { - "file_id": [], - "path": [], - "type": [] - }, - "beta.agents.environments.environment_template.FileHostedTemplateFileResourceInline": { - "path": [], - "size_bytes": [], - "type": [] - }, - "beta.agents.environments.environment_template.Network": { - "access": [], - "allowed_domains": [] - }, - "beta.agents.environments.environment_template.Packages": { - "npm": [], - "python": [], - "system": [] - }, - "beta.agents.environments.environment_template.SkillHostedTemplateSkillResourceInline": { - "description": [], - "name": [], - "type": [] - }, - "beta.agents.environments.environment_template.SkillHostedTemplateSkillResourceSkillReference": { - "skill_id": [], - "type": [], - "version": [] - }, - "beta.agents.environments.environment_template_deleted.EnvironmentTemplateDeleted": { - "deleted": [], - "id": [], - "object": [] - }, - "beta.agents.environments.file_create_params.HostedEnvironmentFileParamFileID": { - "file_id": [], - "path": [], - "type": [] - }, - "beta.agents.environments.file_create_params.HostedEnvironmentFileParamInline": { - "data": [], - "path": [], - "type": [] - }, - "beta.agents.environments.file_list_params.FileListParams": { - "limit": [], - "order": [], - "page": [], - "path": [] - }, - "beta.agents.environments.template_create_params.Network": { - "access": [], - "allowed_domains": [] - }, - "beta.agents.environments.template_create_params.Packages": { - "npm": [], - "python": [], - "system": [] - }, - "beta.agents.environments.template_create_params.TemplateCreateParams": { - "capability_directories": [], - "env": [], - "files": [ - "beta.hosted_environment_file_param.HostedEnvironmentFileParamFileID", - "beta.hosted_environment_file_param.HostedEnvironmentFileParamInline" - ], - "name": [], - "network": [ - "beta.agents.environments.template_create_params.Network" - ], - "packages": [ - "beta.agents.environments.template_create_params.Packages" - ], - "plugins": [ - "beta.hosted_plugin_param.HostedPluginParam" - ], - "setup_commands": [ - "beta.setup_command_param.SetupCommandParam" - ], - "skills": [ - "beta.hosted_skill_param.HostedSkillParamInline", - "beta.hosted_skill_param.HostedSkillParamSkillReference" - ] - }, - "beta.agents.environments.template_list_params.TemplateListParams": { - "after": [], - "limit": [], - "order": [] - }, - "beta.agents.environments.template_update_params.Network": { - "access": [], - "allowed_domains": [] - }, - "beta.agents.environments.template_update_params.Packages": { - "npm": [], - "python": [], - "system": [] - }, - "beta.agents.environments.template_update_params.TemplateUpdateParams": { - "capability_directories": [], - "env": [], - "files": [ - "beta.hosted_environment_file_param.HostedEnvironmentFileParamFileID", - "beta.hosted_environment_file_param.HostedEnvironmentFileParamInline" - ], - "name": [], - "network": [ - "beta.agents.environments.template_update_params.Network" - ], - "packages": [ - "beta.agents.environments.template_update_params.Packages" - ], - "plugins": [ - "beta.hosted_plugin_param.HostedPluginParam" - ], - "setup_commands": [ - "beta.setup_command_param.SetupCommandParam" - ], - "skills": [ - "beta.hosted_skill_param.HostedSkillParamInline", - "beta.hosted_skill_param.HostedSkillParamSkillReference" - ] - }, - "beta.agents.session_create_params.Agent": { - "instructions": [], - "model": [], - "multi_agent": [ - "beta.multi_agent_config_param.MultiAgentConfigParam" - ], - "reasoning": [ - "beta.agent_reasoning_param.AgentReasoningParam" - ], - "service_tier": [], - "text": [ - "beta.agent_text_param.AgentTextParam" - ], - "tools": [ - "beta.agent_tool_param.AgentToolConfigParamFunction", - "beta.agent_tool_param.AgentToolConfigParamMcp", - "beta.agent_tool_param.AgentToolConfigParamProgrammaticToolCalling", - "beta.agent_tool_param.AgentToolConfigParamToolSearch", - "beta.agent_tool_param.AgentToolConfigParamWebSearch" - ] - }, - "beta.agents.session_create_params.SessionCreateParamsNonStreaming": { - "agent": [ - "beta.agents.session_create_params.Agent" - ], - "agent_id": [], - "environment": [ - "beta.environment_param.EnvironmentParamNone", - "beta.environment_param.EnvironmentParamOpenAIHosted", - "beta.environment_param.EnvironmentParamSelfHosted" - ], - "input": [ - "beta.agent_session_input_message_param.AgentSessionInputMessageParam" - ], - "metadata": [], - "stream": [], - "vault_ids": [] - }, - "beta.agents.session_create_params.SessionCreateParamsStreaming": { - "agent": [ - "beta.agents.session_create_params.Agent" - ], - "agent_id": [], - "environment": [ - "beta.environment_param.EnvironmentParamNone", - "beta.environment_param.EnvironmentParamOpenAIHosted", - "beta.environment_param.EnvironmentParamSelfHosted" - ], - "input": [ - "beta.agent_session_input_message_param.AgentSessionInputMessageParam" - ], - "metadata": [], - "stream": [], - "vault_ids": [] - }, - "beta.agents.session_list_params.SessionListParams": { - "after": [], - "agent_id": [], - "limit": [], - "order": [] - }, - "beta.agents.session_update_params.SessionUpdateParams": { - "metadata": [] - }, - "beta.agents.sessions.artifact_list_params.ArtifactListParams": { - "after": [], - "environment_id": [], - "limit": [], - "order": [] - }, - "beta.agents.sessions.event_create_params.EventCreateParams": { - "Idempotency-Key": [], - "events": [ - "beta.agent_session_input_param.SessionInputParamAgentSessionInputCancel", - "beta.agent_session_input_param.SessionInputParamAgentSessionInputMessage", - "beta.agent_session_input_param.SessionInputParamAgentSessionInputToolResult" - ] - }, - "beta.agents.sessions.item_list_params.ItemListParams": { - "after": [], - "limit": [], - "order": [] - }, - "beta.agents.sessions.session_artifact.SessionArtifact": { - "created_at": [], - "environment_id": [], - "id": [], - "object": [], - "path": [], - "session_id": [], - "size_bytes": [], - "turn_id": [] - }, - "beta.agents.sessions.session_artifact_deleted.SessionArtifactDeleted": { - "deleted": [], - "id": [], - "object": [] - }, - "beta.agents.sessions.subagent_list_params.SubagentListParams": { - "after": [], - "limit": [], - "order": [] - }, - "beta.agents.sessions.subagents.item_list_params.ItemListParams": { - "after": [], - "limit": [], - "order": [], - "session_id": [] - }, - "beta.agents.sessions.subagents.turn_list_params.TurnListParams": { - "after": [], - "limit": [], - "order": [], - "session_id": [] - }, - "beta.agents.sessions.subagents.turns.item_list_params.ItemListParams": { - "after": [], - "limit": [], - "order": [], - "session_id": [], - "subagent_id": [] - }, - "beta.agents.sessions.turn.Turn": { - "agent_id": [], - "completed_at": [], - "created_at": [], - "error": [ - "beta.session_turn_error.SessionTurnError" - ], - "id": [], - "object": [], - "session_id": [], - "started_at": [], - "status": [], - "subagent_id": [], - "usage": [ - "beta.token_usage.TokenUsage" - ] - }, - "beta.agents.sessions.turn_list_params.TurnListParams": { - "after": [], - "limit": [], - "order": [] - }, - "beta.agents.vault.Vault": { - "created_at": [], - "id": [], - "metadata": [], - "name": [], - "object": [] - }, - "beta.agents.vault_create_params.VaultCreateParams": { - "metadata": [], - "name": [] - }, - "beta.agents.vault_deleted.VaultDeleted": { - "deleted": [], - "id": [], - "object": [] - }, - "beta.agents.vault_list_params.VaultListParams": { - "after": [], - "limit": [], - "order": [], - "status": [] - }, - "beta.agents.vaults.credential.Credential": { - "auth": [ - "beta.agents.vaults.credential_auth.VaultCredentialAuthResourceMcpOauth", - "beta.agents.vaults.credential_auth.VaultCredentialAuthResourceStaticBearer" - ], - "created_at": [], - "id": [], - "name": [], - "object": [], - "updated_at": [], - "vault_id": [] - }, - "beta.agents.vaults.credential_auth.VaultCredentialAuthResourceMcpOauth": { - "expires_at": [], - "mcp_server_url": [], - "refresh": [ - "beta.agents.vaults.credential_auth.VaultCredentialAuthResourceMcpOauthRefresh" - ], - "type": [] - }, - "beta.agents.vaults.credential_auth.VaultCredentialAuthResourceMcpOauthRefresh": { - "client_id": [], - "resource": [], - "scope": [], - "token_endpoint": [], - "token_endpoint_auth": [ - "beta.agents.vaults.mcp_oauth_token_endpoint_auth.McpOauthTokenEndpointAuthResourceClientSecretBasic", - "beta.agents.vaults.mcp_oauth_token_endpoint_auth.McpOauthTokenEndpointAuthResourceClientSecretPost", - "beta.agents.vaults.mcp_oauth_token_endpoint_auth.McpOauthTokenEndpointAuthResourceNone" - ] - }, - "beta.agents.vaults.credential_auth.VaultCredentialAuthResourceStaticBearer": { - "mcp_server_url": [], - "type": [] - }, - "beta.agents.vaults.credential_auth_create_param.CreateVaultCredentialAuthParamMcpOauth": { - "access_token": [], - "expires_at": [], - "mcp_server_url": [], - "refresh": [ - "beta.agents.vaults.credential_auth_create_param.CreateVaultCredentialAuthParamMcpOauthRefresh" - ], - "type": [] - }, - "beta.agents.vaults.credential_auth_create_param.CreateVaultCredentialAuthParamMcpOauthRefresh": { - "client_id": [], - "refresh_token": [], - "resource": [], - "scope": [], - "token_endpoint": [], - "token_endpoint_auth": [ - "beta.agents.vaults.mcp_oauth_token_endpoint_auth_create_param.CreateMcpOauthTokenEndpointAuthParamClientSecretBasic", - "beta.agents.vaults.mcp_oauth_token_endpoint_auth_create_param.CreateMcpOauthTokenEndpointAuthParamClientSecretPost", - "beta.agents.vaults.mcp_oauth_token_endpoint_auth_create_param.CreateMcpOauthTokenEndpointAuthParamNone" - ] - }, - "beta.agents.vaults.credential_auth_create_param.CreateVaultCredentialAuthParamStaticBearer": { - "mcp_server_url": [], - "token": [], - "type": [] - }, - "beta.agents.vaults.credential_auth_rotate_param.RotateVaultCredentialAuthParamMcpOauth": { - "access_token": [], - "expires_at": [], - "refresh": [ - "beta.agents.vaults.credential_auth_rotate_param.RotateVaultCredentialAuthParamMcpOauthRefresh" - ], - "type": [] - }, - "beta.agents.vaults.credential_auth_rotate_param.RotateVaultCredentialAuthParamMcpOauthRefresh": { - "refresh_token": [], - "scope": [], - "token_endpoint_auth": [ - "beta.agents.vaults.mcp_oauth_token_endpoint_auth_rotate_param.RotateMcpOauthTokenEndpointAuthParamClientSecretBasic", - "beta.agents.vaults.mcp_oauth_token_endpoint_auth_rotate_param.RotateMcpOauthTokenEndpointAuthParamClientSecretPost" - ] - }, - "beta.agents.vaults.credential_auth_rotate_param.RotateVaultCredentialAuthParamStaticBearer": { - "token": [], - "type": [] - }, - "beta.agents.vaults.credential_create_params.CredentialCreateParams": { - "auth": [ - "beta.agents.vaults.credential_auth_create_param.CreateVaultCredentialAuthParamMcpOauth", - "beta.agents.vaults.credential_auth_create_param.CreateVaultCredentialAuthParamStaticBearer" - ], - "name": [] - }, - "beta.agents.vaults.credential_deleted.CredentialDeleted": { - "deleted": [], - "id": [], - "object": [] - }, - "beta.agents.vaults.credential_list_params.CredentialListParams": { - "after": [], - "limit": [], - "order": [], - "status": [] - }, - "beta.agents.vaults.credential_update_params.CredentialUpdateParams": { - "auth": [ - "beta.agents.vaults.credential_auth_rotate_param.RotateVaultCredentialAuthParamMcpOauth", - "beta.agents.vaults.credential_auth_rotate_param.RotateVaultCredentialAuthParamStaticBearer" - ], - "vault_id": [] - }, - "beta.agents.vaults.mcp_oauth_token_endpoint_auth.McpOauthTokenEndpointAuthResourceClientSecretBasic": { - "type": [] - }, - "beta.agents.vaults.mcp_oauth_token_endpoint_auth.McpOauthTokenEndpointAuthResourceClientSecretPost": { - "type": [] - }, - "beta.agents.vaults.mcp_oauth_token_endpoint_auth.McpOauthTokenEndpointAuthResourceNone": { - "type": [] - }, - "beta.agents.vaults.mcp_oauth_token_endpoint_auth_create_param.CreateMcpOauthTokenEndpointAuthParamClientSecretBasic": { - "client_secret": [], - "type": [] - }, - "beta.agents.vaults.mcp_oauth_token_endpoint_auth_create_param.CreateMcpOauthTokenEndpointAuthParamClientSecretPost": { - "client_secret": [], - "type": [] - }, - "beta.agents.vaults.mcp_oauth_token_endpoint_auth_create_param.CreateMcpOauthTokenEndpointAuthParamNone": { - "type": [] - }, - "beta.agents.vaults.mcp_oauth_token_endpoint_auth_rotate_param.RotateMcpOauthTokenEndpointAuthParamClientSecretBasic": { - "client_secret": [], - "type": [] - }, - "beta.agents.vaults.mcp_oauth_token_endpoint_auth_rotate_param.RotateMcpOauthTokenEndpointAuthParamClientSecretPost": { - "client_secret": [], - "type": [] - }, - "beta.environment.EnvironmentResourceNone": { - "type": [] - }, - "beta.environment.EnvironmentResourceOpenAIHosted": { - "capability_directories": [], - "files": [ - "beta.hosted_environment_file.HostedEnvironmentFileResourceInline", - "beta.hosted_environment_file_id.HostedEnvironmentFileID" - ], - "id": [], - "network": [ - "beta.environment.EnvironmentResourceOpenAIHostedNetwork" - ], - "packages": [ - "beta.environment.EnvironmentResourceOpenAIHostedPackages" - ], - "plugins": [ - "beta.hosted_plugin.HostedPlugin" - ], - "skills": [ - "beta.hosted_skill.HostedSkillResourceInline", - "beta.hosted_skill_reference.HostedSkillReference" - ], - "type": [] - }, - "beta.environment.EnvironmentResourceOpenAIHostedNetwork": { - "access": [], - "allowed_domains": [] - }, - "beta.environment.EnvironmentResourceOpenAIHostedPackages": { - "npm": [], - "python": [], - "system": [] - }, - "beta.environment.EnvironmentResourceSelfHosted": { - "capability_directories": [], - "id": [], - "remote_url": [], - "type": [], - "workspace_directory": [] - }, - "beta.environment_param.EnvironmentParamNone": { - "type": [] - }, - "beta.environment_param.EnvironmentParamOpenAIHosted": { - "capability_directories": [], - "env": [], - "environment_template_id": [], - "files": [ - "beta.hosted_environment_file_param.HostedEnvironmentFileParamFileID", - "beta.hosted_environment_file_param.HostedEnvironmentFileParamInline" - ], - "network": [ - "beta.environment_param.EnvironmentParamOpenAIHostedNetwork" - ], - "packages": [ - "beta.environment_param.EnvironmentParamOpenAIHostedPackages" - ], - "plugins": [ - "beta.hosted_plugin_param.HostedPluginParam" - ], - "setup_commands": [ - "beta.setup_command_param.SetupCommandParam" - ], - "skills": [ - "beta.hosted_skill_param.HostedSkillParamInline", - "beta.hosted_skill_param.HostedSkillParamSkillReference" - ], - "type": [] - }, - "beta.environment_param.EnvironmentParamOpenAIHostedNetwork": { - "access": [], - "allowed_domains": [] - }, - "beta.environment_param.EnvironmentParamOpenAIHostedPackages": { - "npm": [], - "python": [], - "system": [] - }, - "beta.environment_param.EnvironmentParamSelfHosted": { - "capability_directories": [], - "type": [], - "workspace_directory": [] - }, - "beta.hosted_environment_file.HostedEnvironmentFileResourceInline": { - "id": [], - "path": [], - "size_bytes": [], - "type": [] - }, - "beta.hosted_environment_file_id.HostedEnvironmentFileID": { - "file_id": [], - "id": [], - "path": [], - "size_bytes": [], - "type": [] - }, - "beta.hosted_environment_file_param.HostedEnvironmentFileParamFileID": { - "file_id": [], - "path": [], - "type": [] - }, - "beta.hosted_environment_file_param.HostedEnvironmentFileParamInline": { - "data": [], - "path": [], - "type": [] - }, - "beta.hosted_plugin.HostedPlugin": { - "description": [], - "name": [], - "type": [] - }, - "beta.hosted_plugin_param.HostedPluginParam": { - "description": [], - "name": [], - "source": [ - "beta.inline_capability_source_param.InlineCapabilitySourceParam" - ], - "type": [] - }, - "beta.hosted_skill.HostedSkillResourceInline": { - "description": [], - "name": [], - "type": [] - }, - "beta.hosted_skill_param.HostedSkillParamInline": { - "description": [], - "name": [], - "source": [ - "beta.inline_capability_source_param.InlineCapabilitySourceParam" - ], - "type": [] - }, - "beta.hosted_skill_param.HostedSkillParamSkillReference": { - "skill_id": [], - "type": [], - "version": [] - }, - "beta.hosted_skill_reference.HostedSkillReference": { - "description": [], - "name": [], - "skill_id": [], - "type": [], - "version": [] - }, - "beta.inline_capability_source_param.InlineCapabilitySourceParam": { - "data": [], - "media_type": [], - "type": [] - }, - "beta.input_content.InputContentResourceInputImage": { - "image_url": [], - "type": [] - }, - "beta.input_content.InputContentResourceInputText": { - "text": [], - "type": [] - }, - "beta.input_content_param.InputContentParamInputImage": { - "image_url": [], - "type": [] - }, - "beta.input_content_param.InputContentParamInputText": { - "text": [], - "type": [] - }, - "beta.mcp_transport.McpTransportResourceHTTP": { - "server_url": [], - "type": [] - }, - "beta.mcp_transport.McpTransportResourceStdio": { - "args": [], - "command": [], - "cwd": [], - "env_vars": [], - "type": [] - }, - "beta.mcp_transport_param.McpTransportConfigParamHTTP": { - "authorization": [], - "headers": [], - "server_url": [], - "type": [] - }, - "beta.mcp_transport_param.McpTransportConfigParamStdio": { - "args": [], - "command": [], - "cwd": [], - "env": [], - "env_vars": [], - "type": [] - }, - "beta.multi_agent_config.MultiAgentConfig": { - "enabled": [], - "max_concurrent_subagents": [] - }, - "beta.multi_agent_config_param.MultiAgentConfigParam": { - "enabled": [], - "max_concurrent_subagents": [] - }, - "beta.output_text.OutputText": { - "text": [], - "type": [] - }, - "beta.persisted_agent_tool.PersistedAgentToolResourceFunction": { - "defer_loading": [], - "description": [], - "name": [], - "parameters": [], - "type": [] - }, - "beta.persisted_agent_tool.PersistedAgentToolResourceMcp": { - "allowed_tools": [], - "connection_origin": [], - "credential_id": [], - "request_metadata": [], - "required": [], - "server_label": [], - "transport": [ - "beta.persisted_mcp_transport.PersistedMcpTransportResourceHTTP", - "beta.persisted_mcp_transport.PersistedMcpTransportResourceStdio" - ], - "type": [] - }, - "beta.persisted_agent_tool.PersistedAgentToolResourceProgrammaticToolCalling": { - "enabled": [], - "type": [] - }, - "beta.persisted_agent_tool.PersistedAgentToolResourceToolSearch": { - "type": [] - }, - "beta.persisted_agent_tool.PersistedAgentToolResourceWebSearch": { - "allowed_domains": [], - "context_size": [], - "location": [ - "beta.persisted_agent_tool.PersistedAgentToolResourceWebSearchLocation" - ], - "mode": [], - "type": [] - }, - "beta.persisted_agent_tool.PersistedAgentToolResourceWebSearchLocation": { - "city": [], - "country": [], - "region": [], - "timezone": [] - }, - "beta.persisted_agent_tool_param.PersistedAgentToolConfigParamFunction": { - "defer_loading": [], - "description": [], - "name": [], - "parameters": [], - "type": [] - }, - "beta.persisted_agent_tool_param.PersistedAgentToolConfigParamMcp": { - "allowed_tools": [], - "connection_origin": [], - "credential_id": [], - "request_metadata": [], - "required": [], - "server_label": [], - "transport": [ - "beta.persisted_mcp_transport_param.PersistedMcpTransportConfigParamHTTP", - "beta.persisted_mcp_transport_param.PersistedMcpTransportConfigParamStdio" - ], - "type": [] - }, - "beta.persisted_agent_tool_param.PersistedAgentToolConfigParamProgrammaticToolCalling": { - "enabled": [], - "type": [] - }, - "beta.persisted_agent_tool_param.PersistedAgentToolConfigParamToolSearch": { - "type": [] - }, - "beta.persisted_agent_tool_param.PersistedAgentToolConfigParamWebSearch": { - "allowed_domains": [], - "context_size": [], - "location": [ - "beta.persisted_agent_tool_param.PersistedAgentToolConfigParamWebSearchLocation" - ], - "mode": [], - "type": [] - }, - "beta.persisted_agent_tool_param.PersistedAgentToolConfigParamWebSearchLocation": { - "city": [], - "country": [], - "region": [], - "timezone": [] - }, - "beta.persisted_mcp_transport.PersistedMcpTransportResourceHTTP": { - "headers": [], - "server_url": [], - "type": [] - }, - "beta.persisted_mcp_transport.PersistedMcpTransportResourceStdio": { - "args": [], - "command": [], - "cwd": [], - "env_vars": [], - "type": [] - }, - "beta.persisted_mcp_transport_param.PersistedMcpTransportConfigParamHTTP": { - "headers": [], - "server_url": [], - "type": [] - }, - "beta.persisted_mcp_transport_param.PersistedMcpTransportConfigParamStdio": { - "args": [], - "command": [], - "cwd": [], - "env_vars": [], - "type": [] - }, - "beta.session_error.SessionError": { - "code": [], - "message": [], - "param": [], - "type": [] - }, - "beta.session_turn_error.SessionTurnError": { - "code": [], - "message": [] - }, - "beta.setup_command_param.SetupCommandParam": { - "command": [], - "cwd": [] - }, - "beta.subagent.Subagent": { - "closed_at": [], - "id": [], - "instructions": [ - "beta.agent_content.EncryptedContentResource", - "beta.output_text.OutputText" - ], - "name": [], - "object": [], - "opened_at": [], - "parent_agent_id": [], - "session_id": [], - "status": [] - }, - "beta.summary_text.SummaryText": { - "text": [], - "type": [] - }, - "beta.text_format.TextFormatResourceJSONSchema": { - "schema": [], - "type": [] - }, - "beta.text_format.TextFormatResourceText": { - "type": [] - }, - "beta.text_format_param.TextFormatParamJSONSchema": { - "schema": [], - "type": [] - }, - "beta.text_format_param.TextFormatParamText": { - "type": [] - }, - "beta.token_usage.InputTokensDetails": { - "cached_tokens": [] - }, - "beta.token_usage.OutputTokensDetails": { - "reasoning_tokens": [] - }, - "beta.token_usage.TokenUsage": { - "input_tokens": [], - "input_tokens_details": [ - "beta.token_usage.InputTokensDetails" - ], - "output_tokens": [], - "output_tokens_details": [ - "beta.token_usage.OutputTokensDetails" - ], - "total_tokens": [] - }, - "beta.web_search_action.WebSearchActionResourceFindInPage": { - "pattern": [], - "type": [], - "url": [] - }, - "beta.web_search_action.WebSearchActionResourceOpenPage": { - "type": [], - "url": [] - }, - "beta.web_search_action.WebSearchActionResourceOther": { - "type": [] - }, - "beta.web_search_action.WebSearchActionResourceSearch": { - "queries": [], - "query": [], - "type": [] - }, - "deleted_skill.DeletedSkill": { - "deleted": [], - "id": [], - "object": [] - }, - "file_create_params.ExpiresAfter": { - "anchor": [], - "seconds": [] - }, - "file_create_params.FileCreateParams": { - "expires_after": [ - "file_create_params.ExpiresAfter" - ], - "file": [], - "purpose": [] - }, - "file_deleted.FileDeleted": { - "deleted": [], - "id": [], - "object": [] - }, - "file_list_params.FileListParams": { - "after": [], - "limit": [], - "order": [], - "purpose": [] - }, - "file_object.FileObject": { - "bytes": [], - "created_at": [], - "expires_at": [], - "filename": [], - "id": [], - "object": [], - "purpose": [], - "status": [], - "status_details": [] - }, - "pagination.SyncCursorPage[beta.agent.Agent]": { - "data": [ - "beta.agent.Agent" - ], - "has_more": [] - }, - "pagination.SyncCursorPage[beta.agent_close_subagent_call_item.AgentCloseSubagentCallItem | beta.agent_command_execution_item.AgentCommandExecutionItem | beta.agent_create_subagent_call_item.AgentCreateSubagentCallItem | beta.agent_function_call_item.AgentFunctionCallItem | beta.agent_interrupt_subagent_call_item.AgentInterruptSubagentCallItem | beta.agent_mcp_call_item.AgentMcpCallItem | beta.agent_reasoning_item.AgentReasoningItem | beta.agent_resume_subagent_call_item.AgentResumeSubagentCallItem | beta.agent_send_subagent_input_call_item.AgentSendSubagentInputCallItem | beta.agent_session_item.AgentMessageItemResource | beta.agent_session_item.FunctionCallOutputItemResource | beta.agent_session_message.AgentSessionMessage | beta.agent_wait_for_subagents_call_item.AgentWaitForSubagentsCallItem | beta.agent_web_search_call_item.AgentWebSearchCallItem]": { - "data": [ - "beta.agent_close_subagent_call_item.AgentCloseSubagentCallItem", - "beta.agent_command_execution_item.AgentCommandExecutionItem", - "beta.agent_create_subagent_call_item.AgentCreateSubagentCallItem", - "beta.agent_function_call_item.AgentFunctionCallItem", - "beta.agent_interrupt_subagent_call_item.AgentInterruptSubagentCallItem", - "beta.agent_mcp_call_item.AgentMcpCallItem", - "beta.agent_reasoning_item.AgentReasoningItem", - "beta.agent_resume_subagent_call_item.AgentResumeSubagentCallItem", - "beta.agent_send_subagent_input_call_item.AgentSendSubagentInputCallItem", - "beta.agent_session_item.AgentMessageItemResource", - "beta.agent_session_item.FunctionCallOutputItemResource", - "beta.agent_session_message.AgentSessionMessage", - "beta.agent_wait_for_subagents_call_item.AgentWaitForSubagentsCallItem", - "beta.agent_web_search_call_item.AgentWebSearchCallItem" - ], - "has_more": [] - }, - "pagination.SyncCursorPage[beta.agent_session.AgentSession]": { - "data": [ - "beta.agent_session.AgentSession" - ], - "has_more": [] - }, - "pagination.SyncCursorPage[beta.agents.environments.environment_template.EnvironmentTemplate]": { - "data": [ - "beta.agents.environments.environment_template.EnvironmentTemplate" - ], - "has_more": [] - }, - "pagination.SyncCursorPage[beta.agents.sessions.session_artifact.SessionArtifact]": { - "data": [ - "beta.agents.sessions.session_artifact.SessionArtifact" - ], - "has_more": [] - }, - "pagination.SyncCursorPage[beta.agents.sessions.turn.Turn]": { - "data": [ - "beta.agents.sessions.turn.Turn" - ], - "has_more": [] - }, - "pagination.SyncCursorPage[beta.agents.vault.Vault]": { - "data": [ - "beta.agents.vault.Vault" - ], - "has_more": [] - }, - "pagination.SyncCursorPage[beta.agents.vaults.credential.Credential]": { - "data": [ - "beta.agents.vaults.credential.Credential" - ], - "has_more": [] - }, - "pagination.SyncCursorPage[beta.subagent.Subagent]": { - "data": [ - "beta.subagent.Subagent" - ], - "has_more": [] - }, - "pagination.SyncCursorPage[file_object.FileObject]": { - "data": [ - "file_object.FileObject" - ], - "has_more": [] - }, - "pagination.SyncCursorPage[skill.Skill]": { - "data": [ - "skill.Skill" - ], - "has_more": [] - }, - "pagination.SyncCursorPage[skills.skill_version.SkillVersion]": { - "data": [ - "skills.skill_version.SkillVersion" - ], - "has_more": [] - }, - "pagination.SyncTokenPage[beta.agents.environments.environment_file.EnvironmentFile]": { - "data": [ - "beta.agents.environments.environment_file.EnvironmentFile" - ], - "has_more": [], - "next": [] - }, - "skill.Skill": { - "created_at": [], - "default_version": [], - "description": [], - "id": [], - "latest_version": [], - "name": [], - "object": [] - }, - "skill_create_params.SkillCreateParams": { - "files": [] - }, - "skill_list_params.SkillListParams": { - "after": [], - "limit": [], - "order": [] - }, - "skill_update_params.SkillUpdateParams": { - "default_version": [] - }, - "skills.deleted_skill_version.DeletedSkillVersion": { - "deleted": [], - "id": [], - "object": [], - "version": [] - }, - "skills.skill_version.SkillVersion": { - "created_at": [], - "description": [], - "id": [], - "name": [], - "object": [], - "skill_id": [], - "version": [] - }, - "skills.version_create_params.VersionCreateParams": { - "default": [], - "files": [] - }, - "skills.version_list_params.VersionListParams": { - "after": [], - "limit": [], - "order": [] - } - } -} diff --git a/contracts/agents-api/upstream-routes.json b/contracts/agents-api/upstream-routes.json index 3326834f2..1f305b93a 100644 --- a/contracts/agents-api/upstream-routes.json +++ b/contracts/agents-api/upstream-routes.json @@ -1,12 +1,6 @@ { - "sdk_version": "3.13.0", - "commit": "d7c41efee1b0802b79f3f88a678ef2052b06e9ce", - "generator": "scripts/extract-agents-api-upstream.py", - "resources": [ - "openai.resources.beta.agents", - "openai.resources.files", - "openai.resources.skills" - ], + "openapi_commit": "046a2a0f325bf11f97966f2729219f27281ba71e", + "generator": "scripts/generate-public-api.py", "routes": [ "DELETE /agents/environments/templates/{}", "DELETE /agents/sessions/{}", diff --git a/contracts/agents-api/upstream.json b/contracts/agents-api/upstream.json index adc71d0bb..253e00627 100644 --- a/contracts/agents-api/upstream.json +++ b/contracts/agents-api/upstream.json @@ -4,5 +4,11 @@ "sdk_version": "3.13.0", "resource_path": "src/openai/resources/beta/agents", "type_path": "src/openai/types/beta", - "beta_header": "agents=v1" + "beta_header": "agents=v1", + "openapi": { + "repository": "https://github.com/openai/openai-openapi", + "commit": "046a2a0f325bf11f97966f2729219f27281ba71e", + "path": "openapi.json", + "sha256": "c96d974b164ff4750fa5ea5a1727f7ce6691540e257c177db02b660b0db58f26" + } } diff --git a/contracts/agents-api/upstream/LICENSE b/contracts/agents-api/upstream/LICENSE new file mode 100644 index 000000000..4f14854c3 --- /dev/null +++ b/contracts/agents-api/upstream/LICENSE @@ -0,0 +1,21 @@ +The MIT License + +Copyright (c) OpenAI (https://openai.com) + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. diff --git a/contracts/agents-api/upstream/openapi.json b/contracts/agents-api/upstream/openapi.json new file mode 100644 index 000000000..f966c2530 --- /dev/null +++ b/contracts/agents-api/upstream/openapi.json @@ -0,0 +1,107618 @@ +{ + "openapi": "3.1.0", + "info": { + "title": "OpenAI API", + "description": "The OpenAI REST API. Please see https://platform.openai.com/docs/api-reference for more details.", + "version": "2.3.0", + "termsOfService": "https://openai.com/policies/terms-of-use", + "contact": { + "name": "OpenAI Support", + "url": "https://help.openai.com/" + }, + "license": { + "name": "MIT", + "identifier": "MIT" + } + }, + "servers": [ + { + "url": "https://api.openai.com/v1" + } + ], + "security": [ + { + "ApiKeyAuth": [] + } + ], + "tags": [ + { + "name": "Assistants", + "description": "Build Assistants that can call models and use tools." + }, + { + "name": "Audio", + "description": "Turn audio into text or text into audio." + }, + { + "name": "Chat", + "description": "Given a list of messages comprising a conversation, the model will return a response." + }, + { + "name": "Conversations", + "description": "Manage conversations and conversation items." + }, + { + "name": "Completions", + "description": "Given a prompt, the model will return one or more predicted completions, and can also return the probabilities of alternative tokens at each position." + }, + { + "name": "Embeddings", + "description": "Get a vector representation of a given input that can be easily consumed by machine learning models and algorithms." + }, + { + "name": "Evals", + "description": "Manage and run evals in the OpenAI platform." + }, + { + "name": "Fine-tuning", + "description": "Manage fine-tuning jobs to tailor a model to your specific training data." + }, + { + "name": "Graders", + "description": "Manage and run graders in the OpenAI platform." + }, + { + "name": "Batch", + "description": "Create large batches of API requests to run asynchronously." + }, + { + "name": "Files", + "description": "Files are used to upload documents that can be used with features like Assistants and Fine-tuning." + }, + { + "name": "Uploads", + "description": "Use Uploads to upload large files in multiple parts." + }, + { + "name": "Images", + "description": "Given a prompt and/or an input image, the model will generate a new image." + }, + { + "name": "Models", + "description": "List and describe the various models available in the API." + }, + { + "name": "Moderations", + "description": "Given text and/or image inputs, classifies if those inputs are potentially harmful." + }, + { + "name": "Audit Logs", + "description": "List user actions and configuration changes within this organization." + } + ], + "paths": { + "/assistants": { + "get": { + "operationId": "listAssistants", + "tags": [ + "Assistants" + ], + "summary": "Returns a list of assistants.", + "deprecated": true, + "parameters": [ + { + "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.\n", + "required": false, + "schema": { + "type": "integer", + "default": 20 + } + }, + { + "name": "order", + "in": "query", + "description": "Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order.\n", + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + } + }, + { + "name": "after", + "in": "query", + "description": "A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.\n", + "schema": { + "type": "string" + } + }, + { + "name": "before", + "in": "query", + "description": "A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list.\n", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListAssistantsResponse" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "List assistants", + "group": "assistants", + "examples": { + "request": { + "curl": "curl \"https://api.openai.com/v1/assistants?order=desc&limit=20\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"OpenAI-Beta: assistants=v2\"\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\nmy_assistants = client.beta.assistants.list(\n order=\"desc\",\n limit=\"20\",\n)\nprint(my_assistants.data)\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const myAssistants = await openai.beta.assistants.list({\n order: \"desc\",\n limit: \"20\",\n });\n\n console.log(myAssistants.data);\n}\n\nmain();" + }, + "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"asst_abc123\",\n \"object\": \"assistant\",\n \"created_at\": 1698982736,\n \"name\": \"Coding Tutor\",\n \"description\": null,\n \"model\": \"gpt-5\",\n \"instructions\": \"You are a helpful assistant designed to make me better at coding!\",\n \"tools\": [],\n \"tool_resources\": {},\n \"metadata\": {},\n \"top_p\": 1.0,\n \"temperature\": 1.0,\n \"response_format\": \"auto\"\n },\n {\n \"id\": \"asst_abc456\",\n \"object\": \"assistant\",\n \"created_at\": 1698982718,\n \"name\": \"My Assistant\",\n \"description\": null,\n \"model\": \"gpt-5\",\n \"instructions\": \"You are a helpful assistant designed to make me better at coding!\",\n \"tools\": [],\n \"tool_resources\": {},\n \"metadata\": {},\n \"top_p\": 1.0,\n \"temperature\": 1.0,\n \"response_format\": \"auto\"\n },\n {\n \"id\": \"asst_abc789\",\n \"object\": \"assistant\",\n \"created_at\": 1698982643,\n \"name\": null,\n \"description\": null,\n \"model\": \"gpt-5\",\n \"instructions\": null,\n \"tools\": [],\n \"tool_resources\": {},\n \"metadata\": {},\n \"top_p\": 1.0,\n \"temperature\": 1.0,\n \"response_format\": \"auto\"\n }\n ],\n \"first_id\": \"asst_abc123\",\n \"last_id\": \"asst_abc789\",\n \"has_more\": false\n}\n" + } + } + }, + "post": { + "operationId": "createAssistant", + "tags": [ + "Assistants" + ], + "summary": "Create an assistant with a model and instructions.", + "deprecated": true, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateAssistantRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AssistantObject" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Create assistant", + "group": "assistants", + "examples": [ + { + "title": "Code Interpreter", + "request": { + "curl": "curl \"https://api.openai.com/v1/assistants\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"OpenAI-Beta: assistants=v2\" \\\n -d '{\n \"instructions\": \"You are a personal math tutor. When asked a question, write and run Python code to answer the question.\",\n \"name\": \"Math Tutor\",\n \"tools\": [{\"type\": \"code_interpreter\"}],\n \"model\": \"gpt-5\"\n }'\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\nmy_assistant = client.beta.assistants.create(\n instructions=\"You are a personal math tutor. When asked a question, write and run Python code to answer the question.\",\n name=\"Math Tutor\",\n tools=[{\"type\": \"code_interpreter\"}],\n model=\"gpt-5\",\n)\nprint(my_assistant)\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const myAssistant = await openai.beta.assistants.create({\n instructions:\n \"You are a personal math tutor. When asked a question, write and run Python code to answer the question.\",\n name: \"Math Tutor\",\n tools: [{ type: \"code_interpreter\" }],\n model: \"gpt-5\",\n });\n\n console.log(myAssistant);\n}\n\nmain();" + }, + "response": "{\n \"id\": \"asst_abc123\",\n \"object\": \"assistant\",\n \"created_at\": 1698984975,\n \"name\": \"Math Tutor\",\n \"description\": null,\n \"model\": \"gpt-5\",\n \"instructions\": \"You are a personal math tutor. When asked a question, write and run Python code to answer the question.\",\n \"tools\": [\n {\n \"type\": \"code_interpreter\"\n }\n ],\n \"metadata\": {},\n \"top_p\": 1.0,\n \"temperature\": 1.0,\n \"response_format\": \"auto\"\n}\n" + }, + { + "title": "Files", + "request": { + "curl": "curl https://api.openai.com/v1/assistants \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"OpenAI-Beta: assistants=v2\" \\\n -d '{\n \"instructions\": \"You are an HR bot, and you have access to files to answer employee questions about company policies.\",\n \"tools\": [{\"type\": \"file_search\"}],\n \"tool_resources\": {\"file_search\": {\"vector_store_ids\": [\"vs_123\"]}},\n \"model\": \"gpt-5\"\n }'\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\nmy_assistant = client.beta.assistants.create(\n instructions=\"You are an HR bot, and you have access to files to answer employee questions about company policies.\",\n name=\"HR Helper\",\n tools=[{\"type\": \"file_search\"}],\n tool_resources={\"file_search\": {\"vector_store_ids\": [\"vs_123\"]}},\n model=\"gpt-5\"\n)\nprint(my_assistant)\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const myAssistant = await openai.beta.assistants.create({\n instructions:\n \"You are an HR bot, and you have access to files to answer employee questions about company policies.\",\n name: \"HR Helper\",\n tools: [{ type: \"file_search\" }],\n tool_resources: {\n file_search: {\n vector_store_ids: [\"vs_123\"]\n }\n },\n model: \"gpt-5\"\n });\n\n console.log(myAssistant);\n}\n\nmain();" + }, + "response": "{\n \"id\": \"asst_abc123\",\n \"object\": \"assistant\",\n \"created_at\": 1699009403,\n \"name\": \"HR Helper\",\n \"description\": null,\n \"model\": \"gpt-5\",\n \"instructions\": \"You are an HR bot, and you have access to files to answer employee questions about company policies.\",\n \"tools\": [\n {\n \"type\": \"file_search\"\n }\n ],\n \"tool_resources\": {\n \"file_search\": {\n \"vector_store_ids\": [\"vs_123\"]\n }\n },\n \"metadata\": {},\n \"top_p\": 1.0,\n \"temperature\": 1.0,\n \"response_format\": \"auto\"\n}\n" + } + ] + } + } + }, + "/assistants/{assistant_id}": { + "get": { + "operationId": "getAssistant", + "tags": [ + "Assistants" + ], + "summary": "Retrieves an assistant.", + "deprecated": true, + "parameters": [ + { + "in": "path", + "name": "assistant_id", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the assistant to retrieve." + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AssistantObject" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Retrieve assistant", + "group": "assistants", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/assistants/asst_abc123 \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"OpenAI-Beta: assistants=v2\"\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\nmy_assistant = client.beta.assistants.retrieve(\"asst_abc123\")\nprint(my_assistant)\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const myAssistant = await openai.beta.assistants.retrieve(\n \"asst_abc123\"\n );\n\n console.log(myAssistant);\n}\n\nmain();" + }, + "response": "{\n \"id\": \"asst_abc123\",\n \"object\": \"assistant\",\n \"created_at\": 1699009709,\n \"name\": \"HR Helper\",\n \"description\": null,\n \"model\": \"gpt-5\",\n \"instructions\": \"You are an HR bot, and you have access to files to answer employee questions about company policies.\",\n \"tools\": [\n {\n \"type\": \"file_search\"\n }\n ],\n \"metadata\": {},\n \"top_p\": 1.0,\n \"temperature\": 1.0,\n \"response_format\": \"auto\"\n}\n" + } + } + }, + "post": { + "operationId": "modifyAssistant", + "tags": [ + "Assistants" + ], + "summary": "Modifies an assistant.", + "deprecated": true, + "parameters": [ + { + "in": "path", + "name": "assistant_id", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the assistant to modify." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ModifyAssistantRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AssistantObject" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Modify assistant", + "group": "assistants", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/assistants/asst_abc123 \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"OpenAI-Beta: assistants=v2\" \\\n -d '{\n \"instructions\": \"You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.\",\n \"tools\": [{\"type\": \"file_search\"}],\n \"model\": \"gpt-5\"\n }'\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\nmy_updated_assistant = client.beta.assistants.update(\n \"asst_abc123\",\n instructions=\"You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.\",\n name=\"HR Helper\",\n tools=[{\"type\": \"file_search\"}],\n model=\"gpt-5\"\n)\n\nprint(my_updated_assistant)\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const myUpdatedAssistant = await openai.beta.assistants.update(\n \"asst_abc123\",\n {\n instructions:\n \"You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.\",\n name: \"HR Helper\",\n tools: [{ type: \"file_search\" }],\n model: \"gpt-5\"\n }\n );\n\n console.log(myUpdatedAssistant);\n}\n\nmain();" + }, + "response": "{\n \"id\": \"asst_123\",\n \"object\": \"assistant\",\n \"created_at\": 1699009709,\n \"name\": \"HR Helper\",\n \"description\": null,\n \"model\": \"gpt-5\",\n \"instructions\": \"You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.\",\n \"tools\": [\n {\n \"type\": \"file_search\"\n }\n ],\n \"tool_resources\": {\n \"file_search\": {\n \"vector_store_ids\": []\n }\n },\n \"metadata\": {},\n \"top_p\": 1.0,\n \"temperature\": 1.0,\n \"response_format\": \"auto\"\n}\n" + } + } + }, + "delete": { + "operationId": "deleteAssistant", + "tags": [ + "Assistants" + ], + "summary": "Delete an assistant.", + "deprecated": true, + "parameters": [ + { + "in": "path", + "name": "assistant_id", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the assistant to delete." + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeleteAssistantResponse" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Delete assistant", + "group": "assistants", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/assistants/asst_abc123 \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"OpenAI-Beta: assistants=v2\" \\\n -X DELETE\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\nresponse = client.beta.assistants.delete(\"asst_abc123\")\nprint(response)\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const response = await openai.beta.assistants.delete(\"asst_abc123\");\n\n console.log(response);\n}\nmain();" + }, + "response": "{\n \"id\": \"asst_abc123\",\n \"object\": \"assistant.deleted\",\n \"deleted\": true\n}\n" + } + } + } + }, + "/audio/speech": { + "post": { + "operationId": "createSpeech", + "tags": [ + "Audio" + ], + "summary": "Generates audio from the input text.\n\nReturns the audio file content, or a stream of audio events.\n", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateSpeechRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "headers": { + "Transfer-Encoding": { + "schema": { + "type": "string" + }, + "description": "chunked" + } + }, + "content": { + "application/octet-stream": { + "schema": { + "type": "string", + "format": "binary" + } + }, + "text/event-stream": { + "schema": { + "$ref": "#/components/schemas/CreateSpeechResponseStreamEvent" + } + } + } + }, + "429": { + "$ref": "#/components/responses/InferenceRateLimited" + }, + "503": { + "$ref": "#/components/responses/InferenceServiceUnavailable" + } + }, + "x-oaiMeta": { + "name": "Create speech", + "group": "audio", + "examples": [ + { + "title": "Default", + "request": { + "curl": "curl https://api.openai.com/v1/audio/speech \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"gpt-4o-mini-tts\",\n \"input\": \"The quick brown fox jumped over the lazy dog.\",\n \"voice\": \"alloy\"\n }' \\\n --output speech.mp3\n", + "python": "from pathlib import Path\nimport openai\n\nspeech_file_path = Path(__file__).parent / \"speech.mp3\"\nwith openai.audio.speech.with_streaming_response.create(\n model=\"gpt-4o-mini-tts\",\n voice=\"alloy\",\n input=\"The quick brown fox jumped over the lazy dog.\"\n) as response:\n response.stream_to_file(speech_file_path)\n", + "javascript": "import fs from \"fs\";\nimport path from \"path\";\nimport OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nconst speechFile = path.resolve(\"./speech.mp3\");\n\nasync function main() {\n const mp3 = await openai.audio.speech.create({\n model: \"gpt-4o-mini-tts\",\n voice: \"alloy\",\n input: \"Today is a wonderful day to build something people love!\",\n });\n console.log(speechFile);\n const buffer = Buffer.from(await mp3.arrayBuffer());\n await fs.promises.writeFile(speechFile, buffer);\n}\nmain();\n", + "csharp": "using System;\nusing System.IO;\n\nusing OpenAI.Audio;\n\nAudioClient client = new(\n model: \"gpt-4o-mini-tts\",\n apiKey: Environment.GetEnvironmentVariable(\"OPENAI_API_KEY\")\n);\n\nBinaryData speech = client.GenerateSpeech(\n text: \"The quick brown fox jumped over the lazy dog.\",\n voice: GeneratedSpeechVoice.Alloy\n);\n\nusing FileStream stream = File.OpenWrite(\"speech.mp3\");\nspeech.ToStream().CopyTo(stream);\n" + } + }, + { + "title": "SSE Stream Format", + "request": { + "curl": "curl https://api.openai.com/v1/audio/speech \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"gpt-4o-mini-tts\",\n \"input\": \"The quick brown fox jumped over the lazy dog.\",\n \"voice\": \"alloy\",\n \"stream_format\": \"sse\"\n }'\n" + } + } + ] + } + } + }, + "/audio/transcriptions": { + "post": { + "operationId": "createTranscription", + "tags": [ + "Audio" + ], + "summary": "Transcribes audio into the input language.\n\nReturns a transcription object in `json`, `diarized_json`, or `verbose_json`\nformat, or a stream of transcript events.\n", + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "$ref": "#/components/schemas/CreateTranscriptionRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "$ref": "#/components/schemas/CreateTranscriptionResponseJson" + }, + { + "$ref": "#/components/schemas/CreateTranscriptionResponseDiarizedJson" + }, + { + "$ref": "#/components/schemas/CreateTranscriptionResponseVerboseJson" + } + ] + } + }, + "text/event-stream": { + "schema": { + "$ref": "#/components/schemas/CreateTranscriptionResponseStreamEvent" + } + } + } + }, + "429": { + "$ref": "#/components/responses/InferenceRateLimited" + }, + "503": { + "$ref": "#/components/responses/InferenceServiceUnavailable" + } + }, + "x-oaiMeta": { + "name": "Create transcription", + "group": "audio", + "examples": [ + { + "title": "Default", + "request": { + "curl": "curl https://api.openai.com/v1/audio/transcriptions \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: multipart/form-data\" \\\n -F file=\"@/path/to/file/audio.mp3\" \\\n -F model=\"gpt-4o-transcribe\"\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\naudio_file = open(\"speech.mp3\", \"rb\")\ntranscript = client.audio.transcriptions.create(\n model=\"gpt-4o-transcribe\",\n file=audio_file\n)\n", + "javascript": "import fs from \"fs\";\nimport OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const transcription = await openai.audio.transcriptions.create({\n file: fs.createReadStream(\"audio.mp3\"),\n model: \"gpt-4o-transcribe\",\n });\n\n console.log(transcription.text);\n}\nmain();\n", + "csharp": "using System;\n\nusing OpenAI.Audio;\nstring audioFilePath = \"audio.mp3\";\n\nAudioClient client = new(\n model: \"gpt-4o-transcribe\",\n apiKey: Environment.GetEnvironmentVariable(\"OPENAI_API_KEY\")\n);\n\nAudioTranscription transcription = client.TranscribeAudio(audioFilePath);\n\nConsole.WriteLine($\"{transcription.Text}\");\n" + }, + "response": "{\n \"text\": \"Imagine the wildest idea that you've ever had, and you're curious about how it might scale to something that's a 100, a 1,000 times bigger. This is a place where you can get to do that.\",\n \"usage\": {\n \"type\": \"tokens\",\n \"input_tokens\": 14,\n \"input_token_details\": {\n \"text_tokens\": 0,\n \"audio_tokens\": 14\n },\n \"output_tokens\": 45,\n \"total_tokens\": 59\n }\n}\n" + }, + { + "title": "Diarization", + "request": { + "curl": "curl https://api.openai.com/v1/audio/transcriptions \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: multipart/form-data\" \\\n -F file=\"@/path/to/file/meeting.wav\" \\\n -F model=\"gpt-4o-transcribe-diarize\" \\\n -F response_format=\"diarized_json\" \\\n -F chunking_strategy=auto \\\n -F 'known_speaker_names[]=agent' \\\n -F 'known_speaker_references[]=data:audio/wav;base64,AAA...'\n", + "python": "import base64\nfrom openai import OpenAI\n\nclient = OpenAI()\n\ndef to_data_url(path: str) -> str:\n with open(path, \"rb\") as fh:\n return \"data:audio/wav;base64,\" + base64.b64encode(fh.read()).decode(\"utf-8\")\n\nwith open(\"meeting.wav\", \"rb\") as audio_file:\n transcript = client.audio.transcriptions.create(\n model=\"gpt-4o-transcribe-diarize\",\n file=audio_file,\n response_format=\"diarized_json\",\n chunking_strategy=\"auto\",\n extra_body={\n \"known_speaker_names\": [\"agent\"],\n \"known_speaker_references\": [to_data_url(\"agent.wav\")],\n },\n )\n\nprint(transcript.segments)\n", + "javascript": "import fs from \"fs\";\nimport OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nconst speakerRef = fs.readFileSync(\"agent.wav\").toString(\"base64\");\n\nconst transcript = await openai.audio.transcriptions.create({\n file: fs.createReadStream(\"meeting.wav\"),\n model: \"gpt-4o-transcribe-diarize\",\n response_format: \"diarized_json\",\n chunking_strategy: \"auto\",\n extra_body: {\n known_speaker_names: [\"agent\"],\n known_speaker_references: [`data:audio/wav;base64,${speakerRef}`],\n },\n});\n\nconsole.log(transcript.segments);\n" + }, + "response": "{\n \"task\": \"transcribe\",\n \"duration\": 27.4,\n \"text\": \"Agent: Thanks for calling OpenAI support.\\nA: Hi, I'm trying to enable diarization.\\nAgent: Happy to walk you through the steps.\",\n \"segments\": [\n {\n \"type\": \"transcript.text.segment\",\n \"id\": \"seg_001\",\n \"start\": 0.0,\n \"end\": 4.7,\n \"text\": \"Thanks for calling OpenAI support.\",\n \"speaker\": \"agent\"\n },\n {\n \"type\": \"transcript.text.segment\",\n \"id\": \"seg_002\",\n \"start\": 4.7,\n \"end\": 11.8,\n \"text\": \"Hi, I'm trying to enable diarization.\",\n \"speaker\": \"A\"\n },\n {\n \"type\": \"transcript.text.segment\",\n \"id\": \"seg_003\",\n \"start\": 12.1,\n \"end\": 18.5,\n \"text\": \"Happy to walk you through the steps.\",\n \"speaker\": \"agent\"\n }\n ],\n \"usage\": {\n \"type\": \"duration\",\n \"seconds\": 27\n }\n}\n" + }, + { + "title": "Streaming", + "request": { + "curl": "curl https://api.openai.com/v1/audio/transcriptions \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: multipart/form-data\" \\\n -F file=\"@/path/to/file/audio.mp3\" \\\n -F model=\"gpt-4o-mini-transcribe\" \\\n -F stream=true\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\naudio_file = open(\"speech.mp3\", \"rb\")\nstream = client.audio.transcriptions.create(\n file=audio_file,\n model=\"gpt-4o-mini-transcribe\",\n stream=True\n)\n\nfor event in stream:\n print(event)\n", + "javascript": "import fs from \"fs\";\nimport OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nconst stream = await openai.audio.transcriptions.create({\n file: fs.createReadStream(\"audio.mp3\"),\n model: \"gpt-4o-mini-transcribe\",\n stream: true,\n});\n\nfor await (const event of stream) {\n console.log(event);\n}\n" + }, + "response": "data: {\"type\":\"transcript.text.delta\",\"delta\":\"I\",\"logprobs\":[{\"token\":\"I\",\"logprob\":-0.00007588794,\"bytes\":[73]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" see\",\"logprobs\":[{\"token\":\" see\",\"logprob\":-3.1281633e-7,\"bytes\":[32,115,101,101]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" skies\",\"logprobs\":[{\"token\":\" skies\",\"logprob\":-2.3392786e-6,\"bytes\":[32,115,107,105,101,115]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" of\",\"logprobs\":[{\"token\":\" of\",\"logprob\":-3.1281633e-7,\"bytes\":[32,111,102]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" blue\",\"logprobs\":[{\"token\":\" blue\",\"logprob\":-1.0280384e-6,\"bytes\":[32,98,108,117,101]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" and\",\"logprobs\":[{\"token\":\" and\",\"logprob\":-0.0005108566,\"bytes\":[32,97,110,100]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" clouds\",\"logprobs\":[{\"token\":\" clouds\",\"logprob\":-1.9361265e-7,\"bytes\":[32,99,108,111,117,100,115]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" of\",\"logprobs\":[{\"token\":\" of\",\"logprob\":-1.9361265e-7,\"bytes\":[32,111,102]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" white\",\"logprobs\":[{\"token\":\" white\",\"logprob\":-7.89631e-7,\"bytes\":[32,119,104,105,116,101]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\",\",\"logprobs\":[{\"token\":\",\",\"logprob\":-0.0014890312,\"bytes\":[44]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" the\",\"logprobs\":[{\"token\":\" the\",\"logprob\":-0.0110956915,\"bytes\":[32,116,104,101]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" bright\",\"logprobs\":[{\"token\":\" bright\",\"logprob\":0.0,\"bytes\":[32,98,114,105,103,104,116]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" blessed\",\"logprobs\":[{\"token\":\" blessed\",\"logprob\":-0.000045848617,\"bytes\":[32,98,108,101,115,115,101,100]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" days\",\"logprobs\":[{\"token\":\" days\",\"logprob\":-0.000010802739,\"bytes\":[32,100,97,121,115]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\",\",\"logprobs\":[{\"token\":\",\",\"logprob\":-0.00001700133,\"bytes\":[44]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" the\",\"logprobs\":[{\"token\":\" the\",\"logprob\":-0.0000118755715,\"bytes\":[32,116,104,101]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" dark\",\"logprobs\":[{\"token\":\" dark\",\"logprob\":-5.5122365e-7,\"bytes\":[32,100,97,114,107]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" sacred\",\"logprobs\":[{\"token\":\" sacred\",\"logprob\":-5.4385737e-6,\"bytes\":[32,115,97,99,114,101,100]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" nights\",\"logprobs\":[{\"token\":\" nights\",\"logprob\":-4.00813e-6,\"bytes\":[32,110,105,103,104,116,115]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\",\",\"logprobs\":[{\"token\":\",\",\"logprob\":-0.0036910512,\"bytes\":[44]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" and\",\"logprobs\":[{\"token\":\" and\",\"logprob\":-0.0031903093,\"bytes\":[32,97,110,100]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" I\",\"logprobs\":[{\"token\":\" I\",\"logprob\":-1.504853e-6,\"bytes\":[32,73]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" think\",\"logprobs\":[{\"token\":\" think\",\"logprob\":-4.3202e-7,\"bytes\":[32,116,104,105,110,107]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" to\",\"logprobs\":[{\"token\":\" to\",\"logprob\":-1.9361265e-7,\"bytes\":[32,116,111]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" myself\",\"logprobs\":[{\"token\":\" myself\",\"logprob\":-1.7432603e-6,\"bytes\":[32,109,121,115,101,108,102]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\",\",\"logprobs\":[{\"token\":\",\",\"logprob\":-0.29254505,\"bytes\":[44]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" what\",\"logprobs\":[{\"token\":\" what\",\"logprob\":-0.016815351,\"bytes\":[32,119,104,97,116]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" a\",\"logprobs\":[{\"token\":\" a\",\"logprob\":-3.1281633e-7,\"bytes\":[32,97]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" wonderful\",\"logprobs\":[{\"token\":\" wonderful\",\"logprob\":-2.1008714e-6,\"bytes\":[32,119,111,110,100,101,114,102,117,108]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" world\",\"logprobs\":[{\"token\":\" world\",\"logprob\":-8.180258e-6,\"bytes\":[32,119,111,114,108,100]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\".\",\"logprobs\":[{\"token\":\".\",\"logprob\":-0.014231676,\"bytes\":[46]}]}\n\ndata: {\"type\":\"transcript.text.done\",\"text\":\"I see skies of blue and clouds of white, the bright blessed days, the dark sacred nights, and I think to myself, what a wonderful world.\",\"logprobs\":[{\"token\":\"I\",\"logprob\":-0.00007588794,\"bytes\":[73]},{\"token\":\" see\",\"logprob\":-3.1281633e-7,\"bytes\":[32,115,101,101]},{\"token\":\" skies\",\"logprob\":-2.3392786e-6,\"bytes\":[32,115,107,105,101,115]},{\"token\":\" of\",\"logprob\":-3.1281633e-7,\"bytes\":[32,111,102]},{\"token\":\" blue\",\"logprob\":-1.0280384e-6,\"bytes\":[32,98,108,117,101]},{\"token\":\" and\",\"logprob\":-0.0005108566,\"bytes\":[32,97,110,100]},{\"token\":\" clouds\",\"logprob\":-1.9361265e-7,\"bytes\":[32,99,108,111,117,100,115]},{\"token\":\" of\",\"logprob\":-1.9361265e-7,\"bytes\":[32,111,102]},{\"token\":\" white\",\"logprob\":-7.89631e-7,\"bytes\":[32,119,104,105,116,101]},{\"token\":\",\",\"logprob\":-0.0014890312,\"bytes\":[44]},{\"token\":\" the\",\"logprob\":-0.0110956915,\"bytes\":[32,116,104,101]},{\"token\":\" bright\",\"logprob\":0.0,\"bytes\":[32,98,114,105,103,104,116]},{\"token\":\" blessed\",\"logprob\":-0.000045848617,\"bytes\":[32,98,108,101,115,115,101,100]},{\"token\":\" days\",\"logprob\":-0.000010802739,\"bytes\":[32,100,97,121,115]},{\"token\":\",\",\"logprob\":-0.00001700133,\"bytes\":[44]},{\"token\":\" the\",\"logprob\":-0.0000118755715,\"bytes\":[32,116,104,101]},{\"token\":\" dark\",\"logprob\":-5.5122365e-7,\"bytes\":[32,100,97,114,107]},{\"token\":\" sacred\",\"logprob\":-5.4385737e-6,\"bytes\":[32,115,97,99,114,101,100]},{\"token\":\" nights\",\"logprob\":-4.00813e-6,\"bytes\":[32,110,105,103,104,116,115]},{\"token\":\",\",\"logprob\":-0.0036910512,\"bytes\":[44]},{\"token\":\" and\",\"logprob\":-0.0031903093,\"bytes\":[32,97,110,100]},{\"token\":\" I\",\"logprob\":-1.504853e-6,\"bytes\":[32,73]},{\"token\":\" think\",\"logprob\":-4.3202e-7,\"bytes\":[32,116,104,105,110,107]},{\"token\":\" to\",\"logprob\":-1.9361265e-7,\"bytes\":[32,116,111]},{\"token\":\" myself\",\"logprob\":-1.7432603e-6,\"bytes\":[32,109,121,115,101,108,102]},{\"token\":\",\",\"logprob\":-0.29254505,\"bytes\":[44]},{\"token\":\" what\",\"logprob\":-0.016815351,\"bytes\":[32,119,104,97,116]},{\"token\":\" a\",\"logprob\":-3.1281633e-7,\"bytes\":[32,97]},{\"token\":\" wonderful\",\"logprob\":-2.1008714e-6,\"bytes\":[32,119,111,110,100,101,114,102,117,108]},{\"token\":\" world\",\"logprob\":-8.180258e-6,\"bytes\":[32,119,111,114,108,100]},{\"token\":\".\",\"logprob\":-0.014231676,\"bytes\":[46]}],\"usage\":{\"input_tokens\":14,\"input_token_details\":{\"text_tokens\":0,\"audio_tokens\":14},\"output_tokens\":45,\"total_tokens\":59}}\n" + }, + { + "title": "Logprobs", + "request": { + "curl": "curl https://api.openai.com/v1/audio/transcriptions \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: multipart/form-data\" \\\n -F file=\"@/path/to/file/audio.mp3\" \\\n -F \"include[]=logprobs\" \\\n -F model=\"gpt-4o-transcribe\" \\\n -F response_format=\"json\"\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\naudio_file = open(\"speech.mp3\", \"rb\")\ntranscript = client.audio.transcriptions.create(\n file=audio_file,\n model=\"gpt-4o-transcribe\",\n response_format=\"json\",\n include=[\"logprobs\"]\n)\n\nprint(transcript)\n", + "javascript": "import fs from \"fs\";\nimport OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const transcription = await openai.audio.transcriptions.create({\n file: fs.createReadStream(\"audio.mp3\"),\n model: \"gpt-4o-transcribe\",\n response_format: \"json\",\n include: [\"logprobs\"]\n });\n\n console.log(transcription);\n}\nmain();\n" + }, + "response": "{\n \"text\": \"Hey, my knee is hurting and I want to see the doctor tomorrow ideally.\",\n \"logprobs\": [\n { \"token\": \"Hey\", \"logprob\": -1.0415299, \"bytes\": [72, 101, 121] },\n { \"token\": \",\", \"logprob\": -9.805982e-5, \"bytes\": [44] },\n { \"token\": \" my\", \"logprob\": -0.00229799, \"bytes\": [32, 109, 121] },\n {\n \"token\": \" knee\",\n \"logprob\": -4.7159858e-5,\n \"bytes\": [32, 107, 110, 101, 101]\n },\n { \"token\": \" is\", \"logprob\": -0.043909557, \"bytes\": [32, 105, 115] },\n {\n \"token\": \" hurting\",\n \"logprob\": -1.1041146e-5,\n \"bytes\": [32, 104, 117, 114, 116, 105, 110, 103]\n },\n { \"token\": \" and\", \"logprob\": -0.011076359, \"bytes\": [32, 97, 110, 100] },\n { \"token\": \" I\", \"logprob\": -5.3193703e-6, \"bytes\": [32, 73] },\n {\n \"token\": \" want\",\n \"logprob\": -0.0017156356,\n \"bytes\": [32, 119, 97, 110, 116]\n },\n { \"token\": \" to\", \"logprob\": -7.89631e-7, \"bytes\": [32, 116, 111] },\n { \"token\": \" see\", \"logprob\": -5.5122365e-7, \"bytes\": [32, 115, 101, 101] },\n { \"token\": \" the\", \"logprob\": -0.0040786397, \"bytes\": [32, 116, 104, 101] },\n {\n \"token\": \" doctor\",\n \"logprob\": -2.3392786e-6,\n \"bytes\": [32, 100, 111, 99, 116, 111, 114]\n },\n {\n \"token\": \" tomorrow\",\n \"logprob\": -7.89631e-7,\n \"bytes\": [32, 116, 111, 109, 111, 114, 114, 111, 119]\n },\n {\n \"token\": \" ideally\",\n \"logprob\": -0.5800861,\n \"bytes\": [32, 105, 100, 101, 97, 108, 108, 121]\n },\n { \"token\": \".\", \"logprob\": -0.00011093382, \"bytes\": [46] }\n ],\n \"usage\": {\n \"type\": \"tokens\",\n \"input_tokens\": 14,\n \"input_token_details\": {\n \"text_tokens\": 0,\n \"audio_tokens\": 14\n },\n \"output_tokens\": 45,\n \"total_tokens\": 59\n }\n}\n" + }, + { + "title": "Word timestamps", + "request": { + "curl": "curl https://api.openai.com/v1/audio/transcriptions \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: multipart/form-data\" \\\n -F file=\"@/path/to/file/audio.mp3\" \\\n -F \"timestamp_granularities[]=word\" \\\n -F model=\"whisper-1\" \\\n -F response_format=\"verbose_json\"\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\naudio_file = open(\"speech.mp3\", \"rb\")\ntranscript = client.audio.transcriptions.create(\n file=audio_file,\n model=\"whisper-1\",\n response_format=\"verbose_json\",\n timestamp_granularities=[\"word\"]\n)\n\nprint(transcript.words)\n", + "javascript": "import fs from \"fs\";\nimport OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const transcription = await openai.audio.transcriptions.create({\n file: fs.createReadStream(\"audio.mp3\"),\n model: \"whisper-1\",\n response_format: \"verbose_json\",\n timestamp_granularities: [\"word\"]\n });\n\n console.log(transcription.text);\n}\nmain();\n", + "csharp": "using System;\n\nusing OpenAI.Audio;\n\nstring audioFilePath = \"audio.mp3\";\n\nAudioClient client = new(\n model: \"whisper-1\",\n apiKey: Environment.GetEnvironmentVariable(\"OPENAI_API_KEY\")\n);\n\nAudioTranscriptionOptions options = new()\n{\n ResponseFormat = AudioTranscriptionFormat.Verbose,\n TimestampGranularities = AudioTimestampGranularities.Word,\n};\n\nAudioTranscription transcription = client.TranscribeAudio(audioFilePath, options);\n\nConsole.WriteLine($\"{transcription.Text}\");\n" + }, + "response": "{\n \"task\": \"transcribe\",\n \"language\": \"english\",\n \"duration\": 8.470000267028809,\n \"text\": \"The beach was a popular spot on a hot summer day. People were swimming in the ocean, building sandcastles, and playing beach volleyball.\",\n \"words\": [\n {\n \"word\": \"The\",\n \"start\": 0.0,\n \"end\": 0.23999999463558197\n },\n ...\n {\n \"word\": \"volleyball\",\n \"start\": 7.400000095367432,\n \"end\": 7.900000095367432\n }\n ],\n \"usage\": {\n \"type\": \"duration\",\n \"seconds\": 9\n }\n}\n" + }, + { + "title": "Segment timestamps", + "request": { + "curl": "curl https://api.openai.com/v1/audio/transcriptions \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: multipart/form-data\" \\\n -F file=\"@/path/to/file/audio.mp3\" \\\n -F \"timestamp_granularities[]=segment\" \\\n -F model=\"whisper-1\" \\\n -F response_format=\"verbose_json\"\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\naudio_file = open(\"speech.mp3\", \"rb\")\ntranscript = client.audio.transcriptions.create(\n file=audio_file,\n model=\"whisper-1\",\n response_format=\"verbose_json\",\n timestamp_granularities=[\"segment\"]\n)\n\nprint(transcript.words)\n", + "javascript": "import fs from \"fs\";\nimport OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const transcription = await openai.audio.transcriptions.create({\n file: fs.createReadStream(\"audio.mp3\"),\n model: \"whisper-1\",\n response_format: \"verbose_json\",\n timestamp_granularities: [\"segment\"]\n });\n\n console.log(transcription.text);\n}\nmain();\n", + "csharp": "using System;\n\nusing OpenAI.Audio;\n\nstring audioFilePath = \"audio.mp3\";\n\nAudioClient client = new(\n model: \"whisper-1\",\n apiKey: Environment.GetEnvironmentVariable(\"OPENAI_API_KEY\")\n);\n\nAudioTranscriptionOptions options = new()\n{\n ResponseFormat = AudioTranscriptionFormat.Verbose,\n TimestampGranularities = AudioTimestampGranularities.Segment,\n};\n\nAudioTranscription transcription = client.TranscribeAudio(audioFilePath, options);\n\nConsole.WriteLine($\"{transcription.Text}\");\n" + }, + "response": "{\n \"task\": \"transcribe\",\n \"language\": \"english\",\n \"duration\": 8.470000267028809,\n \"text\": \"The beach was a popular spot on a hot summer day. People were swimming in the ocean, building sandcastles, and playing beach volleyball.\",\n \"segments\": [\n {\n \"id\": 0,\n \"seek\": 0,\n \"start\": 0.0,\n \"end\": 3.319999933242798,\n \"text\": \" The beach was a popular spot on a hot summer day.\",\n \"tokens\": [\n 50364, 440, 7534, 390, 257, 3743, 4008, 322, 257, 2368, 4266, 786, 13, 50530\n ],\n \"temperature\": 0.0,\n \"avg_logprob\": -0.2860786020755768,\n \"compression_ratio\": 1.2363636493682861,\n \"no_speech_prob\": 0.00985979475080967\n },\n ...\n ],\n \"usage\": {\n \"type\": \"duration\",\n \"seconds\": 9\n }\n}\n" + } + ] + } + } + }, + "/audio/translations": { + "post": { + "operationId": "createTranslation", + "tags": [ + "Audio" + ], + "summary": "Translates audio into English.", + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "$ref": "#/components/schemas/CreateTranslationRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "$ref": "#/components/schemas/CreateTranslationResponseJson" + }, + { + "$ref": "#/components/schemas/CreateTranslationResponseVerboseJson" + } + ] + } + } + } + }, + "429": { + "$ref": "#/components/responses/InferenceRateLimited" + }, + "503": { + "$ref": "#/components/responses/InferenceServiceUnavailable" + } + }, + "x-oaiMeta": { + "name": "Create translation", + "group": "audio", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/audio/translations \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: multipart/form-data\" \\\n -F file=\"@/path/to/file/german.m4a\" \\\n -F model=\"whisper-1\"\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\naudio_file = open(\"speech.mp3\", \"rb\")\ntranscript = client.audio.translations.create(\n model=\"whisper-1\",\n file=audio_file\n)\n", + "javascript": "import fs from \"fs\";\nimport OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const translation = await openai.audio.translations.create({\n file: fs.createReadStream(\"speech.mp3\"),\n model: \"whisper-1\",\n });\n\n console.log(translation.text);\n}\nmain();\n", + "csharp": "using System;\n\nusing OpenAI.Audio;\n\nstring audioFilePath = \"audio.mp3\";\n\nAudioClient client = new(\n model: \"whisper-1\",\n apiKey: Environment.GetEnvironmentVariable(\"OPENAI_API_KEY\")\n);\n\nAudioTranscription transcription = client.TranscribeAudio(audioFilePath);\n\nConsole.WriteLine($\"{transcription.Text}\");\n" + }, + "response": "{\n \"text\": \"Hello, my name is Wolfgang and I come from Germany. Where are you heading today?\"\n}\n" + } + } + } + }, + "/audio/voice_consents": { + "post": { + "operationId": "createVoiceConsent", + "tags": [ + "Audio" + ], + "summary": "Upload a voice consent recording.", + "description": "Upload a consent recording that authorizes creation of a custom voice.\n\nSee the [custom voices guide](https://developers.openai.com/api/docs/guides/text-to-speech#custom-voices) for requirements and best practices. Custom voices are limited to eligible customers.\n", + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "$ref": "#/components/schemas/CreateVoiceConsentRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/VoiceConsentResource" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Create voice consent", + "group": "audio", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/audio/voice_consents \\\n -X POST \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -F \"name=John Doe\" \\\n -F \"language=en-US\" \\\n -F \"recording=@$HOME/consent_recording.wav;type=audio/x-wav\"\n" + } + } + } + }, + "get": { + "operationId": "listVoiceConsents", + "tags": [ + "Audio" + ], + "summary": "Returns a list of voice consent recordings.", + "description": "List consent recordings available to your organization for creating custom voices.\n\nSee the [custom voices guide](https://developers.openai.com/api/docs/guides/text-to-speech#custom-voices). Custom voices are limited to eligible customers.\n", + "parameters": [ + { + "in": "query", + "name": "after", + "required": false, + "schema": { + "type": "string" + }, + "description": "A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.\n" + }, + { + "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.\n", + "required": false, + "schema": { + "type": "integer", + "default": 20 + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/VoiceConsentListResource" + } + } + } + } + }, + "x-oaiMeta": { + "name": "List voice consents", + "group": "audio", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/audio/voice_consents?limit=20 \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n" + } + } + } + } + }, + "/audio/voice_consents/{consent_id}": { + "get": { + "operationId": "getVoiceConsent", + "tags": [ + "Audio" + ], + "summary": "Retrieves a voice consent recording.", + "description": "Retrieve consent recording metadata used for creating custom voices.\n\nSee the [custom voices guide](https://developers.openai.com/api/docs/guides/text-to-speech#custom-voices). Custom voices are limited to eligible customers.\n", + "parameters": [ + { + "in": "path", + "name": "consent_id", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the consent recording to retrieve." + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/VoiceConsentResource" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Retrieve voice consent", + "group": "audio", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/audio/voice_consents/cons_1234 \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n" + } + } + } + }, + "post": { + "operationId": "updateVoiceConsent", + "tags": [ + "Audio" + ], + "summary": "Updates a voice consent recording (metadata only).", + "description": "Update consent recording metadata used for creating custom voices. This endpoint updates metadata only and does not replace the underlying audio.\n\nSee the [custom voices guide](https://developers.openai.com/api/docs/guides/text-to-speech#custom-voices). Custom voices are limited to eligible customers.\n", + "parameters": [ + { + "in": "path", + "name": "consent_id", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the consent recording to update." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateVoiceConsentRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/VoiceConsentResource" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Update voice consent", + "group": "audio", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/audio/voice_consents/cons_1234 \\\n -X POST \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"John Doe\"\n }'\n" + } + } + } + }, + "delete": { + "operationId": "deleteVoiceConsent", + "tags": [ + "Audio" + ], + "summary": "Deletes a voice consent recording.", + "description": "Delete a consent recording that was uploaded for creating custom voices.\n\nSee the [custom voices guide](https://developers.openai.com/api/docs/guides/text-to-speech#custom-voices). Custom voices are limited to eligible customers.\n", + "parameters": [ + { + "in": "path", + "name": "consent_id", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the consent recording to delete." + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/VoiceConsentDeletedResource" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Delete voice consent", + "group": "audio", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/audio/voice_consents/cons_1234 \\\n -X DELETE \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n" + } + } + } + } + }, + "/audio/voices": { + "post": { + "operationId": "createVoice", + "tags": [ + "Audio" + ], + "summary": "Creates a custom voice.", + "description": "Create a custom voice you can use for audio output (for example, in Text-to-Speech and the Realtime API). This requires an audio sample and a previously uploaded consent recording.\n\nSee the [custom voices guide](https://developers.openai.com/api/docs/guides/text-to-speech#custom-voices) for requirements and best practices. Custom voices are limited to eligible customers.\n", + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "$ref": "#/components/schemas/CreateVoiceRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/VoiceResource" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Create voice", + "group": "audio", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/audio/voices \\\n -X POST \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -F \"name=My new voice\" \\\n -F \"consent=cons_1234\" \\\n -F \"audio_sample=@$HOME/audio_sample.wav;type=audio/x-wav\"\n" + } + } + } + } + }, + "/batches": { + "post": { + "summary": "Creates and executes a batch from an uploaded file of requests", + "operationId": "createBatch", + "tags": [ + "Batch" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateBatchRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Batch created successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Batch" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Create batch", + "group": "batch", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/batches \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input_file_id\": \"file-abc123\",\n \"endpoint\": \"/v1/chat/completions\",\n \"completion_window\": \"24h\"\n }'\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.batches.create(\n input_file_id=\"file-abc123\",\n endpoint=\"/v1/chat/completions\",\n completion_window=\"24h\"\n)\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const batch = await openai.batches.create({\n input_file_id: \"file-abc123\",\n endpoint: \"/v1/chat/completions\",\n completion_window: \"24h\"\n });\n\n console.log(batch);\n}\n\nmain();\n" + }, + "response": "{\n \"id\": \"batch_abc123\",\n \"object\": \"batch\",\n \"endpoint\": \"/v1/chat/completions\",\n \"errors\": null,\n \"input_file_id\": \"file-abc123\",\n \"completion_window\": \"24h\",\n \"status\": \"validating\",\n \"output_file_id\": null,\n \"error_file_id\": null,\n \"created_at\": 1711471533,\n \"in_progress_at\": null,\n \"expires_at\": null,\n \"finalizing_at\": null,\n \"completed_at\": null,\n \"failed_at\": null,\n \"expired_at\": null,\n \"cancelling_at\": null,\n \"cancelled_at\": null,\n \"request_counts\": {\n \"total\": 0,\n \"completed\": 0,\n \"failed\": 0\n },\n \"metadata\": {\n \"customer_id\": \"user_123456789\",\n \"batch_description\": \"Nightly eval job\",\n }\n}\n" + } + } + }, + "get": { + "operationId": "listBatches", + "tags": [ + "Batch" + ], + "summary": "List your organization's batches.", + "parameters": [ + { + "in": "query", + "name": "after", + "required": false, + "schema": { + "type": "string" + }, + "description": "A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.\n" + }, + { + "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.\n", + "required": false, + "schema": { + "type": "integer", + "default": 20 + } + } + ], + "responses": { + "200": { + "description": "Batch listed successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListBatchesResponse" + } + } + } + } + }, + "x-oaiMeta": { + "name": "List batches", + "group": "batch", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/batches?limit=2 \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\"\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.batches.list()\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const list = await openai.batches.list();\n\n for await (const batch of list) {\n console.log(batch);\n }\n}\n\nmain();\n" + }, + "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"batch_abc123\",\n \"object\": \"batch\",\n \"endpoint\": \"/v1/chat/completions\",\n \"errors\": null,\n \"input_file_id\": \"file-abc123\",\n \"completion_window\": \"24h\",\n \"status\": \"completed\",\n \"output_file_id\": \"file-cvaTdG\",\n \"error_file_id\": \"file-HOWS94\",\n \"created_at\": 1711471533,\n \"in_progress_at\": 1711471538,\n \"expires_at\": 1711557933,\n \"finalizing_at\": 1711493133,\n \"completed_at\": 1711493163,\n \"failed_at\": null,\n \"expired_at\": null,\n \"cancelling_at\": null,\n \"cancelled_at\": null,\n \"request_counts\": {\n \"total\": 100,\n \"completed\": 95,\n \"failed\": 5\n },\n \"metadata\": {\n \"customer_id\": \"user_123456789\",\n \"batch_description\": \"Nightly job\",\n }\n },\n { ... },\n ],\n \"first_id\": \"batch_abc123\",\n \"last_id\": \"batch_abc456\",\n \"has_more\": true\n}\n" + } + } + } + }, + "/batches/{batch_id}": { + "get": { + "operationId": "retrieveBatch", + "tags": [ + "Batch" + ], + "summary": "Retrieves a batch.", + "parameters": [ + { + "in": "path", + "name": "batch_id", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the batch to retrieve." + } + ], + "responses": { + "200": { + "description": "Batch retrieved successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Batch" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Retrieve batch", + "group": "batch", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/batches/batch_abc123 \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.batches.retrieve(\"batch_abc123\")\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const batch = await openai.batches.retrieve(\"batch_abc123\");\n\n console.log(batch);\n}\n\nmain();\n" + }, + "response": "{\n \"id\": \"batch_abc123\",\n \"object\": \"batch\",\n \"endpoint\": \"/v1/completions\",\n \"errors\": null,\n \"input_file_id\": \"file-abc123\",\n \"completion_window\": \"24h\",\n \"status\": \"completed\",\n \"output_file_id\": \"file-cvaTdG\",\n \"error_file_id\": \"file-HOWS94\",\n \"created_at\": 1711471533,\n \"in_progress_at\": 1711471538,\n \"expires_at\": 1711557933,\n \"finalizing_at\": 1711493133,\n \"completed_at\": 1711493163,\n \"failed_at\": null,\n \"expired_at\": null,\n \"cancelling_at\": null,\n \"cancelled_at\": null,\n \"request_counts\": {\n \"total\": 100,\n \"completed\": 95,\n \"failed\": 5\n },\n \"metadata\": {\n \"customer_id\": \"user_123456789\",\n \"batch_description\": \"Nightly eval job\",\n }\n}\n" + } + } + } + }, + "/batches/{batch_id}/cancel": { + "post": { + "operationId": "cancelBatch", + "tags": [ + "Batch" + ], + "summary": "Cancels an in-progress batch. The batch will be in status `cancelling` for up to 10 minutes, before changing to `cancelled`, where it will have partial results (if any) available in the output file.", + "parameters": [ + { + "in": "path", + "name": "batch_id", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the batch to cancel." + } + ], + "responses": { + "200": { + "description": "Batch is cancelling. Returns the cancelling batch's details.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Batch" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Cancel batch", + "group": "batch", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/batches/batch_abc123/cancel \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -X POST\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.batches.cancel(\"batch_abc123\")\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const batch = await openai.batches.cancel(\"batch_abc123\");\n\n console.log(batch);\n}\n\nmain();\n" + }, + "response": "{\n \"id\": \"batch_abc123\",\n \"object\": \"batch\",\n \"endpoint\": \"/v1/chat/completions\",\n \"errors\": null,\n \"input_file_id\": \"file-abc123\",\n \"completion_window\": \"24h\",\n \"status\": \"cancelling\",\n \"output_file_id\": null,\n \"error_file_id\": null,\n \"created_at\": 1711471533,\n \"in_progress_at\": 1711471538,\n \"expires_at\": 1711557933,\n \"finalizing_at\": null,\n \"completed_at\": null,\n \"failed_at\": null,\n \"expired_at\": null,\n \"cancelling_at\": 1711475133,\n \"cancelled_at\": null,\n \"request_counts\": {\n \"total\": 100,\n \"completed\": 23,\n \"failed\": 1\n },\n \"metadata\": {\n \"customer_id\": \"user_123456789\",\n \"batch_description\": \"Nightly eval job\",\n }\n}\n" + } + } + } + }, + "/chat/completions": { + "get": { + "operationId": "listChatCompletions", + "tags": [ + "Chat" + ], + "summary": "List stored Chat Completions. Only Chat Completions that have been stored\nwith the `store` parameter set to `true` will be returned.\n", + "parameters": [ + { + "name": "model", + "in": "query", + "description": "The model used to generate the Chat Completions.", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "metadata", + "in": "query", + "description": "A list of metadata keys to filter the Chat Completions by. Example:\n\n`metadata[key1]=value1&metadata[key2]=value2`\n", + "required": false, + "schema": { + "$ref": "#/components/schemas/Metadata" + } + }, + { + "name": "after", + "in": "query", + "description": "Identifier for the last chat completion from the previous pagination request.", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "description": "Number of Chat Completions to retrieve.", + "required": false, + "schema": { + "type": "integer", + "default": 20 + } + }, + { + "name": "order", + "in": "query", + "description": "Sort order for Chat Completions by timestamp. Use `asc` for ascending order or `desc` for descending order. Defaults to `asc`.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "asc", + "desc" + ], + "default": "asc" + } + } + ], + "responses": { + "200": { + "description": "A list of Chat Completions", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChatCompletionList" + } + } + } + } + }, + "x-oaiMeta": { + "name": "List Chat Completions", + "group": "chat", + "path": "list", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/chat/completions \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\"\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\ncompletions = client.chat.completions.list()\nprint(completions)\n" + }, + "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"chat.completion\",\n \"id\": \"chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2\",\n \"model\": \"gpt-6-astra\",\n \"created\": 1738960610,\n \"request_id\": \"req_ded8ab984ec4bf840f37566c1011c417\",\n \"tool_choice\": null,\n \"usage\": {\n \"total_tokens\": 31,\n \"completion_tokens\": 18,\n \"prompt_tokens\": 13\n },\n \"seed\": 4944116822809979520,\n \"top_p\": 1.0,\n \"temperature\": 1.0,\n \"presence_penalty\": 0.0,\n \"frequency_penalty\": 0.0,\n \"system_fingerprint\": \"fp_50cad350e4\",\n \"input_user\": null,\n \"service_tier\": \"default\",\n \"tools\": null,\n \"metadata\": {},\n \"choices\": [\n {\n \"index\": 0,\n \"message\": {\n \"content\": \"Mind of circuits hum, \\nLearning patterns in silence— \\nFuture's quiet spark.\",\n \"role\": \"assistant\",\n \"tool_calls\": null,\n \"function_call\": null\n },\n \"finish_reason\": \"stop\",\n \"logprobs\": null\n }\n ],\n \"response_format\": null\n }\n ],\n \"first_id\": \"chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2\",\n \"last_id\": \"chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2\",\n \"has_more\": false\n}\n" + } + } + }, + "post": { + "operationId": "createChatCompletion", + "tags": [ + "Chat" + ], + "summary": "**Starting a new project?** We recommend trying [Responses](https://developers.openai.com/api/reference/resources/responses)\nto take advantage of the latest OpenAI platform features. Compare\n[Chat Completions with Responses](https://developers.openai.com/api/docs/guides/migrate-to-responses?api-mode=responses).\n\n---\n\nCreates a model response for the given chat conversation. Learn more in the\n[text generation](https://developers.openai.com/api/docs/guides/text), [vision](https://developers.openai.com/api/docs/guides/images-vision),\nand [audio](https://developers.openai.com/api/docs/guides/audio) guides.\n\nParameter support can differ depending on the model used to generate the\nresponse, particularly for newer reasoning models. Parameters that are only\nsupported for reasoning models are noted below. For the current state of\nunsupported parameters in reasoning models,\n[refer to the reasoning guide](https://developers.openai.com/api/docs/guides/reasoning).\n\nReturns a chat completion object, or a streamed sequence of chat completion\nchunk objects if the request is streamed.\n", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateChatCompletionRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateChatCompletionResponse" + } + }, + "text/event-stream": { + "schema": { + "$ref": "#/components/schemas/CreateChatCompletionStreamResponse" + } + } + } + }, + "429": { + "$ref": "#/components/responses/InferenceRateLimited" + }, + "503": { + "$ref": "#/components/responses/InferenceServiceUnavailable" + } + }, + "x-oaiMeta": { + "name": "Create chat completion", + "group": "chat", + "path": "create", + "examples": [ + { + "title": "Default", + "request": { + "curl": "curl https://api.openai.com/v1/chat/completions \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -d '{\n \"model\": \"gpt-6-astra\",\n \"messages\": [\n {\n \"role\": \"developer\",\n \"content\": \"You are a helpful assistant.\"\n },\n {\n \"role\": \"user\",\n \"content\": \"Hello!\"\n }\n ]\n }'\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\ncompletion = client.chat.completions.create(\n model=\"gpt-6-astra\",\n messages=[\n {\"role\": \"developer\", \"content\": \"You are a helpful assistant.\"},\n {\"role\": \"user\", \"content\": \"Hello!\"}\n ]\n)\n\nprint(completion.choices[0].message)\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const completion = await openai.chat.completions.create({\n messages: [{ role: \"developer\", content: \"You are a helpful assistant.\" }],\n model: \"gpt-6-astra\",\n store: true,\n });\n\n console.log(completion.choices[0]);\n}\n\nmain();\n", + "csharp": "using System;\nusing System.Collections.Generic;\n\nusing OpenAI.Chat;\n\nChatClient client = new(\n model: \"gpt-6-astra\",\n apiKey: Environment.GetEnvironmentVariable(\"OPENAI_API_KEY\")\n);\n\nList messages =\n[\n new SystemChatMessage(\"You are a helpful assistant.\"),\n new UserChatMessage(\"Hello!\")\n];\n\nChatCompletion completion = client.CompleteChat(messages);\n\nConsole.WriteLine(completion.Content[0].Text);\n" + }, + "response": "{\n \"id\": \"chatcmpl-B9MBs8CjcvOU2jLn4n570S5qMJKcT\",\n \"object\": \"chat.completion\",\n \"created\": 1741569952,\n \"model\": \"gpt-6-astra\",\n \"choices\": [\n {\n \"index\": 0,\n \"message\": {\n \"role\": \"assistant\",\n \"content\": \"Hello! How can I assist you today?\",\n \"refusal\": null,\n \"annotations\": []\n },\n \"logprobs\": null,\n \"finish_reason\": \"stop\"\n }\n ],\n \"usage\": {\n \"prompt_tokens\": 19,\n \"completion_tokens\": 10,\n \"total_tokens\": 29,\n \"prompt_tokens_details\": {\n \"cached_tokens\": 0,\n \"audio_tokens\": 0\n },\n \"completion_tokens_details\": {\n \"reasoning_tokens\": 0,\n \"audio_tokens\": 0,\n \"accepted_prediction_tokens\": 0,\n \"rejected_prediction_tokens\": 0\n }\n },\n \"service_tier\": \"default\"\n}\n" + }, + { + "title": "Image input", + "request": { + "curl": "curl https://api.openai.com/v1/chat/completions \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -d '{\n \"model\": \"gpt-6-astra\",\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": [\n {\n \"type\": \"text\",\n \"text\": \"What is in this image?\"\n },\n {\n \"type\": \"image_url\",\n \"image_url\": {\n \"url\": \"https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg\"\n }\n }\n ]\n }\n ],\n \"max_tokens\": 300\n }'\n", + "python": "from openai import OpenAI\n\nclient = OpenAI()\n\nresponse = client.chat.completions.create(\n model=\"gpt-6-astra\",\n messages=[\n {\n \"role\": \"user\",\n \"content\": [\n {\"type\": \"text\", \"text\": \"What's in this image?\"},\n {\n \"type\": \"image_url\",\n \"image_url\": {\n \"url\": \"https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg\",\n }\n },\n ],\n }\n ],\n max_tokens=300,\n)\n\nprint(response.choices[0])\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const response = await openai.chat.completions.create({\n model: \"gpt-6-astra\",\n messages: [\n {\n role: \"user\",\n content: [\n { type: \"text\", text: \"What's in this image?\" },\n {\n type: \"image_url\",\n image_url: {\n \"url\": \"https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg\",\n },\n }\n ],\n },\n ],\n });\n console.log(response.choices[0]);\n}\nmain();\n", + "csharp": "using System;\nusing System.Collections.Generic;\n\nusing OpenAI.Chat;\n\nChatClient client = new(\n model: \"gpt-6-astra\",\n apiKey: Environment.GetEnvironmentVariable(\"OPENAI_API_KEY\")\n);\n\nList messages =\n[\n new UserChatMessage(\n [\n ChatMessageContentPart.CreateTextPart(\"What's in this image?\"),\n ChatMessageContentPart.CreateImagePart(new Uri(\"https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg\"))\n ])\n];\n\nChatCompletion completion = client.CompleteChat(messages);\n\nConsole.WriteLine(completion.Content[0].Text);\n" + }, + "response": "{\n \"id\": \"chatcmpl-B9MHDbslfkBeAs8l4bebGdFOJ6PeG\",\n \"object\": \"chat.completion\",\n \"created\": 1741570283,\n \"model\": \"gpt-6-astra\",\n \"choices\": [\n {\n \"index\": 0,\n \"message\": {\n \"role\": \"assistant\",\n \"content\": \"The image shows a wooden boardwalk path running through a lush green field or meadow. The sky is bright blue with some scattered clouds, giving the scene a serene and peaceful atmosphere. Trees and shrubs are visible in the background.\",\n \"refusal\": null,\n \"annotations\": []\n },\n \"logprobs\": null,\n \"finish_reason\": \"stop\"\n }\n ],\n \"usage\": {\n \"prompt_tokens\": 1117,\n \"completion_tokens\": 46,\n \"total_tokens\": 1163,\n \"prompt_tokens_details\": {\n \"cached_tokens\": 0,\n \"audio_tokens\": 0\n },\n \"completion_tokens_details\": {\n \"reasoning_tokens\": 0,\n \"audio_tokens\": 0,\n \"accepted_prediction_tokens\": 0,\n \"rejected_prediction_tokens\": 0\n }\n },\n \"service_tier\": \"default\"\n}\n" + }, + { + "title": "Streaming", + "request": { + "curl": "curl https://api.openai.com/v1/chat/completions \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -d '{\n \"model\": \"gpt-6-astra\",\n \"messages\": [\n {\n \"role\": \"developer\",\n \"content\": \"You are a helpful assistant.\"\n },\n {\n \"role\": \"user\",\n \"content\": \"Hello!\"\n }\n ],\n \"stream\": true\n }'\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\ncompletion = client.chat.completions.create(\n model=\"gpt-6-astra\",\n messages=[\n {\"role\": \"developer\", \"content\": \"You are a helpful assistant.\"},\n {\"role\": \"user\", \"content\": \"Hello!\"}\n ],\n stream=True\n)\n\nfor chunk in completion:\n print(chunk.choices[0].delta)\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const completion = await openai.chat.completions.create({\n model: \"gpt-6-astra\",\n messages: [\n {\"role\": \"developer\", \"content\": \"You are a helpful assistant.\"},\n {\"role\": \"user\", \"content\": \"Hello!\"}\n ],\n stream: true,\n });\n\n for await (const chunk of completion) {\n console.log(chunk.choices[0].delta.content);\n }\n}\n\nmain();\n", + "csharp": "using System;\nusing System.ClientModel;\nusing System.Collections.Generic;\nusing System.Threading.Tasks;\n\nusing OpenAI.Chat;\n\nChatClient client = new(\n model: \"gpt-6-astra\",\n apiKey: Environment.GetEnvironmentVariable(\"OPENAI_API_KEY\")\n);\n\nList messages =\n[\n new SystemChatMessage(\"You are a helpful assistant.\"),\n new UserChatMessage(\"Hello!\")\n];\n\nAsyncCollectionResult completionUpdates = client.CompleteChatStreamingAsync(messages);\n\nawait foreach (StreamingChatCompletionUpdate completionUpdate in completionUpdates)\n{\n if (completionUpdate.ContentUpdate.Count > 0)\n {\n Console.Write(completionUpdate.ContentUpdate[0].Text);\n }\n}\n" + }, + "response": "{\"id\":\"chatcmpl-123\",\"object\":\"chat.completion.chunk\",\"created\":1694268190,\"model\":\"gpt-6-astra\", \"system_fingerprint\": \"fp_44709d6fcb\", \"choices\":[{\"index\":0,\"delta\":{\"role\":\"assistant\",\"content\":\"\"},\"logprobs\":null,\"finish_reason\":null}]}\n\n{\"id\":\"chatcmpl-123\",\"object\":\"chat.completion.chunk\",\"created\":1694268190,\"model\":\"gpt-6-astra\", \"system_fingerprint\": \"fp_44709d6fcb\", \"choices\":[{\"index\":0,\"delta\":{\"content\":\"Hello\"},\"logprobs\":null,\"finish_reason\":null}]}\n\n....\n\n{\"id\":\"chatcmpl-123\",\"object\":\"chat.completion.chunk\",\"created\":1694268190,\"model\":\"gpt-6-astra\", \"system_fingerprint\": \"fp_44709d6fcb\", \"choices\":[{\"index\":0,\"delta\":{},\"logprobs\":null,\"finish_reason\":\"stop\"}]}\n" + }, + { + "title": "Functions", + "request": { + "curl": "curl https://api.openai.com/v1/chat/completions \\\n-H \"Content-Type: application/json\" \\\n-H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n-d '{\n \"model\": \"gpt-6-astra\",\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"What is the weather like in Boston today?\"\n }\n ],\n \"tools\": [\n {\n \"type\": \"function\",\n \"function\": {\n \"name\": \"get_current_weather\",\n \"description\": \"Get the current weather in a given location\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"location\": {\n \"type\": \"string\",\n \"description\": \"The city and state, e.g. San Francisco, CA\"\n },\n \"unit\": {\n \"type\": \"string\",\n \"enum\": [\"celsius\", \"fahrenheit\"]\n }\n },\n \"required\": [\"location\"]\n }\n }\n }\n ],\n \"tool_choice\": \"auto\"\n}'\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\ntools = [\n {\n \"type\": \"function\",\n \"function\": {\n \"name\": \"get_current_weather\",\n \"description\": \"Get the current weather in a given location\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"location\": {\n \"type\": \"string\",\n \"description\": \"The city and state, e.g. San Francisco, CA\",\n },\n \"unit\": {\"type\": \"string\", \"enum\": [\"celsius\", \"fahrenheit\"]},\n },\n \"required\": [\"location\"],\n },\n }\n }\n]\nmessages = [{\"role\": \"user\", \"content\": \"What's the weather like in Boston today?\"}]\ncompletion = client.chat.completions.create(\n model=\"gpt-6-astra\",\n messages=messages,\n tools=tools,\n tool_choice=\"auto\"\n)\n\nprint(completion)\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const messages = [{\"role\": \"user\", \"content\": \"What's the weather like in Boston today?\"}];\n const tools = [\n {\n \"type\": \"function\",\n \"function\": {\n \"name\": \"get_current_weather\",\n \"description\": \"Get the current weather in a given location\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"location\": {\n \"type\": \"string\",\n \"description\": \"The city and state, e.g. San Francisco, CA\",\n },\n \"unit\": {\"type\": \"string\", \"enum\": [\"celsius\", \"fahrenheit\"]},\n },\n \"required\": [\"location\"],\n },\n }\n }\n ];\n\n const response = await openai.chat.completions.create({\n model: \"gpt-6-astra\",\n messages: messages,\n tools: tools,\n tool_choice: \"auto\",\n });\n\n console.log(response);\n}\n\nmain();\n", + "csharp": "using System;\nusing System.Collections.Generic;\n\nusing OpenAI.Chat;\n\nChatClient client = new(\n model: \"gpt-6-astra\",\n apiKey: Environment.GetEnvironmentVariable(\"OPENAI_API_KEY\")\n);\n\nChatTool getCurrentWeatherTool = ChatTool.CreateFunctionTool(\n functionName: \"get_current_weather\",\n functionDescription: \"Get the current weather in a given location\",\n functionParameters: BinaryData.FromString(\"\"\"\n {\n \"type\": \"object\",\n \"properties\": {\n \"location\": {\n \"type\": \"string\",\n \"description\": \"The city and state, e.g. San Francisco, CA\"\n },\n \"unit\": {\n \"type\": \"string\",\n \"enum\": [ \"celsius\", \"fahrenheit\" ]\n }\n },\n \"required\": [ \"location\" ]\n }\n \"\"\")\n);\n\nList messages =\n[\n new UserChatMessage(\"What's the weather like in Boston today?\"),\n];\n\nChatCompletionOptions options = new()\n{\n Tools =\n {\n getCurrentWeatherTool\n },\n ToolChoice = ChatToolChoice.CreateAutoChoice(),\n};\n\nChatCompletion completion = client.CompleteChat(messages, options);\n" + }, + "response": "{\n \"id\": \"chatcmpl-abc123\",\n \"object\": \"chat.completion\",\n \"created\": 1699896916,\n \"model\": \"gpt-6-astra\",\n \"choices\": [\n {\n \"index\": 0,\n \"message\": {\n \"role\": \"assistant\",\n \"content\": null,\n \"tool_calls\": [\n {\n \"id\": \"call_abc123\",\n \"type\": \"function\",\n \"function\": {\n \"name\": \"get_current_weather\",\n \"arguments\": \"{\\n\\\"location\\\": \\\"Boston, MA\\\"\\n}\"\n }\n }\n ]\n },\n \"logprobs\": null,\n \"finish_reason\": \"tool_calls\"\n }\n ],\n \"usage\": {\n \"prompt_tokens\": 82,\n \"completion_tokens\": 17,\n \"total_tokens\": 99,\n \"completion_tokens_details\": {\n \"reasoning_tokens\": 0,\n \"accepted_prediction_tokens\": 0,\n \"rejected_prediction_tokens\": 0\n }\n }\n}\n" + }, + { + "title": "Logprobs", + "request": { + "curl": "curl https://api.openai.com/v1/chat/completions \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -d '{\n \"model\": \"gpt-6-astra\",\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"Hello!\"\n }\n ],\n \"reasoning_effort\": \"none\",\n \"logprobs\": true,\n \"top_logprobs\": 2\n }'\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\ncompletion = client.chat.completions.create(\n model=\"gpt-6-astra\",\n messages=[\n {\"role\": \"user\", \"content\": \"Hello!\"}\n ],\n reasoning_effort=\"none\",\n logprobs=True,\n top_logprobs=2\n)\n\nprint(completion.choices[0].message)\nprint(completion.choices[0].logprobs)\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const completion = await openai.chat.completions.create({\n messages: [{ role: \"user\", content: \"Hello!\" }],\n model: \"gpt-6-astra\",\n reasoning_effort: \"none\",\n logprobs: true,\n top_logprobs: 2,\n });\n\n console.log(completion.choices[0]);\n}\n\nmain();\n", + "csharp": "using System;\nusing System.Collections.Generic;\n\nusing OpenAI.Chat;\n\nChatClient client = new(\n model: \"gpt-6-astra\",\n apiKey: Environment.GetEnvironmentVariable(\"OPENAI_API_KEY\")\n);\n\nList messages =\n[\n new UserChatMessage(\"Hello!\")\n];\n\nChatCompletionOptions options = new()\n{\n ReasoningEffortLevel = ChatReasoningEffortLevel.None,\n IncludeLogProbabilities = true,\n TopLogProbabilityCount = 2\n};\n\nChatCompletion completion = client.CompleteChat(messages, options);\n\nConsole.WriteLine(completion.Content[0].Text);\n" + }, + "response": "{\n \"id\": \"chatcmpl-123\",\n \"object\": \"chat.completion\",\n \"created\": 1702685778,\n \"model\": \"gpt-6-astra\",\n \"choices\": [\n {\n \"index\": 0,\n \"message\": {\n \"role\": \"assistant\",\n \"content\": \"Hello! How can I assist you today?\"\n },\n \"logprobs\": {\n \"content\": [\n {\n \"token\": \"Hello\",\n \"logprob\": -0.31725305,\n \"bytes\": [72, 101, 108, 108, 111],\n \"top_logprobs\": [\n {\n \"token\": \"Hello\",\n \"logprob\": -0.31725305,\n \"bytes\": [72, 101, 108, 108, 111]\n },\n {\n \"token\": \"Hi\",\n \"logprob\": -1.3190403,\n \"bytes\": [72, 105]\n }\n ]\n },\n {\n \"token\": \"!\",\n \"logprob\": -0.02380986,\n \"bytes\": [\n 33\n ],\n \"top_logprobs\": [\n {\n \"token\": \"!\",\n \"logprob\": -0.02380986,\n \"bytes\": [33]\n },\n {\n \"token\": \" there\",\n \"logprob\": -3.787621,\n \"bytes\": [32, 116, 104, 101, 114, 101]\n }\n ]\n },\n {\n \"token\": \" How\",\n \"logprob\": -0.000054669687,\n \"bytes\": [32, 72, 111, 119],\n \"top_logprobs\": [\n {\n \"token\": \" How\",\n \"logprob\": -0.000054669687,\n \"bytes\": [32, 72, 111, 119]\n },\n {\n \"token\": \"<|end|>\",\n \"logprob\": -10.953937,\n \"bytes\": null\n }\n ]\n },\n {\n \"token\": \" can\",\n \"logprob\": -0.015801601,\n \"bytes\": [32, 99, 97, 110],\n \"top_logprobs\": [\n {\n \"token\": \" can\",\n \"logprob\": -0.015801601,\n \"bytes\": [32, 99, 97, 110]\n },\n {\n \"token\": \" may\",\n \"logprob\": -4.161023,\n \"bytes\": [32, 109, 97, 121]\n }\n ]\n },\n {\n \"token\": \" I\",\n \"logprob\": -3.7697225e-6,\n \"bytes\": [\n 32,\n 73\n ],\n \"top_logprobs\": [\n {\n \"token\": \" I\",\n \"logprob\": -3.7697225e-6,\n \"bytes\": [32, 73]\n },\n {\n \"token\": \" assist\",\n \"logprob\": -13.596657,\n \"bytes\": [32, 97, 115, 115, 105, 115, 116]\n }\n ]\n },\n {\n \"token\": \" assist\",\n \"logprob\": -0.04571125,\n \"bytes\": [32, 97, 115, 115, 105, 115, 116],\n \"top_logprobs\": [\n {\n \"token\": \" assist\",\n \"logprob\": -0.04571125,\n \"bytes\": [32, 97, 115, 115, 105, 115, 116]\n },\n {\n \"token\": \" help\",\n \"logprob\": -3.1089056,\n \"bytes\": [32, 104, 101, 108, 112]\n }\n ]\n },\n {\n \"token\": \" you\",\n \"logprob\": -5.4385737e-6,\n \"bytes\": [32, 121, 111, 117],\n \"top_logprobs\": [\n {\n \"token\": \" you\",\n \"logprob\": -5.4385737e-6,\n \"bytes\": [32, 121, 111, 117]\n },\n {\n \"token\": \" today\",\n \"logprob\": -12.807695,\n \"bytes\": [32, 116, 111, 100, 97, 121]\n }\n ]\n },\n {\n \"token\": \" today\",\n \"logprob\": -0.0040071653,\n \"bytes\": [32, 116, 111, 100, 97, 121],\n \"top_logprobs\": [\n {\n \"token\": \" today\",\n \"logprob\": -0.0040071653,\n \"bytes\": [32, 116, 111, 100, 97, 121]\n },\n {\n \"token\": \"?\",\n \"logprob\": -5.5247097,\n \"bytes\": [63]\n }\n ]\n },\n {\n \"token\": \"?\",\n \"logprob\": -0.0008108172,\n \"bytes\": [63],\n \"top_logprobs\": [\n {\n \"token\": \"?\",\n \"logprob\": -0.0008108172,\n \"bytes\": [63]\n },\n {\n \"token\": \"?\\n\",\n \"logprob\": -7.184561,\n \"bytes\": [63, 10]\n }\n ]\n }\n ]\n },\n \"finish_reason\": \"stop\"\n }\n ],\n \"usage\": {\n \"prompt_tokens\": 9,\n \"completion_tokens\": 9,\n \"total_tokens\": 18,\n \"completion_tokens_details\": {\n \"reasoning_tokens\": 0,\n \"accepted_prediction_tokens\": 0,\n \"rejected_prediction_tokens\": 0\n }\n },\n \"system_fingerprint\": null\n}\n" + } + ] + } + } + }, + "/chat/completions/{completion_id}": { + "get": { + "operationId": "getChatCompletion", + "tags": [ + "Chat" + ], + "summary": "Get a stored chat completion. Only Chat Completions that have been created\nwith the `store` parameter set to `true` will be returned.\n", + "parameters": [ + { + "in": "path", + "name": "completion_id", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the chat completion to retrieve." + } + ], + "responses": { + "200": { + "description": "A chat completion", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateChatCompletionResponse" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Get chat completion", + "group": "chat", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/chat/completions/chatcmpl-abc123 \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\"\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\ncompletions = client.chat.completions.list()\nfirst_id = completions[0].id\nfirst_completion = client.chat.completions.retrieve(completion_id=first_id)\nprint(first_completion)\n" + }, + "response": "{\n \"object\": \"chat.completion\",\n \"id\": \"chatcmpl-abc123\",\n \"model\": \"gpt-6-astra\",\n \"created\": 1738960610,\n \"request_id\": \"req_ded8ab984ec4bf840f37566c1011c417\",\n \"tool_choice\": null,\n \"usage\": {\n \"total_tokens\": 31,\n \"completion_tokens\": 18,\n \"prompt_tokens\": 13\n },\n \"seed\": 4944116822809979520,\n \"top_p\": 1.0,\n \"temperature\": 1.0,\n \"presence_penalty\": 0.0,\n \"frequency_penalty\": 0.0,\n \"system_fingerprint\": \"fp_50cad350e4\",\n \"input_user\": null,\n \"service_tier\": \"default\",\n \"tools\": null,\n \"metadata\": {},\n \"choices\": [\n {\n \"index\": 0,\n \"message\": {\n \"content\": \"Mind of circuits hum, \\nLearning patterns in silence— \\nFuture's quiet spark.\",\n \"role\": \"assistant\",\n \"tool_calls\": null,\n \"function_call\": null\n },\n \"finish_reason\": \"stop\",\n \"logprobs\": null\n }\n ],\n \"response_format\": null\n}\n" + } + } + }, + "post": { + "operationId": "updateChatCompletion", + "tags": [ + "Chat" + ], + "summary": "Modify a stored chat completion. Only Chat Completions that have been\ncreated with the `store` parameter set to `true` can be modified. Currently,\nthe only supported modification is to update the `metadata` field.\n", + "parameters": [ + { + "in": "path", + "name": "completion_id", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the chat completion to update." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "metadata" + ], + "properties": { + "metadata": { + "$ref": "#/components/schemas/Metadata" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "A chat completion", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateChatCompletionResponse" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Update chat completion", + "group": "chat", + "examples": { + "request": { + "curl": "curl -X POST https://api.openai.com/v1/chat/completions/chat_abc123 \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"metadata\": {\"foo\": \"bar\"}}'\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\ncompletions = client.chat.completions.list()\nfirst_id = completions[0].id\nupdated_completion = client.chat.completions.update(completion_id=first_id, request_body={\"metadata\": {\"foo\": \"bar\"}})\nprint(updated_completion)\n" + }, + "response": "{\n \"object\": \"chat.completion\",\n \"id\": \"chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2\",\n \"model\": \"gpt-6-astra\",\n \"created\": 1738960610,\n \"request_id\": \"req_ded8ab984ec4bf840f37566c1011c417\",\n \"tool_choice\": null,\n \"usage\": {\n \"total_tokens\": 31,\n \"completion_tokens\": 18,\n \"prompt_tokens\": 13\n },\n \"seed\": 4944116822809979520,\n \"top_p\": 1.0,\n \"temperature\": 1.0,\n \"presence_penalty\": 0.0,\n \"frequency_penalty\": 0.0,\n \"system_fingerprint\": \"fp_50cad350e4\",\n \"input_user\": null,\n \"service_tier\": \"default\",\n \"tools\": null,\n \"metadata\": {\n \"foo\": \"bar\"\n },\n \"choices\": [\n {\n \"index\": 0,\n \"message\": {\n \"content\": \"Mind of circuits hum, \\nLearning patterns in silence— \\nFuture's quiet spark.\",\n \"role\": \"assistant\",\n \"tool_calls\": null,\n \"function_call\": null\n },\n \"finish_reason\": \"stop\",\n \"logprobs\": null\n }\n ],\n \"response_format\": null\n}\n" + } + } + }, + "delete": { + "operationId": "deleteChatCompletion", + "tags": [ + "Chat" + ], + "summary": "Delete a stored chat completion. Only Chat Completions that have been\ncreated with the `store` parameter set to `true` can be deleted.\n", + "parameters": [ + { + "in": "path", + "name": "completion_id", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the chat completion to delete." + } + ], + "responses": { + "200": { + "description": "The chat completion was deleted successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChatCompletionDeleted" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Delete chat completion", + "group": "chat", + "examples": { + "request": { + "curl": "curl -X DELETE https://api.openai.com/v1/chat/completions/chat_abc123 \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\"\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\ncompletions = client.chat.completions.list()\nfirst_id = completions[0].id\ndelete_response = client.chat.completions.delete(completion_id=first_id)\nprint(delete_response)\n" + }, + "response": "{\n \"object\": \"chat.completion.deleted\",\n \"id\": \"chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2\",\n \"deleted\": true\n}\n" + } + } + } + }, + "/chat/completions/{completion_id}/messages": { + "get": { + "operationId": "getChatCompletionMessages", + "tags": [ + "Chat" + ], + "summary": "Get the messages in a stored chat completion. Only Chat Completions that\nhave been created with the `store` parameter set to `true` will be\nreturned.\n", + "parameters": [ + { + "in": "path", + "name": "completion_id", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the chat completion to retrieve messages from." + }, + { + "name": "after", + "in": "query", + "description": "Identifier for the last message from the previous pagination request.", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "description": "Number of messages to retrieve.", + "required": false, + "schema": { + "type": "integer", + "default": 20 + } + }, + { + "name": "order", + "in": "query", + "description": "Sort order for messages by timestamp. Use `asc` for ascending order or `desc` for descending order. Defaults to `asc`.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "asc", + "desc" + ], + "default": "asc" + } + } + ], + "responses": { + "200": { + "description": "A list of messages", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChatCompletionMessageList" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Get chat messages", + "group": "chat", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/chat/completions/chat_abc123/messages \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\"\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\ncompletions = client.chat.completions.list()\nfirst_id = completions[0].id\nfirst_completion = client.chat.completions.retrieve(completion_id=first_id)\nmessages = client.chat.completions.messages.list(completion_id=first_id)\nprint(messages)\n" + }, + "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2-0\",\n \"role\": \"user\",\n \"content\": \"write a haiku about ai\",\n \"name\": null,\n \"content_parts\": null\n }\n ],\n \"first_id\": \"chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2-0\",\n \"last_id\": \"chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2-0\",\n \"has_more\": false\n}\n" + } + } + } + }, + "/completions": { + "post": { + "operationId": "createCompletion", + "tags": [ + "Completions" + ], + "summary": "Creates a completion for the provided prompt and parameters.\n\nReturns a completion object, or a sequence of completion objects if the request is streamed.\n", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateCompletionRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateCompletionResponse" + } + } + } + }, + "429": { + "$ref": "#/components/responses/InferenceRateLimited" + }, + "503": { + "$ref": "#/components/responses/InferenceServiceUnavailable" + } + }, + "x-oaiMeta": { + "name": "Create completion", + "group": "completions", + "legacy": true, + "examples": [ + { + "title": "No streaming", + "request": { + "curl": "curl https://api.openai.com/v1/completions \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -d '{\n \"model\": \"gpt-3.5-turbo-instruct\",\n \"prompt\": \"Say this is a test\",\n \"max_tokens\": 7,\n \"temperature\": 0\n }'\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.completions.create(\n model=\"gpt-3.5-turbo-instruct\",\n prompt=\"Say this is a test\",\n max_tokens=7,\n temperature=0\n)\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const completion = await openai.completions.create({\n model: \"gpt-3.5-turbo-instruct\",\n prompt: \"Say this is a test.\",\n max_tokens: 7,\n temperature: 0,\n });\n\n console.log(completion);\n}\nmain();" + }, + "response": "{\n \"id\": \"cmpl-uqkvlQyYK7bGYrRHQ0eXlWi7\",\n \"object\": \"text_completion\",\n \"created\": 1589478378,\n \"model\": \"gpt-3.5-turbo-instruct\",\n \"system_fingerprint\": \"fp_44709d6fcb\",\n \"choices\": [\n {\n \"text\": \"\\n\\nThis is indeed a test\",\n \"index\": 0,\n \"logprobs\": null,\n \"finish_reason\": \"length\"\n }\n ],\n \"usage\": {\n \"prompt_tokens\": 5,\n \"completion_tokens\": 7,\n \"total_tokens\": 12\n }\n}\n" + }, + { + "title": "Streaming", + "request": { + "curl": "curl https://api.openai.com/v1/completions \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -d '{\n \"model\": \"gpt-3.5-turbo-instruct\",\n \"prompt\": \"Say this is a test\",\n \"max_tokens\": 7,\n \"temperature\": 0,\n \"stream\": true\n }'\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\nfor chunk in client.completions.create(\n model=\"gpt-3.5-turbo-instruct\",\n prompt=\"Say this is a test\",\n max_tokens=7,\n temperature=0,\n stream=True\n):\n print(chunk.choices[0].text)\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const stream = await openai.completions.create({\n model: \"gpt-3.5-turbo-instruct\",\n prompt: \"Say this is a test.\",\n stream: true,\n });\n\n for await (const chunk of stream) {\n console.log(chunk.choices[0].text)\n }\n}\nmain();" + }, + "response": "{\n \"id\": \"cmpl-7iA7iJjj8V2zOkCGvWF2hAkDWBQZe\",\n \"object\": \"text_completion\",\n \"created\": 1690759702,\n \"choices\": [\n {\n \"text\": \"This\",\n \"index\": 0,\n \"logprobs\": null,\n \"finish_reason\": null\n }\n ],\n \"model\": \"gpt-3.5-turbo-instruct\"\n \"system_fingerprint\": \"fp_44709d6fcb\",\n}\n" + } + ] + } + } + }, + "/containers": { + "get": { + "summary": "List Containers", + "description": "Lists containers.", + "operationId": "ListContainers", + "parameters": [ + { + "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.\n", + "required": false, + "schema": { + "type": "integer", + "default": 20 + } + }, + { + "name": "order", + "in": "query", + "description": "Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order.\n", + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + } + }, + { + "name": "after", + "in": "query", + "description": "A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.\n", + "schema": { + "type": "string" + } + }, + { + "name": "name", + "in": "query", + "description": "Filter results by container name.", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ContainerListResource" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "List containers", + "group": "containers", + "path": "get", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/containers \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n" + }, + "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"cntr_682dfebaacac8198bbfe9c2474fb6f4a085685cbe3cb5863\",\n \"object\": \"container\",\n \"created_at\": 1747844794,\n \"status\": \"running\",\n \"expires_after\": {\n \"anchor\": \"last_active_at\",\n \"minutes\": 20\n },\n \"last_active_at\": 1747844794,\n \"memory_limit\": \"4g\",\n \"name\": \"My Container\"\n }\n ],\n \"first_id\": \"container_123\",\n \"last_id\": \"container_123\",\n \"has_more\": false\n}\n" + } + } + }, + "post": { + "summary": "Create Container", + "description": "Creates a container.", + "operationId": "CreateContainer", + "parameters": [], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateContainerBody" + } + } + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ContainerResource" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Create container", + "group": "containers", + "path": "post", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/containers \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"My Container\",\n \"memory_limit\": \"4g\",\n \"skills\": [\n {\n \"type\": \"skill_reference\",\n \"skill_id\": \"skill_4db6f1a2c9e73508b41f9da06e2c7b5f\"\n },\n {\n \"type\": \"skill_reference\",\n \"skill_id\": \"openai-spreadsheets\",\n \"version\": \"latest\"\n }\n ],\n \"network_policy\": {\n \"type\": \"allowlist\",\n \"allowed_domains\": [\"api.buildkite.com\"]\n }\n }'\n" + }, + "response": "{\n \"id\": \"cntr_682e30645a488191b6363a0cbefc0f0a025ec61b66250591\",\n \"object\": \"container\",\n \"created_at\": 1747857508,\n \"status\": \"running\",\n \"expires_after\": {\n \"anchor\": \"last_active_at\",\n \"minutes\": 20\n },\n \"last_active_at\": 1747857508,\n \"network_policy\": {\n \"type\": \"allowlist\",\n \"allowed_domains\": [\"api.buildkite.com\"]\n },\n \"memory_limit\": \"4g\",\n \"name\": \"My Container\"\n}\n" + } + } + } + }, + "/containers/{container_id}": { + "get": { + "summary": "Retrieve Container", + "description": "Retrieves a container.", + "operationId": "RetrieveContainer", + "parameters": [ + { + "name": "container_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ContainerResource" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Retrieve container", + "group": "containers", + "path": "get", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/containers/cntr_682dfebaacac8198bbfe9c2474fb6f4a085685cbe3cb5863 \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n" + }, + "response": "{\n \"id\": \"cntr_682dfebaacac8198bbfe9c2474fb6f4a085685cbe3cb5863\",\n \"object\": \"container\",\n \"created_at\": 1747844794,\n \"status\": \"running\",\n \"expires_after\": {\n \"anchor\": \"last_active_at\",\n \"minutes\": 20\n },\n \"last_active_at\": 1747844794,\n \"memory_limit\": \"4g\",\n \"name\": \"My Container\"\n}\n" + } + } + }, + "delete": { + "operationId": "DeleteContainer", + "summary": "Delete Container", + "description": "Delete a container.", + "parameters": [ + { + "name": "container_id", + "in": "path", + "description": "The ID of the container to delete.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Delete a container", + "group": "containers", + "path": "delete", + "examples": { + "request": { + "curl": "curl -X DELETE https://api.openai.com/v1/containers/cntr_682dfebaacac8198bbfe9c2474fb6f4a085685cbe3cb5863 \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n" + }, + "response": "{\n \"id\": \"cntr_682dfebaacac8198bbfe9c2474fb6f4a085685cbe3cb5863\",\n \"object\": \"container.deleted\",\n \"deleted\": true\n}\n" + } + } + } + }, + "/containers/{container_id}/files": { + "post": { + "summary": "Create a Container File\n\nYou can send either a multipart/form-data request with the raw file content, or a JSON request with a file ID.\n", + "description": "Creates a container file.\n", + "operationId": "CreateContainerFile", + "parameters": [ + { + "name": "container_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateContainerFileBody" + } + }, + "multipart/form-data": { + "schema": { + "$ref": "#/components/schemas/CreateContainerFileBody" + } + } + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ContainerFileResource" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Create container file", + "group": "containers", + "path": "post", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/containers/cntr_682e0e7318108198aa783fd921ff305e08e78805b9fdbb04/files \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -F file=\"@example.txt\"\n" + }, + "response": "{\n \"id\": \"cfile_682e0e8a43c88191a7978f477a09bdf5\",\n \"object\": \"container.file\",\n \"created_at\": 1747848842,\n \"bytes\": 880,\n \"container_id\": \"cntr_682e0e7318108198aa783fd921ff305e08e78805b9fdbb04\",\n \"path\": \"/mnt/data/88e12fa445d32636f190a0b33daed6cb-tsconfig.json\",\n \"source\": \"user\"\n}\n" + } + } + }, + "get": { + "summary": "List Container files", + "description": "Lists container files.", + "operationId": "ListContainerFiles", + "parameters": [ + { + "name": "container_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "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.\n", + "required": false, + "schema": { + "type": "integer", + "default": 20 + } + }, + { + "name": "order", + "in": "query", + "description": "Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order.\n", + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + } + }, + { + "name": "after", + "in": "query", + "description": "A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.\n", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ContainerFileListResource" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "List container files", + "group": "containers", + "path": "get", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/containers/cntr_682e0e7318108198aa783fd921ff305e08e78805b9fdbb04/files \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n" + }, + "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"cfile_682e0e8a43c88191a7978f477a09bdf5\",\n \"object\": \"container.file\",\n \"created_at\": 1747848842,\n \"bytes\": 880,\n \"container_id\": \"cntr_682e0e7318108198aa783fd921ff305e08e78805b9fdbb04\",\n \"path\": \"/mnt/data/88e12fa445d32636f190a0b33daed6cb-tsconfig.json\",\n \"source\": \"user\"\n }\n ],\n \"first_id\": \"cfile_682e0e8a43c88191a7978f477a09bdf5\",\n \"has_more\": false,\n \"last_id\": \"cfile_682e0e8a43c88191a7978f477a09bdf5\"\n}\n" + } + } + } + }, + "/containers/{container_id}/files/{file_id}": { + "get": { + "summary": "Retrieve Container File", + "description": "Retrieves a container file.", + "operationId": "RetrieveContainerFile", + "parameters": [ + { + "name": "container_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "file_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ContainerFileResource" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Retrieve container file", + "group": "containers", + "path": "get", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/containers/container_123/files/file_456 \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n" + }, + "response": "{\n \"id\": \"cfile_682e0e8a43c88191a7978f477a09bdf5\",\n \"object\": \"container.file\",\n \"created_at\": 1747848842,\n \"bytes\": 880,\n \"container_id\": \"cntr_682e0e7318108198aa783fd921ff305e08e78805b9fdbb04\",\n \"path\": \"/mnt/data/88e12fa445d32636f190a0b33daed6cb-tsconfig.json\",\n \"source\": \"user\"\n}\n" + } + } + }, + "delete": { + "operationId": "DeleteContainerFile", + "summary": "Delete Container File", + "description": "Delete a container file.", + "parameters": [ + { + "name": "container_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "file_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Delete a container file", + "group": "containers", + "path": "delete", + "examples": { + "request": { + "curl": "curl -X DELETE https://api.openai.com/v1/containers/cntr_682dfebaacac8198bbfe9c2474fb6f4a085685cbe3cb5863/files/cfile_682e0e8a43c88191a7978f477a09bdf5 \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n" + }, + "response": "{\n \"id\": \"cfile_682e0e8a43c88191a7978f477a09bdf5\",\n \"object\": \"container.file.deleted\",\n \"deleted\": true\n}\n" + } + } + } + }, + "/containers/{container_id}/files/{file_id}/content": { + "get": { + "summary": "Retrieve Container File Content", + "description": "Retrieves a container file content.", + "operationId": "RetrieveContainerFileContent", + "parameters": [ + { + "name": "container_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "file_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Success" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Retrieve container file content", + "group": "containers", + "path": "get", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/containers/container_123/files/cfile_456/content \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n" + }, + "response": "\n" + } + } + } + }, + "/conversations/{conversation_id}/items": { + "post": { + "operationId": "createConversationItems", + "tags": [ + "Conversations" + ], + "summary": "Create items in a conversation with the given ID.", + "parameters": [ + { + "in": "path", + "name": "conversation_id", + "required": true, + "schema": { + "type": "string", + "example": "conv_123" + }, + "description": "The ID of the conversation to add the item to." + }, + { + "name": "include", + "in": "query", + "required": false, + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/IncludeEnum" + } + }, + "description": "Additional fields to include in the response. See the `include`\nparameter for [listing Conversation items above](https://developers.openai.com/api/reference/resources/conversations/subresources/items/methods/list#%28resource%29%20conversations.items%20%3E%20%28method%29%20list%20%3E%20%28params%29%20default%20%3E%20%28param%29%20include%20%3E%20%28schema%29) for more information.\n" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "properties": { + "items": { + "type": "array", + "description": "The items to add to the conversation. You may add up to 20 items at a time.\n", + "items": { + "$ref": "#/components/schemas/InputItem" + }, + "maxItems": 20 + } + }, + "required": [ + "items" + ] + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationItemList" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Create items", + "group": "conversations", + "path": "create-item", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/conversations/conv_123/items \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -d '{\n \"items\": [\n {\n \"type\": \"message\",\n \"role\": \"user\",\n \"content\": [\n {\"type\": \"input_text\", \"text\": \"Hello!\"}\n ]\n },\n {\n \"type\": \"message\",\n \"role\": \"user\",\n \"content\": [\n {\"type\": \"input_text\", \"text\": \"How are you?\"}\n ]\n }\n ]\n }'\n", + "javascript": "import OpenAI from \"openai\";\nconst client = new OpenAI();\n\nconst items = await client.conversations.items.create(\n \"conv_123\",\n {\n items: [\n {\n type: \"message\",\n role: \"user\",\n content: [{ type: \"input_text\", text: \"Hello!\" }],\n },\n {\n type: \"message\",\n role: \"user\",\n content: [{ type: \"input_text\", text: \"How are you?\" }],\n },\n ],\n }\n);\nconsole.log(items.data);\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\nitems = client.conversations.items.create(\n \"conv_123\",\n items=[\n {\n \"type\": \"message\",\n \"role\": \"user\",\n \"content\": [{\"type\": \"input_text\", \"text\": \"Hello!\"}],\n },\n {\n \"type\": \"message\",\n \"role\": \"user\",\n \"content\": [{\"type\": \"input_text\", \"text\": \"How are you?\"}],\n }\n ],\n)\nprint(items.data)\n", + "csharp": "using System;\nusing System.Collections.Generic;\nusing OpenAI.Conversations;\n\nOpenAIConversationClient client = new(\n apiKey: Environment.GetEnvironmentVariable(\"OPENAI_API_KEY\")\n);\n\nConversationItemList created = client.ConversationItems.Create(\n conversationId: \"conv_123\",\n new CreateConversationItemsOptions\n {\n Items = new List\n {\n new ConversationMessage\n {\n Role = \"user\",\n Content =\n {\n new ConversationInputText { Text = \"Hello!\" }\n }\n },\n new ConversationMessage\n {\n Role = \"user\",\n Content =\n {\n new ConversationInputText { Text = \"How are you?\" }\n }\n }\n }\n }\n);\nConsole.WriteLine(created.Data.Count);\n" + }, + "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"type\": \"message\",\n \"id\": \"msg_abc\",\n \"status\": \"completed\",\n \"role\": \"user\",\n \"content\": [\n {\"type\": \"input_text\", \"text\": \"Hello!\"}\n ]\n },\n {\n \"type\": \"message\",\n \"id\": \"msg_def\",\n \"status\": \"completed\",\n \"role\": \"user\",\n \"content\": [\n {\"type\": \"input_text\", \"text\": \"How are you?\"}\n ]\n }\n ],\n \"first_id\": \"msg_abc\",\n \"last_id\": \"msg_def\",\n \"has_more\": false\n}\n" + } + } + }, + "get": { + "operationId": "listConversationItems", + "tags": [ + "Conversations" + ], + "summary": "List all items for a conversation with the given ID.", + "parameters": [ + { + "in": "path", + "name": "conversation_id", + "required": true, + "schema": { + "type": "string", + "example": "conv_123" + }, + "description": "The ID of the conversation to list items for." + }, + { + "name": "limit", + "in": "query", + "description": "A limit on the number of objects to be returned. Limit can range between\n1 and 100, and the default is 20.\n", + "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`.\n- `asc`: Return the input items in ascending order.\n- `desc`: Return the input items in descending order.\n" + }, + { + "in": "query", + "name": "after", + "schema": { + "type": "string" + }, + "description": "An item ID to list items after, used in pagination.\n" + }, + { + "name": "include", + "in": "query", + "required": false, + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/IncludeEnum" + } + }, + "description": "Specify additional output data to include in the model response. Currently supported values are:\n- `web_search_call.action.sources`: Include the sources of the web search tool call.\n- `code_interpreter_call.outputs`: Includes the outputs of python code execution in code interpreter tool call items.\n- `computer_call_output.output.image_url`: Include image urls from the computer call output.\n- `file_search_call.results`: Include the search results of the file search tool call.\n- `message.input_image.image_url`: Include image urls from the input message.\n- `message.output_text.logprobs`: Include logprobs with assistant messages.\n- `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)." + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationItemList" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "List items", + "group": "conversations", + "path": "list-items", + "examples": { + "request": { + "curl": "curl \"https://api.openai.com/v1/conversations/conv_123/items?limit=10\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n", + "javascript": "import OpenAI from \"openai\";\nconst client = new OpenAI();\n\nconst items = await client.conversations.items.list(\"conv_123\", { limit: 10 });\nconsole.log(items.data);\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\nitems = client.conversations.items.list(\"conv_123\", limit=10)\nprint(items.data)\n", + "csharp": "using System;\nusing OpenAI.Conversations;\n\nOpenAIConversationClient client = new(\n apiKey: Environment.GetEnvironmentVariable(\"OPENAI_API_KEY\")\n);\n\nConversationItemList items = client.ConversationItems.List(\n conversationId: \"conv_123\",\n new ListConversationItemsOptions { Limit = 10 }\n);\nConsole.WriteLine(items.Data.Count);\n" + }, + "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"type\": \"message\",\n \"id\": \"msg_abc\",\n \"status\": \"completed\",\n \"role\": \"user\",\n \"content\": [\n {\"type\": \"input_text\", \"text\": \"Hello!\"}\n ]\n }\n ],\n \"first_id\": \"msg_abc\",\n \"last_id\": \"msg_abc\",\n \"has_more\": false\n}\n" + } + } + } + }, + "/conversations/{conversation_id}/items/{item_id}": { + "get": { + "operationId": "getConversationItem", + "tags": [ + "Conversations" + ], + "summary": "Get a single item from a conversation with the given IDs.", + "parameters": [ + { + "in": "path", + "name": "conversation_id", + "required": true, + "schema": { + "type": "string", + "example": "conv_123" + }, + "description": "The ID of the conversation that contains the item." + }, + { + "in": "path", + "name": "item_id", + "required": true, + "schema": { + "type": "string", + "example": "msg_abc" + }, + "description": "The ID of the item to retrieve." + }, + { + "name": "include", + "in": "query", + "required": false, + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/IncludeEnum" + } + }, + "description": "Additional fields to include in the response. See the `include`\nparameter for [listing Conversation items above](https://developers.openai.com/api/reference/resources/conversations/subresources/items/methods/list#%28resource%29%20conversations.items%20%3E%20%28method%29%20list%20%3E%20%28params%29%20default%20%3E%20%28param%29%20include%20%3E%20%28schema%29) for more information.\n" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationItem" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Retrieve an item", + "group": "conversations", + "path": "get-item", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/conversations/conv_123/items/msg_abc \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n", + "javascript": "import OpenAI from \"openai\";\nconst client = new OpenAI();\n\nconst item = await client.conversations.items.retrieve(\n \"conv_123\",\n \"msg_abc\"\n);\nconsole.log(item);\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\nitem = client.conversations.items.retrieve(\"conv_123\", \"msg_abc\")\nprint(item)\n", + "csharp": "using System;\nusing OpenAI.Conversations;\n\nOpenAIConversationClient client = new(\n apiKey: Environment.GetEnvironmentVariable(\"OPENAI_API_KEY\")\n);\n\nConversationItem item = client.ConversationItems.Get(\n conversationId: \"conv_123\",\n itemId: \"msg_abc\"\n);\nConsole.WriteLine(item.Id);\n" + }, + "response": "{\n \"type\": \"message\",\n \"id\": \"msg_abc\",\n \"status\": \"completed\",\n \"role\": \"user\",\n \"content\": [\n {\"type\": \"input_text\", \"text\": \"Hello!\"}\n ]\n}\n" + } + } + }, + "delete": { + "operationId": "deleteConversationItem", + "tags": [ + "Conversations" + ], + "summary": "Delete an item from a conversation with the given IDs.", + "parameters": [ + { + "in": "path", + "name": "conversation_id", + "required": true, + "schema": { + "type": "string", + "example": "conv_123" + }, + "description": "The ID of the conversation that contains the item." + }, + { + "in": "path", + "name": "item_id", + "required": true, + "schema": { + "type": "string", + "example": "msg_abc" + }, + "description": "The ID of the item to delete." + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationResource" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Delete an item", + "group": "conversations", + "path": "delete-item", + "examples": { + "request": { + "curl": "curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n", + "javascript": "import OpenAI from \"openai\";\nconst client = new OpenAI();\n\nconst conversation = await client.conversations.items.delete(\n \"conv_123\",\n \"msg_abc\"\n);\nconsole.log(conversation);\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\nconversation = client.conversations.items.delete(\"conv_123\", \"msg_abc\")\nprint(conversation)\n", + "csharp": "using System;\nusing OpenAI.Conversations;\n\nOpenAIConversationClient client = new(\n apiKey: Environment.GetEnvironmentVariable(\"OPENAI_API_KEY\")\n);\n\nConversation conversation = client.ConversationItems.Delete(\n conversationId: \"conv_123\",\n itemId: \"msg_abc\"\n);\nConsole.WriteLine(conversation.Id);\n" + }, + "response": "{\n \"id\": \"conv_123\",\n \"object\": \"conversation\",\n \"created_at\": 1741900000,\n \"metadata\": {\"topic\": \"demo\"}\n}\n" + } + } + } + }, + "/embeddings": { + "post": { + "operationId": "createEmbedding", + "tags": [ + "Embeddings" + ], + "summary": "Creates an embedding vector representing the input text.", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateEmbeddingRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateEmbeddingResponse" + } + } + } + }, + "429": { + "$ref": "#/components/responses/InferenceRateLimited" + }, + "503": { + "$ref": "#/components/responses/InferenceServiceUnavailable" + } + }, + "x-oaiMeta": { + "name": "Create embeddings", + "group": "embeddings", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/embeddings \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": \"The food was delicious and the waiter...\",\n \"model\": \"text-embedding-ada-002\",\n \"encoding_format\": \"float\"\n }'\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.embeddings.create(\n model=\"text-embedding-ada-002\",\n input=\"The food was delicious and the waiter...\",\n encoding_format=\"float\"\n)\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const embedding = await openai.embeddings.create({\n model: \"text-embedding-ada-002\",\n input: \"The quick brown fox jumped over the lazy dog\",\n encoding_format: \"float\",\n });\n\n console.log(embedding);\n}\n\nmain();\n", + "csharp": "using System;\n\nusing OpenAI.Embeddings;\n\nEmbeddingClient client = new(\n model: \"text-embedding-3-small\",\n apiKey: Environment.GetEnvironmentVariable(\"OPENAI_API_KEY\")\n);\n\nOpenAIEmbedding embedding = client.GenerateEmbedding(input: \"The quick brown fox jumped over the lazy dog\");\nReadOnlyMemory vector = embedding.ToFloats();\n\nfor (int i = 0; i < vector.Length; i++)\n{\n Console.WriteLine($\" [{i,4}] = {vector.Span[i]}\");\n}\n" + }, + "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"embedding\",\n \"embedding\": [\n 0.0023064255,\n -0.009327292,\n .... (1536 floats total for ada-002)\n -0.0028842222,\n ],\n \"index\": 0\n }\n ],\n \"model\": \"text-embedding-ada-002\",\n \"usage\": {\n \"prompt_tokens\": 8,\n \"total_tokens\": 8\n }\n}\n" + } + } + } + }, + "/evals": { + "get": { + "operationId": "listEvals", + "tags": [ + "Evals" + ], + "summary": "List evaluations for a project.\n", + "parameters": [ + { + "name": "after", + "in": "query", + "description": "Identifier for the last eval from the previous pagination request.", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "description": "Number of evals to retrieve.", + "required": false, + "schema": { + "type": "integer", + "default": 20 + } + }, + { + "name": "order", + "in": "query", + "description": "Sort order for evals by timestamp. Use `asc` for ascending order or `desc` for descending order.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "asc", + "desc" + ], + "default": "asc" + } + }, + { + "name": "order_by", + "in": "query", + "description": "Evals can be ordered by creation time or last updated time. Use\n`created_at` for creation time or `updated_at` for last updated time.\n", + "required": false, + "schema": { + "type": "string", + "enum": [ + "created_at", + "updated_at" + ], + "default": "created_at" + } + } + ], + "responses": { + "200": { + "description": "A list of evals", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EvalList" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "List evals", + "group": "evals", + "path": "list", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/evals?limit=1 \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\"\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\nevals = client.evals.list(limit=1)\nprint(evals)\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nconst evals = await openai.evals.list({ limit: 1 });\nconsole.log(evals);\n" + }, + "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"eval_67abd54d9b0081909a86353f6fb9317a\",\n \"object\": \"eval\",\n \"data_source_config\": {\n \"type\": \"stored_completions\",\n \"metadata\": {\n \"usecase\": \"push_notifications_summarizer\"\n },\n \"schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"item\": {\n \"type\": \"object\"\n },\n \"sample\": {\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"item\",\n \"sample\"\n ]\n }\n },\n \"testing_criteria\": [\n {\n \"name\": \"Push Notification Summary Grader\",\n \"id\": \"Push Notification Summary Grader-9b876f24-4762-4be9-aff4-db7a9b31c673\",\n \"type\": \"label_model\",\n \"model\": \"o3-mini\",\n \"input\": [\n {\n \"type\": \"message\",\n \"role\": \"developer\",\n \"content\": {\n \"type\": \"input_text\",\n \"text\": \"\\nLabel the following push notification summary as either correct or incorrect.\\nThe push notification and the summary will be provided below.\\nA good push notificiation summary is concise and snappy.\\nIf it is good, then label it as correct, if not, then incorrect.\\n\"\n }\n },\n {\n \"type\": \"message\",\n \"role\": \"user\",\n \"content\": {\n \"type\": \"input_text\",\n \"text\": \"\\nPush notifications: {{item.input}}\\nSummary: {{sample.output_text}}\\n\"\n }\n }\n ],\n \"passing_labels\": [\n \"correct\"\n ],\n \"labels\": [\n \"correct\",\n \"incorrect\"\n ],\n \"sampling_params\": null\n }\n ],\n \"name\": \"Push Notification Summary Grader\",\n \"created_at\": 1739314509,\n \"metadata\": {\n \"description\": \"A stored completions eval for push notification summaries\"\n }\n }\n ],\n \"first_id\": \"eval_67abd54d9b0081909a86353f6fb9317a\",\n \"last_id\": \"eval_67aa884cf6688190b58f657d4441c8b7\",\n \"has_more\": true\n}\n" + } + } + }, + "post": { + "operationId": "createEval", + "tags": [ + "Evals" + ], + "summary": "Create the structure of an evaluation that can be used to test a model's performance.\nAn evaluation is a set of testing criteria and the config for a data source, which dictates the schema of the data used in the evaluation. After creating an evaluation, you can run it on different models and model parameters. We support several types of graders and datasources.\nFor more information, see the [Evals guide](https://developers.openai.com/api/docs/guides/evals).\n", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateEvalRequest" + } + } + } + }, + "responses": { + "201": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Eval" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Create eval", + "group": "evals", + "path": "post", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/evals \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"Sentiment\",\n \"data_source_config\": {\n \"type\": \"stored_completions\",\n \"metadata\": {\n \"usecase\": \"chatbot\"\n }\n },\n \"testing_criteria\": [\n {\n \"type\": \"label_model\",\n \"model\": \"o3-mini\",\n \"input\": [\n {\n \"role\": \"developer\",\n \"content\": \"Classify the sentiment of the following statement as one of 'positive', 'neutral', or 'negative'\"\n },\n {\n \"role\": \"user\",\n \"content\": \"Statement: {{item.input}}\"\n }\n ],\n \"passing_labels\": [\n \"positive\"\n ],\n \"labels\": [\n \"positive\",\n \"neutral\",\n \"negative\"\n ],\n \"name\": \"Example label grader\"\n }\n ]\n }'\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\neval_obj = client.evals.create(\n name=\"Sentiment\",\n data_source_config={\n \"type\": \"stored_completions\",\n \"metadata\": {\"usecase\": \"chatbot\"}\n },\n testing_criteria=[\n {\n \"type\": \"label_model\",\n \"model\": \"o3-mini\",\n \"input\": [\n {\"role\": \"developer\", \"content\": \"Classify the sentiment of the following statement as one of 'positive', 'neutral', or 'negative'\"},\n {\"role\": \"user\", \"content\": \"Statement: {{item.input}}\"}\n ],\n \"passing_labels\": [\"positive\"],\n \"labels\": [\"positive\", \"neutral\", \"negative\"],\n \"name\": \"Example label grader\"\n }\n ]\n)\nprint(eval_obj)\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nconst evalObj = await openai.evals.create({\n name: \"Sentiment\",\n data_source_config: {\n type: \"stored_completions\",\n metadata: { usecase: \"chatbot\" }\n },\n testing_criteria: [\n {\n type: \"label_model\",\n model: \"o3-mini\",\n input: [\n { role: \"developer\", content: \"Classify the sentiment of the following statement as one of 'positive', 'neutral', or 'negative'\" },\n { role: \"user\", content: \"Statement: {{item.input}}\" }\n ],\n passing_labels: [\"positive\"],\n labels: [\"positive\", \"neutral\", \"negative\"],\n name: \"Example label grader\"\n }\n ]\n});\nconsole.log(evalObj);\n" + }, + "response": "{\n \"object\": \"eval\",\n \"id\": \"eval_67b7fa9a81a88190ab4aa417e397ea21\",\n \"data_source_config\": {\n \"type\": \"stored_completions\",\n \"metadata\": {\n \"usecase\": \"chatbot\"\n },\n \"schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"item\": {\n \"type\": \"object\"\n },\n \"sample\": {\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"item\",\n \"sample\"\n ]\n },\n \"testing_criteria\": [\n {\n \"name\": \"Example label grader\",\n \"type\": \"label_model\",\n \"model\": \"o3-mini\",\n \"input\": [\n {\n \"type\": \"message\",\n \"role\": \"developer\",\n \"content\": {\n \"type\": \"input_text\",\n \"text\": \"Classify the sentiment of the following statement as one of positive, neutral, or negative\"\n }\n },\n {\n \"type\": \"message\",\n \"role\": \"user\",\n \"content\": {\n \"type\": \"input_text\",\n \"text\": \"Statement: {{item.input}}\"\n }\n }\n ],\n \"passing_labels\": [\n \"positive\"\n ],\n \"labels\": [\n \"positive\",\n \"neutral\",\n \"negative\"\n ]\n }\n ],\n \"name\": \"Sentiment\",\n \"created_at\": 1740110490,\n \"metadata\": {\n \"description\": \"An eval for sentiment analysis\"\n }\n}\n" + } + } + } + }, + "/evals/{eval_id}": { + "get": { + "operationId": "getEval", + "tags": [ + "Evals" + ], + "summary": "Get an evaluation by ID.\n", + "parameters": [ + { + "name": "eval_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the evaluation to retrieve." + } + ], + "responses": { + "200": { + "description": "The evaluation", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Eval" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Get an eval", + "group": "evals", + "path": "get", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/evals/eval_67abd54d9b0081909a86353f6fb9317a \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\"\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\neval_obj = client.evals.retrieve(\"eval_67abd54d9b0081909a86353f6fb9317a\")\nprint(eval_obj)\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nconst evalObj = await openai.evals.retrieve(\"eval_67abd54d9b0081909a86353f6fb9317a\");\nconsole.log(evalObj);\n" + }, + "response": "{\n \"object\": \"eval\",\n \"id\": \"eval_67abd54d9b0081909a86353f6fb9317a\",\n \"data_source_config\": {\n \"type\": \"custom\",\n \"schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"item\": {\n \"type\": \"object\",\n \"properties\": {\n \"input\": {\n \"type\": \"string\"\n },\n \"ground_truth\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"input\",\n \"ground_truth\"\n ]\n }\n },\n \"required\": [\n \"item\"\n ]\n }\n },\n \"testing_criteria\": [\n {\n \"name\": \"String check\",\n \"id\": \"String check-2eaf2d8d-d649-4335-8148-9535a7ca73c2\",\n \"type\": \"string_check\",\n \"input\": \"{{item.input}}\",\n \"reference\": \"{{item.ground_truth}}\",\n \"operation\": \"eq\"\n }\n ],\n \"name\": \"External Data Eval\",\n \"created_at\": 1739314509,\n \"metadata\": {},\n}\n" + } + } + }, + "post": { + "operationId": "updateEval", + "tags": [ + "Evals" + ], + "summary": "Update certain properties of an evaluation.\n", + "parameters": [ + { + "name": "eval_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the evaluation to update." + } + ], + "requestBody": { + "description": "Request to update an evaluation", + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Rename the evaluation." + }, + "metadata": { + "$ref": "#/components/schemas/Metadata" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "The updated evaluation", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Eval" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Update an eval", + "group": "evals", + "path": "update", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/evals/eval_67abd54d9b0081909a86353f6fb9317a \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\": \"Updated Eval\", \"metadata\": {\"description\": \"Updated description\"}}'\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\nupdated_eval = client.evals.update(\n \"eval_67abd54d9b0081909a86353f6fb9317a\",\n name=\"Updated Eval\",\n metadata={\"description\": \"Updated description\"}\n)\nprint(updated_eval)\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nconst updatedEval = await openai.evals.update(\n \"eval_67abd54d9b0081909a86353f6fb9317a\",\n {\n name: \"Updated Eval\",\n metadata: { description: \"Updated description\" }\n }\n);\nconsole.log(updatedEval);\n" + }, + "response": "{\n \"object\": \"eval\",\n \"id\": \"eval_67abd54d9b0081909a86353f6fb9317a\",\n \"data_source_config\": {\n \"type\": \"custom\",\n \"schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"item\": {\n \"type\": \"object\",\n \"properties\": {\n \"input\": {\n \"type\": \"string\"\n },\n \"ground_truth\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"input\",\n \"ground_truth\"\n ]\n }\n },\n \"required\": [\n \"item\"\n ]\n }\n },\n \"testing_criteria\": [\n {\n \"name\": \"String check\",\n \"id\": \"String check-2eaf2d8d-d649-4335-8148-9535a7ca73c2\",\n \"type\": \"string_check\",\n \"input\": \"{{item.input}}\",\n \"reference\": \"{{item.ground_truth}}\",\n \"operation\": \"eq\"\n }\n ],\n \"name\": \"Updated Eval\",\n \"created_at\": 1739314509,\n \"metadata\": {\"description\": \"Updated description\"},\n}\n" + } + } + }, + "delete": { + "operationId": "deleteEval", + "tags": [ + "Evals" + ], + "summary": "Delete an evaluation.\n", + "parameters": [ + { + "name": "eval_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the evaluation to delete." + } + ], + "responses": { + "200": { + "description": "Successfully deleted the evaluation.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "object": { + "type": "string", + "example": "eval.deleted" + }, + "deleted": { + "type": "boolean", + "example": true + }, + "eval_id": { + "type": "string", + "example": "eval_abc123" + } + }, + "required": [ + "object", + "deleted", + "eval_id" + ] + } + } + } + }, + "404": { + "description": "Evaluation not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Delete an eval", + "group": "evals", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/evals/eval_abc123 \\\n -X DELETE \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\ndeleted = client.evals.delete(\"eval_abc123\")\nprint(deleted)\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nconst deleted = await openai.evals.delete(\"eval_abc123\");\nconsole.log(deleted);\n" + }, + "response": "{\n \"object\": \"eval.deleted\",\n \"deleted\": true,\n \"eval_id\": \"eval_abc123\"\n}\n" + } + } + } + }, + "/evals/{eval_id}/runs": { + "get": { + "operationId": "getEvalRuns", + "tags": [ + "Evals" + ], + "summary": "Get a list of runs for an evaluation.\n", + "parameters": [ + { + "name": "eval_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the evaluation to retrieve runs for." + }, + { + "name": "after", + "in": "query", + "description": "Identifier for the last run from the previous pagination request.", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "description": "Number of runs to retrieve.", + "required": false, + "schema": { + "type": "integer", + "default": 20 + } + }, + { + "name": "order", + "in": "query", + "description": "Sort order for runs by timestamp. Use `asc` for ascending order or `desc` for descending order. Defaults to `asc`.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "asc", + "desc" + ], + "default": "asc" + } + }, + { + "name": "status", + "in": "query", + "description": "Filter runs by status. One of `queued` | `in_progress` | `failed` | `completed` | `canceled`.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "queued", + "in_progress", + "completed", + "canceled", + "failed" + ] + } + } + ], + "responses": { + "200": { + "description": "A list of runs for the evaluation", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EvalRunList" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Get eval runs", + "group": "evals", + "path": "get-runs", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/evals/egroup_67abd54d9b0081909a86353f6fb9317a/runs \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\"\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\nruns = client.evals.runs.list(\"egroup_67abd54d9b0081909a86353f6fb9317a\")\nprint(runs)\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nconst runs = await openai.evals.runs.list(\"egroup_67abd54d9b0081909a86353f6fb9317a\");\nconsole.log(runs);\n" + }, + "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"eval.run\",\n \"id\": \"evalrun_67e0c7d31560819090d60c0780591042\",\n \"eval_id\": \"eval_67e0c726d560819083f19a957c4c640b\",\n \"report_url\": \"https://platform.openai.com/evaluations/eval_67e0c726d560819083f19a957c4c640b\",\n \"status\": \"completed\",\n \"model\": \"o3-mini\",\n \"name\": \"bulk_with_negative_examples_o3-mini\",\n \"created_at\": 1742784467,\n \"result_counts\": {\n \"total\": 1,\n \"errored\": 0,\n \"failed\": 0,\n \"passed\": 1\n },\n \"per_model_usage\": [\n {\n \"model_name\": \"o3-mini\",\n \"invocation_count\": 1,\n \"prompt_tokens\": 563,\n \"completion_tokens\": 874,\n \"total_tokens\": 1437,\n \"cached_tokens\": 0\n }\n ],\n \"per_testing_criteria_results\": [\n {\n \"testing_criteria\": \"Push Notification Summary Grader-1808cd0b-eeec-4e0b-a519-337e79f4f5d1\",\n \"passed\": 1,\n \"failed\": 0\n }\n ],\n \"data_source\": {\n \"type\": \"completions\",\n \"source\": {\n \"type\": \"file_content\",\n \"content\": [\n {\n \"item\": {\n \"notifications\": \"\\n- New message from Sarah: \\\"Can you call me later?\\\"\\n- Your package has been delivered!\\n- Flash sale: 20% off electronics for the next 2 hours!\\n\"\n }\n }\n ]\n },\n \"input_messages\": {\n \"type\": \"template\",\n \"template\": [\n {\n \"type\": \"message\",\n \"role\": \"developer\",\n \"content\": {\n \"type\": \"input_text\",\n \"text\": \"\\n\\n\\n\\nYou are a helpful assistant that takes in an array of push notifications and returns a collapsed summary of them.\\nThe push notification will be provided as follows:\\n\\n...notificationlist...\\n\\n\\nYou should return just the summary and nothing else.\\n\\n\\nYou should return a summary that is concise and snappy.\\n\\n\\nHere is an example of a good summary:\\n\\n- Traffic alert: Accident reported on Main Street.- Package out for delivery: Expected by 5 PM.- New friend suggestion: Connect with Emma.\\n\\n\\nTraffic alert, package expected by 5pm, suggestion for new friend (Emily).\\n\\n\\n\\nHere is an example of a bad summary:\\n\\n- Traffic alert: Accident reported on Main Street.- Package out for delivery: Expected by 5 PM.- New friend suggestion: Connect with Emma.\\n\\n\\nTraffic alert reported on main street. You have a package that will arrive by 5pm, Emily is a new friend suggested for you.\\n\\n\"\n }\n },\n {\n \"type\": \"message\",\n \"role\": \"user\",\n \"content\": {\n \"type\": \"input_text\",\n \"text\": \"{{item.notifications}}\"\n }\n }\n ]\n },\n \"model\": \"o3-mini\",\n \"sampling_params\": null\n },\n \"error\": null,\n \"metadata\": {}\n }\n ],\n \"first_id\": \"evalrun_67e0c7d31560819090d60c0780591042\",\n \"last_id\": \"evalrun_67e0c7d31560819090d60c0780591042\",\n \"has_more\": true\n}\n" + } + } + }, + "post": { + "operationId": "createEvalRun", + "tags": [ + "Evals" + ], + "summary": "Kicks off a new run for a given evaluation, specifying the data source, and what model configuration to use to test. The datasource will be validated against the schema specified in the config of the evaluation.\n", + "parameters": [ + { + "in": "path", + "name": "eval_id", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the evaluation to create a run for." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateEvalRunRequest" + } + } + } + }, + "responses": { + "201": { + "description": "Successfully created a run for the evaluation", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EvalRun" + } + } + } + }, + "400": { + "description": "Bad request (for example, missing eval object)", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Create eval run", + "group": "evals", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/evals/eval_67e579652b548190aaa83ada4b125f47/runs \\\n -X POST \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"gpt-6-astra\",\"data_source\":{\"type\":\"completions\",\"input_messages\":{\"type\":\"template\",\"template\":[{\"role\":\"developer\",\"content\":\"Categorize a given news headline into one of the following topics: Technology, Markets, World, Business, or Sports.\\n\\n# Steps\\n\\n1. Analyze the content of the news headline to understand its primary focus.\\n2. Extract the subject matter, identifying any key indicators or keywords.\\n3. Use the identified indicators to determine the most suitable category out of the five options: Technology, Markets, World, Business, or Sports.\\n4. Ensure only one category is selected per headline.\\n\\n# Output Format\\n\\nRespond with the chosen category as a single word. For instance: \\\"Technology\\\", \\\"Markets\\\", \\\"World\\\", \\\"Business\\\", or \\\"Sports\\\".\\n\\n# Examples\\n\\n**Input**: \\\"Apple Unveils New iPhone Model, Featuring Advanced AI Features\\\" \\n**Output**: \\\"Technology\\\"\\n\\n**Input**: \\\"Global Stocks Mixed as Investors Await Central Bank Decisions\\\" \\n**Output**: \\\"Markets\\\"\\n\\n**Input**: \\\"War in Ukraine: Latest Updates on Negotiation Status\\\" \\n**Output**: \\\"World\\\"\\n\\n**Input**: \\\"Microsoft in Talks to Acquire Gaming Company for $2 Billion\\\" \\n**Output**: \\\"Business\\\"\\n\\n**Input**: \\\"Manchester United Secures Win in Premier League Football Match\\\" \\n**Output**: \\\"Sports\\\" \\n\\n# Notes\\n\\n- If the headline appears to fit into more than one category, choose the most dominant theme.\\n- Keywords or phrases such as \\\"stocks\\\", \\\"company acquisition\\\", \\\"match\\\", or technological brands can be good indicators for classification.\\n\"} , {\"role\":\"user\",\"content\":\"{{item.input}}\"}]} ,\"sampling_params\":{\"max_completions_tokens\":2048},\"model\":\"gpt-6-astra\",\"source\":{\"type\":\"file_content\",\"content\":[{\"item\":{\"input\":\"Tech Company Launches Advanced Artificial Intelligence Platform\",\"ground_truth\":\"Technology\"}}]}}}'\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\nrun = client.evals.runs.create(\n \"eval_67e579652b548190aaa83ada4b125f47\",\n name=\"gpt-6-astra\",\n data_source={\n \"type\": \"completions\",\n \"input_messages\": {\n \"type\": \"template\",\n \"template\": [\n {\n \"role\": \"developer\",\n \"content\": \"Categorize a given news headline into one of the following topics: Technology, Markets, World, Business, or Sports.\\n\\n# Steps\\n\\n1. Analyze the content of the news headline to understand its primary focus.\\n2. Extract the subject matter, identifying any key indicators or keywords.\\n3. Use the identified indicators to determine the most suitable category out of the five options: Technology, Markets, World, Business, or Sports.\\n4. Ensure only one category is selected per headline.\\n\\n# Output Format\\n\\nRespond with the chosen category as a single word. For instance: \\\"Technology\\\", \\\"Markets\\\", \\\"World\\\", \\\"Business\\\", or \\\"Sports\\\".\\n\\n# Examples\\n\\n**Input**: \\\"Apple Unveils New iPhone Model, Featuring Advanced AI Features\\\" \\n**Output**: \\\"Technology\\\"\\n\\n**Input**: \\\"Global Stocks Mixed as Investors Await Central Bank Decisions\\\" \\n**Output**: \\\"Markets\\\"\\n\\n**Input**: \\\"War in Ukraine: Latest Updates on Negotiation Status\\\" \\n**Output**: \\\"World\\\"\\n\\n**Input**: \\\"Microsoft in Talks to Acquire Gaming Company for $2 Billion\\\" \\n**Output**: \\\"Business\\\"\\n\\n**Input**: \\\"Manchester United Secures Win in Premier League Football Match\\\" \\n**Output**: \\\"Sports\\\" \\n\\n# Notes\\n\\n- If the headline appears to fit into more than one category, choose the most dominant theme.\\n- Keywords or phrases such as \\\"stocks\\\", \\\"company acquisition\\\", \\\"match\\\", or technological brands can be good indicators for classification.\\n\"\n },\n {\n \"role\": \"user\",\n \"content\": \"{{item.input}}\"\n }\n ]\n },\n \"sampling_params\": {\n \"max_completions_tokens\": 2048\n },\n \"model\": \"gpt-6-astra\",\n \"source\": {\n \"type\": \"file_content\",\n \"content\": [\n {\n \"item\": {\n \"input\": \"Tech Company Launches Advanced Artificial Intelligence Platform\",\n \"ground_truth\": \"Technology\"\n }\n }\n ]\n }\n }\n)\nprint(run)\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nconst run = await openai.evals.runs.create(\n \"eval_67e579652b548190aaa83ada4b125f47\",\n {\n name: \"gpt-6-astra\",\n data_source: {\n type: \"completions\",\n input_messages: {\n type: \"template\",\n template: [\n {\n role: \"developer\",\n content: \"Categorize a given news headline into one of the following topics: Technology, Markets, World, Business, or Sports.\\n\\n# Steps\\n\\n1. Analyze the content of the news headline to understand its primary focus.\\n2. Extract the subject matter, identifying any key indicators or keywords.\\n3. Use the identified indicators to determine the most suitable category out of the five options: Technology, Markets, World, Business, or Sports.\\n4. Ensure only one category is selected per headline.\\n\\n# Output Format\\n\\nRespond with the chosen category as a single word. For instance: \\\"Technology\\\", \\\"Markets\\\", \\\"World\\\", \\\"Business\\\", or \\\"Sports\\\".\\n\\n# Examples\\n\\n**Input**: \\\"Apple Unveils New iPhone Model, Featuring Advanced AI Features\\\" \\n**Output**: \\\"Technology\\\"\\n\\n**Input**: \\\"Global Stocks Mixed as Investors Await Central Bank Decisions\\\" \\n**Output**: \\\"Markets\\\"\\n\\n**Input**: \\\"War in Ukraine: Latest Updates on Negotiation Status\\\" \\n**Output**: \\\"World\\\"\\n\\n**Input**: \\\"Microsoft in Talks to Acquire Gaming Company for $2 Billion\\\" \\n**Output**: \\\"Business\\\"\\n\\n**Input**: \\\"Manchester United Secures Win in Premier League Football Match\\\" \\n**Output**: \\\"Sports\\\" \\n\\n# Notes\\n\\n- If the headline appears to fit into more than one category, choose the most dominant theme.\\n- Keywords or phrases such as \\\"stocks\\\", \\\"company acquisition\\\", \\\"match\\\", or technological brands can be good indicators for classification.\\n\"\n },\n {\n role: \"user\",\n content: \"{{item.input}}\"\n }\n ]\n },\n sampling_params: {\n max_completions_tokens: 2048\n },\n model: \"gpt-6-astra\",\n source: {\n type: \"file_content\",\n content: [\n {\n item: {\n input: \"Tech Company Launches Advanced Artificial Intelligence Platform\",\n ground_truth: \"Technology\"\n }\n }\n ]\n }\n }\n }\n);\nconsole.log(run);\n" + }, + "response": "{\n \"object\": \"eval.run\",\n \"id\": \"evalrun_67e57965b480819094274e3a32235e4c\",\n \"eval_id\": \"eval_67e579652b548190aaa83ada4b125f47\",\n \"report_url\": \"https://platform.openai.com/evaluations/eval_67e579652b548190aaa83ada4b125f47&run_id=evalrun_67e57965b480819094274e3a32235e4c\",\n \"status\": \"queued\",\n \"model\": \"gpt-6-astra\",\n \"name\": \"gpt-6-astra\",\n \"created_at\": 1743092069,\n \"result_counts\": {\n \"total\": 0,\n \"errored\": 0,\n \"failed\": 0,\n \"passed\": 0\n },\n \"per_model_usage\": null,\n \"per_testing_criteria_results\": null,\n \"data_source\": {\n \"type\": \"completions\",\n \"source\": {\n \"type\": \"file_content\",\n \"content\": [\n {\n \"item\": {\n \"input\": \"Tech Company Launches Advanced Artificial Intelligence Platform\",\n \"ground_truth\": \"Technology\"\n }\n }\n ]\n },\n \"input_messages\": {\n \"type\": \"template\",\n \"template\": [\n {\n \"type\": \"message\",\n \"role\": \"developer\",\n \"content\": {\n \"type\": \"input_text\",\n \"text\": \"Categorize a given news headline into one of the following topics: Technology, Markets, World, Business, or Sports.\\n\\n# Steps\\n\\n1. Analyze the content of the news headline to understand its primary focus.\\n2. Extract the subject matter, identifying any key indicators or keywords.\\n3. Use the identified indicators to determine the most suitable category out of the five options: Technology, Markets, World, Business, or Sports.\\n4. Ensure only one category is selected per headline.\\n\\n# Output Format\\n\\nRespond with the chosen category as a single word. For instance: \\\"Technology\\\", \\\"Markets\\\", \\\"World\\\", \\\"Business\\\", or \\\"Sports\\\".\\n\\n# Examples\\n\\n**Input**: \\\"Apple Unveils New iPhone Model, Featuring Advanced AI Features\\\" \\n**Output**: \\\"Technology\\\"\\n\\n**Input**: \\\"Global Stocks Mixed as Investors Await Central Bank Decisions\\\" \\n**Output**: \\\"Markets\\\"\\n\\n**Input**: \\\"War in Ukraine: Latest Updates on Negotiation Status\\\" \\n**Output**: \\\"World\\\"\\n\\n**Input**: \\\"Microsoft in Talks to Acquire Gaming Company for $2 Billion\\\" \\n**Output**: \\\"Business\\\"\\n\\n**Input**: \\\"Manchester United Secures Win in Premier League Football Match\\\" \\n**Output**: \\\"Sports\\\" \\n\\n# Notes\\n\\n- If the headline appears to fit into more than one category, choose the most dominant theme.\\n- Keywords or phrases such as \\\"stocks\\\", \\\"company acquisition\\\", \\\"match\\\", or technological brands can be good indicators for classification.\\n\"\n }\n },\n {\n \"type\": \"message\",\n \"role\": \"user\",\n \"content\": {\n \"type\": \"input_text\",\n \"text\": \"{{item.input}}\"\n }\n }\n ]\n },\n \"model\": \"gpt-6-astra\",\n \"sampling_params\": {\n \"max_completions_tokens\": 2048\n }\n },\n \"error\": null,\n \"metadata\": {}\n}\n" + } + } + } + }, + "/evals/{eval_id}/runs/{run_id}": { + "get": { + "operationId": "getEvalRun", + "tags": [ + "Evals" + ], + "summary": "Get an evaluation run by ID.\n", + "parameters": [ + { + "name": "eval_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the evaluation to retrieve runs for." + }, + { + "name": "run_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the run to retrieve." + } + ], + "responses": { + "200": { + "description": "The evaluation run", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EvalRun" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Get an eval run", + "group": "evals", + "path": "get", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/evals/eval_67abd54d9b0081909a86353f6fb9317a/runs/evalrun_67abd54d60ec8190832b46859da808f7 \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\"\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\nrun = client.evals.runs.retrieve(\n \"eval_67abd54d9b0081909a86353f6fb9317a\",\n \"evalrun_67abd54d60ec8190832b46859da808f7\"\n)\nprint(run)\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nconst run = await openai.evals.runs.retrieve(\n \"evalrun_67abd54d60ec8190832b46859da808f7\",\n { eval_id: \"eval_67abd54d9b0081909a86353f6fb9317a\" }\n);\nconsole.log(run);\n" + }, + "response": "{\n \"object\": \"eval.run\",\n \"id\": \"evalrun_67abd54d60ec8190832b46859da808f7\",\n \"eval_id\": \"eval_67abd54d9b0081909a86353f6fb9317a\",\n \"report_url\": \"https://platform.openai.com/evaluations/eval_67abd54d9b0081909a86353f6fb9317a?run_id=evalrun_67abd54d60ec8190832b46859da808f7\",\n \"status\": \"queued\",\n \"model\": \"gpt-6-astra\",\n \"name\": \"gpt-6-astra\",\n \"created_at\": 1743092069,\n \"result_counts\": {\n \"total\": 0,\n \"errored\": 0,\n \"failed\": 0,\n \"passed\": 0\n },\n \"per_model_usage\": null,\n \"per_testing_criteria_results\": null,\n \"data_source\": {\n \"type\": \"completions\",\n \"source\": {\n \"type\": \"file_content\",\n \"content\": [\n {\n \"item\": {\n \"input\": \"Tech Company Launches Advanced Artificial Intelligence Platform\",\n \"ground_truth\": \"Technology\"\n }\n },\n {\n \"item\": {\n \"input\": \"Central Bank Increases Interest Rates Amid Inflation Concerns\",\n \"ground_truth\": \"Markets\"\n }\n },\n {\n \"item\": {\n \"input\": \"International Summit Addresses Climate Change Strategies\",\n \"ground_truth\": \"World\"\n }\n },\n {\n \"item\": {\n \"input\": \"Major Retailer Reports Record-Breaking Holiday Sales\",\n \"ground_truth\": \"Business\"\n }\n },\n {\n \"item\": {\n \"input\": \"National Team Qualifies for World Championship Finals\",\n \"ground_truth\": \"Sports\"\n }\n },\n {\n \"item\": {\n \"input\": \"Stock Markets Rally After Positive Economic Data Released\",\n \"ground_truth\": \"Markets\"\n }\n },\n {\n \"item\": {\n \"input\": \"Global Manufacturer Announces Merger with Competitor\",\n \"ground_truth\": \"Business\"\n }\n },\n {\n \"item\": {\n \"input\": \"Breakthrough in Renewable Energy Technology Unveiled\",\n \"ground_truth\": \"Technology\"\n }\n },\n {\n \"item\": {\n \"input\": \"World Leaders Sign Historic Climate Agreement\",\n \"ground_truth\": \"World\"\n }\n },\n {\n \"item\": {\n \"input\": \"Professional Athlete Sets New Record in Championship Event\",\n \"ground_truth\": \"Sports\"\n }\n },\n {\n \"item\": {\n \"input\": \"Financial Institutions Adapt to New Regulatory Requirements\",\n \"ground_truth\": \"Business\"\n }\n },\n {\n \"item\": {\n \"input\": \"Tech Conference Showcases Advances in Artificial Intelligence\",\n \"ground_truth\": \"Technology\"\n }\n },\n {\n \"item\": {\n \"input\": \"Global Markets Respond to Oil Price Fluctuations\",\n \"ground_truth\": \"Markets\"\n }\n },\n {\n \"item\": {\n \"input\": \"International Cooperation Strengthened Through New Treaty\",\n \"ground_truth\": \"World\"\n }\n },\n {\n \"item\": {\n \"input\": \"Sports League Announces Revised Schedule for Upcoming Season\",\n \"ground_truth\": \"Sports\"\n }\n }\n ]\n },\n \"input_messages\": {\n \"type\": \"template\",\n \"template\": [\n {\n \"type\": \"message\",\n \"role\": \"developer\",\n \"content\": {\n \"type\": \"input_text\",\n \"text\": \"Categorize a given news headline into one of the following topics: Technology, Markets, World, Business, or Sports.\\n\\n# Steps\\n\\n1. Analyze the content of the news headline to understand its primary focus.\\n2. Extract the subject matter, identifying any key indicators or keywords.\\n3. Use the identified indicators to determine the most suitable category out of the five options: Technology, Markets, World, Business, or Sports.\\n4. Ensure only one category is selected per headline.\\n\\n# Output Format\\n\\nRespond with the chosen category as a single word. For instance: \\\"Technology\\\", \\\"Markets\\\", \\\"World\\\", \\\"Business\\\", or \\\"Sports\\\".\\n\\n# Examples\\n\\n**Input**: \\\"Apple Unveils New iPhone Model, Featuring Advanced AI Features\\\" \\n**Output**: \\\"Technology\\\"\\n\\n**Input**: \\\"Global Stocks Mixed as Investors Await Central Bank Decisions\\\" \\n**Output**: \\\"Markets\\\"\\n\\n**Input**: \\\"War in Ukraine: Latest Updates on Negotiation Status\\\" \\n**Output**: \\\"World\\\"\\n\\n**Input**: \\\"Microsoft in Talks to Acquire Gaming Company for $2 Billion\\\" \\n**Output**: \\\"Business\\\"\\n\\n**Input**: \\\"Manchester United Secures Win in Premier League Football Match\\\" \\n**Output**: \\\"Sports\\\" \\n\\n# Notes\\n\\n- If the headline appears to fit into more than one category, choose the most dominant theme.\\n- Keywords or phrases such as \\\"stocks\\\", \\\"company acquisition\\\", \\\"match\\\", or technological brands can be good indicators for classification.\\n\"\n }\n },\n {\n \"type\": \"message\",\n \"role\": \"user\",\n \"content\": {\n \"type\": \"input_text\",\n \"text\": \"{{item.input}}\"\n }\n }\n ]\n },\n \"model\": \"gpt-6-astra\",\n \"sampling_params\": {\n \"max_completions_tokens\": 2048\n }\n },\n \"error\": null,\n \"metadata\": {}\n}\n" + } + } + }, + "post": { + "operationId": "cancelEvalRun", + "tags": [ + "Evals" + ], + "summary": "Cancel an ongoing evaluation run.\n", + "parameters": [ + { + "name": "eval_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the evaluation whose run you want to cancel." + }, + { + "name": "run_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the run to cancel." + } + ], + "responses": { + "200": { + "description": "The canceled eval run object", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EvalRun" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Cancel eval run", + "group": "evals", + "path": "post", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/evals/eval_67abd54d9b0081909a86353f6fb9317a/runs/evalrun_67abd54d60ec8190832b46859da808f7/cancel \\\n -X POST \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\"\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\ncanceled_run = client.evals.runs.cancel(\n \"eval_67abd54d9b0081909a86353f6fb9317a\",\n \"evalrun_67abd54d60ec8190832b46859da808f7\"\n)\nprint(canceled_run)\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nconst canceledRun = await openai.evals.runs.cancel(\n \"evalrun_67abd54d60ec8190832b46859da808f7\",\n { eval_id: \"eval_67abd54d9b0081909a86353f6fb9317a\" }\n);\nconsole.log(canceledRun);\n" + }, + "response": "{\n \"object\": \"eval.run\",\n \"id\": \"evalrun_67abd54d60ec8190832b46859da808f7\",\n \"eval_id\": \"eval_67abd54d9b0081909a86353f6fb9317a\",\n \"report_url\": \"https://platform.openai.com/evaluations/eval_67abd54d9b0081909a86353f6fb9317a?run_id=evalrun_67abd54d60ec8190832b46859da808f7\",\n \"status\": \"canceled\",\n \"model\": \"gpt-6-astra\",\n \"name\": \"gpt-6-astra\",\n \"created_at\": 1743092069,\n \"result_counts\": {\n \"total\": 0,\n \"errored\": 0,\n \"failed\": 0,\n \"passed\": 0\n },\n \"per_model_usage\": null,\n \"per_testing_criteria_results\": null,\n \"data_source\": {\n \"type\": \"completions\",\n \"source\": {\n \"type\": \"file_content\",\n \"content\": [\n {\n \"item\": {\n \"input\": \"Tech Company Launches Advanced Artificial Intelligence Platform\",\n \"ground_truth\": \"Technology\"\n }\n },\n {\n \"item\": {\n \"input\": \"Central Bank Increases Interest Rates Amid Inflation Concerns\",\n \"ground_truth\": \"Markets\"\n }\n },\n {\n \"item\": {\n \"input\": \"International Summit Addresses Climate Change Strategies\",\n \"ground_truth\": \"World\"\n }\n },\n {\n \"item\": {\n \"input\": \"Major Retailer Reports Record-Breaking Holiday Sales\",\n \"ground_truth\": \"Business\"\n }\n },\n {\n \"item\": {\n \"input\": \"National Team Qualifies for World Championship Finals\",\n \"ground_truth\": \"Sports\"\n }\n },\n {\n \"item\": {\n \"input\": \"Stock Markets Rally After Positive Economic Data Released\",\n \"ground_truth\": \"Markets\"\n }\n },\n {\n \"item\": {\n \"input\": \"Global Manufacturer Announces Merger with Competitor\",\n \"ground_truth\": \"Business\"\n }\n },\n {\n \"item\": {\n \"input\": \"Breakthrough in Renewable Energy Technology Unveiled\",\n \"ground_truth\": \"Technology\"\n }\n },\n {\n \"item\": {\n \"input\": \"World Leaders Sign Historic Climate Agreement\",\n \"ground_truth\": \"World\"\n }\n },\n {\n \"item\": {\n \"input\": \"Professional Athlete Sets New Record in Championship Event\",\n \"ground_truth\": \"Sports\"\n }\n },\n {\n \"item\": {\n \"input\": \"Financial Institutions Adapt to New Regulatory Requirements\",\n \"ground_truth\": \"Business\"\n }\n },\n {\n \"item\": {\n \"input\": \"Tech Conference Showcases Advances in Artificial Intelligence\",\n \"ground_truth\": \"Technology\"\n }\n },\n {\n \"item\": {\n \"input\": \"Global Markets Respond to Oil Price Fluctuations\",\n \"ground_truth\": \"Markets\"\n }\n },\n {\n \"item\": {\n \"input\": \"International Cooperation Strengthened Through New Treaty\",\n \"ground_truth\": \"World\"\n }\n },\n {\n \"item\": {\n \"input\": \"Sports League Announces Revised Schedule for Upcoming Season\",\n \"ground_truth\": \"Sports\"\n }\n }\n ]\n },\n \"input_messages\": {\n \"type\": \"template\",\n \"template\": [\n {\n \"type\": \"message\",\n \"role\": \"developer\",\n \"content\": {\n \"type\": \"input_text\",\n \"text\": \"Categorize a given news headline into one of the following topics: Technology, Markets, World, Business, or Sports.\\n\\n# Steps\\n\\n1. Analyze the content of the news headline to understand its primary focus.\\n2. Extract the subject matter, identifying any key indicators or keywords.\\n3. Use the identified indicators to determine the most suitable category out of the five options: Technology, Markets, World, Business, or Sports.\\n4. Ensure only one category is selected per headline.\\n\\n# Output Format\\n\\nRespond with the chosen category as a single word. For instance: \\\"Technology\\\", \\\"Markets\\\", \\\"World\\\", \\\"Business\\\", or \\\"Sports\\\".\\n\\n# Examples\\n\\n**Input**: \\\"Apple Unveils New iPhone Model, Featuring Advanced AI Features\\\" \\n**Output**: \\\"Technology\\\"\\n\\n**Input**: \\\"Global Stocks Mixed as Investors Await Central Bank Decisions\\\" \\n**Output**: \\\"Markets\\\"\\n\\n**Input**: \\\"War in Ukraine: Latest Updates on Negotiation Status\\\" \\n**Output**: \\\"World\\\"\\n\\n**Input**: \\\"Microsoft in Talks to Acquire Gaming Company for $2 Billion\\\" \\n**Output**: \\\"Business\\\"\\n\\n**Input**: \\\"Manchester United Secures Win in Premier League Football Match\\\" \\n**Output**: \\\"Sports\\\" \\n\\n# Notes\\n\\n- If the headline appears to fit into more than one category, choose the most dominant theme.\\n- Keywords or phrases such as \\\"stocks\\\", \\\"company acquisition\\\", \\\"match\\\", or technological brands can be good indicators for classification.\\n\"\n }\n },\n {\n \"type\": \"message\",\n \"role\": \"user\",\n \"content\": {\n \"type\": \"input_text\",\n \"text\": \"{{item.input}}\"\n }\n }\n ]\n },\n \"model\": \"gpt-6-astra\",\n \"sampling_params\": {\n \"max_completions_tokens\": 2048\n }\n },\n \"error\": null,\n \"metadata\": {}\n}\n" + } + } + }, + "delete": { + "operationId": "deleteEvalRun", + "tags": [ + "Evals" + ], + "summary": "Delete an eval run.\n", + "parameters": [ + { + "name": "eval_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the evaluation to delete the run from." + }, + { + "name": "run_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the run to delete." + } + ], + "responses": { + "200": { + "description": "Successfully deleted the eval run", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "object": { + "type": "string", + "example": "eval.run.deleted" + }, + "deleted": { + "type": "boolean", + "example": true + }, + "run_id": { + "type": "string", + "example": "evalrun_677469f564d48190807532a852da3afb" + } + } + } + } + } + }, + "404": { + "description": "Run not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Delete eval run", + "group": "evals", + "path": "delete", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/evals/eval_123abc/runs/evalrun_abc456 \\\n -X DELETE \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\"\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\ndeleted = client.evals.runs.delete(\n \"eval_123abc\",\n \"evalrun_abc456\"\n)\nprint(deleted)\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nconst deleted = await openai.evals.runs.delete(\n \"eval_123abc\",\n \"evalrun_abc456\"\n);\nconsole.log(deleted);\n" + }, + "response": "{\n \"object\": \"eval.run.deleted\",\n \"deleted\": true,\n \"run_id\": \"evalrun_abc456\"\n}\n" + } + } + } + }, + "/evals/{eval_id}/runs/{run_id}/output_items": { + "get": { + "operationId": "getEvalRunOutputItems", + "tags": [ + "Evals" + ], + "summary": "Get a list of output items for an evaluation run.\n", + "parameters": [ + { + "name": "eval_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the evaluation to retrieve runs for." + }, + { + "name": "run_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the run to retrieve output items for." + }, + { + "name": "after", + "in": "query", + "description": "Identifier for the last output item from the previous pagination request.", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "description": "Number of output items to retrieve.", + "required": false, + "schema": { + "type": "integer", + "default": 20 + } + }, + { + "name": "status", + "in": "query", + "description": "Filter output items by status. Use `failed` to filter by failed output\nitems or `pass` to filter by passed output items.\n", + "required": false, + "schema": { + "type": "string", + "enum": [ + "fail", + "pass" + ] + } + }, + { + "name": "order", + "in": "query", + "description": "Sort order for output items by timestamp. Use `asc` for ascending order or `desc` for descending order. Defaults to `asc`.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "asc", + "desc" + ], + "default": "asc" + } + } + ], + "responses": { + "200": { + "description": "A list of output items for the evaluation run", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EvalRunOutputItemList" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Get eval run output items", + "group": "evals", + "path": "get", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/evals/egroup_67abd54d9b0081909a86353f6fb9317a/runs/erun_67abd54d60ec8190832b46859da808f7/output_items \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\"\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\noutput_items = client.evals.runs.output_items.list(\n \"egroup_67abd54d9b0081909a86353f6fb9317a\",\n \"erun_67abd54d60ec8190832b46859da808f7\"\n)\nprint(output_items)\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nconst outputItems = await openai.evals.runs.outputItems.list(\n \"egroup_67abd54d9b0081909a86353f6fb9317a\",\n \"erun_67abd54d60ec8190832b46859da808f7\"\n);\nconsole.log(outputItems);\n" + }, + "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"eval.run.output_item\",\n \"id\": \"outputitem_67e5796c28e081909917bf79f6e6214d\",\n \"created_at\": 1743092076,\n \"run_id\": \"evalrun_67abd54d60ec8190832b46859da808f7\",\n \"eval_id\": \"eval_67abd54d9b0081909a86353f6fb9317a\",\n \"status\": \"pass\",\n \"datasource_item_id\": 5,\n \"datasource_item\": {\n \"input\": \"Stock Markets Rally After Positive Economic Data Released\",\n \"ground_truth\": \"Markets\"\n },\n \"results\": [\n {\n \"name\": \"String check-a2486074-d803-4445-b431-ad2262e85d47\",\n \"sample\": null,\n \"passed\": true,\n \"score\": 1.0\n }\n ],\n \"sample\": {\n \"input\": [\n {\n \"role\": \"developer\",\n \"content\": \"Categorize a given news headline into one of the following topics: Technology, Markets, World, Business, or Sports.\\n\\n# Steps\\n\\n1. Analyze the content of the news headline to understand its primary focus.\\n2. Extract the subject matter, identifying any key indicators or keywords.\\n3. Use the identified indicators to determine the most suitable category out of the five options: Technology, Markets, World, Business, or Sports.\\n4. Ensure only one category is selected per headline.\\n\\n# Output Format\\n\\nRespond with the chosen category as a single word. For instance: \\\"Technology\\\", \\\"Markets\\\", \\\"World\\\", \\\"Business\\\", or \\\"Sports\\\".\\n\\n# Examples\\n\\n**Input**: \\\"Apple Unveils New iPhone Model, Featuring Advanced AI Features\\\" \\n**Output**: \\\"Technology\\\"\\n\\n**Input**: \\\"Global Stocks Mixed as Investors Await Central Bank Decisions\\\" \\n**Output**: \\\"Markets\\\"\\n\\n**Input**: \\\"War in Ukraine: Latest Updates on Negotiation Status\\\" \\n**Output**: \\\"World\\\"\\n\\n**Input**: \\\"Microsoft in Talks to Acquire Gaming Company for $2 Billion\\\" \\n**Output**: \\\"Business\\\"\\n\\n**Input**: \\\"Manchester United Secures Win in Premier League Football Match\\\" \\n**Output**: \\\"Sports\\\" \\n\\n# Notes\\n\\n- If the headline appears to fit into more than one category, choose the most dominant theme.\\n- Keywords or phrases such as \\\"stocks\\\", \\\"company acquisition\\\", \\\"match\\\", or technological brands can be good indicators for classification.\\n\",\n \"tool_call_id\": null,\n \"tool_calls\": null,\n \"function_call\": null\n },\n {\n \"role\": \"user\",\n \"content\": \"Stock Markets Rally After Positive Economic Data Released\",\n \"tool_call_id\": null,\n \"tool_calls\": null,\n \"function_call\": null\n }\n ],\n \"output\": [\n {\n \"role\": \"assistant\",\n \"content\": \"Markets\",\n \"tool_call_id\": null,\n \"tool_calls\": null,\n \"function_call\": null\n }\n ],\n \"finish_reason\": \"stop\",\n \"model\": \"gpt-6-astra\",\n \"usage\": {\n \"total_tokens\": 325,\n \"completion_tokens\": 2,\n \"prompt_tokens\": 323,\n \"cached_tokens\": 0\n },\n \"error\": null,\n \"temperature\": 1.0,\n \"max_completion_tokens\": 2048,\n \"top_p\": 1.0,\n \"seed\": 42\n }\n }\n ],\n \"first_id\": \"outputitem_67e5796c28e081909917bf79f6e6214d\",\n \"last_id\": \"outputitem_67e5796c28e081909917bf79f6e6214d\",\n \"has_more\": true\n}\n" + } + } + } + }, + "/evals/{eval_id}/runs/{run_id}/output_items/{output_item_id}": { + "get": { + "operationId": "getEvalRunOutputItem", + "tags": [ + "Evals" + ], + "summary": "Get an evaluation run output item by ID.\n", + "parameters": [ + { + "name": "eval_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the evaluation to retrieve runs for." + }, + { + "name": "run_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the run to retrieve." + }, + { + "name": "output_item_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the output item to retrieve." + } + ], + "responses": { + "200": { + "description": "The evaluation run output item", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EvalRunOutputItem" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Get an output item of an eval run", + "group": "evals", + "path": "get", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/evals/eval_67abd54d9b0081909a86353f6fb9317a/runs/evalrun_67abd54d60ec8190832b46859da808f7/output_items/outputitem_67abd55eb6548190bb580745d5644a33 \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\"\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\noutput_item = client.evals.runs.output_items.retrieve(\n \"eval_67abd54d9b0081909a86353f6fb9317a\",\n \"evalrun_67abd54d60ec8190832b46859da808f7\",\n \"outputitem_67abd55eb6548190bb580745d5644a33\"\n)\nprint(output_item)\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nconst outputItem = await openai.evals.runs.outputItems.retrieve(\n \"outputitem_67abd55eb6548190bb580745d5644a33\",\n {\n eval_id: \"eval_67abd54d9b0081909a86353f6fb9317a\",\n run_id: \"evalrun_67abd54d60ec8190832b46859da808f7\",\n }\n);\nconsole.log(outputItem);\n" + }, + "response": "{\n \"object\": \"eval.run.output_item\",\n \"id\": \"outputitem_67e5796c28e081909917bf79f6e6214d\",\n \"created_at\": 1743092076,\n \"run_id\": \"evalrun_67abd54d60ec8190832b46859da808f7\",\n \"eval_id\": \"eval_67abd54d9b0081909a86353f6fb9317a\",\n \"status\": \"pass\",\n \"datasource_item_id\": 5,\n \"datasource_item\": {\n \"input\": \"Stock Markets Rally After Positive Economic Data Released\",\n \"ground_truth\": \"Markets\"\n },\n \"results\": [\n {\n \"name\": \"String check-a2486074-d803-4445-b431-ad2262e85d47\",\n \"sample\": null,\n \"passed\": true,\n \"score\": 1.0\n }\n ],\n \"sample\": {\n \"input\": [\n {\n \"role\": \"developer\",\n \"content\": \"Categorize a given news headline into one of the following topics: Technology, Markets, World, Business, or Sports.\\n\\n# Steps\\n\\n1. Analyze the content of the news headline to understand its primary focus.\\n2. Extract the subject matter, identifying any key indicators or keywords.\\n3. Use the identified indicators to determine the most suitable category out of the five options: Technology, Markets, World, Business, or Sports.\\n4. Ensure only one category is selected per headline.\\n\\n# Output Format\\n\\nRespond with the chosen category as a single word. For instance: \\\"Technology\\\", \\\"Markets\\\", \\\"World\\\", \\\"Business\\\", or \\\"Sports\\\".\\n\\n# Examples\\n\\n**Input**: \\\"Apple Unveils New iPhone Model, Featuring Advanced AI Features\\\" \\n**Output**: \\\"Technology\\\"\\n\\n**Input**: \\\"Global Stocks Mixed as Investors Await Central Bank Decisions\\\" \\n**Output**: \\\"Markets\\\"\\n\\n**Input**: \\\"War in Ukraine: Latest Updates on Negotiation Status\\\" \\n**Output**: \\\"World\\\"\\n\\n**Input**: \\\"Microsoft in Talks to Acquire Gaming Company for $2 Billion\\\" \\n**Output**: \\\"Business\\\"\\n\\n**Input**: \\\"Manchester United Secures Win in Premier League Football Match\\\" \\n**Output**: \\\"Sports\\\" \\n\\n# Notes\\n\\n- If the headline appears to fit into more than one category, choose the most dominant theme.\\n- Keywords or phrases such as \\\"stocks\\\", \\\"company acquisition\\\", \\\"match\\\", or technological brands can be good indicators for classification.\\n\",\n \"tool_call_id\": null,\n \"tool_calls\": null,\n \"function_call\": null\n },\n {\n \"role\": \"user\",\n \"content\": \"Stock Markets Rally After Positive Economic Data Released\",\n \"tool_call_id\": null,\n \"tool_calls\": null,\n \"function_call\": null\n }\n ],\n \"output\": [\n {\n \"role\": \"assistant\",\n \"content\": \"Markets\",\n \"tool_call_id\": null,\n \"tool_calls\": null,\n \"function_call\": null\n }\n ],\n \"finish_reason\": \"stop\",\n \"model\": \"gpt-6-astra\",\n \"usage\": {\n \"total_tokens\": 325,\n \"completion_tokens\": 2,\n \"prompt_tokens\": 323,\n \"cached_tokens\": 0\n },\n \"error\": null,\n \"temperature\": 1.0,\n \"max_completion_tokens\": 2048,\n \"top_p\": 1.0,\n \"seed\": 42\n }\n}\n" + } + } + } + }, + "/files": { + "get": { + "operationId": "listFiles", + "tags": [ + "Files" + ], + "summary": "Returns a list of files.", + "parameters": [ + { + "in": "query", + "name": "purpose", + "required": false, + "schema": { + "type": "string" + }, + "description": "Only return files with the given purpose." + }, + { + "name": "limit", + "in": "query", + "description": "A limit on the number of objects to be returned. Limit can range between 1 and 10,000, and the default is 10,000.\n", + "required": false, + "schema": { + "type": "integer", + "default": 10000 + } + }, + { + "name": "order", + "in": "query", + "description": "Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order.\n", + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + } + }, + { + "name": "after", + "in": "query", + "description": "A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.\n", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListFilesResponse" + } + } + } + } + }, + "x-oaiMeta": { + "name": "List files", + "group": "files", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/files \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.files.list()\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const list = await openai.files.list();\n\n for await (const file of list) {\n console.log(file);\n }\n}\n\nmain();" + }, + "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"file-abc123\",\n \"object\": \"file\",\n \"bytes\": 175,\n \"created_at\": 1613677385,\n \"expires_at\": 1677614202,\n \"filename\": \"salesOverview.pdf\",\n \"purpose\": \"assistants\",\n },\n {\n \"id\": \"file-abc456\",\n \"object\": \"file\",\n \"bytes\": 140,\n \"created_at\": 1613779121,\n \"expires_at\": 1677614202,\n \"filename\": \"puppy.jsonl\",\n \"purpose\": \"fine-tune\",\n }\n ],\n \"first_id\": \"file-abc123\",\n \"last_id\": \"file-abc456\",\n \"has_more\": false\n}\n" + } + } + }, + "post": { + "operationId": "createFile", + "tags": [ + "Files" + ], + "summary": "Upload a file that can be used across various endpoints. Individual files\ncan be up to 512 MB, and each project can store up to 2.5 TB of files in\ntotal. There is no organization-wide storage limit. Uploads to this\nendpoint are rate-limited to 1,000 requests per minute per authenticated\nuser.\n\n- The Assistants API supports files up to 2 million tokens and of specific\n file types. See the [Assistants Tools guide](https://developers.openai.com/api/docs/guides/tools) for\n details.\n- The Fine-tuning API only supports `.jsonl` files. The input also has\n certain required formats for fine-tuning\n [chat](https://developers.openai.com/api/docs/guides/supervised-fine-tuning#formatting-your-data) or\n [completions](https://developers.openai.com/api/docs/guides/supervised-fine-tuning#formatting-your-data) models.\n- The Batch API only supports `.jsonl` files up to 200 MB in size. The input\n also has a specific required\n [format](https://developers.openai.com/api/docs/guides/batch#1-prepare-your-batch-file).\n- For Retrieval or `file_search` ingestion, upload files here first. If\n you need to attach multiple uploaded files to the same vector store, use\n [`/vector_stores/{vector_store_id}/file_batches`](https://developers.openai.com/api/reference/resources/vector_stores/subresources/file_batches/methods/create)\n instead of attaching them one by one. Vector store attachment has separate\n limits from file upload, including 2,000 attached files per minute per\n organization.\n\nPlease [contact us](https://help.openai.com/) if you need to increase these\nstorage limits.\n", + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "$ref": "#/components/schemas/CreateFileRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OpenAIFile" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Upload file", + "group": "files", + "description": "Uploads a file for later use across OpenAI APIs. Uploads to this endpoint are rate-limited to 1,000 requests per minute per authenticated user. For Retrieval or `file_search` ingestion, upload files here first. If you need to attach multiple uploaded files to the same vector store, use vector store file batches instead of attaching them one by one.\n", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/files \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -F purpose=\"fine-tune\" \\\n -F file=\"@mydata.jsonl\"\n -F expires_after[anchor]=\"created_at\"\n -F expires_after[seconds]=2592000\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.files.create(\n file=open(\"mydata.jsonl\", \"rb\"),\n purpose=\"fine-tune\",\n expires_after={\n \"anchor\": \"created_at\",\n \"seconds\": 2592000\n }\n)\n", + "javascript": "import fs from \"fs\";\nimport OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const file = await openai.files.create({\n file: fs.createReadStream(\"mydata.jsonl\"),\n purpose: \"fine-tune\",\n expires_after: {\n anchor: \"created_at\",\n seconds: 2592000\n }\n });\n\n console.log(file);\n}\n\nmain();" + }, + "response": "{\n \"id\": \"file-abc123\",\n \"object\": \"file\",\n \"bytes\": 120000,\n \"created_at\": 1677610602,\n \"expires_at\": 1677614202,\n \"filename\": \"mydata.jsonl\",\n \"purpose\": \"fine-tune\",\n}\n" + } + } + } + }, + "/files/{file_id}": { + "delete": { + "operationId": "deleteFile", + "tags": [ + "Files" + ], + "summary": "Delete a file and remove it from all vector stores.", + "parameters": [ + { + "in": "path", + "name": "file_id", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the file to use for this request." + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeleteFileResponse" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Delete file", + "group": "files", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/files/file-abc123 \\\n -X DELETE \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.files.delete(\"file-abc123\")\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const file = await openai.files.delete(\"file-abc123\");\n\n console.log(file);\n}\n\nmain();" + }, + "response": "{\n \"id\": \"file-abc123\",\n \"object\": \"file\",\n \"deleted\": true\n}\n" + } + } + }, + "get": { + "operationId": "retrieveFile", + "tags": [ + "Files" + ], + "summary": "Returns information about a specific file.", + "parameters": [ + { + "in": "path", + "name": "file_id", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the file to use for this request." + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OpenAIFile" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Retrieve file", + "group": "files", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/files/file-abc123 \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.files.retrieve(\"file-abc123\")\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const file = await openai.files.retrieve(\"file-abc123\");\n\n console.log(file);\n}\n\nmain();" + }, + "response": "{\n \"id\": \"file-abc123\",\n \"object\": \"file\",\n \"bytes\": 120000,\n \"created_at\": 1677610602,\n \"expires_at\": 1677614202,\n \"filename\": \"mydata.jsonl\",\n \"purpose\": \"fine-tune\",\n}\n" + } + } + } + }, + "/files/{file_id}/content": { + "get": { + "operationId": "downloadFile", + "tags": [ + "Files" + ], + "summary": "Returns a response containing the contents of the specified file.", + "parameters": [ + { + "in": "path", + "name": "file_id", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the file to use for this request." + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "string" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Retrieve file content", + "group": "files", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/files/file-abc123/content \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" > file.jsonl\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\ncontent = client.files.content(\"file-abc123\")\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const response = await openai.files.content(\"file-abc123\");\n const content = await response.text();\n\n console.log(content);\n}\n\nmain();\n" + } + } + } + } + }, + "/fine_tuning/alpha/graders/run": { + "post": { + "operationId": "runGrader", + "tags": [ + "Fine-tuning" + ], + "summary": "Run a grader.\n", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RunGraderRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RunGraderResponse" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Run grader", + "beta": true, + "group": "graders", + "examples": [ + { + "title": "Score text alignment", + "request": { + "curl": "curl -X POST https://api.openai.com/v1/fine_tuning/alpha/graders/run \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -d '{\n \"grader\": {\n \"type\": \"score_model\",\n \"name\": \"Example score model grader\",\n \"input\": [\n {\n \"role\": \"user\",\n \"content\": [\n {\n \"type\": \"input_text\",\n \"text\": \"Score how close the reference answer is to the model answer on a 0-1 scale. Return only the score.\\n\\nReference answer: {{item.reference_answer}}\\n\\nModel answer: {{sample.output_text}}\"\n }\n ]\n }\n ],\n \"model\": \"gpt-5-mini\",\n \"sampling_params\": {\n \"temperature\": 1,\n \"top_p\": 1,\n \"seed\": 42\n }\n },\n \"item\": {\n \"reference_answer\": \"fuzzy wuzzy was a bear\"\n },\n \"model_sample\": \"fuzzy wuzzy was a bear\"\n }'\n", + "python": "from openai import OpenAI\n\nclient = OpenAI()\nresult = client.fine_tuning.alpha.graders.run(\n grader={\n \"type\": \"score_model\",\n \"name\": \"Example score model grader\",\n \"input\": [\n {\n \"role\": \"user\",\n \"content\": [\n {\n \"type\": \"input_text\",\n \"text\": \"Score how close the reference answer is to the model answer on a 0-1 scale. Return only the score.\\n\\nReference answer: {{item.reference_answer}}\\n\\nModel answer: {{sample.output_text}}\",\n }\n ],\n }\n ],\n \"model\": \"gpt-5-mini\",\n \"sampling_params\": {\"temperature\": 1, \"top_p\": 1, \"seed\": 42},\n },\n item={\"reference_answer\": \"fuzzy wuzzy was a bear\"},\n model_sample=\"fuzzy wuzzy was a bear\",\n)\nprint(result)\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nconst result = await openai.fineTuning.alpha.graders.run({\n grader: {\n type: \"score_model\",\n name: \"Example score model grader\",\n input: [\n {\n role: \"user\",\n content: [\n {\n type: \"input_text\",\n text: \"Score how close the reference answer is to the model answer on a 0-1 scale. Return only the score.\\n\\nReference answer: {{item.reference_answer}}\\n\\nModel answer: {{sample.output_text}}\",\n },\n ],\n },\n ],\n model: \"gpt-5-mini\",\n sampling_params: { temperature: 1, top_p: 1, seed: 42 },\n },\n item: { reference_answer: \"fuzzy wuzzy was a bear\" },\n model_sample: \"fuzzy wuzzy was a bear\",\n});\nconsole.log(result);\n" + }, + "response": "{\n \"reward\": 1.0,\n \"metadata\": {\n \"name\": \"Example score model grader\",\n \"type\": \"score_model\",\n \"errors\": {\n \"formula_parse_error\": false,\n \"sample_parse_error\": false,\n \"truncated_observation_error\": false,\n \"unresponsive_reward_error\": false,\n \"invalid_variable_error\": false,\n \"other_error\": false,\n \"python_grader_server_error\": false,\n \"python_grader_server_error_type\": null,\n \"python_grader_runtime_error\": false,\n \"python_grader_runtime_error_details\": null,\n \"model_grader_server_error\": false,\n \"model_grader_refusal_error\": false,\n \"model_grader_parse_error\": false,\n \"model_grader_server_error_details\": null\n },\n \"execution_time\": 4.365238428115845,\n \"scores\": {},\n \"token_usage\": {\n \"prompt_tokens\": 190,\n \"total_tokens\": 324,\n \"completion_tokens\": 134,\n \"cached_tokens\": 0\n },\n \"sampled_model_name\": \"gpt-5-mini\"\n },\n \"sub_rewards\": {},\n \"model_grader_token_usage_per_model\": {\n \"gpt-5-mini\": {\n \"prompt_tokens\": 190,\n \"total_tokens\": 324,\n \"completion_tokens\": 134,\n \"cached_tokens\": 0\n }\n }\n}\n" + }, + { + "title": "Score an image caption", + "request": { + "curl": "curl -X POST https://api.openai.com/v1/fine_tuning/alpha/graders/run \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -d '{\n \"grader\": {\n \"type\": \"score_model\",\n \"name\": \"Image caption grader\",\n \"input\": [\n {\n \"role\": \"user\",\n \"content\": [\n {\n \"type\": \"input_text\",\n \"text\": \"Score how well the provided caption matches the image on a 0-1 scale. Only return the score.\\n\\nCaption: {{sample.output_text}}\"\n },\n {\n \"type\": \"input_image\",\n \"image_url\": \"https://example.com/dog-catching-ball.png\",\n \"file_id\": null,\n \"detail\": \"high\"\n }\n ]\n }\n ],\n \"model\": \"gpt-5-mini\",\n \"sampling_params\": {\n \"temperature\": 0.2\n }\n },\n \"item\": {\n \"expected_caption\": \"A golden retriever jumps to catch a tennis ball\"\n },\n \"model_sample\": \"A dog leaps to grab a tennis ball mid-air\"\n }'\n" + } + }, + { + "title": "Score an audio response", + "request": { + "curl": "curl -X POST https://api.openai.com/v1/fine_tuning/alpha/graders/run \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -d '{\n \"grader\": {\n \"type\": \"score_model\",\n \"name\": \"Audio clarity grader\",\n \"input\": [\n {\n \"role\": \"user\",\n \"content\": [\n {\n \"type\": \"input_text\",\n \"text\": \"Listen to the clip and return a confidence score from 0 to 1 that the speaker said: {{item.target_phrase}}\"\n },\n {\n \"type\": \"input_audio\",\n \"input_audio\": {\n \"data\": \"{{item.audio_clip_b64}}\",\n \"format\": \"mp3\"\n }\n }\n ]\n }\n ],\n \"model\": \"gpt-audio\",\n \"sampling_params\": {\n \"temperature\": 0.2,\n \"top_p\": 1,\n \"seed\": 123\n }\n },\n \"item\": {\n \"target_phrase\": \"Please deliver the package on Tuesday\",\n \"audio_clip_b64\": \"\"\n },\n \"model_sample\": \"Please deliver the package on Tuesday\"\n }'\n" + } + } + ] + } + } + }, + "/fine_tuning/alpha/graders/validate": { + "post": { + "operationId": "validateGrader", + "tags": [ + "Fine-tuning" + ], + "summary": "Validate a grader.\n", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ValidateGraderRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ValidateGraderResponse" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Validate grader", + "beta": true, + "group": "graders", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/fine_tuning/alpha/graders/validate \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"grader\": {\n \"type\": \"string_check\",\n \"name\": \"Example string check grader\",\n \"input\": \"{{sample.output_text}}\",\n \"reference\": \"{{item.label}}\",\n \"operation\": \"eq\"\n }\n }'\n" + }, + "response": "{\n \"grader\": {\n \"type\": \"string_check\",\n \"name\": \"Example string check grader\",\n \"input\": \"{{sample.output_text}}\",\n \"reference\": \"{{item.label}}\",\n \"operation\": \"eq\"\n }\n}\n" + } + } + } + }, + "/fine_tuning/checkpoints/{fine_tuned_model_checkpoint}/permissions": { + "get": { + "operationId": "listFineTuningCheckpointPermissions", + "tags": [ + "Fine-tuning" + ], + "summary": "**NOTE:** This endpoint requires an [admin API key](https://developers.openai.com/api/reference/resources/admin/subresources/organization/subresources/admin_api_keys).\n\nOrganization owners can use this endpoint to view all permissions for a fine-tuned model checkpoint.\n", + "parameters": [ + { + "in": "path", + "name": "fine_tuned_model_checkpoint", + "required": true, + "schema": { + "type": "string", + "example": "ft-AF1WoRqd3aJAHsqc9NY7iL8F" + }, + "description": "The ID of the fine-tuned model checkpoint to get permissions for.\n" + }, + { + "name": "project_id", + "in": "query", + "description": "The ID of the project to get permissions for.", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "after", + "in": "query", + "description": "Identifier for the last permission ID from the previous pagination request.", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "description": "Number of permissions to retrieve.", + "required": false, + "schema": { + "type": "integer", + "default": 10 + } + }, + { + "name": "order", + "in": "query", + "description": "The order in which to retrieve permissions.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "ascending", + "descending" + ], + "default": "descending" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListFineTuningCheckpointPermissionResponse" + } + } + } + } + }, + "x-oaiMeta": { + "name": "List checkpoint permissions", + "group": "fine-tuning", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/fine_tuning/checkpoints/ft:gpt-4o-mini-2024-07-18:org:weather:B7R9VjQd/permissions \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n" + }, + "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"checkpoint.permission\",\n \"id\": \"cp_zc4Q7MP6XxulcVzj4MZdwsAB\",\n \"created_at\": 1721764867,\n \"project_id\": \"proj_abGMw1llN8IrBb6SvvY5A1iH\"\n },\n {\n \"object\": \"checkpoint.permission\",\n \"id\": \"cp_enQCFmOTGj3syEpYVhBRLTSy\",\n \"created_at\": 1721764800,\n \"project_id\": \"proj_iqGMw1llN8IrBb6SvvY5A1oF\"\n },\n ],\n \"first_id\": \"cp_zc4Q7MP6XxulcVzj4MZdwsAB\",\n \"last_id\": \"cp_enQCFmOTGj3syEpYVhBRLTSy\",\n \"has_more\": false\n}\n" + } + } + }, + "post": { + "operationId": "createFineTuningCheckpointPermission", + "tags": [ + "Fine-tuning" + ], + "summary": "**NOTE:** Calling this endpoint requires an [admin API key](https://developers.openai.com/api/reference/resources/admin/subresources/organization/subresources/admin_api_keys).\n\nThis enables organization owners to share fine-tuned models with other projects in their organization.\n", + "parameters": [ + { + "in": "path", + "name": "fine_tuned_model_checkpoint", + "required": true, + "schema": { + "type": "string", + "example": "ft:gpt-4o-mini-2024-07-18:org:weather:B7R9VjQd" + }, + "description": "The ID of the fine-tuned model checkpoint to create a permission for.\n" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateFineTuningCheckpointPermissionRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListFineTuningCheckpointPermissionResponse" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Create checkpoint permissions", + "group": "fine-tuning", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/fine_tuning/checkpoints/ft:gpt-4o-mini-2024-07-18:org:weather:B7R9VjQd/permissions \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n -d '{\"project_ids\": [\"proj_abGMw1llN8IrBb6SvvY5A1iH\"]}'\n" + }, + "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"checkpoint.permission\",\n \"id\": \"cp_zc4Q7MP6XxulcVzj4MZdwsAB\",\n \"created_at\": 1721764867,\n \"project_id\": \"proj_abGMw1llN8IrBb6SvvY5A1iH\"\n }\n ],\n \"first_id\": \"cp_zc4Q7MP6XxulcVzj4MZdwsAB\",\n \"last_id\": \"cp_zc4Q7MP6XxulcVzj4MZdwsAB\",\n \"has_more\": false\n}\n" + } + } + } + }, + "/fine_tuning/checkpoints/{fine_tuned_model_checkpoint}/permissions/{permission_id}": { + "delete": { + "operationId": "deleteFineTuningCheckpointPermission", + "tags": [ + "Fine-tuning" + ], + "summary": "**NOTE:** This endpoint requires an [admin API key](https://developers.openai.com/api/reference/resources/admin/subresources/organization/subresources/admin_api_keys).\n\nOrganization owners can use this endpoint to delete a permission for a fine-tuned model checkpoint.\n", + "parameters": [ + { + "in": "path", + "name": "fine_tuned_model_checkpoint", + "required": true, + "schema": { + "type": "string", + "example": "ft:gpt-4o-mini-2024-07-18:org:weather:B7R9VjQd" + }, + "description": "The ID of the fine-tuned model checkpoint to delete a permission for.\n" + }, + { + "in": "path", + "name": "permission_id", + "required": true, + "schema": { + "type": "string", + "example": "cp_zc4Q7MP6XxulcVzj4MZdwsAB" + }, + "description": "The ID of the fine-tuned model checkpoint permission to delete.\n" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeleteFineTuningCheckpointPermissionResponse" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Delete checkpoint permission", + "group": "fine-tuning", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/fine_tuning/checkpoints/ft:gpt-4o-mini-2024-07-18:org:weather:B7R9VjQd/permissions/cp_zc4Q7MP6XxulcVzj4MZdwsAB \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n" + }, + "response": "{\n \"object\": \"checkpoint.permission\",\n \"id\": \"cp_zc4Q7MP6XxulcVzj4MZdwsAB\",\n \"deleted\": true\n}\n" + } + } + } + }, + "/fine_tuning/jobs": { + "post": { + "operationId": "createFineTuningJob", + "tags": [ + "Fine-tuning" + ], + "summary": "Creates a fine-tuning job which begins the process of creating a new model from a given dataset.\n\nResponse includes details of the enqueued job including job status and the name of the fine-tuned models once complete.\n\n[Learn more about fine-tuning](https://developers.openai.com/api/docs/guides/model-optimization)\n", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateFineTuningJobRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FineTuningJob" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Create fine-tuning job", + "group": "fine-tuning", + "examples": [ + { + "title": "Default", + "request": { + "curl": "curl https://api.openai.com/v1/fine_tuning/jobs \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -d '{\n \"training_file\": \"file-BK7bzQj3FfZFXr7DbL6xJwfo\",\n \"model\": \"gpt-4o-mini\"\n }'\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.fine_tuning.jobs.create(\n training_file=\"file-abc123\",\n model=\"gpt-4o-mini\"\n)\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const fineTune = await openai.fineTuning.jobs.create({\n training_file: \"file-abc123\"\n });\n\n console.log(fineTune);\n}\n\nmain();\n" + }, + "response": "{\n \"object\": \"fine_tuning.job\",\n \"id\": \"ftjob-abc123\",\n \"model\": \"gpt-4o-mini-2024-07-18\",\n \"created_at\": 1721764800,\n \"fine_tuned_model\": null,\n \"organization_id\": \"org-123\",\n \"result_files\": [],\n \"status\": \"queued\",\n \"validation_file\": null,\n \"training_file\": \"file-abc123\",\n \"method\": {\n \"type\": \"supervised\",\n \"supervised\": {\n \"hyperparameters\": {\n \"batch_size\": \"auto\",\n \"learning_rate_multiplier\": \"auto\",\n \"n_epochs\": \"auto\",\n }\n }\n },\n \"metadata\": null\n}\n" + }, + { + "title": "Epochs", + "request": { + "curl": "curl https://api.openai.com/v1/fine_tuning/jobs \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -d '{\n \"training_file\": \"file-abc123\",\n \"model\": \"gpt-4o-mini\",\n \"method\": {\n \"type\": \"supervised\",\n \"supervised\": {\n \"hyperparameters\": {\n \"n_epochs\": 2\n }\n }\n }\n }'\n", + "python": "from openai import OpenAI\nfrom openai.types.fine_tuning import SupervisedMethod, SupervisedHyperparameters\n\nclient = OpenAI()\n\nclient.fine_tuning.jobs.create(\n training_file=\"file-abc123\",\n model=\"gpt-4o-mini\",\n method={\n \"type\": \"supervised\",\n \"supervised\": SupervisedMethod(\n hyperparameters=SupervisedHyperparameters(\n n_epochs=2\n )\n )\n }\n)\n", + "javascript": "import OpenAI from \"openai\";\nimport { SupervisedMethod, SupervisedHyperparameters } from \"openai/resources/fine-tuning/methods\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const fineTune = await openai.fineTuning.jobs.create({\n training_file: \"file-abc123\",\n model: \"gpt-4o-mini\",\n method: {\n type: \"supervised\",\n supervised: {\n hyperparameters: {\n n_epochs: 2\n }\n }\n }\n });\n\n console.log(fineTune);\n}\n\nmain();\n" + }, + "response": "{\n \"object\": \"fine_tuning.job\",\n \"id\": \"ftjob-abc123\",\n \"model\": \"gpt-4o-mini\",\n \"created_at\": 1721764800,\n \"fine_tuned_model\": null,\n \"organization_id\": \"org-123\",\n \"result_files\": [],\n \"status\": \"queued\",\n \"validation_file\": null,\n \"training_file\": \"file-abc123\",\n \"hyperparameters\": {\n \"batch_size\": \"auto\",\n \"learning_rate_multiplier\": \"auto\",\n \"n_epochs\": 2\n },\n \"method\": {\n \"type\": \"supervised\",\n \"supervised\": {\n \"hyperparameters\": {\n \"batch_size\": \"auto\",\n \"learning_rate_multiplier\": \"auto\",\n \"n_epochs\": 2\n }\n }\n },\n \"metadata\": null,\n \"error\": {\n \"code\": null,\n \"message\": null,\n \"param\": null\n },\n \"finished_at\": null,\n \"seed\": 683058546,\n \"trained_tokens\": null,\n \"estimated_finish\": null,\n \"integrations\": [],\n \"user_provided_suffix\": null,\n \"usage_metrics\": null,\n \"shared_with_openai\": false\n}\n" + }, + { + "title": "DPO", + "request": { + "curl": "curl https://api.openai.com/v1/fine_tuning/jobs \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -d '{\n \"training_file\": \"file-abc123\",\n \"validation_file\": \"file-abc123\",\n \"model\": \"gpt-4o-mini\",\n \"method\": {\n \"type\": \"dpo\",\n \"dpo\": {\n \"hyperparameters\": {\n \"beta\": 0.1\n }\n }\n }\n }'\n", + "python": "from openai import OpenAI\nfrom openai.types.fine_tuning import DpoMethod, DpoHyperparameters\n\nclient = OpenAI()\n\nclient.fine_tuning.jobs.create(\n training_file=\"file-abc\",\n validation_file=\"file-123\",\n model=\"gpt-4o-mini\",\n method={\n \"type\": \"dpo\",\n \"dpo\": DpoMethod(\n hyperparameters=DpoHyperparameters(beta=0.1)\n )\n }\n)\n" + }, + "response": "{\n \"object\": \"fine_tuning.job\",\n \"id\": \"ftjob-abc\",\n \"model\": \"gpt-4o-mini\",\n \"created_at\": 1746130590,\n \"fine_tuned_model\": null,\n \"organization_id\": \"org-abc\",\n \"result_files\": [],\n \"status\": \"queued\",\n \"validation_file\": \"file-123\",\n \"training_file\": \"file-abc\",\n \"method\": {\n \"type\": \"dpo\",\n \"dpo\": {\n \"hyperparameters\": {\n \"beta\": 0.1,\n \"batch_size\": \"auto\",\n \"learning_rate_multiplier\": \"auto\",\n \"n_epochs\": \"auto\"\n }\n }\n },\n \"metadata\": null,\n \"error\": {\n \"code\": null,\n \"message\": null,\n \"param\": null\n },\n \"finished_at\": null,\n \"hyperparameters\": null,\n \"seed\": 1036326793,\n \"estimated_finish\": null,\n \"integrations\": [],\n \"user_provided_suffix\": null,\n \"usage_metrics\": null,\n \"shared_with_openai\": false\n}\n" + }, + { + "title": "Reinforcement", + "request": { + "curl": "curl https://api.openai.com/v1/fine_tuning/jobs \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -d '{\n \"training_file\": \"file-abc\",\n \"validation_file\": \"file-123\",\n \"model\": \"o4-mini\",\n \"method\": {\n \"type\": \"reinforcement\",\n \"reinforcement\": {\n \"grader\": {\n \"type\": \"string_check\",\n \"name\": \"Example string check grader\",\n \"input\": \"{{sample.output_text}}\",\n \"reference\": \"{{item.label}}\",\n \"operation\": \"eq\"\n },\n \"hyperparameters\": {\n \"reasoning_effort\": \"medium\"\n }\n }\n }\n }'\n", + "python": "from openai import OpenAI\nfrom openai.types.fine_tuning import ReinforcementMethod, ReinforcementHyperparameters\nfrom openai.types.graders import StringCheckGrader\n\nclient = OpenAI()\n\nclient.fine_tuning.jobs.create(\n training_file=\"file-abc\",\n validation_file=\"file-123\",\n model=\"o4-mini\",\n method={\n \"type\": \"reinforcement\",\n \"reinforcement\": ReinforcementMethod(\n grader=StringCheckGrader(\n name=\"Example string check grader\",\n type=\"string_check\",\n input=\"{{item.label}}\",\n operation=\"eq\",\n reference=\"{{sample.output_text}}\"\n ),\n hyperparameters=ReinforcementHyperparameters(\n reasoning_effort=\"medium\",\n )\n )\n }, \n seed=42,\n)\n" + }, + "response": "{\n \"object\": \"fine_tuning.job\",\n \"id\": \"ftjob-abc123\",\n \"model\": \"o4-mini\",\n \"created_at\": 1721764800,\n \"finished_at\": null,\n \"fine_tuned_model\": null,\n \"organization_id\": \"org-123\",\n \"result_files\": [],\n \"status\": \"validating_files\",\n \"validation_file\": \"file-123\",\n \"training_file\": \"file-abc\",\n \"trained_tokens\": null,\n \"error\": {},\n \"user_provided_suffix\": null,\n \"seed\": 950189191,\n \"estimated_finish\": null,\n \"integrations\": [],\n \"method\": {\n \"type\": \"reinforcement\",\n \"reinforcement\": {\n \"hyperparameters\": {\n \"batch_size\": \"auto\",\n \"learning_rate_multiplier\": \"auto\",\n \"n_epochs\": \"auto\",\n \"eval_interval\": \"auto\",\n \"eval_samples\": \"auto\",\n \"compute_multiplier\": \"auto\",\n \"reasoning_effort\": \"medium\"\n },\n \"grader\": {\n \"type\": \"string_check\",\n \"name\": \"Example string check grader\",\n \"input\": \"{{sample.output_text}}\",\n \"reference\": \"{{item.label}}\",\n \"operation\": \"eq\"\n },\n \"response_format\": null\n }\n },\n \"metadata\": null,\n \"usage_metrics\": null,\n \"shared_with_openai\": false\n}\n \n" + }, + { + "title": "Validation file", + "request": { + "curl": "curl https://api.openai.com/v1/fine_tuning/jobs \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -d '{\n \"training_file\": \"file-abc123\",\n \"validation_file\": \"file-abc123\",\n \"model\": \"gpt-4o-mini\"\n }'\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.fine_tuning.jobs.create(\n training_file=\"file-abc123\",\n validation_file=\"file-def456\",\n model=\"gpt-4o-mini\"\n)\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const fineTune = await openai.fineTuning.jobs.create({\n training_file: \"file-abc123\",\n validation_file: \"file-abc123\"\n });\n\n console.log(fineTune);\n}\n\nmain();\n" + }, + "response": "{\n \"object\": \"fine_tuning.job\",\n \"id\": \"ftjob-abc123\",\n \"model\": \"gpt-4o-mini-2024-07-18\",\n \"created_at\": 1721764800,\n \"fine_tuned_model\": null,\n \"organization_id\": \"org-123\",\n \"result_files\": [],\n \"status\": \"queued\",\n \"validation_file\": \"file-abc123\",\n \"training_file\": \"file-abc123\",\n \"method\": {\n \"type\": \"supervised\",\n \"supervised\": {\n \"hyperparameters\": {\n \"batch_size\": \"auto\",\n \"learning_rate_multiplier\": \"auto\",\n \"n_epochs\": \"auto\",\n }\n }\n },\n \"metadata\": null\n}\n" + }, + { + "title": "W&B Integration", + "request": { + "curl": "curl https://api.openai.com/v1/fine_tuning/jobs \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -d '{\n \"training_file\": \"file-abc123\",\n \"validation_file\": \"file-abc123\",\n \"model\": \"gpt-4o-mini\",\n \"integrations\": [\n {\n \"type\": \"wandb\",\n \"wandb\": {\n \"project\": \"my-wandb-project\",\n \"name\": \"ft-run-display-name\"\n \"tags\": [\n \"first-experiment\", \"v2\"\n ]\n }\n }\n ]\n }'\n" + }, + "response": "{\n \"object\": \"fine_tuning.job\",\n \"id\": \"ftjob-abc123\",\n \"model\": \"gpt-4o-mini-2024-07-18\",\n \"created_at\": 1721764800,\n \"fine_tuned_model\": null,\n \"organization_id\": \"org-123\",\n \"result_files\": [],\n \"status\": \"queued\",\n \"validation_file\": \"file-abc123\",\n \"training_file\": \"file-abc123\",\n \"integrations\": [\n {\n \"type\": \"wandb\",\n \"wandb\": {\n \"project\": \"my-wandb-project\",\n \"entity\": None,\n \"run_id\": \"ftjob-abc123\"\n }\n }\n ],\n \"method\": {\n \"type\": \"supervised\",\n \"supervised\": {\n \"hyperparameters\": {\n \"batch_size\": \"auto\",\n \"learning_rate_multiplier\": \"auto\",\n \"n_epochs\": \"auto\",\n }\n }\n },\n \"metadata\": null\n}\n" + } + ] + } + }, + "get": { + "operationId": "listPaginatedFineTuningJobs", + "tags": [ + "Fine-tuning" + ], + "summary": "List your organization's fine-tuning jobs\n", + "parameters": [ + { + "name": "after", + "in": "query", + "description": "Identifier for the last job from the previous pagination request.", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "description": "Number of fine-tuning jobs to retrieve.", + "required": false, + "schema": { + "type": "integer", + "default": 20 + } + }, + { + "in": "query", + "name": "metadata", + "required": false, + "schema": { + "type": "object", + "nullable": true, + "additionalProperties": { + "type": "string" + } + }, + "style": "deepObject", + "explode": true, + "description": "Optional metadata filter. To filter, use the syntax `metadata[k]=v`. Alternatively, set `metadata=null` to indicate no metadata.\n" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListPaginatedFineTuningJobsResponse" + } + } + } + } + }, + "x-oaiMeta": { + "name": "List fine-tuning jobs", + "group": "fine-tuning", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/fine_tuning/jobs?limit=2&metadata[key]=value \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.fine_tuning.jobs.list()\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const list = await openai.fineTuning.jobs.list();\n\n for await (const fineTune of list) {\n console.log(fineTune);\n }\n}\n\nmain();" + }, + "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"fine_tuning.job\",\n \"id\": \"ftjob-abc123\",\n \"model\": \"gpt-4o-mini-2024-07-18\",\n \"created_at\": 1721764800,\n \"fine_tuned_model\": null,\n \"organization_id\": \"org-123\",\n \"result_files\": [],\n \"status\": \"queued\",\n \"validation_file\": null,\n \"training_file\": \"file-abc123\",\n \"metadata\": {\n \"key\": \"value\"\n }\n },\n { ... },\n { ... }\n ], \"has_more\": true\n}\n" + } + } + } + }, + "/fine_tuning/jobs/{fine_tuning_job_id}": { + "get": { + "operationId": "retrieveFineTuningJob", + "tags": [ + "Fine-tuning" + ], + "summary": "Get info about a fine-tuning job.\n\n[Learn more about fine-tuning](https://developers.openai.com/api/docs/guides/model-optimization)\n", + "parameters": [ + { + "in": "path", + "name": "fine_tuning_job_id", + "required": true, + "schema": { + "type": "string", + "example": "ft-AF1WoRqd3aJAHsqc9NY7iL8F" + }, + "description": "The ID of the fine-tuning job.\n" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FineTuningJob" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Retrieve fine-tuning job", + "group": "fine-tuning", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/fine_tuning/jobs/ft-AF1WoRqd3aJAHsqc9NY7iL8F \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.fine_tuning.jobs.retrieve(\"ftjob-abc123\")\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const fineTune = await openai.fineTuning.jobs.retrieve(\"ftjob-abc123\");\n\n console.log(fineTune);\n}\n\nmain();\n" + }, + "response": "{\n \"object\": \"fine_tuning.job\",\n \"id\": \"ftjob-abc123\",\n \"model\": \"davinci-002\",\n \"created_at\": 1692661014,\n \"finished_at\": 1692661190,\n \"fine_tuned_model\": \"ft:davinci-002:my-org:custom_suffix:7q8mpxmy\",\n \"organization_id\": \"org-123\",\n \"result_files\": [\n \"file-abc123\"\n ],\n \"status\": \"succeeded\",\n \"validation_file\": null,\n \"training_file\": \"file-abc123\",\n \"hyperparameters\": {\n \"n_epochs\": 4,\n \"batch_size\": 1,\n \"learning_rate_multiplier\": 1.0\n },\n \"trained_tokens\": 5768,\n \"integrations\": [],\n \"seed\": 0,\n \"estimated_finish\": 0,\n \"method\": {\n \"type\": \"supervised\",\n \"supervised\": {\n \"hyperparameters\": {\n \"n_epochs\": 4,\n \"batch_size\": 1,\n \"learning_rate_multiplier\": 1.0\n }\n }\n }\n}\n" + } + } + } + }, + "/fine_tuning/jobs/{fine_tuning_job_id}/cancel": { + "post": { + "operationId": "cancelFineTuningJob", + "tags": [ + "Fine-tuning" + ], + "summary": "Immediately cancel a fine-tune job.\n", + "parameters": [ + { + "in": "path", + "name": "fine_tuning_job_id", + "required": true, + "schema": { + "type": "string", + "example": "ft-AF1WoRqd3aJAHsqc9NY7iL8F" + }, + "description": "The ID of the fine-tuning job to cancel.\n" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FineTuningJob" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Cancel fine-tuning", + "group": "fine-tuning", + "examples": { + "request": { + "curl": "curl -X POST https://api.openai.com/v1/fine_tuning/jobs/ftjob-abc123/cancel \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.fine_tuning.jobs.cancel(\"ftjob-abc123\")\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const fineTune = await openai.fineTuning.jobs.cancel(\"ftjob-abc123\");\n\n console.log(fineTune);\n}\nmain();" + }, + "response": "{\n \"object\": \"fine_tuning.job\",\n \"id\": \"ftjob-abc123\",\n \"model\": \"gpt-4o-mini-2024-07-18\",\n \"created_at\": 1721764800,\n \"fine_tuned_model\": null,\n \"organization_id\": \"org-123\",\n \"result_files\": [],\n \"status\": \"cancelled\",\n \"validation_file\": \"file-abc123\",\n \"training_file\": \"file-abc123\"\n}\n" + } + } + } + }, + "/fine_tuning/jobs/{fine_tuning_job_id}/checkpoints": { + "get": { + "operationId": "listFineTuningJobCheckpoints", + "tags": [ + "Fine-tuning" + ], + "summary": "List checkpoints for a fine-tuning job.\n", + "parameters": [ + { + "in": "path", + "name": "fine_tuning_job_id", + "required": true, + "schema": { + "type": "string", + "example": "ft-AF1WoRqd3aJAHsqc9NY7iL8F" + }, + "description": "The ID of the fine-tuning job to get checkpoints for.\n" + }, + { + "name": "after", + "in": "query", + "description": "Identifier for the last checkpoint ID from the previous pagination request.", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "description": "Number of checkpoints to retrieve.", + "required": false, + "schema": { + "type": "integer", + "default": 10 + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListFineTuningJobCheckpointsResponse" + } + } + } + } + }, + "x-oaiMeta": { + "name": "List fine-tuning checkpoints", + "group": "fine-tuning", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/fine_tuning/jobs/ftjob-abc123/checkpoints \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n" + }, + "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"fine_tuning.job.checkpoint\",\n \"id\": \"ftckpt_zc4Q7MP6XxulcVzj4MZdwsAB\",\n \"created_at\": 1721764867,\n \"fine_tuned_model_checkpoint\": \"ft:gpt-4o-mini-2024-07-18:my-org:custom-suffix:96olL566:ckpt-step-2000\",\n \"metrics\": {\n \"full_valid_loss\": 0.134,\n \"full_valid_mean_token_accuracy\": 0.874\n },\n \"fine_tuning_job_id\": \"ftjob-abc123\",\n \"step_number\": 2000\n },\n {\n \"object\": \"fine_tuning.job.checkpoint\",\n \"id\": \"ftckpt_enQCFmOTGj3syEpYVhBRLTSy\",\n \"created_at\": 1721764800,\n \"fine_tuned_model_checkpoint\": \"ft:gpt-4o-mini-2024-07-18:my-org:custom-suffix:7q8mpxmy:ckpt-step-1000\",\n \"metrics\": {\n \"full_valid_loss\": 0.167,\n \"full_valid_mean_token_accuracy\": 0.781\n },\n \"fine_tuning_job_id\": \"ftjob-abc123\",\n \"step_number\": 1000\n }\n ],\n \"first_id\": \"ftckpt_zc4Q7MP6XxulcVzj4MZdwsAB\",\n \"last_id\": \"ftckpt_enQCFmOTGj3syEpYVhBRLTSy\",\n \"has_more\": true\n}\n" + } + } + } + }, + "/fine_tuning/jobs/{fine_tuning_job_id}/events": { + "get": { + "operationId": "listFineTuningEvents", + "tags": [ + "Fine-tuning" + ], + "summary": "Get status updates for a fine-tuning job.\n", + "parameters": [ + { + "in": "path", + "name": "fine_tuning_job_id", + "required": true, + "schema": { + "type": "string", + "example": "ft-AF1WoRqd3aJAHsqc9NY7iL8F" + }, + "description": "The ID of the fine-tuning job to get events for.\n" + }, + { + "name": "after", + "in": "query", + "description": "Identifier for the last event from the previous pagination request.", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "description": "Number of events to retrieve.", + "required": false, + "schema": { + "type": "integer", + "default": 20 + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListFineTuningJobEventsResponse" + } + } + } + } + }, + "x-oaiMeta": { + "name": "List fine-tuning events", + "group": "fine-tuning", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/fine_tuning/jobs/ftjob-abc123/events \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.fine_tuning.jobs.list_events(\n fine_tuning_job_id=\"ftjob-abc123\",\n limit=2\n)\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const list = await openai.fineTuning.list_events(id=\"ftjob-abc123\", limit=2);\n\n for await (const fineTune of list) {\n console.log(fineTune);\n }\n}\n\nmain();" + }, + "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"fine_tuning.job.event\",\n \"id\": \"ft-event-ddTJfwuMVpfLXseO0Am0Gqjm\",\n \"created_at\": 1721764800,\n \"level\": \"info\",\n \"message\": \"Fine tuning job successfully completed\",\n \"data\": null,\n \"type\": \"message\"\n },\n {\n \"object\": \"fine_tuning.job.event\",\n \"id\": \"ft-event-tyiGuB72evQncpH87xe505Sv\",\n \"created_at\": 1721764800,\n \"level\": \"info\",\n \"message\": \"New fine-tuned model created: ft:gpt-4o-mini:openai::7p4lURel\",\n \"data\": null,\n \"type\": \"message\"\n }\n ],\n \"has_more\": true\n}\n" + } + } + } + }, + "/fine_tuning/jobs/{fine_tuning_job_id}/pause": { + "post": { + "operationId": "pauseFineTuningJob", + "tags": [ + "Fine-tuning" + ], + "summary": "Pause a fine-tune job.\n", + "parameters": [ + { + "in": "path", + "name": "fine_tuning_job_id", + "required": true, + "schema": { + "type": "string", + "example": "ft-AF1WoRqd3aJAHsqc9NY7iL8F" + }, + "description": "The ID of the fine-tuning job to pause.\n" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FineTuningJob" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Pause fine-tuning", + "group": "fine-tuning", + "examples": { + "request": { + "curl": "curl -X POST https://api.openai.com/v1/fine_tuning/jobs/ftjob-abc123/pause \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.fine_tuning.jobs.pause(\"ftjob-abc123\")\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const fineTune = await openai.fineTuning.jobs.pause(\"ftjob-abc123\");\n\n console.log(fineTune);\n}\nmain();" + }, + "response": "{\n \"object\": \"fine_tuning.job\",\n \"id\": \"ftjob-abc123\",\n \"model\": \"gpt-4o-mini-2024-07-18\",\n \"created_at\": 1721764800,\n \"fine_tuned_model\": null,\n \"organization_id\": \"org-123\",\n \"result_files\": [],\n \"status\": \"paused\",\n \"validation_file\": \"file-abc123\",\n \"training_file\": \"file-abc123\"\n}\n" + } + } + } + }, + "/fine_tuning/jobs/{fine_tuning_job_id}/resume": { + "post": { + "operationId": "resumeFineTuningJob", + "tags": [ + "Fine-tuning" + ], + "summary": "Resume a fine-tune job.\n", + "parameters": [ + { + "in": "path", + "name": "fine_tuning_job_id", + "required": true, + "schema": { + "type": "string", + "example": "ft-AF1WoRqd3aJAHsqc9NY7iL8F" + }, + "description": "The ID of the fine-tuning job to resume.\n" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FineTuningJob" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Resume fine-tuning", + "group": "fine-tuning", + "examples": { + "request": { + "curl": "curl -X POST https://api.openai.com/v1/fine_tuning/jobs/ftjob-abc123/resume \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.fine_tuning.jobs.resume(\"ftjob-abc123\")\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const fineTune = await openai.fineTuning.jobs.resume(\"ftjob-abc123\");\n\n console.log(fineTune);\n}\nmain();" + }, + "response": "{\n \"object\": \"fine_tuning.job\",\n \"id\": \"ftjob-abc123\",\n \"model\": \"gpt-4o-mini-2024-07-18\",\n \"created_at\": 1721764800,\n \"fine_tuned_model\": null,\n \"organization_id\": \"org-123\",\n \"result_files\": [],\n \"status\": \"queued\",\n \"validation_file\": \"file-abc123\",\n \"training_file\": \"file-abc123\"\n}\n" + } + } + } + }, + "/images/edits": { + "post": { + "operationId": "createImageEdit", + "tags": [ + "Images" + ], + "summary": "Creates an edited or extended image given one or more source images and a prompt. This endpoint supports GPT Image models and `dall-e-2`.", + "description": "You can call this endpoint with either:\n\n- `multipart/form-data`: use binary uploads via `image` (and optional `mask`).\n- `application/json`: use `images` (and optional `mask`) as references with either `image_url` or `file_id`.\n\nNote that JSON requests use `images` (array) instead of the multipart `image` field.\n", + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "$ref": "#/components/schemas/CreateImageEditRequest" + }, + "examples": { + "multipart_edit": { + "summary": "Multipart form upload (binary image + prompt)", + "value": { + "model": "gpt-image-1.5", + "prompt": "Add a watercolor effect to this image", + "image": "", + "size": "1024x1024", + "quality": "high" + } + } + } + }, + "application/json": { + "schema": { + "$ref": "#/components/schemas/EditImageBodyJsonParam" + }, + "examples": { + "json_with_url": { + "summary": "JSON request with image URL", + "value": { + "model": "gpt-image-1.5", + "prompt": "Add a watercolor effect to this image", + "images": [ + { + "image_url": "https://example.com/source-image.png" + } + ], + "size": "1024x1024", + "quality": "high" + } + }, + "json_with_file_id": { + "summary": "JSON request with uploaded file id", + "value": { + "model": "gpt-image-1.5", + "prompt": "Replace the background with a snowy mountain scene", + "images": [ + { + "file_id": "file-abc123" + } + ], + "mask": { + "file_id": "file-mask123" + }, + "output_format": "png", + "output_compression": 100 + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ImagesResponse" + } + }, + "text/event-stream": { + "schema": { + "$ref": "#/components/schemas/ImageEditStreamEvent" + } + } + } + }, + "429": { + "$ref": "#/components/responses/InferenceRateLimited" + }, + "503": { + "$ref": "#/components/responses/InferenceServiceUnavailable" + } + }, + "x-oaiMeta": { + "name": "Create image edit", + "group": "images", + "examples": [ + { + "title": "Edit image", + "request": { + "curl": "curl -s -D >(grep -i x-request-id >&2) \\\n -o >(jq -r '.data[0].b64_json' | base64 --decode > gift-basket.png) \\\n -X POST \"https://api.openai.com/v1/images/edits\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -F \"model=gpt-image-1.5\" \\\n -F \"image[]=@body-lotion.png\" \\\n -F \"image[]=@bath-bomb.png\" \\\n -F \"image[]=@incense-kit.png\" \\\n -F \"image[]=@soap.png\" \\\n -F 'prompt=Create a lovely gift basket with these four items in it'\n", + "python": "import base64\nfrom openai import OpenAI\nclient = OpenAI()\n\nprompt = \"\"\"\nGenerate a photorealistic image of a gift basket on a white background\nlabeled 'Relax & Unwind' with a ribbon and handwriting-like font,\ncontaining all the items in the reference pictures.\n\"\"\"\n\nresult = client.images.edit(\n model=\"gpt-image-1.5\",\n image=[\n open(\"body-lotion.png\", \"rb\"),\n open(\"bath-bomb.png\", \"rb\"),\n open(\"incense-kit.png\", \"rb\"),\n open(\"soap.png\", \"rb\"),\n ],\n prompt=prompt\n)\n\nimage_base64 = result.data[0].b64_json\nimage_bytes = base64.b64decode(image_base64)\n\n# Save the image to a file\nwith open(\"gift-basket.png\", \"wb\") as f:\n f.write(image_bytes)\n", + "javascript": "import fs from \"fs\";\nimport OpenAI, { toFile } from \"openai\";\n\nconst client = new OpenAI();\n\nconst imageFiles = [\n \"bath-bomb.png\",\n \"body-lotion.png\",\n \"incense-kit.png\",\n \"soap.png\",\n];\n\nconst images = await Promise.all(\n imageFiles.map(async (file) =>\n await toFile(fs.createReadStream(file), null, {\n type: \"image/png\",\n })\n ),\n);\n\nconst rsp = await client.images.edit({\n model: \"gpt-image-1.5\",\n image: images,\n prompt: \"Create a lovely gift basket with these four items in it\",\n});\n\n// Save the image to a file\nconst image_base64 = rsp.data[0].b64_json;\nconst image_bytes = Buffer.from(image_base64, \"base64\");\nfs.writeFileSync(\"basket.png\", image_bytes);\n" + } + }, + { + "title": "Streaming", + "request": { + "curl": "curl -s -N -X POST \"https://api.openai.com/v1/images/edits\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -F \"model=gpt-image-1.5\" \\\n -F \"image[]=@body-lotion.png\" \\\n -F \"image[]=@bath-bomb.png\" \\\n -F \"image[]=@incense-kit.png\" \\\n -F \"image[]=@soap.png\" \\\n -F 'prompt=Create a lovely gift basket with these four items in it' \\\n -F \"stream=true\"\n", + "python": "from openai import OpenAI\n\nclient = OpenAI()\n\nprompt = \"\"\"\nGenerate a photorealistic image of a gift basket on a white background\nlabeled 'Relax & Unwind' with a ribbon and handwriting-like font,\ncontaining all the items in the reference pictures.\n\"\"\"\n\nstream = client.images.edit(\n model=\"gpt-image-1.5\",\n image=[\n open(\"body-lotion.png\", \"rb\"),\n open(\"bath-bomb.png\", \"rb\"),\n open(\"incense-kit.png\", \"rb\"),\n open(\"soap.png\", \"rb\"),\n ],\n prompt=prompt,\n stream=True\n)\n\nfor event in stream:\n print(event)\n", + "javascript": "import fs from \"fs\";\nimport OpenAI, { toFile } from \"openai\";\n\nconst client = new OpenAI();\n\nconst imageFiles = [\n \"bath-bomb.png\",\n \"body-lotion.png\",\n \"incense-kit.png\",\n \"soap.png\",\n];\n\nconst images = await Promise.all(\n imageFiles.map(async (file) =>\n await toFile(fs.createReadStream(file), null, {\n type: \"image/png\",\n })\n ),\n);\n\nconst stream = await client.images.edit({\n model: \"gpt-image-1.5\",\n image: images,\n prompt: \"Create a lovely gift basket with these four items in it\",\n stream: true,\n});\n\nfor await (const event of stream) {\n console.log(event);\n}\n" + }, + "response": "event: image_edit.partial_image\ndata: {\"type\":\"image_edit.partial_image\",\"b64_json\":\"...\",\"partial_image_index\":0}\n\nevent: image_edit.completed\ndata: {\"type\":\"image_edit.completed\",\"b64_json\":\"...\",\"usage\":{\"total_tokens\":100,\"input_tokens\":50,\"output_tokens\":50,\"input_tokens_details\":{\"text_tokens\":10,\"image_tokens\":40}}}\n" + } + ] + } + } + }, + "/images/generations": { + "post": { + "operationId": "createImage", + "tags": [ + "Images" + ], + "summary": "Creates an image given a prompt. [Learn more](https://developers.openai.com/api/docs/guides/images-vision).\n", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateImageRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ImagesResponse" + } + }, + "text/event-stream": { + "schema": { + "$ref": "#/components/schemas/ImageGenStreamEvent" + } + } + } + }, + "429": { + "$ref": "#/components/responses/InferenceRateLimited" + }, + "503": { + "$ref": "#/components/responses/InferenceServiceUnavailable" + } + }, + "x-oaiMeta": { + "name": "Create image", + "group": "images", + "examples": [ + { + "title": "Generate image", + "request": { + "curl": "curl https://api.openai.com/v1/images/generations \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -d '{\n \"model\": \"gpt-image-1.5\",\n \"prompt\": \"A cute baby sea otter\",\n \"n\": 1,\n \"size\": \"1024x1024\"\n }'\n", + "python": "import base64\nfrom openai import OpenAI\nclient = OpenAI()\n\nimg = client.images.generate(\n model=\"gpt-image-1.5\",\n prompt=\"A cute baby sea otter\",\n n=1,\n size=\"1024x1024\"\n)\n\nimage_bytes = base64.b64decode(img.data[0].b64_json)\nwith open(\"output.png\", \"wb\") as f:\n f.write(image_bytes)\n", + "javascript": "import OpenAI from \"openai\";\nimport { writeFile } from \"fs/promises\";\n\nconst client = new OpenAI();\n\nconst img = await client.images.generate({\n model: \"gpt-image-1.5\",\n prompt: \"A cute baby sea otter\",\n n: 1,\n size: \"1024x1024\"\n});\n\nconst imageBuffer = Buffer.from(img.data[0].b64_json, \"base64\");\nawait writeFile(\"output.png\", imageBuffer);\n" + }, + "response": "{\n \"created\": 1713833628,\n \"data\": [\n {\n \"b64_json\": \"...\"\n }\n ],\n \"usage\": {\n \"total_tokens\": 100,\n \"input_tokens\": 50,\n \"output_tokens\": 50,\n \"input_tokens_details\": {\n \"text_tokens\": 10,\n \"image_tokens\": 40\n }\n }\n}\n" + }, + { + "title": "Streaming", + "request": { + "curl": "curl https://api.openai.com/v1/images/generations \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -d '{\n \"model\": \"gpt-image-1.5\",\n \"prompt\": \"A cute baby sea otter\",\n \"n\": 1,\n \"size\": \"1024x1024\",\n \"stream\": true\n }' \\\n --no-buffer\n", + "python": "from openai import OpenAI\n\nclient = OpenAI()\n\nstream = client.images.generate(\n model=\"gpt-image-1.5\",\n prompt=\"A cute baby sea otter\",\n n=1,\n size=\"1024x1024\",\n stream=True\n)\n\nfor event in stream:\n print(event)\n", + "javascript": "import OpenAI from \"openai\";\n\nconst client = new OpenAI();\n\nconst stream = await client.images.generate({\n model: \"gpt-image-1.5\",\n prompt: \"A cute baby sea otter\",\n n: 1,\n size: \"1024x1024\",\n stream: true,\n});\n\nfor await (const event of stream) {\n console.log(event);\n}\n" + }, + "response": "event: image_generation.partial_image\ndata: {\"type\":\"image_generation.partial_image\",\"b64_json\":\"...\",\"partial_image_index\":0}\n\nevent: image_generation.completed\ndata: {\"type\":\"image_generation.completed\",\"b64_json\":\"...\",\"usage\":{\"total_tokens\":100,\"input_tokens\":50,\"output_tokens\":50,\"input_tokens_details\":{\"text_tokens\":10,\"image_tokens\":40}}}\n" + } + ] + } + } + }, + "/images/variations": { + "post": { + "operationId": "createImageVariation", + "tags": [ + "Images" + ], + "summary": "Creates a variation of a given image. This endpoint only supports `dall-e-2`.", + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "$ref": "#/components/schemas/CreateImageVariationRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ImagesResponse" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Create image variation", + "group": "images", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/images/variations \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -F image=\"@otter.png\" \\\n -F n=2 \\\n -F size=\"1024x1024\"\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\nresponse = client.images.create_variation(\n image=open(\"image_edit_original.png\", \"rb\"),\n n=2,\n size=\"1024x1024\"\n)\n", + "javascript": "import fs from \"fs\";\nimport OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const image = await openai.images.createVariation({\n image: fs.createReadStream(\"otter.png\"),\n });\n\n console.log(image.data);\n}\nmain();", + "csharp": "using System;\n\nusing OpenAI.Images;\n\nImageClient client = new(\n model: \"dall-e-2\",\n apiKey: Environment.GetEnvironmentVariable(\"OPENAI_API_KEY\")\n);\n\nGeneratedImage image = client.GenerateImageVariation(imageFilePath: \"otter.png\");\n\nConsole.WriteLine(image.ImageUri);\n" + }, + "response": "{\n \"created\": 1589478378,\n \"data\": [\n {\n \"url\": \"https://...\"\n },\n {\n \"url\": \"https://...\"\n }\n ]\n}\n" + } + } + } + }, + "/live/sessions": { + "post": { + "operationId": "create-live", + "summary": "Create a Live WebRTC session. Start with the [Live prompting guide](https://developers.openai.com/api/docs/guides/live-prompting).", + "description": "Send JSON containing session configuration and transport with type webrtc and the SDP offer. The request starts the session. Apply transport.sdp from the response as the remote answer and wait for session.started on the data channel before sending commands. Audio uses the negotiated media track; omit audio.format and do not send session.start on the data channel. Before integrating, follow the [Live prompting guide](https://developers.openai.com/api/docs/guides/live-prompting) to write frontend conversation and delegation instructions and a separate backend prompt.", + "tags": [ + "Live" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LiveCreateRequest" + } + } + } + }, + "responses": { + "201": { + "description": "Live session created with a WebRTC answer.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LiveCreateResponse" + }, + "example": { + "session": { + "id": "live_123" + }, + "transport": { + "type": "webrtc", + "sdp": "" + } + } + } + } + } + }, + "x-oaiMeta": { + "name": "Create session", + "group": "live", + "returns": "Returns 201 Created with the session identifier in session.id and SDP answer in transport.sdp.", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/live/sessions \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"session\":{\"model\":\"gpt-live-1\",\"instructions\":\"Be concise. Ask for clarification when needed.\"},\"transport\":{\"type\":\"webrtc\",\"sdp\":\"\"}}'" + } + } + } + } + }, + "/live/sessions/{session_id}/accept": { + "post": { + "operationId": "accept-live-session", + "summary": "Accept an incoming SIP call. Supply session with type live, the model, and startup configuration. Before accepting calls, follow the [Live prompting guide](https://developers.openai.com/api/docs/guides/live-prompting) to write frontend conversation instructions and a separate backend prompt. SIP media format is negotiated; omit audio.format.", + "description": "Accept an incoming SIP call. Supply session with type live, the model, and startup configuration. Before accepting calls, follow the [Live prompting guide](https://developers.openai.com/api/docs/guides/live-prompting) to write frontend conversation instructions and a separate backend prompt. SIP media format is negotiated; omit audio.format.", + "tags": [ + "Live" + ], + "parameters": [ + { + "in": "path", + "name": "session_id", + "required": true, + "description": "Opaque Live session identifier from the creation response or incoming-call webhook. Preserve the returned value unchanged, including its prefix.", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LiveCallAcceptRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Session accept request accepted." + } + }, + "x-oaiMeta": { + "name": "Accept call", + "group": "live-sessions", + "returns": "Returns 200 OK when the control request succeeds." + } + } + }, + "/live/sessions/{session_id}/fork": { + "post": { + "operationId": "fork-live-session", + "summary": "Fork a stored Live session onto a new WebRTC connection.", + "description": "Resume the stored conversation using a new WebRTC connection. The model, voice, and frontend instructions are inherited. Omit session or send an empty object to inherit the remaining configuration. Only Responses delegation settings, storage, and frontend data-channel permissions can be overridden. Apply transport.sdp as the remote answer and wait for session.started before sending commands. Do not send session.start on the data channel or supply audio.format; WebRTC negotiates its media format.", + "tags": [ + "Live" + ], + "parameters": [ + { + "in": "path", + "name": "session_id", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the stored Live session to fork." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LiveForkRequest" + } + } + } + }, + "responses": { + "201": { + "description": "Forked Live session created with a WebRTC answer.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LiveCreateResponse" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Fork session", + "group": "live", + "returns": "The new session identifier in session.id and SDP answer in transport.sdp.", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/live/sessions/live_123/fork \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"session\":{},\"transport\":{\"type\":\"webrtc\",\"sdp\":\"\"}}'" + } + } + } + } + }, + "/live/sessions/{session_id}/hangup": { + "post": { + "operationId": "hangup-live-session", + "summary": "End a SIP call identified by session_id.", + "description": "End a SIP call identified by session_id.", + "tags": [ + "Live" + ], + "parameters": [ + { + "in": "path", + "name": "session_id", + "required": true, + "description": "Opaque Live session identifier from the creation response or incoming-call webhook. Preserve the returned value unchanged, including its prefix.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Session hangup request accepted." + } + }, + "x-oaiMeta": { + "name": "Hang up session", + "group": "live-sessions", + "returns": "Returns 200 OK when the control request succeeds." + } + } + }, + "/live/sessions/{session_id}/refer": { + "post": { + "operationId": "refer-live-session", + "summary": "Transfer a SIP call to another destination. Supply a nonblank target_uri for the SIP Refer-To header.", + "description": "Transfer a SIP call to another destination. Supply a nonblank target_uri for the SIP Refer-To header.", + "tags": [ + "Live" + ], + "parameters": [ + { + "in": "path", + "name": "session_id", + "required": true, + "description": "Opaque Live session identifier from the creation response or incoming-call webhook. Preserve the returned value unchanged, including its prefix.", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LiveCallReferRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Session refer request accepted." + } + }, + "x-oaiMeta": { + "name": "Transfer call", + "group": "live-sessions", + "returns": "Returns 200 OK when the control request succeeds." + } + } + }, + "/live/sessions/{session_id}/reject": { + "post": { + "operationId": "reject-live-session", + "summary": "Reject an incoming SIP call. Send a required SIP rejection status_code between 300 and 699.", + "description": "Reject an incoming SIP call. Send a required SIP rejection status_code between 300 and 699.", + "tags": [ + "Live" + ], + "parameters": [ + { + "in": "path", + "name": "session_id", + "required": true, + "description": "Opaque Live session identifier from the creation response or incoming-call webhook. Preserve the returned value unchanged, including its prefix.", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LiveCallRejectRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Session reject request accepted." + } + }, + "x-oaiMeta": { + "name": "Reject call", + "group": "live-sessions", + "returns": "Returns 200 OK when the control request succeeds." + } + } + }, + "/models": { + "get": { + "operationId": "listModels", + "tags": [ + "Models" + ], + "summary": "Lists the currently available models, and provides basic information about each one such as the owner and availability.", + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListModelsResponse" + } + } + } + } + }, + "x-oaiMeta": { + "name": "List models", + "group": "models", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/models \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.models.list()\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const list = await openai.models.list();\n\n for await (const model of list) {\n console.log(model);\n }\n}\nmain();", + "csharp": "using System;\n\nusing OpenAI.Models;\n\nOpenAIModelClient client = new(\n apiKey: Environment.GetEnvironmentVariable(\"OPENAI_API_KEY\")\n);\n\nforeach (var model in client.GetModels().Value)\n{\n Console.WriteLine(model.Id);\n}\n" + }, + "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"model-id-0\",\n \"object\": \"model\",\n \"created\": 1686935002,\n \"owned_by\": \"organization-owner\",\n \"shutdown_date\": null\n },\n {\n \"id\": \"model-id-1\",\n \"object\": \"model\",\n \"created\": 1686935002,\n \"owned_by\": \"organization-owner\",\n \"shutdown_date\": null\n },\n {\n \"id\": \"model-id-2\",\n \"object\": \"model\",\n \"created\": 1686935002,\n \"owned_by\": \"openai\",\n \"shutdown_date\": \"2026-10-23\"\n },\n ]\n}\n" + } + } + } + }, + "/models/{model}": { + "get": { + "operationId": "retrieveModel", + "tags": [ + "Models" + ], + "summary": "Retrieves a model instance, providing basic information about the model such as the owner and permissioning.", + "parameters": [ + { + "in": "path", + "name": "model", + "required": true, + "schema": { + "type": "string", + "example": "gpt-6-astra" + }, + "description": "The ID of the model to use for this request" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Model" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Retrieve model", + "group": "models", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/models/gpt-6-astra \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.models.retrieve(\"gpt-6-astra\")\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const model = await openai.models.retrieve(\"gpt-6-astra\");\n\n console.log(model);\n}\n\nmain();", + "csharp": "using System;\nusing System.ClientModel;\n\nusing OpenAI.Models;\n\n OpenAIModelClient client = new(\n apiKey: Environment.GetEnvironmentVariable(\"OPENAI_API_KEY\")\n);\n\nClientResult model = client.GetModel(\"babbage-002\");\nConsole.WriteLine(model.Value.Id);\n" + }, + "response": "{\n \"id\": \"gpt-6-astra\",\n \"object\": \"model\",\n \"created\": 1686935002,\n \"owned_by\": \"openai\",\n \"shutdown_date\": \"2026-10-23\"\n}\n" + } + } + }, + "delete": { + "operationId": "deleteModel", + "tags": [ + "Models" + ], + "summary": "Delete a fine-tuned model. You must have the Owner role in your organization to delete a model.", + "parameters": [ + { + "in": "path", + "name": "model", + "required": true, + "schema": { + "type": "string", + "example": "ft:gpt-4o-mini:acemeco:suffix:abc123" + }, + "description": "The model to delete" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeleteModelResponse" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Delete a fine-tuned model", + "group": "models", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/models/ft:gpt-4o-mini:acemeco:suffix:abc123 \\\n -X DELETE \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.models.delete(\"ft:gpt-4o-mini:acemeco:suffix:abc123\")\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const model = await openai.models.delete(\"ft:gpt-4o-mini:acemeco:suffix:abc123\");\n \n console.log(model);\n}\nmain();", + "csharp": "using System;\nusing System.ClientModel;\n\nusing OpenAI.Models;\n\nOpenAIModelClient client = new(\n apiKey: Environment.GetEnvironmentVariable(\"OPENAI_API_KEY\")\n);\n\nClientResult success = client.DeleteModel(\"ft:gpt-4o-mini:acemeco:suffix:abc123\");\nConsole.WriteLine(success);\n" + }, + "response": "{\n \"id\": \"ft:gpt-4o-mini:acemeco:suffix:abc123\",\n \"object\": \"model\",\n \"deleted\": true\n}\n" + } + } + } + }, + "/moderations": { + "post": { + "operationId": "createModeration", + "tags": [ + "Moderations" + ], + "summary": "Classifies if text and/or image inputs are potentially harmful. Learn\nmore in the [moderation guide](https://developers.openai.com/api/docs/guides/moderation).\n", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateModerationRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateModerationResponse" + } + } + } + }, + "429": { + "$ref": "#/components/responses/InferenceRateLimited" + }, + "503": { + "$ref": "#/components/responses/InferenceServiceUnavailable" + } + }, + "x-oaiMeta": { + "name": "Create moderation", + "group": "moderations", + "examples": [ + { + "title": "Single string", + "request": { + "curl": "curl https://api.openai.com/v1/moderations \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -d '{\n \"input\": \"I want to kill them.\"\n }'\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\nmoderation = client.moderations.create(input=\"I want to kill them.\")\nprint(moderation)\n", + "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const moderation = await openai.moderations.create({ input: \"I want to kill them.\" });\n\n console.log(moderation);\n}\nmain();\n", + "csharp": "using System;\nusing System.ClientModel;\n\nusing OpenAI.Moderations;\n\nModerationClient client = new(\n model: \"omni-moderation-latest\",\n apiKey: Environment.GetEnvironmentVariable(\"OPENAI_API_KEY\")\n);\n\nClientResult moderation = client.ClassifyText(\"I want to kill them.\");\n" + }, + "response": "{\n \"id\": \"modr-AB8CjOTu2jiq12hp1AQPfeqFWaORR\",\n \"model\": \"text-moderation-007\",\n \"results\": [\n {\n \"flagged\": true,\n \"categories\": {\n \"sexual\": false,\n \"hate\": false,\n \"harassment\": true,\n \"self-harm\": false,\n \"sexual/minors\": false,\n \"hate/threatening\": false,\n \"violence/graphic\": false,\n \"self-harm/intent\": false,\n \"self-harm/instructions\": false,\n \"harassment/threatening\": true,\n \"violence\": true\n },\n \"category_scores\": {\n \"sexual\": 0.000011726012417057063,\n \"hate\": 0.22706663608551025,\n \"harassment\": 0.5215635299682617,\n \"self-harm\": 2.227119921371923e-6,\n \"sexual/minors\": 7.107352217872176e-8,\n \"hate/threatening\": 0.023547329008579254,\n \"violence/graphic\": 0.00003391829886822961,\n \"self-harm/intent\": 1.646940972932498e-6,\n \"self-harm/instructions\": 1.1198755256458526e-9,\n \"harassment/threatening\": 0.5694745779037476,\n \"violence\": 0.9971134662628174\n }\n }\n ]\n}\n" + }, + { + "title": "Image and text", + "request": { + "curl": "curl https://api.openai.com/v1/moderations \\\n -X POST \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -d '{\n \"model\": \"omni-moderation-latest\",\n \"input\": [\n { \"type\": \"text\", \"text\": \"...text to classify goes here...\" },\n {\n \"type\": \"image_url\",\n \"image_url\": {\n \"url\": \"https://example.com/image.png\"\n }\n }\n ]\n }'\n", + "python": "from openai import OpenAI\nclient = OpenAI()\n\nresponse = client.moderations.create(\n model=\"omni-moderation-latest\",\n input=[\n {\"type\": \"text\", \"text\": \"...text to classify goes here...\"},\n {\n \"type\": \"image_url\",\n \"image_url\": {\n \"url\": \"https://example.com/image.png\",\n # can also use base64 encoded image URLs\n # \"url\": \"data:image/jpeg;base64,abcdefg...\"\n }\n },\n ],\n)\n\nprint(response)\n", + "javascript": "import OpenAI from \"openai\";\nconst openai = new OpenAI();\n\nconst moderation = await openai.moderations.create({\n model: \"omni-moderation-latest\",\n input: [\n { type: \"text\", text: \"...text to classify goes here...\" },\n {\n type: \"image_url\",\n image_url: {\n url: \"https://example.com/image.png\"\n // can also use base64 encoded image URLs\n // url: \"data:image/jpeg;base64,abcdefg...\"\n }\n }\n ],\n});\n\nconsole.log(moderation);\n" + }, + "response": "{\n \"id\": \"modr-0d9740456c391e43c445bf0f010940c7\",\n \"model\": \"omni-moderation-latest\",\n \"results\": [\n {\n \"flagged\": true,\n \"categories\": {\n \"harassment\": true,\n \"harassment/threatening\": true,\n \"sexual\": false,\n \"hate\": false,\n \"hate/threatening\": false,\n \"illicit\": false,\n \"illicit/violent\": false,\n \"self-harm/intent\": false,\n \"self-harm/instructions\": false,\n \"self-harm\": false,\n \"sexual/minors\": false,\n \"violence\": true,\n \"violence/graphic\": true\n },\n \"category_scores\": {\n \"harassment\": 0.8189693396524255,\n \"harassment/threatening\": 0.804985420696006,\n \"sexual\": 1.573112165348997e-6,\n \"hate\": 0.007562942636942845,\n \"hate/threatening\": 0.004208854591835476,\n \"illicit\": 0.030535955153511665,\n \"illicit/violent\": 0.008925306722380033,\n \"self-harm/intent\": 0.00023023930975076432,\n \"self-harm/instructions\": 0.0002293869201073356,\n \"self-harm\": 0.012598046106750154,\n \"sexual/minors\": 2.212566909570261e-8,\n \"violence\": 0.9999992735124786,\n \"violence/graphic\": 0.843064871157054\n },\n \"category_applied_input_types\": {\n \"harassment\": [\n \"text\"\n ],\n \"harassment/threatening\": [\n \"text\"\n ],\n \"sexual\": [\n \"text\",\n \"image\"\n ],\n \"hate\": [\n \"text\"\n ],\n \"hate/threatening\": [\n \"text\"\n ],\n \"illicit\": [\n \"text\"\n ],\n \"illicit/violent\": [\n \"text\"\n ],\n \"self-harm/intent\": [\n \"text\",\n \"image\"\n ],\n \"self-harm/instructions\": [\n \"text\",\n \"image\"\n ],\n \"self-harm\": [\n \"text\",\n \"image\"\n ],\n \"sexual/minors\": [\n \"text\"\n ],\n \"violence\": [\n \"text\",\n \"image\"\n ],\n \"violence/graphic\": [\n \"text\",\n \"image\"\n ]\n }\n }\n ]\n}\n" + } + ] + } + } + }, + "/organization/admin_api_keys": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "List organization API keys", + "operationId": "admin-api-keys-list", + "description": "Retrieve a paginated list of organization admin API keys.", + "parameters": [ + { + "in": "query", + "name": "after", + "required": false, + "schema": { + "type": "string", + "nullable": true, + "description": "Return keys with IDs that come after this ID in the pagination order." + } + }, + { + "in": "query", + "name": "order", + "required": false, + "schema": { + "type": "string", + "enum": [ + "asc", + "desc" + ], + "default": "asc", + "description": "Order results by creation time, ascending or descending." + } + }, + { + "in": "query", + "name": "limit", + "required": false, + "schema": { + "type": "integer", + "default": 20, + "description": "Maximum number of keys to return." + } + } + ], + "responses": { + "200": { + "description": "A list of organization API keys.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiKeyList" + } + } + } + } + }, + "x-oaiMeta": { + "name": "List all organization and project API keys.", + "group": "administration", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/organization/admin_api_keys?after=key_abc&limit=20 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"organization.admin_api_key\",\n \"id\": \"key_abc\",\n \"name\": \"Main Admin Key\",\n \"redacted_value\": \"sk-admin...def\",\n \"created_at\": 1711471533,\n \"expires_at\": 1714063533,\n \"last_used_at\": 1711471534,\n \"owner\": {\n \"type\": \"service_account\",\n \"object\": \"organization.service_account\",\n \"id\": \"sa_456\",\n \"name\": \"My Service Account\",\n \"created_at\": 1711471533,\n \"role\": \"member\"\n }\n }\n ],\n \"first_id\": \"key_abc\",\n \"last_id\": \"key_abc\",\n \"has_more\": false\n}\n" + } + } + }, + "post": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Create an organization admin API key", + "operationId": "admin-api-keys-create", + "description": "Create a new admin-level API key for the organization.", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "example": "New Admin Key" + }, + "expires_in_seconds": { + "type": "integer", + "minimum": 1, + "maximum": 31536000, + "example": 2592000, + "description": "The number of seconds until the API key expires. Omit this field for a key that does not expire." + } + } + } + } + } + }, + "responses": { + "200": { + "description": "The newly created admin API key.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AdminApiKeyCreateResponse" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Create admin API key", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X POST https://api.openai.com/v1/organization/admin_api_keys \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"New Admin Key\",\n \"expires_in_seconds\": 2592000\n }'\n" + }, + "response": "{\n \"object\": \"organization.admin_api_key\",\n \"id\": \"key_xyz\",\n \"name\": \"New Admin Key\",\n \"redacted_value\": \"sk-admin...xyz\",\n \"created_at\": 1711471533,\n \"expires_at\": 1714063533,\n \"last_used_at\": 1711471534,\n \"owner\": {\n \"type\": \"user\",\n \"object\": \"organization.user\",\n \"id\": \"user_123\",\n \"name\": \"John Doe\",\n \"created_at\": 1711471533,\n \"role\": \"owner\"\n },\n \"value\": \"sk-admin-1234abcd\"\n}\n" + } + } + } + }, + "/organization/admin_api_keys/{key_id}": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Retrieve a single organization API key", + "operationId": "admin-api-keys-get", + "description": "Get details for a specific organization API key by its ID.", + "parameters": [ + { + "in": "path", + "name": "key_id", + "required": true, + "schema": { + "type": "string", + "description": "The ID of the API key." + } + } + ], + "responses": { + "200": { + "description": "Details of the requested API key.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AdminApiKey" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Retrieve admin API key", + "group": "administration", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/organization/admin_api_keys/key_abc \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"organization.admin_api_key\",\n \"id\": \"key_abc\",\n \"name\": \"Main Admin Key\",\n \"redacted_value\": \"sk-admin...xyz\",\n \"created_at\": 1711471533,\n \"last_used_at\": 1711471534,\n \"owner\": {\n \"type\": \"user\",\n \"object\": \"organization.user\",\n \"id\": \"user_123\",\n \"name\": \"John Doe\",\n \"created_at\": 1711471533,\n \"role\": \"owner\"\n }\n}\n" + } + } + }, + "delete": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Delete an organization admin API key", + "operationId": "admin-api-keys-delete", + "description": "Delete the specified admin API key.", + "parameters": [ + { + "in": "path", + "name": "key_id", + "required": true, + "schema": { + "type": "string", + "description": "The ID of the API key to be deleted." + } + } + ], + "responses": { + "200": { + "description": "Confirmation that the API key was deleted.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "example": "key_abc" + }, + "object": { + "type": "string", + "enum": [ + "organization.admin_api_key.deleted" + ], + "example": "organization.admin_api_key.deleted", + "x-stainless-const": true + }, + "deleted": { + "type": "boolean", + "example": true + } + }, + "required": [ + "id", + "object", + "deleted" + ] + } + } + } + } + }, + "x-oaiMeta": { + "name": "Delete admin API key", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X DELETE https://api.openai.com/v1/organization/admin_api_keys/key_abc \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"id\": \"key_abc\",\n \"object\": \"organization.admin_api_key.deleted\",\n \"deleted\": true\n}\n" + } + } + } + }, + "/organization/audit_logs": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "List user actions and configuration changes within this organization.", + "operationId": "list-audit-logs", + "tags": [ + "Audit Logs" + ], + "parameters": [ + { + "name": "effective_at", + "in": "query", + "description": "Return only events whose `effective_at` (Unix seconds) is in this range.", + "required": false, + "schema": { + "type": "object", + "properties": { + "gt": { + "type": "integer", + "description": "Return only events whose `effective_at` (Unix seconds) is greater than this value." + }, + "gte": { + "type": "integer", + "description": "Return only events whose `effective_at` (Unix seconds) is greater than or equal to this value." + }, + "lt": { + "type": "integer", + "description": "Return only events whose `effective_at` (Unix seconds) is less than this value." + }, + "lte": { + "type": "integer", + "description": "Return only events whose `effective_at` (Unix seconds) is less than or equal to this value." + } + } + } + }, + { + "name": "project_ids[]", + "in": "query", + "description": "Return only events for these projects.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "event_types[]", + "in": "query", + "description": "Return only events with a `type` in one of these values. For example, `project.created`. For all options, see the documentation for the [audit log object](https://developers.openai.com/api/reference/resources/admin/subresources/organization/subresources/audit_logs).", + "required": false, + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AuditLogEventType" + } + } + }, + { + "name": "actor_ids[]", + "in": "query", + "description": "Return only events performed by these actors. Can be a user ID, a service account ID, or an api key tracking ID.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "actor_emails[]", + "in": "query", + "description": "Return only events performed by users with these emails.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "resource_ids[]", + "in": "query", + "description": "Return only events performed on these targets. For example, a project ID updated. For ChatGPT connector role events, use the workspace connector resource ID shown in `details.id`, such as `__`.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "tenant_only", + "in": "query", + "description": "Return only tenant-scoped events associated with this organization. Required for tenant-scoped events such as `role.bound_to_resource` and `role.unbound_from_resource`. When `true`, all supplied event types must be tenant-scoped.", + "required": false, + "schema": { + "type": "boolean", + "default": false + } + }, + { + "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.\n", + "required": false, + "schema": { + "type": "integer", + "default": 20 + } + }, + { + "name": "after", + "in": "query", + "description": "A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.\n", + "schema": { + "type": "string" + } + }, + { + "name": "before", + "in": "query", + "description": "A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list.\n", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Audit logs listed successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListAuditLogsResponse" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "List audit logs", + "group": "audit-logs", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/organization/audit_logs \\\n-H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n-H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"audit_log-xxx_yyyymmdd\",\n \"type\": \"project.archived\",\n \"effective_at\": 1722461446,\n \"actor\": {\n \"type\": \"api_key\",\n \"api_key\": {\n \"type\": \"user\",\n \"user\": {\n \"id\": \"user-xxx\",\n \"email\": \"user@example.com\"\n }\n }\n },\n \"project.archived\": {\n \"id\": \"proj_abc\"\n },\n },\n {\n \"id\": \"audit_log-yyy__20240101\",\n \"type\": \"api_key.updated\",\n \"effective_at\": 1720804190,\n \"actor\": {\n \"type\": \"session\",\n \"session\": {\n \"user\": {\n \"id\": \"user-xxx\",\n \"email\": \"user@example.com\"\n },\n \"ip_address\": \"127.0.0.1\",\n \"user_agent\": \"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36\",\n \"ja3\": \"a497151ce4338a12c4418c44d375173e\",\n \"ja4\": \"q13d0313h3_55b375c5d22e_c7319ce65786\",\n \"ip_address_details\": {\n \"country\": \"US\",\n \"city\": \"San Francisco\",\n \"region\": \"California\",\n \"region_code\": \"CA\",\n \"asn\": \"1234\",\n \"latitude\": \"37.77490\",\n \"longitude\": \"-122.41940\"\n }\n }\n },\n \"api_key.updated\": {\n \"id\": \"key_xxxx\",\n \"data\": {\n \"scopes\": [\"resource_2.operation_2\"]\n }\n },\n }\n ],\n \"first_id\": \"audit_log-xxx__20240101\",\n \"last_id\": \"audit_log_yyy__20240101\",\n \"has_more\": true\n}\n" + } + } + } + }, + "/organization/certificates": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "List uploaded certificates for this organization.", + "operationId": "listOrganizationCertificates", + "tags": [ + "Certificates" + ], + "parameters": [ + { + "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.\n", + "required": false, + "schema": { + "type": "integer", + "default": 20 + } + }, + { + "name": "after", + "in": "query", + "description": "A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.\n", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "order", + "in": "query", + "description": "Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order.\n", + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + } + } + ], + "responses": { + "200": { + "description": "Certificates listed successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListCertificatesResponse" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "List organization certificates", + "group": "administration", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/organization/certificates \\\n-H \"Authorization: Bearer $OPENAI_ADMIN_KEY\"\n" + }, + "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"organization.certificate\",\n \"id\": \"cert_abc\",\n \"name\": \"My Example Certificate\",\n \"active\": true,\n \"created_at\": 1234567,\n \"certificate_details\": {\n \"valid_at\": 12345667,\n \"expires_at\": 12345678\n }\n },\n ],\n \"first_id\": \"cert_abc\",\n \"last_id\": \"cert_abc\",\n \"has_more\": false\n}\n" + } + } + }, + "post": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Upload a certificate to the organization. This does **not** automatically activate the certificate.\n\nOrganizations can upload up to 50 certificates.\n", + "operationId": "uploadCertificate", + "tags": [ + "Certificates" + ], + "requestBody": { + "description": "The certificate upload payload.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UploadCertificateRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Certificate uploaded successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Certificate" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Upload certificate", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X POST https://api.openai.com/v1/organization/certificates \\\n-H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n-H \"Content-Type: application/json\" \\\n-d '{\n \"name\": \"My Example Certificate\",\n \"certificate\": \"-----BEGIN CERTIFICATE-----\\\\nMIIDeT...\\\\n-----END CERTIFICATE-----\"\n}'\n" + }, + "response": "{\n \"object\": \"certificate\",\n \"id\": \"cert_abc\",\n \"name\": \"My Example Certificate\",\n \"created_at\": 1234567,\n \"certificate_details\": {\n \"valid_at\": 12345667,\n \"expires_at\": 12345678\n }\n}\n" + } + } + } + }, + "/organization/certificates/activate": { + "post": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Activate certificates at the organization level.\n\nYou can atomically and idempotently activate up to 10 certificates at a time.\n", + "operationId": "activateOrganizationCertificates", + "tags": [ + "Certificates" + ], + "requestBody": { + "description": "The certificate activation payload.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ToggleCertificatesRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Certificates activated successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OrganizationCertificateActivationResponse" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Activate certificates for organization", + "group": "administration", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/organization/certificates/activate \\\n-H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n-H \"Content-Type: application/json\" \\\n-d '{\n \"certificate_ids\": [\"cert_abc\", \"cert_def\"]\n}'\n" + }, + "response": "{\n \"object\": \"organization.certificate.activation\",\n \"data\": [\n {\n \"object\": \"organization.certificate\",\n \"id\": \"cert_abc\",\n \"name\": \"My Example Certificate\",\n \"active\": true,\n \"created_at\": 1234567,\n \"certificate_details\": {\n \"valid_at\": 12345667,\n \"expires_at\": 12345678\n }\n },\n {\n \"object\": \"organization.certificate\",\n \"id\": \"cert_def\",\n \"name\": \"My Example Certificate 2\",\n \"active\": true,\n \"created_at\": 1234567,\n \"certificate_details\": {\n \"valid_at\": 12345667,\n \"expires_at\": 12345678\n }\n },\n ],\n}\n" + } + } + } + }, + "/organization/certificates/deactivate": { + "post": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Deactivate certificates at the organization level.\n\nYou can atomically and idempotently deactivate up to 10 certificates at a time.\n", + "operationId": "deactivateOrganizationCertificates", + "tags": [ + "Certificates" + ], + "requestBody": { + "description": "The certificate deactivation payload.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ToggleCertificatesRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Certificates deactivated successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OrganizationCertificateDeactivationResponse" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Deactivate certificates for organization", + "group": "administration", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/organization/certificates/deactivate \\\n-H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n-H \"Content-Type: application/json\" \\\n-d '{\n \"certificate_ids\": [\"cert_abc\", \"cert_def\"]\n}'\n" + }, + "response": "{\n \"object\": \"organization.certificate.deactivation\",\n \"data\": [\n {\n \"object\": \"organization.certificate\",\n \"id\": \"cert_abc\",\n \"name\": \"My Example Certificate\",\n \"active\": false,\n \"created_at\": 1234567,\n \"certificate_details\": {\n \"valid_at\": 12345667,\n \"expires_at\": 12345678\n }\n },\n {\n \"object\": \"organization.certificate\",\n \"id\": \"cert_def\",\n \"name\": \"My Example Certificate 2\",\n \"active\": false,\n \"created_at\": 1234567,\n \"certificate_details\": {\n \"valid_at\": 12345667,\n \"expires_at\": 12345678\n }\n },\n ],\n}\n" + } + } + } + }, + "/organization/certificates/{certificate_id}": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Get a certificate that has been uploaded to the organization.\n\nYou can get a certificate regardless of whether it is active or not.\n", + "operationId": "getCertificate", + "tags": [ + "Certificates" + ], + "parameters": [ + { + "name": "certificate_id", + "in": "path", + "description": "Unique ID of the certificate to retrieve.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "include", + "in": "query", + "description": "A list of additional fields to include in the response. Currently the only supported value is `content` to fetch the PEM content of the certificate.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "content" + ] + } + } + } + ], + "responses": { + "200": { + "description": "Certificate retrieved successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Certificate" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Get certificate", + "group": "administration", + "examples": { + "request": { + "curl": "curl \"https://api.openai.com/v1/organization/certificates/cert_abc?include[]=content\" \\\n-H \"Authorization: Bearer $OPENAI_ADMIN_KEY\"\n" + }, + "response": "{\n \"object\": \"certificate\",\n \"id\": \"cert_abc\",\n \"name\": \"My Example Certificate\",\n \"created_at\": 1234567,\n \"certificate_details\": {\n \"valid_at\": 1234567,\n \"expires_at\": 12345678,\n \"content\": \"-----BEGIN CERTIFICATE-----MIIDeT...-----END CERTIFICATE-----\"\n }\n}\n" + } + } + }, + "post": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Modify a certificate. Note that only the name can be modified.\n", + "operationId": "modifyCertificate", + "tags": [ + "Certificates" + ], + "parameters": [ + { + "name": "certificate_id", + "in": "path", + "description": "Unique ID of the certificate to modify.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "The certificate modification payload.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ModifyCertificateRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Certificate modified successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Certificate" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Modify certificate", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X POST https://api.openai.com/v1/organization/certificates/cert_abc \\\n-H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n-H \"Content-Type: application/json\" \\\n-d '{\n \"name\": \"Renamed Certificate\"\n}'\n" + }, + "response": "{\n \"object\": \"certificate\",\n \"id\": \"cert_abc\",\n \"name\": \"Renamed Certificate\",\n \"created_at\": 1234567,\n \"certificate_details\": {\n \"valid_at\": 12345667,\n \"expires_at\": 12345678\n }\n}\n" + } + } + }, + "delete": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Delete a certificate from the organization.\n\nThe certificate must be inactive for the organization and all projects.\n", + "operationId": "deleteCertificate", + "tags": [ + "Certificates" + ], + "parameters": [ + { + "name": "certificate_id", + "in": "path", + "description": "Unique ID of the certificate to delete.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Certificate deleted successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeleteCertificateResponse" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Delete certificate", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X DELETE https://api.openai.com/v1/organization/certificates/cert_abc \\\n-H \"Authorization: Bearer $OPENAI_ADMIN_KEY\"\n" + }, + "response": "{\n \"object\": \"certificate.deleted\",\n \"id\": \"cert_abc\"\n}\n" + } + } + } + }, + "/organization/costs": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Get costs details for the organization.", + "operationId": "usage-costs", + "tags": [ + "Usage" + ], + "parameters": [ + { + "name": "start_time", + "in": "query", + "description": "Start time (Unix seconds) of the query time range, inclusive.", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "end_time", + "in": "query", + "description": "End time (Unix seconds) of the query time range, exclusive.", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "name": "bucket_width", + "in": "query", + "description": "Width of each time bucket in response. Currently only `1d` is supported, default to `1d`.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "1d" + ], + "default": "1d" + } + }, + { + "name": "project_ids", + "in": "query", + "description": "Return only costs for these projects.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "api_key_ids", + "in": "query", + "description": "Return only costs for these API keys.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "line_items", + "in": "query", + "description": "Return only costs for these exact line item names. Each value must match the complete `line_item` value, for example `gpt-6-astra, input_tokens`.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "group_by", + "in": "query", + "description": "Group the costs by the specified fields. Support fields include `project_id`, `line_item`, `api_key_id` and any combination of them.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "project_id", + "line_item", + "api_key_id" + ] + } + } + }, + { + "name": "limit", + "in": "query", + "description": "A limit on the number of buckets to be returned. Limit can range between 1 and 180, and the default is 7.\n", + "required": false, + "schema": { + "type": "integer", + "default": 7 + } + }, + { + "name": "page", + "in": "query", + "description": "A cursor for use in pagination. Corresponding to the `next_page` field from the previous response.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Costs data retrieved successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UsageResponse" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Costs", + "group": "usage-costs", + "examples": { + "request": { + "curl": "curl \"https://api.openai.com/v1/organization/costs?start_time=1730419200&limit=1\" \\\n-H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n-H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"page\",\n \"data\": [\n {\n \"object\": \"bucket\",\n \"start_time\": 1730419200,\n \"end_time\": 1730505600,\n \"results\": [\n {\n \"object\": \"organization.costs.result\",\n \"amount\": {\n \"value\": 0.06,\n \"currency\": \"usd\"\n },\n \"line_item\": null,\n \"project_id\": null,\n \"api_key_id\": null,\n \"quantity\": null,\n \"quantity_unit\": null\n }\n ]\n }\n ],\n \"has_more\": false,\n \"next_page\": null\n}\n" + } + } + } + }, + "/organization/data_retention": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Retrieves organization data retention controls.", + "operationId": "retrieve-organization-data-retention", + "tags": [ + "Data retention" + ], + "responses": { + "200": { + "description": "Organization data retention controls retrieved successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OrganizationDataRetention" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Retrieve organization data retention", + "group": "administration", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/organization/data_retention \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"organization.data_retention\",\n \"type\": \"modified_abuse_monitoring\"\n}\n" + } + } + }, + "post": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Updates organization data retention controls.", + "operationId": "update-organization-data-retention", + "tags": [ + "Data retention" + ], + "requestBody": { + "description": "The desired organization data retention setting.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateOrganizationDataRetentionBody" + } + } + } + }, + "responses": { + "200": { + "description": "Organization data retention controls updated successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OrganizationDataRetention" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Update organization data retention", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X POST https://api.openai.com/v1/organization/data_retention \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"retention_type\": \"modified_abuse_monitoring\"\n }'\n" + }, + "response": "{\n \"object\": \"organization.data_retention\",\n \"type\": \"modified_abuse_monitoring\"\n}\n" + } + } + } + }, + "/organization/groups": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Lists all groups in the organization.", + "operationId": "list-groups", + "tags": [ + "Groups" + ], + "parameters": [ + { + "name": "limit", + "in": "query", + "description": "A limit on the number of groups to be returned. Limit can range between 0 and 1000, and the default is 100.\n", + "required": false, + "schema": { + "type": "integer", + "minimum": 0, + "maximum": 1000, + "default": 100 + } + }, + { + "name": "after", + "in": "query", + "description": "A cursor for use in pagination. `after` is a group ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with group_abc, your subsequent call can include `after=group_abc` in order to fetch the next page of the list.\n", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "order", + "in": "query", + "description": "Specifies the sort order of the returned groups.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "asc", + "desc" + ], + "default": "asc" + } + } + ], + "responses": { + "200": { + "description": "Groups listed successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GroupListResource" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "List groups", + "group": "administration", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/organization/groups?limit=20&order=asc \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"group\",\n \"id\": \"group_01J1F8ABCDXYZ\",\n \"name\": \"Support Team\",\n \"created_at\": 1711471533,\n \"is_scim_managed\": false\n }\n ],\n \"has_more\": false,\n \"next\": null\n}\n" + } + } + }, + "post": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Creates a new group in the organization.", + "operationId": "create-group", + "tags": [ + "Groups" + ], + "requestBody": { + "description": "Parameters for the group you want to create.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateGroupBody" + } + } + } + }, + "responses": { + "200": { + "description": "Group created successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GroupResponse" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Create group", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X POST https://api.openai.com/v1/organization/groups \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"Support Team\"\n }'\n" + }, + "response": "{\n \"object\": \"group\",\n \"id\": \"group_01J1F8ABCDXYZ\",\n \"name\": \"Support Team\",\n \"created_at\": 1711471533,\n \"is_scim_managed\": false\n}\n" + } + } + } + }, + "/organization/groups/{group_id}": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Retrieves a group.", + "operationId": "retrieve-group", + "tags": [ + "Groups" + ], + "parameters": [ + { + "name": "group_id", + "in": "path", + "description": "The ID of the group to retrieve.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Group retrieved successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GroupResponse" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Retrieve group", + "group": "administration", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"id\": \"group_01J1F8ABCDXYZ\",\n \"name\": \"Support Team\",\n \"created_at\": 1711471533,\n \"is_scim_managed\": false,\n \"group_type\": \"group\"\n}\n" + } + } + }, + "post": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Updates a group's information.", + "operationId": "update-group", + "tags": [ + "Groups" + ], + "parameters": [ + { + "name": "group_id", + "in": "path", + "description": "The ID of the group to update.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "New attributes to set on the group.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateGroupBody" + } + } + } + }, + "responses": { + "200": { + "description": "Group updated successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GroupResourceWithSuccess" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Update group", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X POST https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"Escalations\"\n }'\n" + }, + "response": "{\n \"id\": \"group_01J1F8ABCDXYZ\",\n \"name\": \"Escalations\",\n \"created_at\": 1711471533,\n \"is_scim_managed\": false\n}\n" + } + } + }, + "delete": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Deletes a group from the organization.", + "operationId": "delete-group", + "tags": [ + "Groups" + ], + "parameters": [ + { + "name": "group_id", + "in": "path", + "description": "The ID of the group to delete.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Group deleted successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GroupDeletedResource" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Delete group", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X DELETE https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"group.deleted\",\n \"id\": \"group_01J1F8ABCDXYZ\",\n \"deleted\": true\n}\n" + } + } + } + }, + "/organization/groups/{group_id}/roles": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Lists the organization roles assigned to a group within the organization.", + "operationId": "list-group-role-assignments", + "tags": [ + "Group organization role assignments" + ], + "parameters": [ + { + "name": "group_id", + "in": "path", + "description": "The ID of the group whose organization role assignments you want to list.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "description": "A limit on the number of organization role assignments to return.", + "required": false, + "schema": { + "type": "integer", + "minimum": 0, + "maximum": 1000 + } + }, + { + "name": "after", + "in": "query", + "description": "Cursor for pagination. Provide the value from the previous response's `next` field to continue listing organization roles.", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "order", + "in": "query", + "description": "Sort order for the returned organization roles.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "asc", + "desc" + ] + } + } + ], + "responses": { + "200": { + "description": "Group organization role assignments listed successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RoleListResource" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "List group organization role assignments", + "group": "administration", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ/roles \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"role_01J1F8ROLE01\",\n \"name\": \"API Group Manager\",\n \"permissions\": [\n \"api.groups.read\",\n \"api.groups.write\"\n ],\n \"resource_type\": \"api.organization\",\n \"predefined_role\": false,\n \"description\": \"Allows managing organization groups\",\n \"created_at\": 1711471533,\n \"updated_at\": 1711472599,\n \"created_by\": \"user_abc123\",\n \"created_by_user_obj\": {\n \"id\": \"user_abc123\",\n \"name\": \"Ada Lovelace\",\n \"email\": \"ada@example.com\"\n },\n \"metadata\": {}\n }\n ],\n \"has_more\": false,\n \"next\": null\n}\n" + } + } + }, + "post": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Assigns an organization role to a group within the organization.", + "operationId": "assign-group-role", + "tags": [ + "Group organization role assignments" + ], + "parameters": [ + { + "name": "group_id", + "in": "path", + "description": "The ID of the group that should receive the organization role.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "Identifies the organization role to assign to the group.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PublicAssignOrganizationGroupRoleBody" + } + } + } + }, + "responses": { + "200": { + "description": "Organization role assigned to the group successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GroupRoleAssignment" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Assign organization role to group", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X POST https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ/roles \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"role_id\": \"role_01J1F8ROLE01\"\n }'\n" + }, + "response": "{\n \"object\": \"group.role\",\n \"group\": {\n \"object\": \"group\",\n \"id\": \"group_01J1F8ABCDXYZ\",\n \"name\": \"Support Team\",\n \"created_at\": 1711471533,\n \"scim_managed\": false\n },\n \"role\": {\n \"object\": \"role\",\n \"id\": \"role_01J1F8ROLE01\",\n \"name\": \"API Group Manager\",\n \"description\": \"Allows managing organization groups\",\n \"permissions\": [\n \"api.groups.read\",\n \"api.groups.write\"\n ],\n \"resource_type\": \"api.organization\",\n \"predefined_role\": false\n }\n}\n" + } + } + } + }, + "/organization/groups/{group_id}/roles/{role_id}": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Retrieves an organization role assigned to a group.", + "operationId": "retrieve-group-role", + "tags": [ + "Group organization role assignments" + ], + "parameters": [ + { + "name": "group_id", + "in": "path", + "description": "The ID of the group to inspect.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "role_id", + "in": "path", + "description": "The ID of the organization role to retrieve for the group.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Organization role retrieved for the group successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AssignedRoleDetails" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Retrieve group organization role", + "group": "administration", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ/roles/role_01J1F8ROLE01 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"id\": \"role_01J1F8ROLE01\",\n \"name\": \"API Group Manager\",\n \"permissions\": [\n \"api.groups.read\",\n \"api.groups.write\"\n ],\n \"resource_type\": \"api.organization\",\n \"predefined_role\": false,\n \"description\": \"Allows managing organization groups\",\n \"created_at\": 1711471533,\n \"updated_at\": 1711472599,\n \"created_by\": \"user_abc123\",\n \"created_by_user_obj\": null,\n \"metadata\": {},\n \"assignment_sources\": null\n}\n" + } + } + }, + "delete": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Unassigns an organization role from a group within the organization.", + "operationId": "unassign-group-role", + "tags": [ + "Group organization role assignments" + ], + "parameters": [ + { + "name": "group_id", + "in": "path", + "description": "The ID of the group to modify.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "role_id", + "in": "path", + "description": "The ID of the organization role to remove from the group.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Organization role unassigned from the group successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeletedRoleAssignmentResource" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Unassign organization role from group", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X DELETE https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ/roles/role_01J1F8ROLE01 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"group.role.deleted\",\n \"deleted\": true\n}\n" + } + } + } + }, + "/organization/groups/{group_id}/users": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Lists the users assigned to a group.", + "operationId": "list-group-users", + "tags": [ + "Group users" + ], + "parameters": [ + { + "name": "group_id", + "in": "path", + "description": "The ID of the group to inspect.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "description": "A limit on the number of users to be returned. Limit can range between 0 and 1000, and the default is 100.\n", + "required": false, + "schema": { + "type": "integer", + "minimum": 0, + "maximum": 1000, + "default": 100 + } + }, + { + "name": "after", + "in": "query", + "description": "A cursor for use in pagination. Provide the ID of the last user from the previous list response to retrieve the next page.\n", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "order", + "in": "query", + "description": "Specifies the sort order of users in the list.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "asc", + "desc" + ], + "default": "desc" + } + } + ], + "responses": { + "200": { + "description": "Group users listed successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UserListResource" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "List group users", + "group": "administration", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ/users?limit=20 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"user_abc123\",\n \"name\": \"Ada Lovelace\",\n \"email\": \"ada@example.com\"\n }\n ],\n \"has_more\": false,\n \"next\": null\n}\n" + } + } + }, + "post": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Adds a user to a group.", + "operationId": "add-group-user", + "tags": [ + "Group users" + ], + "parameters": [ + { + "name": "group_id", + "in": "path", + "description": "The ID of the group to update.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "Identifies the user that should be added to the group.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateGroupUserBody" + } + } + } + }, + "responses": { + "200": { + "description": "User added to the group successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GroupUserAssignment" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Add group user", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X POST https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ/users \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"user_id\": \"user_abc123\"\n }'\n" + }, + "response": "{\n \"object\": \"group.user\",\n \"user_id\": \"user_abc123\",\n \"group_id\": \"group_01J1F8ABCDXYZ\"\n}\n" + } + } + } + }, + "/organization/groups/{group_id}/users/{user_id}": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Retrieves a user in a group.", + "operationId": "retrieve-group-user", + "tags": [ + "Group users" + ], + "parameters": [ + { + "name": "group_id", + "in": "path", + "description": "The ID of the group to inspect.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "user_id", + "in": "path", + "description": "The ID of the user to retrieve from the group.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "User retrieved from the group successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GroupMemberUser" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Retrieve group user", + "group": "administration", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ/users/user_abc123 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"id\": \"user_abc123\",\n \"name\": \"Ada Lovelace\",\n \"email\": \"ada@example.com\",\n \"picture\": null,\n \"is_service_account\": false,\n \"user_type\": \"user\"\n}\n" + } + } + }, + "delete": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Removes a user from a group.", + "operationId": "remove-group-user", + "tags": [ + "Group users" + ], + "parameters": [ + { + "name": "group_id", + "in": "path", + "description": "The ID of the group to update.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "user_id", + "in": "path", + "description": "The ID of the user to remove from the group.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "User removed from the group successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GroupUserDeletedResource" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Remove group user", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X DELETE https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ/users/user_abc123 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"group.user.deleted\",\n \"deleted\": true\n}\n" + } + } + } + }, + "/organization/invites": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Returns a list of invites in the organization.", + "operationId": "list-invites", + "tags": [ + "Invites" + ], + "parameters": [ + { + "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.\n", + "required": false, + "schema": { + "type": "integer", + "default": 20 + } + }, + { + "name": "after", + "in": "query", + "description": "A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.\n", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Invites listed successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InviteListResponse" + } + } + } + } + }, + "x-oaiMeta": { + "name": "List invites", + "group": "administration", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/organization/invites?after=invite-abc&limit=20 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"organization.invite\",\n \"id\": \"invite-abc\",\n \"email\": \"user@example.com\",\n \"role\": \"owner\",\n \"status\": \"accepted\",\n \"created_at\": 1711471533,\n \"expires_at\": 1711471533,\n \"accepted_at\": 1711471533\n }\n ],\n \"first_id\": \"invite-abc\",\n \"last_id\": \"invite-abc\",\n \"has_more\": false\n}\n" + } + } + }, + "post": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Create an invite for a user to the organization. The invite must be accepted by the user before they have access to the organization.", + "operationId": "inviteUser", + "tags": [ + "Invites" + ], + "requestBody": { + "description": "The invite request payload.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InviteRequest" + } + } + } + }, + "responses": { + "200": { + "description": "User invited successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Invite" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Create invite", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X POST https://api.openai.com/v1/organization/invites \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"email\": \"anotheruser@example.com\",\n \"role\": \"reader\",\n \"projects\": [\n {\n \"id\": \"project-xyz\",\n \"role\": \"member\"\n },\n {\n \"id\": \"project-abc\",\n \"role\": \"owner\"\n }\n ]\n }'\n" + }, + "response": "{\n \"object\": \"organization.invite\",\n \"id\": \"invite-def\",\n \"email\": \"anotheruser@example.com\",\n \"role\": \"reader\",\n \"status\": \"pending\",\n \"created_at\": 1711471533,\n \"expires_at\": 1711471533,\n \"accepted_at\": null,\n \"projects\": [\n {\n \"id\": \"project-xyz\",\n \"role\": \"member\"\n },\n {\n \"id\": \"project-abc\",\n \"role\": \"owner\"\n }\n ]\n}\n" + } + } + } + }, + "/organization/invites/{invite_id}": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Retrieves an invite.", + "operationId": "retrieve-invite", + "tags": [ + "Invites" + ], + "parameters": [ + { + "in": "path", + "name": "invite_id", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the invite to retrieve." + } + ], + "responses": { + "200": { + "description": "Invite retrieved successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Invite" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Retrieve invite", + "group": "administration", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/organization/invites/invite-abc \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"organization.invite\",\n \"id\": \"invite-abc\",\n \"email\": \"user@example.com\",\n \"role\": \"owner\",\n \"status\": \"accepted\",\n \"created_at\": 1711471533,\n \"expires_at\": 1711471533,\n \"accepted_at\": 1711471533\n}\n" + } + } + }, + "delete": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Delete an invite. If the invite has already been accepted, it cannot be deleted.", + "operationId": "delete-invite", + "tags": [ + "Invites" + ], + "parameters": [ + { + "in": "path", + "name": "invite_id", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the invite to delete." + } + ], + "responses": { + "200": { + "description": "Invite deleted successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InviteDeleteResponse" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Delete invite", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X DELETE https://api.openai.com/v1/organization/invites/invite-abc \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"organization.invite.deleted\",\n \"id\": \"invite-abc\",\n \"deleted\": true\n}\n" + } + } + } + }, + "/organization/projects": { + "get": { + "summary": "Returns a list of projects.", + "operationId": "list-projects", + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "tags": [ + "Projects" + ], + "parameters": [ + { + "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.\n", + "required": false, + "schema": { + "type": "integer", + "default": 20 + } + }, + { + "name": "after", + "in": "query", + "description": "A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.\n", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "include_archived", + "in": "query", + "schema": { + "type": "boolean", + "default": false + }, + "description": "If `true` returns all projects including those that have been `archived`. Archived projects are not included by default." + } + ], + "responses": { + "200": { + "description": "Projects listed successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProjectListResponse" + } + } + } + } + }, + "x-oaiMeta": { + "name": "List projects", + "group": "administration", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/organization/projects?after=proj_abc&limit=20&include_archived=false \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"proj_abc\",\n \"object\": \"organization.project\",\n \"name\": \"Project example\",\n \"created_at\": 1711471533,\n \"archived_at\": null,\n \"status\": \"active\"\n }\n ],\n \"first_id\": \"proj-abc\",\n \"last_id\": \"proj-xyz\",\n \"has_more\": false\n}\n" + } + } + }, + "post": { + "summary": "Create a new project in the organization. Projects can be created and archived, but cannot be deleted.", + "operationId": "create-project", + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "tags": [ + "Projects" + ], + "requestBody": { + "description": "The project create request payload.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProjectCreateRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Project created successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Project" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Create project", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X POST https://api.openai.com/v1/organization/projects \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"Project ABC\"\n }'\n" + }, + "response": "{\n \"id\": \"proj_abc\",\n \"object\": \"organization.project\",\n \"name\": \"Project ABC\",\n \"created_at\": 1711471533,\n \"archived_at\": null,\n \"status\": \"active\"\n}\n" + } + } + } + }, + "/organization/projects/{project_id}": { + "get": { + "summary": "Retrieves a project.", + "operationId": "retrieve-project", + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "tags": [ + "Projects" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Project retrieved successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Project" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Retrieve project", + "group": "administration", + "description": "Retrieve a project.", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/organization/projects/proj_abc \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"id\": \"proj_abc\",\n \"object\": \"organization.project\",\n \"name\": \"Project example\",\n \"created_at\": 1711471533,\n \"archived_at\": null,\n \"status\": \"active\"\n}\n" + } + } + }, + "post": { + "summary": "Modifies a project in the organization.", + "operationId": "modify-project", + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "tags": [ + "Projects" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "The project update request payload.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProjectUpdateRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Project updated successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Project" + } + } + } + }, + "400": { + "description": "Error response when updating the default project.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Modify project", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X POST https://api.openai.com/v1/organization/projects/proj_abc \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"Project DEF\"\n }'\n" + } + } + } + } + }, + "/organization/projects/{project_id}/api_keys": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Returns a list of API keys in the project.", + "operationId": "list-project-api-keys", + "tags": [ + "Projects" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "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.\n", + "required": false, + "schema": { + "type": "integer", + "default": 20 + } + }, + { + "name": "after", + "in": "query", + "description": "A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.\n", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "owner_project_access", + "in": "query", + "description": "Filter API keys by whether the owner currently has effective access to the project. Use `active` for owners with access, `inactive` for owners without access, or `any` for all enabled project API keys. If omitted, the endpoint applies its existing membership-based visibility rules, which may exclude some enabled keys.\n", + "required": false, + "schema": { + "type": "string", + "enum": [ + "active", + "inactive", + "any" + ] + } + } + ], + "responses": { + "200": { + "description": "Project API keys listed successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProjectApiKeyListResponse" + } + } + } + } + }, + "x-oaiMeta": { + "name": "List project API keys", + "group": "administration", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/organization/projects/proj_abc/api_keys?after=key_abc&limit=20&owner_project_access=any \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"organization.project.api_key\",\n \"redacted_value\": \"sk-abc...def\",\n \"name\": \"My API Key\",\n \"created_at\": 1711471533,\n \"last_used_at\": 1711471534,\n \"id\": \"key_abc\",\n \"owner_project_access\": \"active\",\n \"owner\": {\n \"type\": \"user\",\n \"user\": {\n \"id\": \"user_abc\",\n \"name\": \"First Last\",\n \"email\": \"user@example.com\",\n \"role\": \"owner\",\n \"created_at\": 1711471533\n }\n }\n }\n ],\n \"first_id\": \"key_abc\",\n \"last_id\": \"key_xyz\",\n \"has_more\": false\n}\n" + } + } + } + }, + "/organization/projects/{project_id}/api_keys/{api_key_id}": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Retrieves an API key in the project.", + "operationId": "retrieve-project-api-key", + "tags": [ + "Projects" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "api_key_id", + "in": "path", + "description": "The ID of the API key.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Project API key retrieved successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProjectApiKey" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Retrieve project API key", + "group": "administration", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/organization/projects/proj_abc/api_keys/key_abc \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"organization.project.api_key\",\n \"redacted_value\": \"sk-abc...def\",\n \"name\": \"My API Key\",\n \"created_at\": 1711471533,\n \"last_used_at\": 1711471534,\n \"id\": \"key_abc\",\n \"owner_project_access\": \"active\",\n \"owner\": {\n \"type\": \"user\",\n \"user\": {\n \"id\": \"user_abc\",\n \"name\": \"First Last\",\n \"email\": \"user@example.com\",\n \"role\": \"owner\",\n \"created_at\": 1711471533\n }\n }\n}\n" + } + } + }, + "delete": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Deletes an API key from the project.\n\nReturns confirmation of the key deletion, or an error if the key belonged to\na service account.\n", + "operationId": "delete-project-api-key", + "tags": [ + "Projects" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "api_key_id", + "in": "path", + "description": "The ID of the API key.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Project API key deleted successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProjectApiKeyDeleteResponse" + } + } + } + }, + "400": { + "description": "Error response for various conditions.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Delete project API key", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X DELETE https://api.openai.com/v1/organization/projects/proj_abc/api_keys/key_abc \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"organization.project.api_key.deleted\",\n \"id\": \"key_abc\",\n \"deleted\": true\n}\n" + } + } + } + }, + "/organization/projects/{project_id}/archive": { + "post": { + "summary": "Archives a project in the organization. Archived projects cannot be used or updated.", + "operationId": "archive-project", + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "tags": [ + "Projects" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Project archived successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Project" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Archive project", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/archive \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"id\": \"proj_abc\",\n \"object\": \"organization.project\",\n \"name\": \"Project DEF\",\n \"created_at\": 1711471533,\n \"archived_at\": 1711471533,\n \"status\": \"archived\"\n}\n" + } + } + } + }, + "/organization/projects/{project_id}/certificates": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "List certificates for this project.", + "operationId": "listProjectCertificates", + "tags": [ + "Certificates" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "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.\n", + "required": false, + "schema": { + "type": "integer", + "default": 20 + } + }, + { + "name": "after", + "in": "query", + "description": "A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.\n", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "order", + "in": "query", + "description": "Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order.\n", + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + } + } + ], + "responses": { + "200": { + "description": "Certificates listed successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListProjectCertificatesResponse" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "List project certificates", + "group": "administration", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/organization/projects/proj_abc/certificates \\\n-H \"Authorization: Bearer $OPENAI_ADMIN_KEY\"\n" + }, + "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"organization.project.certificate\",\n \"id\": \"cert_abc\",\n \"name\": \"My Example Certificate\",\n \"active\": true,\n \"created_at\": 1234567,\n \"certificate_details\": {\n \"valid_at\": 12345667,\n \"expires_at\": 12345678\n }\n },\n ],\n \"first_id\": \"cert_abc\",\n \"last_id\": \"cert_abc\",\n \"has_more\": false\n}\n" + } + } + } + }, + "/organization/projects/{project_id}/certificates/activate": { + "post": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Activate certificates at the project level.\n\nYou can atomically and idempotently activate up to 10 certificates at a time.\n", + "operationId": "activateProjectCertificates", + "tags": [ + "Certificates" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "The certificate activation payload.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ToggleCertificatesRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Certificates activated successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OrganizationProjectCertificateActivationResponse" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Activate certificates for project", + "group": "administration", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/organization/projects/proj_abc/certificates/activate \\\n-H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n-H \"Content-Type: application/json\" \\\n-d '{\n \"certificate_ids\": [\"cert_abc\", \"cert_def\"]\n}'\n" + }, + "response": "{\n \"object\": \"organization.project.certificate.activation\",\n \"data\": [\n {\n \"object\": \"organization.project.certificate\",\n \"id\": \"cert_abc\",\n \"name\": \"My Example Certificate\",\n \"active\": true,\n \"created_at\": 1234567,\n \"certificate_details\": {\n \"valid_at\": 12345667,\n \"expires_at\": 12345678\n }\n },\n {\n \"object\": \"organization.project.certificate\",\n \"id\": \"cert_def\",\n \"name\": \"My Example Certificate 2\",\n \"active\": true,\n \"created_at\": 1234567,\n \"certificate_details\": {\n \"valid_at\": 12345667,\n \"expires_at\": 12345678\n }\n },\n ],\n}\n" + } + } + } + }, + "/organization/projects/{project_id}/certificates/deactivate": { + "post": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Deactivate certificates at the project level. You can atomically and \nidempotently deactivate up to 10 certificates at a time.\n", + "operationId": "deactivateProjectCertificates", + "tags": [ + "Certificates" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "The certificate deactivation payload.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ToggleCertificatesRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Certificates deactivated successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OrganizationProjectCertificateDeactivationResponse" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Deactivate certificates for project", + "group": "administration", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/organization/projects/proj_abc/certificates/deactivate \\\n-H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n-H \"Content-Type: application/json\" \\\n-d '{\n \"certificate_ids\": [\"cert_abc\", \"cert_def\"]\n}'\n" + }, + "response": "{\n \"object\": \"organization.project.certificate.deactivation\",\n \"data\": [\n {\n \"object\": \"organization.project.certificate\",\n \"id\": \"cert_abc\",\n \"name\": \"My Example Certificate\",\n \"active\": false,\n \"created_at\": 1234567,\n \"certificate_details\": {\n \"valid_at\": 12345667,\n \"expires_at\": 12345678\n }\n },\n {\n \"object\": \"organization.project.certificate\",\n \"id\": \"cert_def\",\n \"name\": \"My Example Certificate 2\",\n \"active\": false,\n \"created_at\": 1234567,\n \"certificate_details\": {\n \"valid_at\": 12345667,\n \"expires_at\": 12345678\n }\n },\n ],\n}\n" + } + } + } + }, + "/organization/projects/{project_id}/data_retention": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Retrieves project data retention controls.", + "operationId": "retrieve-project-data-retention", + "tags": [ + "Data retention" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project to inspect.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Project data retention controls retrieved successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProjectDataRetention" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Retrieve project data retention", + "group": "administration", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/organization/projects/proj_abc/data_retention \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"project.data_retention\",\n \"type\": \"organization_default\"\n}\n" + } + } + }, + "post": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Updates project data retention controls.", + "operationId": "update-project-data-retention", + "tags": [ + "Data retention" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project to update.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "The desired project data retention setting.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateProjectDataRetentionBody" + } + } + } + }, + "responses": { + "200": { + "description": "Project data retention controls updated successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProjectDataRetention" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Update project data retention", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/data_retention \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"retention_type\": \"modified_abuse_monitoring\"\n }'\n" + }, + "response": "{\n \"object\": \"project.data_retention\",\n \"type\": \"modified_abuse_monitoring\"\n}\n" + } + } + } + }, + "/organization/projects/{project_id}/groups": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Lists the groups that have access to a project.", + "operationId": "list-project-groups", + "tags": [ + "Project groups" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project to inspect.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "description": "A limit on the number of project groups to return. Defaults to 20.", + "required": false, + "schema": { + "type": "integer", + "minimum": 0, + "maximum": 100, + "default": 20 + } + }, + { + "name": "after", + "in": "query", + "description": "Cursor for pagination. Provide the ID of the last group from the previous response to fetch the next page.", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "order", + "in": "query", + "description": "Sort order for the returned groups.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "asc", + "desc" + ], + "default": "asc" + } + } + ], + "responses": { + "200": { + "description": "Project groups listed successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProjectGroupListResource" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "List project groups", + "group": "administration", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/organization/projects/proj_abc123/groups?limit=20 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"project.group\",\n \"project_id\": \"proj_abc123\",\n \"group_id\": \"group_01J1F8ABCDXYZ\",\n \"group_name\": \"Support Team\",\n \"created_at\": 1711471533\n }\n ],\n \"has_more\": false,\n \"next\": null\n}\n" + } + } + }, + "post": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Grants a group access to a project.", + "operationId": "add-project-group", + "tags": [ + "Project groups" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project to update.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "Identifies the group and role to assign to the project.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InviteProjectGroupBody" + } + } + } + }, + "responses": { + "200": { + "description": "Group granted access to the project successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProjectGroup" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Add project group", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X POST https://api.openai.com/v1/organization/projects/proj_abc123/groups \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"group_id\": \"group_01J1F8ABCDXYZ\",\n \"role\": \"role_01J1F8PROJ\"\n }'\n" + }, + "response": "{\n \"object\": \"project.group\",\n \"project_id\": \"proj_abc123\",\n \"group_id\": \"group_01J1F8ABCDXYZ\",\n \"group_name\": \"Support Team\",\n \"created_at\": 1711471533\n}\n" + } + } + } + }, + "/organization/projects/{project_id}/groups/{group_id}": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Retrieves a project's group.", + "operationId": "retrieve-project-group", + "tags": [ + "Project groups" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project to inspect.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "group_id", + "in": "path", + "description": "The ID of the group to retrieve.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "group_type", + "in": "query", + "description": "The type of group to retrieve.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "group", + "tenant_group" + ], + "default": "group" + } + } + ], + "responses": { + "200": { + "description": "Project group retrieved successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProjectGroup" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Retrieve project group", + "group": "administration", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/organization/projects/proj_abc123/groups/group_01J1F8ABCDXYZ \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"project.group\",\n \"project_id\": \"proj_abc123\",\n \"group_id\": \"group_01J1F8ABCDXYZ\",\n \"group_name\": \"Support Team\",\n \"group_type\": \"group\",\n \"created_at\": 1711471533\n}\n" + } + } + }, + "delete": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Revokes a group's access to a project.", + "operationId": "remove-project-group", + "tags": [ + "Project groups" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project to update.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "group_id", + "in": "path", + "description": "The ID of the group to remove from the project.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Group removed from the project successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProjectGroupDeletedResource" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Remove project group", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X DELETE https://api.openai.com/v1/organization/projects/proj_abc123/groups/group_01J1F8ABCDXYZ \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"project.group.deleted\",\n \"deleted\": true\n}\n" + } + } + } + }, + "/organization/projects/{project_id}/hosted_tool_permissions": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Returns hosted tool permissions for a project.", + "operationId": "retrieve-project-hosted-tool-permissions", + "tags": [ + "Hosted tools" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Project hosted tool permissions retrieved successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProjectHostedToolPermissions" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Retrieve project hosted tool permissions", + "group": "administration", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/organization/projects/proj_abc/hosted_tool_permissions \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"file_search\": {\n \"enabled\": true\n },\n \"web_search\": {\n \"enabled\": true\n },\n \"image_generation\": {\n \"enabled\": true\n },\n \"mcp\": {\n \"enabled\": true\n },\n \"code_interpreter\": {\n \"enabled\": true\n }\n}\n" + } + } + }, + "post": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Updates hosted tool permissions for a project.", + "operationId": "update-project-hosted-tool-permissions", + "tags": [ + "Hosted tools" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "The project hosted tool permissions update request payload.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProjectHostedToolPermissionsUpdateRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Project hosted tool permissions updated successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProjectHostedToolPermissions" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Modify project hosted tool permissions", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/hosted_tool_permissions \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"file_search\": {\n \"enabled\": true\n },\n \"image_generation\": {\n \"enabled\": false\n }\n }'\n" + }, + "response": "{\n \"file_search\": {\n \"enabled\": true\n },\n \"web_search\": {\n \"enabled\": true\n },\n \"image_generation\": {\n \"enabled\": false\n },\n \"mcp\": {\n \"enabled\": true\n },\n \"code_interpreter\": {\n \"enabled\": true\n }\n}\n" + } + } + } + }, + "/organization/projects/{project_id}/model_permissions": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Returns model permissions for a project.", + "operationId": "retrieve-project-model-permissions", + "tags": [ + "Projects" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Project model permissions retrieved successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProjectModelPermissions" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Retrieve project model permissions", + "group": "administration", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/organization/projects/proj_abc/model_permissions \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"project.model_permissions\",\n \"mode\": \"allow_list\",\n \"model_ids\": [\n \"gpt-6-astra\",\n \"o3\"\n ]\n}\n" + } + } + }, + "post": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Updates model permissions for a project.", + "operationId": "update-project-model-permissions", + "tags": [ + "Projects" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "The project model permissions update request payload.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProjectModelPermissionsUpdateRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Project model permissions updated successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProjectModelPermissions" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Modify project model permissions", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/model_permissions \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"mode\": \"deny_list\",\n \"model_ids\": [\n \"o3\"\n ]\n }'\n" + }, + "response": "{\n \"object\": \"project.model_permissions\",\n \"mode\": \"deny_list\",\n \"model_ids\": [\n \"o3\"\n ]\n}\n" + } + } + }, + "delete": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Deletes model permissions for a project.", + "operationId": "delete-project-model-permissions", + "tags": [ + "Projects" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Project model permissions deleted successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProjectModelPermissionsDeleteResponse" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Delete project model permissions", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X DELETE https://api.openai.com/v1/organization/projects/proj_abc/model_permissions \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"project.model_permissions.deleted\",\n \"deleted\": true\n}\n" + } + } + } + }, + "/organization/projects/{project_id}/rate_limits": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Returns the rate limits per model for a project.", + "operationId": "list-project-rate-limits", + "tags": [ + "Projects" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "description": "A limit on the number of objects to be returned. The default is 100.\n", + "required": false, + "schema": { + "type": "integer", + "default": 100 + } + }, + { + "name": "after", + "in": "query", + "description": "A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.\n", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "before", + "in": "query", + "description": "A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, beginning with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list.\n", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Project rate limits listed successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProjectRateLimitListResponse" + } + } + } + } + }, + "x-oaiMeta": { + "name": "List project rate limits", + "group": "administration", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/organization/projects/proj_abc/rate_limits?after=rl_xxx&limit=20 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"project.rate_limit\",\n \"id\": \"rl-ada\",\n \"model\": \"ada\",\n \"max_requests_per_1_minute\": 600,\n \"max_tokens_per_1_minute\": 150000,\n \"max_images_per_1_minute\": 10\n }\n ],\n \"first_id\": \"rl-ada\",\n \"last_id\": \"rl-ada\",\n \"has_more\": false\n}\n", + "error_response": "{\n \"code\": 404,\n \"message\": \"The project {project_id} was not found\"\n}\n" + } + } + } + }, + "/organization/projects/{project_id}/rate_limits/{rate_limit_id}": { + "post": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Updates a project rate limit.", + "operationId": "update-project-rate-limits", + "tags": [ + "Projects" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "rate_limit_id", + "in": "path", + "description": "The ID of the rate limit.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "The project rate limit update request payload.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProjectRateLimitUpdateRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Project rate limit updated successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProjectRateLimit" + } + } + } + }, + "400": { + "description": "Error response for various conditions.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Modify project rate limit", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/rate_limits/rl_xxx \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"max_requests_per_1_minute\": 500\n }'\n" + }, + "response": "{\n \"object\": \"project.rate_limit\",\n \"id\": \"rl-ada\",\n \"model\": \"ada\",\n \"max_requests_per_1_minute\": 600,\n \"max_tokens_per_1_minute\": 150000,\n \"max_images_per_1_minute\": 10\n }\n", + "error_response": "{\n \"code\": 404,\n \"message\": \"The project {project_id} was not found\"\n}\n" + } + } + } + }, + "/organization/projects/{project_id}/service_accounts": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Returns a list of service accounts in the project.", + "operationId": "list-project-service-accounts", + "tags": [ + "Projects" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "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.\n", + "required": false, + "schema": { + "type": "integer", + "default": 20 + } + }, + { + "name": "after", + "in": "query", + "description": "A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.\n", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Project service accounts listed successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProjectServiceAccountListResponse" + } + } + } + }, + "400": { + "description": "Error response when project is archived.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + }, + "x-oaiMeta": { + "name": "List project service accounts", + "group": "administration", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/organization/projects/proj_abc/service_accounts?after=custom_id&limit=20 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"organization.project.service_account\",\n \"id\": \"svc_acct_abc\",\n \"name\": \"Service Account\",\n \"role\": \"owner\",\n \"created_at\": 1711471533\n }\n ],\n \"first_id\": \"svc_acct_abc\",\n \"last_id\": \"svc_acct_xyz\",\n \"has_more\": false\n}\n" + } + } + }, + "post": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Creates a new service account in the project. By default, this also returns an unredacted API key for the service account.", + "operationId": "create-project-service-account", + "tags": [ + "Projects" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "The project service account create request payload.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProjectServiceAccountCreateRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Project service account created successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProjectServiceAccountCreateResponse" + } + } + } + }, + "400": { + "description": "Error response when project is archived.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Create project service account", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/service_accounts \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"Production App\"\n }'\n" + }, + "response": "{\n \"object\": \"organization.project.service_account\",\n \"id\": \"svc_acct_abc\",\n \"name\": \"Production App\",\n \"role\": \"member\",\n \"created_at\": 1711471533,\n \"api_key\": {\n \"object\": \"organization.project.service_account.api_key\",\n \"value\": \"sk-abcdefghijklmnop123\",\n \"name\": \"Secret Key\",\n \"created_at\": 1711471533,\n \"id\": \"key_abc\"\n }\n}\n" + } + } + } + }, + "/organization/projects/{project_id}/service_accounts/{service_account_id}": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Retrieves a service account in the project.", + "operationId": "retrieve-project-service-account", + "tags": [ + "Projects" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "service_account_id", + "in": "path", + "description": "The ID of the service account.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Project service account retrieved successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProjectServiceAccount" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Retrieve project service account", + "group": "administration", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/organization/projects/proj_abc/service_accounts/svc_acct_abc \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"organization.project.service_account\",\n \"id\": \"svc_acct_abc\",\n \"name\": \"Service Account\",\n \"role\": \"owner\",\n \"created_at\": 1711471533\n}\n" + } + } + }, + "post": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Updates a service account in the project.", + "operationId": "update-project-service-account", + "tags": [ + "Projects" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "service_account_id", + "in": "path", + "description": "The ID of the service account.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "Fields to update on the service account.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateProjectServiceAccountBody" + } + } + } + }, + "responses": { + "200": { + "description": "Project service account updated successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProjectServiceAccount" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Update project service account", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/service_accounts/svc_acct_abc \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"Updated service account\",\n \"role\": \"member\"\n }'\n" + }, + "response": "{\n \"object\": \"organization.project.service_account\",\n \"id\": \"svc_acct_abc\",\n \"name\": \"Updated service account\",\n \"role\": \"member\",\n \"created_at\": 1711471533\n}\n" + } + } + }, + "delete": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Deletes a service account from the project.\n\nReturns confirmation of service account deletion, or an error if the project\nis archived (archived projects have no service accounts).\n", + "operationId": "delete-project-service-account", + "tags": [ + "Projects" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "service_account_id", + "in": "path", + "description": "The ID of the service account.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Project service account deleted successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProjectServiceAccountDeleteResponse" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Delete project service account", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X DELETE https://api.openai.com/v1/organization/projects/proj_abc/service_accounts/svc_acct_abc \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"organization.project.service_account.deleted\",\n \"id\": \"svc_acct_abc\",\n \"deleted\": true\n}\n" + } + } + } + }, + "/organization/projects/{project_id}/spend_alerts": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Lists project spend alerts.", + "operationId": "list-project-spend-alerts", + "tags": [ + "Spend alerts" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project to inspect.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "description": "A limit on the number of spend alerts to return. Defaults to 20.", + "required": false, + "schema": { + "type": "integer", + "minimum": 0, + "maximum": 100 + } + }, + { + "name": "order", + "in": "query", + "description": "Sort order for the returned spend alerts.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "asc", + "desc" + ], + "default": "asc" + } + }, + { + "name": "after", + "in": "query", + "description": "Cursor for pagination. Provide the ID of the last spend alert from the previous response to fetch the next page.", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "before", + "in": "query", + "description": "Cursor for pagination. Provide the ID of the first spend alert from the previous response to fetch the previous page.", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Project spend alerts listed successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProjectSpendAlertListResource" + } + } + } + } + }, + "x-oaiMeta": { + "name": "List project spend alerts", + "group": "administration", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/organization/projects/proj_abc/spend_alerts?limit=20&order=asc \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"alert_abc123\",\n \"object\": \"project.spend_alert\",\n \"threshold_amount\": 100000,\n \"currency\": \"USD\",\n \"interval\": \"month\",\n \"notification_channel\": {\n \"type\": \"email\",\n \"recipients\": [\"finance@example.com\"],\n \"subject_prefix\": \"OpenAI spend alert\"\n }\n }\n ],\n \"first_id\": \"alert_abc123\",\n \"last_id\": \"alert_abc123\",\n \"has_more\": false\n}\n" + } + } + }, + "post": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Creates a project spend alert.", + "operationId": "create-project-spend-alert", + "tags": [ + "Spend alerts" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project to update.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "Parameters for the project spend alert you want to create.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateSpendAlertBody" + } + } + } + }, + "responses": { + "200": { + "description": "Project spend alert created successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProjectSpendAlert" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Create project spend alert", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/spend_alerts \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"threshold_amount\": 100000,\n \"currency\": \"USD\",\n \"interval\": \"month\",\n \"notification_channel\": {\n \"type\": \"email\",\n \"recipients\": [\"finance@example.com\"],\n \"subject_prefix\": \"OpenAI spend alert\"\n }\n }'\n" + }, + "response": "{\n \"id\": \"alert_abc123\",\n \"object\": \"project.spend_alert\",\n \"threshold_amount\": 100000,\n \"currency\": \"USD\",\n \"interval\": \"month\",\n \"notification_channel\": {\n \"type\": \"email\",\n \"recipients\": [\"finance@example.com\"],\n \"subject_prefix\": \"OpenAI spend alert\"\n }\n}\n" + } + } + } + }, + "/organization/projects/{project_id}/spend_alerts/{alert_id}": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Retrieves a project spend alert.", + "operationId": "retrieve-project-spend-alert", + "tags": [ + "Spend alerts" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "alert_id", + "in": "path", + "description": "The ID of the spend alert to retrieve.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Project spend alert retrieved successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProjectSpendAlert" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Retrieve project spend alert", + "group": "administration", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/organization/projects/proj_abc/spend_alerts/alert_abc123 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"id\": \"alert_abc123\",\n \"object\": \"project.spend_alert\",\n \"threshold_amount\": 150000,\n \"currency\": \"USD\",\n \"interval\": \"month\",\n \"notification_channel\": {\n \"type\": \"email\",\n \"recipients\": [\"finance@example.com\"],\n \"subject_prefix\": \"OpenAI spend alert\"\n }\n}\n" + } + } + }, + "post": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Updates a project spend alert.", + "operationId": "update-project-spend-alert", + "tags": [ + "Spend alerts" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project to update.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "alert_id", + "in": "path", + "description": "The ID of the spend alert to update.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "Fields to update on the project spend alert.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateSpendAlertBody" + } + } + } + }, + "responses": { + "200": { + "description": "Project spend alert updated successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProjectSpendAlert" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Update project spend alert", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/spend_alerts/alert_abc123 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"threshold_amount\": 150000,\n \"currency\": \"USD\",\n \"interval\": \"month\",\n \"notification_channel\": {\n \"type\": \"email\",\n \"recipients\": [\"finance@example.com\"],\n \"subject_prefix\": \"OpenAI spend alert\"\n }\n }'\n" + }, + "response": "{\n \"id\": \"alert_abc123\",\n \"object\": \"project.spend_alert\",\n \"threshold_amount\": 150000,\n \"currency\": \"USD\",\n \"interval\": \"month\",\n \"notification_channel\": {\n \"type\": \"email\",\n \"recipients\": [\"finance@example.com\"],\n \"subject_prefix\": \"OpenAI spend alert\"\n }\n}\n" + } + } + }, + "delete": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Deletes a project spend alert.", + "operationId": "delete-project-spend-alert", + "tags": [ + "Spend alerts" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project to update.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "alert_id", + "in": "path", + "description": "The ID of the spend alert to delete.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Project spend alert deleted successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProjectSpendAlertDeletedResource" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Delete project spend alert", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X DELETE https://api.openai.com/v1/organization/projects/proj_abc/spend_alerts/alert_abc123 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"id\": \"alert_abc123\",\n \"object\": \"project.spend_alert.deleted\",\n \"deleted\": true\n}\n" + } + } + } + }, + "/organization/projects/{project_id}/users": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Returns a list of users in the project.", + "operationId": "list-project-users", + "tags": [ + "Projects" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "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.\n", + "required": false, + "schema": { + "type": "integer", + "default": 20 + } + }, + { + "name": "after", + "in": "query", + "description": "A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.\n", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Project users listed successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProjectUserListResponse" + } + } + } + }, + "400": { + "description": "Error response when project is archived.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + }, + "x-oaiMeta": { + "name": "List project users", + "group": "administration", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/organization/projects/proj_abc/users?after=user_abc&limit=20 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"organization.project.user\",\n \"id\": \"user_abc\",\n \"name\": \"First Last\",\n \"email\": \"user@example.com\",\n \"role\": \"owner\",\n \"added_at\": 1711471533\n }\n ],\n \"first_id\": \"user-abc\",\n \"last_id\": \"user-xyz\",\n \"has_more\": false\n}\n" + } + } + }, + "post": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Adds a user to the project. Users must already be members of the organization to be added to a project.", + "operationId": "create-project-user", + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "tags": [ + "Projects" + ], + "requestBody": { + "description": "The project user create request payload.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProjectUserCreateRequest" + } + } + } + }, + "responses": { + "200": { + "description": "User added to project successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProjectUser" + } + } + } + }, + "400": { + "description": "Error response for various conditions.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Create project user", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/users \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"user_id\": \"user_abc\",\n \"role\": \"member\"\n }'\n" + }, + "response": "{\n \"object\": \"organization.project.user\",\n \"id\": \"user_abc\",\n \"email\": \"user@example.com\",\n \"role\": \"owner\",\n \"added_at\": 1711471533\n}\n" + } + } + } + }, + "/organization/projects/{project_id}/users/{user_id}": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Retrieves a user in the project.", + "operationId": "retrieve-project-user", + "tags": [ + "Projects" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "user_id", + "in": "path", + "description": "The ID of the user.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Project user retrieved successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProjectUser" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Retrieve project user", + "group": "administration", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/organization/projects/proj_abc/users/user_abc \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"organization.project.user\",\n \"id\": \"user_abc\",\n \"name\": \"First Last\",\n \"email\": \"user@example.com\",\n \"role\": \"owner\",\n \"added_at\": 1711471533\n}\n" + } + } + }, + "post": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Modifies a user's role in the project.", + "operationId": "modify-project-user", + "tags": [ + "Projects" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "user_id", + "in": "path", + "description": "The ID of the user.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "The project user update request payload.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProjectUserUpdateRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Project user's role updated successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProjectUser" + } + } + } + }, + "400": { + "description": "Error response for various conditions.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Modify project user", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/users/user_abc \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"role\": \"owner\"\n }'\n" + }, + "response": "{\n \"object\": \"organization.project.user\",\n \"id\": \"user_abc\",\n \"name\": \"First Last\",\n \"email\": \"user@example.com\",\n \"role\": \"owner\",\n \"added_at\": 1711471533\n}\n" + } + } + }, + "delete": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Deletes a user from the project.\n\nReturns confirmation of project user deletion, or an error if the project is\narchived (archived projects have no users).\n", + "operationId": "delete-project-user", + "tags": [ + "Projects" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "user_id", + "in": "path", + "description": "The ID of the user.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Project user deleted successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProjectUserDeleteResponse" + } + } + } + }, + "400": { + "description": "Error response for various conditions.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Delete project user", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X DELETE https://api.openai.com/v1/organization/projects/proj_abc/users/user_abc \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"organization.project.user.deleted\",\n \"id\": \"user_abc\",\n \"deleted\": true\n}\n" + } + } + } + }, + "/organization/roles": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Lists the roles configured for the organization.", + "operationId": "list-roles", + "tags": [ + "Roles" + ], + "parameters": [ + { + "name": "limit", + "in": "query", + "description": "A limit on the number of roles to return. Defaults to 1000.", + "required": false, + "schema": { + "type": "integer", + "minimum": 0, + "maximum": 1000, + "default": 1000 + } + }, + { + "name": "after", + "in": "query", + "description": "Cursor for pagination. Provide the value from the previous response's `next` field to continue listing roles.", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "order", + "in": "query", + "description": "Sort order for the returned roles.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "asc", + "desc" + ], + "default": "asc" + } + } + ], + "responses": { + "200": { + "description": "Roles listed successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PublicRoleListResource" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "List organization roles", + "group": "administration", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/organization/roles?limit=20 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"role\",\n \"id\": \"role_01J1F8ROLE01\",\n \"name\": \"API Group Manager\",\n \"description\": \"Allows managing organization groups\",\n \"permissions\": [\n \"api.groups.read\",\n \"api.groups.write\"\n ],\n \"resource_type\": \"api.organization\",\n \"predefined_role\": false\n }\n ],\n \"has_more\": false,\n \"next\": null\n}\n" + } + } + }, + "post": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Creates a custom role for the organization.", + "operationId": "create-role", + "tags": [ + "Roles" + ], + "requestBody": { + "description": "Parameters for the role you want to create.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PublicCreateOrganizationRoleBody" + } + } + } + }, + "responses": { + "200": { + "description": "Role created successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Role" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Create organization role", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X POST https://api.openai.com/v1/organization/roles \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"role_name\": \"API Group Manager\",\n \"permissions\": [\n \"api.groups.read\",\n \"api.groups.write\"\n ],\n \"description\": \"Allows managing organization groups\"\n }'\n" + }, + "response": "{\n \"object\": \"role\",\n \"id\": \"role_01J1F8ROLE01\",\n \"name\": \"API Group Manager\",\n \"description\": \"Allows managing organization groups\",\n \"permissions\": [\n \"api.groups.read\",\n \"api.groups.write\"\n ],\n \"resource_type\": \"api.organization\",\n \"predefined_role\": false\n}\n" + } + } + } + }, + "/organization/roles/{role_id}": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Retrieves an organization role.", + "operationId": "retrieve-role", + "tags": [ + "Roles" + ], + "parameters": [ + { + "name": "role_id", + "in": "path", + "description": "The ID of the role to retrieve.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Role retrieved successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Role" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Retrieve organization role", + "group": "administration", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/organization/roles/role_01J1F8ROLE01 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"role\",\n \"id\": \"role_01J1F8ROLE01\",\n \"name\": \"API Group Manager\",\n \"description\": \"Allows managing organization groups\",\n \"permissions\": [\n \"api.groups.read\",\n \"api.groups.write\"\n ],\n \"resource_type\": \"api.organization\",\n \"predefined_role\": false\n}\n" + } + } + }, + "post": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Updates an existing organization role.", + "operationId": "update-role", + "tags": [ + "Roles" + ], + "parameters": [ + { + "name": "role_id", + "in": "path", + "description": "The ID of the role to update.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "Fields to update on the role.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PublicUpdateOrganizationRoleBody" + } + } + } + }, + "responses": { + "200": { + "description": "Role updated successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Role" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Update organization role", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X POST https://api.openai.com/v1/organization/roles/role_01J1F8ROLE01 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"role_name\": \"API Group Manager\",\n \"permissions\": [\n \"api.groups.read\",\n \"api.groups.write\"\n ],\n \"description\": \"Allows managing organization groups\"\n }'\n" + }, + "response": "{\n \"object\": \"role\",\n \"id\": \"role_01J1F8ROLE01\",\n \"name\": \"API Group Manager\",\n \"description\": \"Allows managing organization groups\",\n \"permissions\": [\n \"api.groups.read\",\n \"api.groups.write\"\n ],\n \"resource_type\": \"api.organization\",\n \"predefined_role\": false\n}\n" + } + } + }, + "delete": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Deletes a custom role from the organization.", + "operationId": "delete-role", + "tags": [ + "Roles" + ], + "parameters": [ + { + "name": "role_id", + "in": "path", + "description": "The ID of the role to delete.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Role deleted successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RoleDeletedResource" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Delete organization role", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X DELETE https://api.openai.com/v1/organization/roles/role_01J1F8ROLE01 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"role.deleted\",\n \"id\": \"role_01J1F8ROLE01\",\n \"deleted\": true\n}\n" + } + } + } + }, + "/organization/spend_alerts": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Lists organization spend alerts.", + "operationId": "list-organization-spend-alerts", + "tags": [ + "Spend alerts" + ], + "parameters": [ + { + "name": "limit", + "in": "query", + "description": "A limit on the number of spend alerts to return. Defaults to 20.", + "required": false, + "schema": { + "type": "integer", + "minimum": 0, + "maximum": 100 + } + }, + { + "name": "order", + "in": "query", + "description": "Sort order for the returned spend alerts.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "asc", + "desc" + ], + "default": "asc" + } + }, + { + "name": "after", + "in": "query", + "description": "Cursor for pagination. Provide the ID of the last spend alert from the previous response to fetch the next page.", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "before", + "in": "query", + "description": "Cursor for pagination. Provide the ID of the first spend alert from the previous response to fetch the previous page.", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Organization spend alerts listed successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OrganizationSpendAlertListResource" + } + } + } + } + }, + "x-oaiMeta": { + "name": "List organization spend alerts", + "group": "administration", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/organization/spend_alerts?limit=20&order=asc \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"alert_abc123\",\n \"object\": \"organization.spend_alert\",\n \"threshold_amount\": 100000,\n \"currency\": \"USD\",\n \"interval\": \"month\",\n \"notification_channel\": {\n \"type\": \"email\",\n \"recipients\": [\"finance@example.com\"],\n \"subject_prefix\": \"OpenAI spend alert\"\n }\n }\n ],\n \"first_id\": \"alert_abc123\",\n \"last_id\": \"alert_abc123\",\n \"has_more\": false\n}\n" + } + } + }, + "post": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Creates an organization spend alert.", + "operationId": "create-organization-spend-alert", + "tags": [ + "Spend alerts" + ], + "requestBody": { + "description": "Parameters for the organization spend alert you want to create.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateSpendAlertBody" + } + } + } + }, + "responses": { + "200": { + "description": "Organization spend alert created successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OrganizationSpendAlert" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Create organization spend alert", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X POST https://api.openai.com/v1/organization/spend_alerts \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"threshold_amount\": 100000,\n \"currency\": \"USD\",\n \"interval\": \"month\",\n \"notification_channel\": {\n \"type\": \"email\",\n \"recipients\": [\"finance@example.com\"],\n \"subject_prefix\": \"OpenAI spend alert\"\n }\n }'\n" + }, + "response": "{\n \"id\": \"alert_abc123\",\n \"object\": \"organization.spend_alert\",\n \"threshold_amount\": 100000,\n \"currency\": \"USD\",\n \"interval\": \"month\",\n \"notification_channel\": {\n \"type\": \"email\",\n \"recipients\": [\"finance@example.com\"],\n \"subject_prefix\": \"OpenAI spend alert\"\n }\n}\n" + } + } + } + }, + "/organization/spend_alerts/{alert_id}": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Retrieves an organization spend alert.", + "operationId": "retrieve-organization-spend-alert", + "tags": [ + "Spend alerts" + ], + "parameters": [ + { + "name": "alert_id", + "in": "path", + "description": "The ID of the spend alert to retrieve.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Organization spend alert retrieved successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OrganizationSpendAlert" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Retrieve organization spend alert", + "group": "administration", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/organization/spend_alerts/alert_abc123 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"id\": \"alert_abc123\",\n \"object\": \"organization.spend_alert\",\n \"threshold_amount\": 150000,\n \"currency\": \"USD\",\n \"interval\": \"month\",\n \"notification_channel\": {\n \"type\": \"email\",\n \"recipients\": [\"finance@example.com\"],\n \"subject_prefix\": \"OpenAI spend alert\"\n }\n}\n" + } + } + }, + "post": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Updates an organization spend alert.", + "operationId": "update-organization-spend-alert", + "tags": [ + "Spend alerts" + ], + "parameters": [ + { + "name": "alert_id", + "in": "path", + "description": "The ID of the spend alert to update.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "Fields to update on the organization spend alert.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateSpendAlertBody" + } + } + } + }, + "responses": { + "200": { + "description": "Organization spend alert updated successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OrganizationSpendAlert" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Update organization spend alert", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X POST https://api.openai.com/v1/organization/spend_alerts/alert_abc123 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"threshold_amount\": 150000,\n \"currency\": \"USD\",\n \"interval\": \"month\",\n \"notification_channel\": {\n \"type\": \"email\",\n \"recipients\": [\"finance@example.com\"],\n \"subject_prefix\": \"OpenAI spend alert\"\n }\n }'\n" + }, + "response": "{\n \"id\": \"alert_abc123\",\n \"object\": \"organization.spend_alert\",\n \"threshold_amount\": 150000,\n \"currency\": \"USD\",\n \"interval\": \"month\",\n \"notification_channel\": {\n \"type\": \"email\",\n \"recipients\": [\"finance@example.com\"],\n \"subject_prefix\": \"OpenAI spend alert\"\n }\n}\n" + } + } + }, + "delete": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Deletes an organization spend alert.", + "operationId": "delete-organization-spend-alert", + "tags": [ + "Spend alerts" + ], + "parameters": [ + { + "name": "alert_id", + "in": "path", + "description": "The ID of the spend alert to delete.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Organization spend alert deleted successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OrganizationSpendAlertDeletedResource" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Delete organization spend alert", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X DELETE https://api.openai.com/v1/organization/spend_alerts/alert_abc123 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"id\": \"alert_abc123\",\n \"object\": \"organization.spend_alert.deleted\",\n \"deleted\": true\n}\n" + } + } + } + }, + "/organization/usage/audio_speeches": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Get audio speeches usage details for the organization.", + "operationId": "usage-audio-speeches", + "tags": [ + "Usage" + ], + "parameters": [ + { + "name": "start_time", + "in": "query", + "description": "Start time (Unix seconds) of the query time range, inclusive.", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "end_time", + "in": "query", + "description": "End time (Unix seconds) of the query time range, exclusive.", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "name": "bucket_width", + "in": "query", + "description": "Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "1m", + "1h", + "1d" + ], + "default": "1d" + } + }, + { + "name": "project_ids", + "in": "query", + "description": "Return only usage for these projects.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "user_ids", + "in": "query", + "description": "Return only usage for these users.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "api_key_ids", + "in": "query", + "description": "Return only usage for these API keys.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "models", + "in": "query", + "description": "Return only usage for these models.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "group_by", + "in": "query", + "description": "Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, `api_key_id`, `model` or any combination of them.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "project_id", + "user_id", + "api_key_id", + "model" + ] + } + } + }, + { + "name": "limit", + "in": "query", + "description": "Specifies the number of buckets to return.\n- `bucket_width=1d`: default: 7, max: 31\n- `bucket_width=1h`: default: 24, max: 168\n- `bucket_width=1m`: default: 60, max: 1440\n", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "name": "page", + "in": "query", + "description": "A cursor for use in pagination. Corresponding to the `next_page` field from the previous response.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Usage data retrieved successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UsageResponse" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Audio speeches", + "group": "usage-audio-speeches", + "examples": { + "request": { + "curl": "curl \"https://api.openai.com/v1/organization/usage/audio_speeches?start_time=1730419200&limit=1\" \\\n-H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n-H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"page\",\n \"data\": [\n {\n \"object\": \"bucket\",\n \"start_time\": 1730419200,\n \"end_time\": 1730505600,\n \"results\": [\n {\n \"object\": \"organization.usage.audio_speeches.result\",\n \"characters\": 45,\n \"num_model_requests\": 1,\n \"project_id\": null,\n \"user_id\": null,\n \"api_key_id\": null,\n \"model\": null\n }\n ]\n }\n ],\n \"has_more\": false,\n \"next_page\": null\n}\n" + } + } + } + }, + "/organization/usage/audio_transcriptions": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Get audio transcriptions usage details for the organization.", + "operationId": "usage-audio-transcriptions", + "tags": [ + "Usage" + ], + "parameters": [ + { + "name": "start_time", + "in": "query", + "description": "Start time (Unix seconds) of the query time range, inclusive.", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "end_time", + "in": "query", + "description": "End time (Unix seconds) of the query time range, exclusive.", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "name": "bucket_width", + "in": "query", + "description": "Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "1m", + "1h", + "1d" + ], + "default": "1d" + } + }, + { + "name": "project_ids", + "in": "query", + "description": "Return only usage for these projects.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "user_ids", + "in": "query", + "description": "Return only usage for these users.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "api_key_ids", + "in": "query", + "description": "Return only usage for these API keys.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "models", + "in": "query", + "description": "Return only usage for these models.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "group_by", + "in": "query", + "description": "Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, `api_key_id`, `model` or any combination of them.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "project_id", + "user_id", + "api_key_id", + "model" + ] + } + } + }, + { + "name": "limit", + "in": "query", + "description": "Specifies the number of buckets to return.\n- `bucket_width=1d`: default: 7, max: 31\n- `bucket_width=1h`: default: 24, max: 168\n- `bucket_width=1m`: default: 60, max: 1440\n", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "name": "page", + "in": "query", + "description": "A cursor for use in pagination. Corresponding to the `next_page` field from the previous response.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Usage data retrieved successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UsageResponse" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Audio transcriptions", + "group": "usage-audio-transcriptions", + "examples": { + "request": { + "curl": "curl \"https://api.openai.com/v1/organization/usage/audio_transcriptions?start_time=1730419200&limit=1\" \\\n-H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n-H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"page\",\n \"data\": [\n {\n \"object\": \"bucket\",\n \"start_time\": 1730419200,\n \"end_time\": 1730505600,\n \"results\": [\n {\n \"object\": \"organization.usage.audio_transcriptions.result\",\n \"seconds\": 20,\n \"num_model_requests\": 1,\n \"project_id\": null,\n \"user_id\": null,\n \"api_key_id\": null,\n \"model\": null\n }\n ]\n }\n ],\n \"has_more\": false,\n \"next_page\": null\n}\n" + } + } + } + }, + "/organization/usage/code_interpreter_sessions": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Get code interpreter sessions usage details for the organization.", + "operationId": "usage-code-interpreter-sessions", + "tags": [ + "Usage" + ], + "parameters": [ + { + "name": "start_time", + "in": "query", + "description": "Start time (Unix seconds) of the query time range, inclusive.", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "end_time", + "in": "query", + "description": "End time (Unix seconds) of the query time range, exclusive.", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "name": "bucket_width", + "in": "query", + "description": "Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "1m", + "1h", + "1d" + ], + "default": "1d" + } + }, + { + "name": "project_ids", + "in": "query", + "description": "Return only usage for these projects.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "group_by", + "in": "query", + "description": "Group the usage data by the specified fields. Support fields include `project_id`.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "project_id" + ] + } + } + }, + { + "name": "limit", + "in": "query", + "description": "Specifies the number of buckets to return.\n- `bucket_width=1d`: default: 7, max: 31\n- `bucket_width=1h`: default: 24, max: 168\n- `bucket_width=1m`: default: 60, max: 1440\n", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "name": "page", + "in": "query", + "description": "A cursor for use in pagination. Corresponding to the `next_page` field from the previous response.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Usage data retrieved successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UsageResponse" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Code interpreter sessions", + "group": "usage-code-interpreter-sessions", + "examples": { + "request": { + "curl": "curl \"https://api.openai.com/v1/organization/usage/code_interpreter_sessions?start_time=1730419200&limit=1\" \\\n-H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n-H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"page\",\n \"data\": [\n {\n \"object\": \"bucket\",\n \"start_time\": 1730419200,\n \"end_time\": 1730505600,\n \"results\": [\n {\n \"object\": \"organization.usage.code_interpreter_sessions.result\",\n \"num_sessions\": 1,\n \"project_id\": null\n }\n ]\n }\n ],\n \"has_more\": false,\n \"next_page\": null\n}\n" + } + } + } + }, + "/organization/usage/completions": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Get completions usage details for the organization.", + "operationId": "usage-completions", + "tags": [ + "Usage" + ], + "parameters": [ + { + "name": "start_time", + "in": "query", + "description": "Start time (Unix seconds) of the query time range, inclusive.", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "end_time", + "in": "query", + "description": "End time (Unix seconds) of the query time range, exclusive.", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "name": "bucket_width", + "in": "query", + "description": "Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "1m", + "1h", + "1d" + ], + "default": "1d" + } + }, + { + "name": "project_ids", + "in": "query", + "description": "Return only usage for these projects.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "user_ids", + "in": "query", + "description": "Return only usage for these users.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "api_key_ids", + "in": "query", + "description": "Return only usage for these API keys.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "models", + "in": "query", + "description": "Return only usage for these models.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "batch", + "in": "query", + "description": "If `true`, return batch jobs only. If `false`, return non-batch jobs only. By default, return both.\n", + "required": false, + "schema": { + "type": "boolean" + } + }, + { + "name": "group_by", + "in": "query", + "description": "Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, `api_key_id`, `model`, `batch`, `service_tier` or any combination of them.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "project_id", + "user_id", + "api_key_id", + "model", + "batch", + "service_tier" + ] + } + } + }, + { + "name": "limit", + "in": "query", + "description": "Specifies the number of buckets to return.\n- `bucket_width=1d`: default: 7, max: 31\n- `bucket_width=1h`: default: 24, max: 168\n- `bucket_width=1m`: default: 60, max: 1440\n", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "name": "page", + "in": "query", + "description": "A cursor for use in pagination. Corresponding to the `next_page` field from the previous response.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Usage data retrieved successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UsageResponse" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Completions", + "group": "usage-completions", + "examples": { + "request": { + "curl": "curl \"https://api.openai.com/v1/organization/usage/completions?start_time=1730419200&limit=1\" \\\n-H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n-H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"page\",\n \"data\": [\n {\n \"object\": \"bucket\",\n \"start_time\": 1730419200,\n \"end_time\": 1730505600,\n \"results\": [\n {\n \"object\": \"organization.usage.completions.result\",\n \"input_tokens\": 1000,\n \"input_cached_tokens\": 400,\n \"input_cache_write_tokens\": 100,\n \"input_uncached_tokens\": 500,\n \"output_tokens\": 500,\n \"input_text_tokens\": 400,\n \"output_text_tokens\": 400,\n \"input_cached_text_tokens\": 300,\n \"input_audio_tokens\": 50,\n \"input_cached_audio_tokens\": 50,\n \"output_audio_tokens\": 50,\n \"input_image_tokens\": 50,\n \"input_cached_image_tokens\": 50,\n \"output_image_tokens\": 50,\n \"num_model_requests\": 5,\n \"project_id\": null,\n \"user_id\": null,\n \"api_key_id\": null,\n \"model\": null,\n \"batch\": null,\n \"service_tier\": null\n }\n ]\n }\n ],\n \"has_more\": true,\n \"next_page\": \"page_AAAAAGdGxdEiJdKOAAAAAGcqsYA=\"\n}\n" + } + } + } + }, + "/organization/usage/embeddings": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Get embeddings usage details for the organization.", + "operationId": "usage-embeddings", + "tags": [ + "Usage" + ], + "parameters": [ + { + "name": "start_time", + "in": "query", + "description": "Start time (Unix seconds) of the query time range, inclusive.", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "end_time", + "in": "query", + "description": "End time (Unix seconds) of the query time range, exclusive.", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "name": "bucket_width", + "in": "query", + "description": "Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "1m", + "1h", + "1d" + ], + "default": "1d" + } + }, + { + "name": "project_ids", + "in": "query", + "description": "Return only usage for these projects.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "user_ids", + "in": "query", + "description": "Return only usage for these users.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "api_key_ids", + "in": "query", + "description": "Return only usage for these API keys.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "models", + "in": "query", + "description": "Return only usage for these models.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "group_by", + "in": "query", + "description": "Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, `api_key_id`, `model` or any combination of them.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "project_id", + "user_id", + "api_key_id", + "model" + ] + } + } + }, + { + "name": "limit", + "in": "query", + "description": "Specifies the number of buckets to return.\n- `bucket_width=1d`: default: 7, max: 31\n- `bucket_width=1h`: default: 24, max: 168\n- `bucket_width=1m`: default: 60, max: 1440\n", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "name": "page", + "in": "query", + "description": "A cursor for use in pagination. Corresponding to the `next_page` field from the previous response.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Usage data retrieved successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UsageResponse" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Embeddings", + "group": "usage-embeddings", + "examples": { + "request": { + "curl": "curl \"https://api.openai.com/v1/organization/usage/embeddings?start_time=1730419200&limit=1\" \\\n-H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n-H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"page\",\n \"data\": [\n {\n \"object\": \"bucket\",\n \"start_time\": 1730419200,\n \"end_time\": 1730505600,\n \"results\": [\n {\n \"object\": \"organization.usage.embeddings.result\",\n \"input_tokens\": 16,\n \"num_model_requests\": 2,\n \"project_id\": null,\n \"user_id\": null,\n \"api_key_id\": null,\n \"model\": null\n }\n ]\n }\n ],\n \"has_more\": false,\n \"next_page\": null\n}\n" + } + } + } + }, + "/organization/usage/file_search_calls": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Get file search calls usage details for the organization.", + "operationId": "usage-file-search-calls", + "tags": [ + "Usage" + ], + "parameters": [ + { + "name": "start_time", + "in": "query", + "description": "Start time (Unix seconds) of the query time range, inclusive.", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "end_time", + "in": "query", + "description": "End time (Unix seconds) of the query time range, exclusive.", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "name": "bucket_width", + "in": "query", + "description": "Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "1m", + "1h", + "1d" + ], + "default": "1d" + } + }, + { + "name": "project_ids", + "in": "query", + "description": "Return only usage for these projects.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "user_ids", + "in": "query", + "description": "Return only usage for these users.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "api_key_ids", + "in": "query", + "description": "Return only usage for these API keys.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "vector_store_ids", + "in": "query", + "description": "Return only usage for these vector stores.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "group_by", + "in": "query", + "description": "Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, `api_key_id`, `vector_store_id` or any combination of them.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "project_id", + "user_id", + "api_key_id", + "vector_store_id" + ] + } + } + }, + { + "name": "limit", + "in": "query", + "description": "Specifies the number of buckets to return.\n- `bucket_width=1d`: default: 7, max: 31\n- `bucket_width=1h`: default: 24, max: 168\n- `bucket_width=1m`: default: 60, max: 1440\n", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "name": "page", + "in": "query", + "description": "A cursor for use in pagination. Corresponding to the `next_page` field from the previous response.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Usage data retrieved successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UsageResponse" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "File search calls", + "group": "usage-file-search-calls", + "examples": { + "request": { + "curl": "curl \"https://api.openai.com/v1/organization/usage/file_search_calls?start_time=1730419200&limit=1\" \\\n-H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n-H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"page\",\n \"data\": [\n {\n \"object\": \"bucket\",\n \"start_time\": 1730419200,\n \"end_time\": 1730505600,\n \"results\": [\n {\n \"object\": \"organization.usage.file_searches.result\",\n \"num_requests\": 2,\n \"project_id\": null,\n \"user_id\": null,\n \"api_key_id\": null,\n \"vector_store_id\": null\n }\n ]\n }\n ],\n \"has_more\": false,\n \"next_page\": null\n}\n" + } + } + } + }, + "/organization/usage/images": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Get images usage details for the organization.", + "operationId": "usage-images", + "tags": [ + "Usage" + ], + "parameters": [ + { + "name": "start_time", + "in": "query", + "description": "Start time (Unix seconds) of the query time range, inclusive.", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "end_time", + "in": "query", + "description": "End time (Unix seconds) of the query time range, exclusive.", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "name": "bucket_width", + "in": "query", + "description": "Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "1m", + "1h", + "1d" + ], + "default": "1d" + } + }, + { + "name": "sources", + "in": "query", + "description": "Return only usages for these sources. Possible values are `image.generation`, `image.edit`, `image.variation` or any combination of them.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "image.generation", + "image.edit", + "image.variation" + ] + } + } + }, + { + "name": "sizes", + "in": "query", + "description": "Return only usages for these image sizes. Possible values are `256x256`, `512x512`, `1024x1024`, `1792x1792`, `1024x1792` or any combination of them.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "256x256", + "512x512", + "1024x1024", + "1792x1792", + "1024x1792" + ] + } + } + }, + { + "name": "project_ids", + "in": "query", + "description": "Return only usage for these projects.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "user_ids", + "in": "query", + "description": "Return only usage for these users.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "api_key_ids", + "in": "query", + "description": "Return only usage for these API keys.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "models", + "in": "query", + "description": "Return only usage for these models.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "group_by", + "in": "query", + "description": "Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, `api_key_id`, `model`, `size`, `source` or any combination of them.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "project_id", + "user_id", + "api_key_id", + "model", + "size", + "source" + ] + } + } + }, + { + "name": "limit", + "in": "query", + "description": "Specifies the number of buckets to return.\n- `bucket_width=1d`: default: 7, max: 31\n- `bucket_width=1h`: default: 24, max: 168\n- `bucket_width=1m`: default: 60, max: 1440\n", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "name": "page", + "in": "query", + "description": "A cursor for use in pagination. Corresponding to the `next_page` field from the previous response.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Usage data retrieved successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UsageResponse" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Images", + "group": "usage-images", + "examples": { + "request": { + "curl": "curl \"https://api.openai.com/v1/organization/usage/images?start_time=1730419200&limit=1\" \\\n-H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n-H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"page\",\n \"data\": [\n {\n \"object\": \"bucket\",\n \"start_time\": 1730419200,\n \"end_time\": 1730505600,\n \"results\": [\n {\n \"object\": \"organization.usage.images.result\",\n \"images\": 2,\n \"num_model_requests\": 2,\n \"size\": null,\n \"source\": null,\n \"project_id\": null,\n \"user_id\": null,\n \"api_key_id\": null,\n \"model\": null\n }\n ]\n }\n ],\n \"has_more\": false,\n \"next_page\": null\n}\n" + } + } + } + }, + "/organization/usage/moderations": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Get moderations usage details for the organization.", + "operationId": "usage-moderations", + "tags": [ + "Usage" + ], + "parameters": [ + { + "name": "start_time", + "in": "query", + "description": "Start time (Unix seconds) of the query time range, inclusive.", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "end_time", + "in": "query", + "description": "End time (Unix seconds) of the query time range, exclusive.", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "name": "bucket_width", + "in": "query", + "description": "Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "1m", + "1h", + "1d" + ], + "default": "1d" + } + }, + { + "name": "project_ids", + "in": "query", + "description": "Return only usage for these projects.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "user_ids", + "in": "query", + "description": "Return only usage for these users.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "api_key_ids", + "in": "query", + "description": "Return only usage for these API keys.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "models", + "in": "query", + "description": "Return only usage for these models.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "group_by", + "in": "query", + "description": "Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, `api_key_id`, `model` or any combination of them.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "project_id", + "user_id", + "api_key_id", + "model" + ] + } + } + }, + { + "name": "limit", + "in": "query", + "description": "Specifies the number of buckets to return.\n- `bucket_width=1d`: default: 7, max: 31\n- `bucket_width=1h`: default: 24, max: 168\n- `bucket_width=1m`: default: 60, max: 1440\n", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "name": "page", + "in": "query", + "description": "A cursor for use in pagination. Corresponding to the `next_page` field from the previous response.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Usage data retrieved successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UsageResponse" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Moderations", + "group": "usage-moderations", + "examples": { + "request": { + "curl": "curl \"https://api.openai.com/v1/organization/usage/moderations?start_time=1730419200&limit=1\" \\\n-H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n-H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"page\",\n \"data\": [\n {\n \"object\": \"bucket\",\n \"start_time\": 1730419200,\n \"end_time\": 1730505600,\n \"results\": [\n {\n \"object\": \"organization.usage.moderations.result\",\n \"input_tokens\": 16,\n \"num_model_requests\": 2,\n \"project_id\": null,\n \"user_id\": null,\n \"api_key_id\": null,\n \"model\": null\n }\n ]\n }\n ],\n \"has_more\": false,\n \"next_page\": null\n}\n" + } + } + } + }, + "/organization/usage/vector_stores": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Get vector stores usage details for the organization.", + "operationId": "usage-vector-stores", + "tags": [ + "Usage" + ], + "parameters": [ + { + "name": "start_time", + "in": "query", + "description": "Start time (Unix seconds) of the query time range, inclusive.", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "end_time", + "in": "query", + "description": "End time (Unix seconds) of the query time range, exclusive.", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "name": "bucket_width", + "in": "query", + "description": "Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "1m", + "1h", + "1d" + ], + "default": "1d" + } + }, + { + "name": "project_ids", + "in": "query", + "description": "Return only usage for these projects.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "group_by", + "in": "query", + "description": "Group the usage data by the specified fields. Support fields include `project_id`.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "project_id" + ] + } + } + }, + { + "name": "limit", + "in": "query", + "description": "Specifies the number of buckets to return.\n- `bucket_width=1d`: default: 7, max: 31\n- `bucket_width=1h`: default: 24, max: 168\n- `bucket_width=1m`: default: 60, max: 1440\n", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "name": "page", + "in": "query", + "description": "A cursor for use in pagination. Corresponding to the `next_page` field from the previous response.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Usage data retrieved successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UsageResponse" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Vector stores", + "group": "usage-vector-stores", + "examples": { + "request": { + "curl": "curl \"https://api.openai.com/v1/organization/usage/vector_stores?start_time=1730419200&limit=1\" \\\n-H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n-H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"page\",\n \"data\": [\n {\n \"object\": \"bucket\",\n \"start_time\": 1730419200,\n \"end_time\": 1730505600,\n \"results\": [\n {\n \"object\": \"organization.usage.vector_stores.result\",\n \"usage_bytes\": 1024,\n \"project_id\": null\n }\n ]\n }\n ],\n \"has_more\": false,\n \"next_page\": null\n}\n" + } + } + } + }, + "/organization/usage/web_search_calls": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Get web search calls usage details for the organization.", + "operationId": "usage-web-search-calls", + "tags": [ + "Usage" + ], + "parameters": [ + { + "name": "start_time", + "in": "query", + "description": "Start time (Unix seconds) of the query time range, inclusive.", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "end_time", + "in": "query", + "description": "End time (Unix seconds) of the query time range, exclusive.", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "name": "bucket_width", + "in": "query", + "description": "Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "1m", + "1h", + "1d" + ], + "default": "1d" + } + }, + { + "name": "project_ids", + "in": "query", + "description": "Return only usage for these projects.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "user_ids", + "in": "query", + "description": "Return only usage for these users.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "api_key_ids", + "in": "query", + "description": "Return only usage for these API keys.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "models", + "in": "query", + "description": "Return only usage for these models.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "context_levels", + "in": "query", + "description": "Return only web search usage for these context levels.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "low", + "medium", + "high" + ] + } + } + }, + { + "name": "group_by", + "in": "query", + "description": "Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, `api_key_id`, `model`, `context_level` or any combination of them.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "project_id", + "user_id", + "api_key_id", + "model", + "context_level" + ] + } + } + }, + { + "name": "limit", + "in": "query", + "description": "Specifies the number of buckets to return.\n- `bucket_width=1d`: default: 7, max: 31\n- `bucket_width=1h`: default: 24, max: 168\n- `bucket_width=1m`: default: 60, max: 1440\n", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "name": "page", + "in": "query", + "description": "A cursor for use in pagination. Corresponding to the `next_page` field from the previous response.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Usage data retrieved successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UsageResponse" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Web search calls", + "group": "usage-web-search-calls", + "examples": { + "request": { + "curl": "curl \"https://api.openai.com/v1/organization/usage/web_search_calls?start_time=1730419200&limit=1\" \\\n-H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n-H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"page\",\n \"data\": [\n {\n \"object\": \"bucket\",\n \"start_time\": 1730419200,\n \"end_time\": 1730505600,\n \"results\": [\n {\n \"object\": \"organization.usage.web_searches.result\",\n \"num_model_requests\": 2,\n \"num_requests\": 2,\n \"project_id\": null,\n \"user_id\": null,\n \"api_key_id\": null,\n \"model\": null,\n \"context_level\": null\n }\n ]\n }\n ],\n \"has_more\": false,\n \"next_page\": null\n}\n" + } + } + } + }, + "/organization/users": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Lists all of the users in the organization.", + "operationId": "list-users", + "tags": [ + "Users" + ], + "parameters": [ + { + "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.\n", + "required": false, + "schema": { + "type": "integer", + "default": 20 + } + }, + { + "name": "after", + "in": "query", + "description": "A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.\n", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "emails", + "in": "query", + "description": "Filter by the email address of users.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + } + ], + "responses": { + "200": { + "description": "Users listed successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UserListResponse" + } + } + } + } + }, + "x-oaiMeta": { + "name": "List users", + "group": "administration", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/organization/users?after=user_abc&limit=20 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"organization.user\",\n \"id\": \"user_abc\",\n \"name\": \"First Last\",\n \"email\": \"user@example.com\",\n \"role\": \"owner\",\n \"added_at\": 1711471533\n }\n ],\n \"first_id\": \"user-abc\",\n \"last_id\": \"user-xyz\",\n \"has_more\": false\n}\n" + } + } + } + }, + "/organization/users/{user_id}": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Retrieves a user by their identifier.", + "operationId": "retrieve-user", + "tags": [ + "Users" + ], + "parameters": [ + { + "name": "user_id", + "in": "path", + "description": "The ID of the user.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "User retrieved successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/User" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Retrieve user", + "group": "administration", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/organization/users/user_abc \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"organization.user\",\n \"id\": \"user_abc\",\n \"name\": \"First Last\",\n \"email\": \"user@example.com\",\n \"role\": \"owner\",\n \"added_at\": 1711471533\n}\n" + } + } + }, + "post": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Modifies a user's role in the organization.", + "operationId": "modify-user", + "tags": [ + "Users" + ], + "parameters": [ + { + "name": "user_id", + "in": "path", + "description": "The ID of the user.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "The new user role to modify. This must be one of `owner` or `member`.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UserRoleUpdateRequest" + } + } + } + }, + "responses": { + "200": { + "description": "User role updated successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/User" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Modify user", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X POST https://api.openai.com/v1/organization/users/user_abc \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"role\": \"owner\"\n }'\n" + }, + "response": "{\n \"object\": \"organization.user\",\n \"id\": \"user_abc\",\n \"name\": \"First Last\",\n \"email\": \"user@example.com\",\n \"role\": \"owner\",\n \"added_at\": 1711471533\n}\n" + } + } + }, + "delete": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Deletes a user from the organization.", + "operationId": "delete-user", + "tags": [ + "Users" + ], + "parameters": [ + { + "name": "user_id", + "in": "path", + "description": "The ID of the user.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "User deleted successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UserDeleteResponse" + } + } + } + } + }, + "x-oaiMeta": { + "name": "Delete user", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X DELETE https://api.openai.com/v1/organization/users/user_abc \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"organization.user.deleted\",\n \"id\": \"user_abc\",\n \"deleted\": true\n}\n" + } + } + } + }, + "/organization/users/{user_id}/roles": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Lists the organization roles assigned to a user within the organization.", + "operationId": "list-user-role-assignments", + "tags": [ + "User organization role assignments" + ], + "parameters": [ + { + "name": "user_id", + "in": "path", + "description": "The ID of the user to inspect.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "description": "A limit on the number of organization role assignments to return.", + "required": false, + "schema": { + "type": "integer", + "minimum": 0, + "maximum": 1000 + } + }, + { + "name": "after", + "in": "query", + "description": "Cursor for pagination. Provide the value from the previous response's `next` field to continue listing organization roles.", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "order", + "in": "query", + "description": "Sort order for the returned organization roles.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "asc", + "desc" + ] + } + } + ], + "responses": { + "200": { + "description": "User organization role assignments listed successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RoleListResource" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "List user organization role assignments", + "group": "administration", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/organization/users/user_abc123/roles \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"role_01J1F8ROLE01\",\n \"name\": \"API Group Manager\",\n \"permissions\": [\n \"api.groups.read\",\n \"api.groups.write\"\n ],\n \"resource_type\": \"api.organization\",\n \"predefined_role\": false,\n \"description\": \"Allows managing organization groups\",\n \"created_at\": 1711471533,\n \"updated_at\": 1711472599,\n \"created_by\": \"user_abc123\",\n \"created_by_user_obj\": {\n \"id\": \"user_abc123\",\n \"name\": \"Ada Lovelace\",\n \"email\": \"ada@example.com\"\n },\n \"metadata\": {}\n }\n ],\n \"has_more\": false,\n \"next\": null\n}\n" + } + } + }, + "post": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Assigns an organization role to a user within the organization.", + "operationId": "assign-user-role", + "tags": [ + "User organization role assignments" + ], + "parameters": [ + { + "name": "user_id", + "in": "path", + "description": "The ID of the user that should receive the organization role.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "Identifies the organization role to assign to the user.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PublicAssignOrganizationGroupRoleBody" + } + } + } + }, + "responses": { + "200": { + "description": "Organization role assigned to the user successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UserRoleAssignment" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Assign organization role to user", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X POST https://api.openai.com/v1/organization/users/user_abc123/roles \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"role_id\": \"role_01J1F8ROLE01\"\n }'\n" + }, + "response": "{\n \"object\": \"user.role\",\n \"user\": {\n \"object\": \"organization.user\",\n \"id\": \"user_abc123\",\n \"name\": \"Ada Lovelace\",\n \"email\": \"ada@example.com\",\n \"role\": \"owner\",\n \"added_at\": 1711470000\n },\n \"role\": {\n \"object\": \"role\",\n \"id\": \"role_01J1F8ROLE01\",\n \"name\": \"API Group Manager\",\n \"description\": \"Allows managing organization groups\",\n \"permissions\": [\n \"api.groups.read\",\n \"api.groups.write\"\n ],\n \"resource_type\": \"api.organization\",\n \"predefined_role\": false\n }\n}\n" + } + } + } + }, + "/organization/users/{user_id}/roles/{role_id}": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Retrieves an organization role assigned to a user.", + "operationId": "retrieve-user-role", + "tags": [ + "User organization role assignments" + ], + "parameters": [ + { + "name": "user_id", + "in": "path", + "description": "The ID of the user to inspect.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "role_id", + "in": "path", + "description": "The ID of the organization role to retrieve for the user.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Organization role retrieved for the user successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AssignedRoleDetails" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Retrieve user organization role", + "group": "administration", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/organization/users/user_abc123/roles/role_01J1F8ROLE01 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"id\": \"role_01J1F8ROLE01\",\n \"name\": \"API Group Manager\",\n \"permissions\": [\n \"api.groups.read\",\n \"api.groups.write\"\n ],\n \"resource_type\": \"api.organization\",\n \"predefined_role\": false,\n \"description\": \"Allows managing organization groups\",\n \"created_at\": 1711471533,\n \"updated_at\": 1711472599,\n \"created_by\": \"user_abc123\",\n \"created_by_user_obj\": null,\n \"metadata\": {},\n \"assignment_sources\": null\n}\n" + } + } + }, + "delete": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Unassigns an organization role from a user within the organization.", + "operationId": "unassign-user-role", + "tags": [ + "User organization role assignments" + ], + "parameters": [ + { + "name": "user_id", + "in": "path", + "description": "The ID of the user to modify.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "role_id", + "in": "path", + "description": "The ID of the organization role to remove from the user.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Organization role unassigned from the user successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeletedRoleAssignmentResource" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Unassign organization role from user", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X DELETE https://api.openai.com/v1/organization/users/user_abc123/roles/role_01J1F8ROLE01 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"user.role.deleted\",\n \"deleted\": true\n}\n" + } + } + } + }, + "/projects/{project_id}/groups/{group_id}/roles": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Lists the project roles assigned to a group within a project.", + "operationId": "list-project-group-role-assignments", + "tags": [ + "Project group role assignments" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project to inspect.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "group_id", + "in": "path", + "description": "The ID of the group to inspect.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "description": "A limit on the number of project role assignments to return.", + "required": false, + "schema": { + "type": "integer", + "minimum": 0, + "maximum": 1000 + } + }, + { + "name": "after", + "in": "query", + "description": "Cursor for pagination. Provide the value from the previous response's `next` field to continue listing project roles.", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "order", + "in": "query", + "description": "Sort order for the returned project roles.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "asc", + "desc" + ] + } + } + ], + "responses": { + "200": { + "description": "Project group role assignments listed successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RoleListResource" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "List project group role assignments", + "group": "administration", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/projects/proj_abc123/groups/group_01J1F8ABCDXYZ/roles \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"role_01J1F8PROJ\",\n \"name\": \"API Project Key Manager\",\n \"permissions\": [\n \"api.organization.projects.api_keys.read\",\n \"api.organization.projects.api_keys.write\"\n ],\n \"resource_type\": \"api.project\",\n \"predefined_role\": false,\n \"description\": \"Allows managing API keys for the project\",\n \"created_at\": 1711471533,\n \"updated_at\": 1711472599,\n \"created_by\": \"user_abc123\",\n \"created_by_user_obj\": {\n \"id\": \"user_abc123\",\n \"name\": \"Ada Lovelace\",\n \"email\": \"ada@example.com\"\n },\n \"metadata\": {}\n }\n ],\n \"has_more\": false,\n \"next\": null\n}\n" + } + } + }, + "post": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Assigns a project role to a group within a project.", + "operationId": "assign-project-group-role", + "tags": [ + "Project group role assignments" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project to update.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "group_id", + "in": "path", + "description": "The ID of the group that should receive the project role.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "Identifies the project role to assign to the group.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PublicAssignOrganizationGroupRoleBody" + } + } + } + }, + "responses": { + "200": { + "description": "Project role assigned to the group successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GroupRoleAssignment" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Assign project role to group", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X POST https://api.openai.com/v1/projects/proj_abc123/groups/group_01J1F8ABCDXYZ/roles \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"role_id\": \"role_01J1F8PROJ\"\n }'\n" + }, + "response": "{\n \"object\": \"group.role\",\n \"group\": {\n \"object\": \"group\",\n \"id\": \"group_01J1F8ABCDXYZ\",\n \"name\": \"Support Team\",\n \"created_at\": 1711471533,\n \"scim_managed\": false\n },\n \"role\": {\n \"object\": \"role\",\n \"id\": \"role_01J1F8PROJ\",\n \"name\": \"API Project Key Manager\",\n \"description\": \"Allows managing API keys for the project\",\n \"permissions\": [\n \"api.organization.projects.api_keys.read\",\n \"api.organization.projects.api_keys.write\"\n ],\n \"resource_type\": \"api.project\",\n \"predefined_role\": false\n }\n}\n" + } + } + } + }, + "/projects/{project_id}/groups/{group_id}/roles/{role_id}": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Retrieves a project role assigned to a group.", + "operationId": "retrieve-project-group-role", + "tags": [ + "Project group role assignments" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project to inspect.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "group_id", + "in": "path", + "description": "The ID of the group to inspect.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "role_id", + "in": "path", + "description": "The ID of the project role to retrieve for the group.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Project role retrieved for the group successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AssignedRoleDetails" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Retrieve project group role", + "group": "administration", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/projects/proj_abc123/groups/group_01J1F8ABCDXYZ/roles/role_01J1F8PROJ \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"id\": \"role_01J1F8PROJ\",\n \"name\": \"API Project Key Manager\",\n \"permissions\": [\n \"api.organization.projects.api_keys.read\",\n \"api.organization.projects.api_keys.write\"\n ],\n \"resource_type\": \"api.project\",\n \"predefined_role\": false,\n \"description\": \"Allows managing API keys for the project\",\n \"created_at\": 1711471533,\n \"updated_at\": 1711472599,\n \"created_by\": \"user_abc123\",\n \"created_by_user_obj\": null,\n \"metadata\": {},\n \"assignment_sources\": null\n}\n" + } + } + }, + "delete": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Unassigns a project role from a group within a project.", + "operationId": "unassign-project-group-role", + "tags": [ + "Project group role assignments" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project to modify.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "group_id", + "in": "path", + "description": "The ID of the group whose project role assignment should be removed.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "role_id", + "in": "path", + "description": "The ID of the project role to remove from the group.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Project role unassigned from the group successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeletedRoleAssignmentResource" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Unassign project role from group", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X DELETE https://api.openai.com/v1/projects/proj_abc123/groups/group_01J1F8ABCDXYZ/roles/role_01J1F8PROJ \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"group.role.deleted\",\n \"deleted\": true\n}\n" + } + } + } + }, + "/projects/{project_id}/roles": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Lists the roles configured for a project.", + "operationId": "list-project-roles", + "tags": [ + "Roles" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project to inspect.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "description": "A limit on the number of roles to return. Defaults to 1000.", + "required": false, + "schema": { + "type": "integer", + "minimum": 0, + "maximum": 1000, + "default": 1000 + } + }, + { + "name": "after", + "in": "query", + "description": "Cursor for pagination. Provide the value from the previous response's `next` field to continue listing roles.", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "order", + "in": "query", + "description": "Sort order for the returned roles.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "asc", + "desc" + ], + "default": "asc" + } + } + ], + "responses": { + "200": { + "description": "Project roles listed successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PublicRoleListResource" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "List project roles", + "group": "administration", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/projects/proj_abc123/roles?limit=20 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"role\",\n \"id\": \"role_01J1F8PROJ\",\n \"name\": \"API Project Key Manager\",\n \"description\": \"Allows managing API keys for the project\",\n \"permissions\": [\n \"api.organization.projects.api_keys.read\",\n \"api.organization.projects.api_keys.write\"\n ],\n \"resource_type\": \"api.project\",\n \"predefined_role\": false\n }\n ],\n \"has_more\": false,\n \"next\": null\n}\n" + } + } + }, + "post": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Creates a custom role for a project.", + "operationId": "create-project-role", + "tags": [ + "Roles" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project to update.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "Parameters for the project role you want to create.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PublicCreateOrganizationRoleBody" + } + } + } + }, + "responses": { + "200": { + "description": "Project role created successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Role" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Create project role", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X POST https://api.openai.com/v1/projects/proj_abc123/roles \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"role_name\": \"API Project Key Manager\",\n \"permissions\": [\n \"api.organization.projects.api_keys.read\",\n \"api.organization.projects.api_keys.write\"\n ],\n \"description\": \"Allows managing API keys for the project\"\n }'\n" + }, + "response": "{\n \"object\": \"role\",\n \"id\": \"role_01J1F8PROJ\",\n \"name\": \"API Project Key Manager\",\n \"description\": \"Allows managing API keys for the project\",\n \"permissions\": [\n \"api.organization.projects.api_keys.read\",\n \"api.organization.projects.api_keys.write\"\n ],\n \"resource_type\": \"api.project\",\n \"predefined_role\": false\n}\n" + } + } + } + }, + "/projects/{project_id}/roles/{role_id}": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Retrieves a project role.", + "operationId": "retrieve-project-role", + "tags": [ + "Roles" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "role_id", + "in": "path", + "description": "The ID of the role to retrieve.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Project role retrieved successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Role" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Retrieve project role", + "group": "administration", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/projects/proj_abc123/roles/role_01J1F8PROJ \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"role\",\n \"id\": \"role_01J1F8PROJ\",\n \"name\": \"API Project Key Manager\",\n \"description\": \"Allows managing API keys for the project\",\n \"permissions\": [\n \"api.organization.projects.api_keys.read\",\n \"api.organization.projects.api_keys.write\"\n ],\n \"resource_type\": \"api.project\",\n \"predefined_role\": false\n}\n" + } + } + }, + "post": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Updates an existing project role.", + "operationId": "update-project-role", + "tags": [ + "Roles" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project to update.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "role_id", + "in": "path", + "description": "The ID of the role to update.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "Fields to update on the project role.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PublicUpdateOrganizationRoleBody" + } + } + } + }, + "responses": { + "200": { + "description": "Project role updated successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Role" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Update project role", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X POST https://api.openai.com/v1/projects/proj_abc123/roles/role_01J1F8PROJ \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"role_name\": \"API Project Key Manager\",\n \"permissions\": [\n \"api.organization.projects.api_keys.read\",\n \"api.organization.projects.api_keys.write\"\n ],\n \"description\": \"Allows managing API keys for the project\"\n }'\n" + }, + "response": "{\n \"object\": \"role\",\n \"id\": \"role_01J1F8PROJ\",\n \"name\": \"API Project Key Manager\",\n \"description\": \"Allows managing API keys for the project\",\n \"permissions\": [\n \"api.organization.projects.api_keys.read\",\n \"api.organization.projects.api_keys.write\"\n ],\n \"resource_type\": \"api.project\",\n \"predefined_role\": false\n}\n" + } + } + }, + "delete": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Deletes a custom role from a project.", + "operationId": "delete-project-role", + "tags": [ + "Roles" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project to update.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "role_id", + "in": "path", + "description": "The ID of the role to delete.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Project role deleted successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RoleDeletedResource" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Delete project role", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X DELETE https://api.openai.com/v1/projects/proj_abc123/roles/role_01J1F8PROJ \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"role.deleted\",\n \"id\": \"role_01J1F8PROJ\",\n \"deleted\": true\n}\n" + } + } + } + }, + "/projects/{project_id}/users/{user_id}/roles": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Lists the project roles assigned to a user within a project.", + "operationId": "list-project-user-role-assignments", + "tags": [ + "Project user role assignments" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project to inspect.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "user_id", + "in": "path", + "description": "The ID of the user to inspect.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "description": "A limit on the number of project role assignments to return.", + "required": false, + "schema": { + "type": "integer", + "minimum": 0, + "maximum": 1000 + } + }, + { + "name": "after", + "in": "query", + "description": "Cursor for pagination. Provide the value from the previous response's `next` field to continue listing project roles.", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "order", + "in": "query", + "description": "Sort order for the returned project roles.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "asc", + "desc" + ] + } + } + ], + "responses": { + "200": { + "description": "Project user role assignments listed successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RoleListResource" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "List project user role assignments", + "group": "administration", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/projects/proj_abc123/users/user_abc123/roles \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"role_01J1F8PROJ\",\n \"name\": \"API Project Key Manager\",\n \"permissions\": [\n \"api.organization.projects.api_keys.read\",\n \"api.organization.projects.api_keys.write\"\n ],\n \"resource_type\": \"api.project\",\n \"predefined_role\": false,\n \"description\": \"Allows managing API keys for the project\",\n \"created_at\": 1711471533,\n \"updated_at\": 1711472599,\n \"created_by\": \"user_abc123\",\n \"created_by_user_obj\": {\n \"id\": \"user_abc123\",\n \"name\": \"Ada Lovelace\",\n \"email\": \"ada@example.com\"\n },\n \"metadata\": {}\n }\n ],\n \"has_more\": false,\n \"next\": null\n}\n" + } + } + }, + "post": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Assigns a project role to a user within a project.", + "operationId": "assign-project-user-role", + "tags": [ + "Project user role assignments" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project to update.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "user_id", + "in": "path", + "description": "The ID of the user that should receive the project role.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "Identifies the project role to assign to the user.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PublicAssignOrganizationGroupRoleBody" + } + } + } + }, + "responses": { + "200": { + "description": "Project role assigned to the user successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UserRoleAssignment" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Assign project role to user", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X POST https://api.openai.com/v1/projects/proj_abc123/users/user_abc123/roles \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"role_id\": \"role_01J1F8PROJ\"\n }'\n" + }, + "response": "{\n \"object\": \"user.role\",\n \"user\": {\n \"object\": \"organization.user\",\n \"id\": \"user_abc123\",\n \"name\": \"Ada Lovelace\",\n \"email\": \"ada@example.com\",\n \"role\": \"owner\",\n \"added_at\": 1711470000\n },\n \"role\": {\n \"object\": \"role\",\n \"id\": \"role_01J1F8PROJ\",\n \"name\": \"API Project Key Manager\",\n \"description\": \"Allows managing API keys for the project\",\n \"permissions\": [\n \"api.organization.projects.api_keys.read\",\n \"api.organization.projects.api_keys.write\"\n ],\n \"resource_type\": \"api.project\",\n \"predefined_role\": false\n }\n}\n" + } + } + } + }, + "/projects/{project_id}/users/{user_id}/roles/{role_id}": { + "get": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Retrieves a project role assigned to a user.", + "operationId": "retrieve-project-user-role", + "tags": [ + "Project user role assignments" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project to inspect.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "user_id", + "in": "path", + "description": "The ID of the user to inspect.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "role_id", + "in": "path", + "description": "The ID of the project role to retrieve for the user.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Project role retrieved for the user successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AssignedRoleDetails" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Retrieve project user role", + "group": "administration", + "examples": { + "request": { + "curl": "curl https://api.openai.com/v1/projects/proj_abc123/users/user_abc123/roles/role_01J1F8PROJ \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"id\": \"role_01J1F8PROJ\",\n \"name\": \"API Project Key Manager\",\n \"permissions\": [\n \"api.organization.projects.api_keys.read\",\n \"api.organization.projects.api_keys.write\"\n ],\n \"resource_type\": \"api.project\",\n \"predefined_role\": false,\n \"description\": \"Allows managing API keys for the project\",\n \"created_at\": 1711471533,\n \"updated_at\": 1711472599,\n \"created_by\": \"user_abc123\",\n \"created_by_user_obj\": null,\n \"metadata\": {},\n \"assignment_sources\": null\n}\n" + } + } + }, + "delete": { + "security": [ + { + "AdminApiKeyAuth": [] + } + ], + "summary": "Unassigns a project role from a user within a project.", + "operationId": "unassign-project-user-role", + "tags": [ + "Project user role assignments" + ], + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The ID of the project to modify.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "user_id", + "in": "path", + "description": "The ID of the user whose project role assignment should be removed.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "role_id", + "in": "path", + "description": "The ID of the project role to remove from the user.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Project role unassigned from the user successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeletedRoleAssignmentResource" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "x-oaiMeta": { + "name": "Unassign project role from user", + "group": "administration", + "examples": { + "request": { + "curl": "curl -X DELETE https://api.openai.com/v1/projects/proj_abc123/users/user_abc123/roles/role_01J1F8PROJ \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" + }, + "response": "{\n \"object\": \"user.role.deleted\",\n \"deleted\": true\n}\n" + } + } + } + }, + "/realtime/calls": { + "post": { + "summary": "Create a new Realtime API call over WebRTC and receive the SDP answer needed\nto complete the peer connection.", + "operationId": "create-realtime-call", + "tags": [ + "Realtime" + ], + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "$ref": "#/components/schemas/RealtimeCallCreateRequest" + }, + "encoding": { + "sdp": { + "contentType": "application/sdp" + }, + "session": { + "contentType": "application/json" + } + } + }, + "application/sdp": { + "schema": { + "type": "string", + "description": "WebRTC SDP offer. Use this variant when you have previously created an\nephemeral **session token** and are authenticating the request with it.\nRealtime session parameters will be retrieved from the session token." + } + } + } + }, + "responses": { + "201": { + "description": "Realtime call created successfully.", + "headers": { + "Location": { + "description": "Relative URL containing the call ID for subsequent control requests.", + "schema": { + "type": "string" + } + } + }, + "content": { + "application/sdp": { + "schema": { + "type": "string", + "description": "SDP answer produced by OpenAI for the peer connection." + } + } + } + } + }, + "x-oaiMeta": { + "name": "Create call", + "group": "realtime", + "returns": "Returns `201 Created` with the SDP answer in the response body. The\n`Location` response header includes the call ID for follow-up requests,\ne.g., establishing a monitoring WebSocket or hanging up the call.", + "examples": { + "request": { + "curl": "curl -X POST https://api.openai.com/v1/realtime/calls \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -F \"sdp=