{
  "openapi": "3.1.0",
  "info": {
    "title": "AuthAPI",
    "version": "1.0.0",
    "description": "OpenAI-compatible API backed by each user's connected Codex/ChatGPT session."
  },
  "servers": [{ "url": "https://authapi.dev" }],
  "security": [{ "bearerAuth": [] }],
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "cxa API key" },
      "cookieAuth": { "type": "apiKey", "in": "cookie", "name": "cxa_session" }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "message": { "type": "string" },
              "type": { "type": "string" },
              "param": { "type": ["string", "null"] },
              "code": { "type": ["string", "null"] }
            }
          }
        }
      },
      "FunctionDefinition": {
        "type": "object",
        "required": ["name"],
        "properties": {
          "name": { "type": "string", "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$" },
          "description": { "type": "string", "maxLength": 4096 },
          "parameters": { "type": "object", "description": "JSON Schema for function arguments; defaults to an empty object schema when omitted", "default": { "type": "object", "properties": {} } },
          "strict": { "type": "boolean" }
        }
      },
      "ChatFunctionTool": {
        "type": "object", "required": ["type", "function"],
        "properties": { "type": { "const": "function" }, "function": { "$ref": "#/components/schemas/FunctionDefinition" } }
      },
      "ResponseFunctionTool": {
        "allOf": [
          { "$ref": "#/components/schemas/FunctionDefinition" },
          { "type": "object", "required": ["type"], "properties": { "type": { "const": "function" } } }
        ]
      },
      "ChatToolCall": {
        "type": "object", "required": ["id", "type", "function"],
        "properties": {
          "id": { "type": "string" }, "type": { "const": "function" },
          "function": { "type": "object", "required": ["name", "arguments"], "properties": { "name": { "type": "string" }, "arguments": { "type": "string", "description": "JSON-encoded arguments" } } }
        }
      },
      "ChatToolChoice": {
        "oneOf": [
          { "type": "string", "enum": ["none", "auto", "required"] },
          { "type": "object", "required": ["type", "function"], "properties": { "type": { "const": "function" }, "function": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string" } } } } }
        ]
      },
      "ResponseToolChoice": {
        "oneOf": [
          { "type": "string", "enum": ["none", "auto", "required"] },
          { "type": "object", "required": ["type", "name"], "properties": { "type": { "const": "function" }, "name": { "type": "string" } } }
        ]
      },
      "Message": {
        "oneOf": [
          {
            "type": "object", "required": ["role", "content"],
            "properties": {
              "role": { "type": "string", "enum": ["system", "developer", "user"] },
              "content": { "oneOf": [{ "type": "string" }, { "type": "array", "items": { "type": "object" } }] }
            }
          },
          {
            "type": "object", "required": ["role"],
            "properties": {
              "role": { "const": "assistant" },
              "content": { "oneOf": [{ "type": "string" }, { "type": "array", "items": { "type": "object" } }, { "type": "null" }] },
              "tool_calls": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/ChatToolCall" } }
            }
          },
          {
            "type": "object", "required": ["role", "tool_call_id", "content"],
            "properties": { "role": { "const": "tool" }, "tool_call_id": { "type": "string" }, "content": { "type": "string" } }
          }
        ]
      },
      "ResponseFunctionCallInput": {
        "type": "object", "required": ["type", "call_id", "name", "arguments"],
        "properties": { "type": { "const": "function_call" }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" } }
      },
      "ResponseFunctionCallOutput": {
        "type": "object", "required": ["type", "call_id", "output"],
        "properties": { "type": { "const": "function_call_output" }, "call_id": { "type": "string" }, "output": {} }
      },
      "ResponseTextInputPart": {
        "type": "object", "required": ["type", "text"], "additionalProperties": false,
        "properties": { "type": { "type": "string", "enum": ["text", "input_text", "output_text"] }, "text": { "type": "string" } }
      },
      "ResponseImageInputPart": {
        "oneOf": [
          { "type": "object", "required": ["type", "image_url"], "additionalProperties": false, "properties": { "type": { "const": "input_image" }, "image_url": { "type": "string" } } },
          { "type": "object", "required": ["type", "image_url"], "additionalProperties": false, "properties": { "type": { "const": "image_url" }, "image_url": { "oneOf": [{ "type": "string" }, { "type": "object", "required": ["url"], "additionalProperties": false, "properties": { "url": { "type": "string" } } }] } } }
        ]
      },
      "ResponseInputItem": {
        "description": "A supported Responses message input. Function items use their dedicated schemas.",
        "oneOf": [
          {
            "type": "object", "required": ["role", "content"], "additionalProperties": false,
            "properties": {
              "type": { "const": "message" },
              "role": { "type": "string", "enum": ["system", "developer", "user"] },
              "content": { "oneOf": [{ "type": "string" }, { "type": "array", "minItems": 1, "items": { "oneOf": [{ "$ref": "#/components/schemas/ResponseTextInputPart" }, { "$ref": "#/components/schemas/ResponseImageInputPart" }] } }] }
            }
          },
          {
            "type": "object", "required": ["role", "content"], "additionalProperties": false,
            "properties": {
              "type": { "const": "message" }, "role": { "const": "assistant" },
              "content": { "oneOf": [{ "type": "string" }, { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/ResponseTextInputPart" } }] }
            }
          }
        ]
      },
      "ResponseFunctionCall": {
        "type": "object", "required": ["id", "type", "call_id", "name", "arguments"],
        "properties": { "id": { "type": "string" }, "type": { "const": "function_call" }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" }, "status": { "type": "string", "enum": ["in_progress", "completed", "incomplete"] } }
      },
      "ResponseOutputItem": {
        "type": "object",
        "description": "A non-function-call Responses output item, such as an assistant message or reasoning item.",
        "not": { "type": "object", "required": ["type"], "properties": { "type": { "const": "function_call" } } }
      },
      "ChatCompletionResponse": {
        "type": "object", "required": ["id", "object", "created", "model", "choices"],
        "properties": {
          "id": { "type": "string" }, "object": { "const": "chat.completion" }, "created": { "type": "integer" }, "model": { "type": "string" },
          "choices": { "type": "array", "items": { "type": "object", "required": ["index", "message", "finish_reason"], "properties": {
            "index": { "type": "integer" },
            "message": { "type": "object", "required": ["role", "content"], "properties": { "role": { "const": "assistant" }, "content": { "type": ["string", "null"] }, "tool_calls": { "type": "array", "items": { "$ref": "#/components/schemas/ChatToolCall" } } } },
            "finish_reason": { "type": "string", "enum": ["stop", "tool_calls"] }
          } } },
          "usage": { "type": "object" }
        },
        "example": { "id": "chatcmpl-example", "object": "chat.completion", "created": 1784563200, "model": "gpt-5.6-sol", "choices": [{ "index": 0, "message": { "role": "assistant", "content": null, "tool_calls": [{ "id": "call_weather", "type": "function", "function": { "name": "get_weather", "arguments": "{\"city\":\"Paris\"}" } }] }, "finish_reason": "tool_calls" }], "usage": { "prompt_tokens": 12, "completion_tokens": 8, "total_tokens": 20 } }
      },
      "ChatToolCallDelta": {
        "type": "object", "required": ["index"],
        "properties": { "index": { "type": "integer" }, "id": { "type": "string" }, "type": { "const": "function" }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "arguments": { "type": "string" } } } }
      },
      "ChatCompletionChunk": {
        "type": "object", "required": ["id", "object", "created", "model", "choices"],
        "properties": {
          "id": { "type": "string" }, "object": { "const": "chat.completion.chunk" }, "created": { "type": "integer" }, "model": { "type": "string" },
          "choices": { "type": "array", "items": { "type": "object", "required": ["index", "delta", "finish_reason"], "properties": { "index": { "type": "integer" }, "delta": { "type": "object", "properties": { "role": { "const": "assistant" }, "content": { "type": "string" }, "tool_calls": { "type": "array", "items": { "$ref": "#/components/schemas/ChatToolCallDelta" } } } }, "finish_reason": { "type": ["string", "null"], "enum": ["stop", "tool_calls", null] } } } }
        },
        "examples": [
          { "id": "chatcmpl-example", "object": "chat.completion.chunk", "created": 1784563200, "model": "gpt-5.6-sol", "choices": [{ "index": 0, "delta": { "tool_calls": [{ "index": 0, "id": "call_weather", "type": "function", "function": { "name": "get_weather", "arguments": "{\"city\"" } }] }, "finish_reason": null }] },
          { "id": "chatcmpl-example", "object": "chat.completion.chunk", "created": 1784563200, "model": "gpt-5.6-sol", "choices": [{ "index": 0, "delta": { "tool_calls": [{ "index": 0, "function": { "arguments": ":\"Paris\"}" } }] }, "finish_reason": null }] },
          { "id": "chatcmpl-example", "object": "chat.completion.chunk", "created": 1784563200, "model": "gpt-5.6-sol", "choices": [{ "index": 0, "delta": {}, "finish_reason": "tool_calls" }] }
        ]
      },
      "ResponseObject": {
        "type": "object", "required": ["id", "object", "status", "output"],
        "properties": { "id": { "type": "string" }, "object": { "const": "response" }, "status": { "type": "string" }, "output": { "type": "array", "items": { "oneOf": [{ "$ref": "#/components/schemas/ResponseFunctionCall" }, { "$ref": "#/components/schemas/ResponseOutputItem" }] } }, "output_text": { "type": "string" }, "usage": { "type": "object" } },
        "example": { "id": "resp_example", "object": "response", "status": "completed", "output": [{ "id": "fc_example", "type": "function_call", "call_id": "call_weather", "name": "get_weather", "arguments": "{\"city\":\"Paris\"}", "status": "completed" }], "output_text": "", "usage": { "input_tokens": 12, "output_tokens": 8, "total_tokens": 20 } }
      },
      "ResponseStreamEvent": {
        "oneOf": [
          { "type": "object", "required": ["type", "output_index", "item"], "properties": { "type": { "const": "response.output_item.added" }, "output_index": { "type": "integer" }, "item": { "$ref": "#/components/schemas/ResponseFunctionCall" } } },
          { "type": "object", "required": ["type", "item_id", "output_index", "delta"], "properties": { "type": { "const": "response.function_call_arguments.delta" }, "item_id": { "type": "string" }, "output_index": { "type": "integer" }, "delta": { "type": "string" } } },
          { "type": "object", "required": ["type", "item_id", "output_index", "arguments"], "properties": { "type": { "const": "response.function_call_arguments.done" }, "item_id": { "type": "string" }, "output_index": { "type": "integer" }, "arguments": { "type": "string" } } },
          { "type": "object", "required": ["type", "response"], "properties": { "type": { "const": "response.completed" }, "response": { "$ref": "#/components/schemas/ResponseObject" } } }
        ],
        "examples": [
          { "type": "response.output_item.added", "output_index": 0, "item": { "id": "fc_example", "type": "function_call", "call_id": "call_weather", "name": "get_weather", "arguments": "", "status": "in_progress" } },
          { "type": "response.function_call_arguments.delta", "item_id": "fc_example", "output_index": 0, "delta": "{\"city\":\"Par" },
          { "type": "response.function_call_arguments.done", "item_id": "fc_example", "output_index": 0, "arguments": "{\"city\":\"Paris\"}" }
        ]
      }
    },
    "headers": {
      "RequestId": { "description": "Request correlation UUID", "schema": { "type": "string", "format": "uuid" } }
    },
    "responses": {
      "ImageError": {
        "description": "Sanitized image request error",
        "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } },
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      }
    }
  },
  "paths": {
    "/v1/limits": {
      "get": {
        "summary": "Read the API key owner's current Codex plan limits",
        "description": "API-key-authenticated provider quota endpoint. Returns the same normalized 5-hour, weekly, other, and additional limits schema as /api/provider-usage, scoped to the bearer key's owner, with no account identity or credentials. /limits is an equivalent alias.",
        "operationId": "getLimits",
        "responses": {
          "200": {
            "description": "Current normalized Codex usage windows",
            "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } } },
            "content": { "application/json": { "schema": { "$ref": "#/paths/~1api~1provider-usage/get/responses/200/content/application~1json/schema" } } }
          },
          "401": { "description": "Valid bearer API key required", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "409": { "description": "Codex must be connected or reconnected", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "502": { "description": "Sanitized upstream or response-schema failure", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "503": { "description": "Provider usage service temporarily rate limited", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "504": { "description": "Provider usage request timed out", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/limits": {
      "get": {
        "summary": "Alias for GET /v1/limits",
        "description": "API-key-authenticated alias for /v1/limits, scoped to the bearer key's owner and returned with Cache-Control: private, no-store.",
        "operationId": "getLimitsAlias",
        "responses": {
          "200": { "$ref": "#/paths/~1v1~1limits/get/responses/200" },
          "401": { "$ref": "#/paths/~1v1~1limits/get/responses/401" },
          "409": { "$ref": "#/paths/~1v1~1limits/get/responses/409" },
          "502": { "$ref": "#/paths/~1v1~1limits/get/responses/502" },
          "503": { "$ref": "#/paths/~1v1~1limits/get/responses/503" },
          "504": { "$ref": "#/paths/~1v1~1limits/get/responses/504" }
        }
      }
    },
    "/api/provider-usage": {
      "get": {
        "summary": "Read the logged-in owner's current Codex plan limits",
        "description": "Fetches provider-reported rolling usage windows through the owner's connected Codex OAuth account. This account endpoint requires the cxa_session cookie, returns only normalized limit data, omits account identity and credentials, classifies 5-hour and weekly windows by duration, and does not fabricate missing windows.",
        "operationId": "getProviderUsage",
        "security": [{ "cookieAuth": [] }],
        "responses": {
          "200": {
            "description": "Current normalized Codex usage windows",
            "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } } },
            "content": { "application/json": { "schema": {
              "type": "object",
              "required": ["available", "fetchedAt", "planType", "limits"],
              "properties": {
                "available": { "const": true },
                "fetchedAt": { "type": "string", "format": "date-time" },
                "planType": { "type": ["string", "null"] },
                "limits": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": ["id", "name", "meteredFeature", "allowed", "limitReached", "windows"],
                    "properties": {
                      "id": { "type": "string" },
                      "name": { "type": "string" },
                      "meteredFeature": { "type": ["string", "null"] },
                      "allowed": { "type": "boolean" },
                      "limitReached": { "type": "boolean" },
                      "windows": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "required": ["kind", "label", "usedPercent", "remainingPercent", "windowSeconds", "resetsAt"],
                          "properties": {
                            "kind": { "type": "string", "enum": ["five_hour", "weekly", "other"] },
                            "label": { "type": "string" },
                            "usedPercent": { "type": "number", "minimum": 0, "maximum": 100 },
                            "remainingPercent": { "type": "number", "minimum": 0, "maximum": 100 },
                            "windowSeconds": { "type": "integer", "minimum": 1 },
                            "resetsAt": { "type": "string", "format": "date-time" }
                          }
                        }
                      }
                    }
                  }
                }
              }
            } } }
          },
          "401": { "description": "Logged-in browser session required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "409": { "description": "Codex must be connected or reconnected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "502": { "description": "Sanitized upstream or response-schema failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "503": { "description": "Provider usage service temporarily rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "504": { "description": "Provider usage request timed out", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/voice/session": {
      "post": {
        "summary": "Create a WebRTC voice session with optional custom functions",
        "description": "Creates an experimental Codex Frameless Bidi V3 WebRTC session using the authenticated owner's connected Codex account. Supply OpenAI-style flat function tools to register the client-delegation Responses adapter, or set conversation_only to true for a server-instructed no-tools session. Same-origin AuthAPI browsers use a login cookie. External browsers must send their SDP through their own backend, which makes an origin-less bearer request; never expose a cxa key in browser code. The backend resolves delegated text through POST /v1/responses, executes allowlisted functions, and returns outputs over the browser's oai-events data channel; the gateway never executes caller tools.",
        "operationId": "createVoiceSession",
        "security": [{ "cookieAuth": [] }, { "bearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object",
            "required": ["sdp"],
            "properties": {
              "sdp": { "type": "string", "maxLength": 131072, "description": "ICE-complete browser WebRTC SDP audio offer" },
              "voice": { "type": "string", "enum": ["juniper", "maple", "spruce", "ember", "vale", "breeze", "arbor", "sol", "cove"], "default": "cove" },
              "instructions": { "type": "string", "minLength": 1, "maxLength": 16384, "pattern": ".*\\S.*", "description": "Live voice instructions that help Frameless Bidi decide when to delegate. Requires tools. Do not blindly copy untrusted voice instructions into the privileged /v1/responses selector instructions." },
              "tools": { "type": "array", "minItems": 1, "maxItems": 128, "items": { "$ref": "#/components/schemas/ResponseFunctionTool" }, "description": "Flat OpenAI function definitions for the client-delegation Responses adapter. A bounded name/description registry is placed in voice instructions. Voice Lab resolves delegations through same-origin /api/voice/responses; external callers resubmit the tools to bearer-authenticated /v1/responses, execute the selected function, and return its output as delegation context." },
              "tool_choice": { "allOf": [{ "$ref": "#/components/schemas/ResponseToolChoice" }], "description": "auto, none, required, or a forced supplied function. Requires tools." },
              "response_model": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$", "default": "gpt-5.5", "description": "Responses model used for delegated function selection. Requires tools." },
              "conversation_only": { "type": "boolean", "default": false, "description": "Create a fixed-instruction conversational session with delegation disabled. Cannot be combined with tools, tool_choice, instructions, or response_model." }
            },
            "dependentRequired": { "instructions": ["tools"], "tool_choice": ["tools"], "response_model": ["tools"] },
            "allOf": [{
              "not": {
                "required": ["conversation_only"],
                "properties": { "conversation_only": { "const": true } },
                "anyOf": [
                  { "required": ["tools"] }, { "required": ["tool_choice"] },
                  { "required": ["instructions"] }, { "required": ["response_model"] }
                ]
              }
            }],
            "additionalProperties": false
          } } }
        },
        "x-realtime-data-channel": {
          "label": "oai-events",
          "encoding": "UTF-8 JSON; one object per message",
          "createBeforeOffer": true,
          "audioDelivery": "WebRTC media tracks, not data-channel JSON",
          "transcriptEvents": [
            { "type": "input_transcript.added", "role": "user", "textPath": "item.text", "action": "append_to_role_draft" },
            { "type": "output_transcript.added", "role": "assistant", "textPath": "item.text", "action": "append_to_role_draft" },
            { "type": "turn.done", "rolePath": "turn.role", "textPath": "turn.transcript", "action": "replace_role_draft_and_finalize" }
          ],
          "externalBrowserTopology": {
            "browserToApplicationBackend": ["ICE-complete SDP offer", "application voice-session ID plus delegation item ID and text"],
            "applicationBackendToAuthAPI": ["origin-less bearer POST /api/voice/session", "bearer POST /v1/responses with stream=true and parallel_tool_calls=false"],
            "secretRule": "Never expose a cxa API key in browser JavaScript. External browser origins cannot authenticate /api/voice/session with a bearer key.",
            "responseModelMapping": "Copy the session response_model value into the /v1/responses model field.",
            "toolChoiceMapping": "Retain the session's normalized tool_choice and send it as /v1/responses.tool_choice.",
            "instructionsMapping": "Voice instructions control delegation. Use separate trusted Responses instructions for privileged function selection."
          },
          "delegationEvents": [
            { "type": "delegation.created", "direction": "server_to_client", "itemIdPath": "item.id", "handoffIdPath": "item.handoff_id", "handoffIdSemantics": "Optional voice transport metadata; not a Responses call_id.", "inputPath": "item.content[type=input_text].text" },
            { "type": "delegation.context.append", "direction": "client_to_server", "bindingPath": "delegation_item_id", "contentPath": "content[type=input_text].text", "contentSemantics": "Success context contains encoded OpenAI-style function_call_output with the Responses call_id. A pre-call/no-call failure uses sanitized plain text and must not invent a call_id." },
            { "type": "delegation.context.appended", "direction": "server_to_client", "bindingPath": "delegation_item_id" }
          ],
          "clientFunctions": [
            { "type": "function", "name": "change_voice", "strict": true, "parameters": { "type": "object", "properties": { "voice": { "type": "string", "enum": ["cove", "juniper", "maple", "spruce", "ember", "vale", "breeze", "arbor", "sol"] } }, "additionalProperties": false } },
            { "type": "function", "name": "clear_voice_transcript", "strict": true, "parameters": { "type": "object", "properties": {}, "additionalProperties": false } }
          ],
          "customFunctionEvents": [
            { "type": "delegation.created", "direction": "server_to_client", "source": "oai-events", "purpose": "Read item.id and delegated input, then send them to the application's backend. Voice Lab uses same-origin /api/voice/responses; external backends use bearer-authenticated /v1/responses with parallel_tool_calls=false and stream=true." },
            { "type": "response.output_item.added", "direction": "server_to_client", "source": "Responses SSE", "purpose": "Store item.id, item.call_id, and item.name for each selected function_call." },
            { "type": "response.function_call_arguments.delta", "direction": "server_to_client", "source": "Responses SSE", "purpose": "Append bounded argument fragments for the correlated item when needed." },
            { "type": "response.function_call_arguments.done", "direction": "server_to_client", "source": "Responses SSE", "purpose": "Store complete arguments for the correlated item." },
            { "type": "response.output_item.done", "direction": "server_to_client", "source": "Responses SSE", "purpose": "Authoritative completed function_call item, including full arguments when supplied." },
            { "type": "response.completed", "direction": "server_to_client", "source": "Responses SSE", "purpose": "Required terminal success event. Execute only after exactly one allowlisted call has complete valid arguments." },
            { "type": "response.failed", "direction": "server_to_client", "source": "Responses SSE", "purpose": "Terminal failure. Execute nothing and return sanitized failure context." },
            { "type": "error", "direction": "server_to_client", "source": "Responses SSE or oai-events", "purpose": "Execute nothing, sanitize details, and resolve the delegation with safe failure context when possible." },
            { "type": "delegation.context.append", "direction": "client_to_server", "source": "oai-events", "purpose": "Return success or failure context, bound by delegation_item_id. Structured function output must be stringified." },
            { "type": "delegation.context.appended", "direction": "server_to_client", "source": "oai-events", "purpose": "Acknowledges accepted function output context; a missing acknowledgement must not cause blind re-execution." }
          ],
          "customFunctionFailurePolicy": {
            "failClosedOn": ["zero or multiple calls", "unknown function", "invalid or uncorrelated arguments", "schema mismatch", "malformed or truncated SSE", "response.failed", "error", "timeout", "execution exception"],
            "action": "Execute nothing and append sanitized failure context so the live voice turn can continue.",
            "idempotency": "Cache work by delegation.created.item.id; never repeat a side effect for a duplicate event or delayed acknowledgement.",
            "output": "function_call_output.output must be a string. Enforce an application limit and summarize or store large results elsewhere."
          },
          "customFunctionResult": { "type": "delegation.context.append", "delegation_item_id": "delegation_123", "channel": "speakable", "content": [{ "type": "input_text", "text": "Function get_weather completed successfully. {\"type\":\"function_call_output\",\"call_id\":\"call_123\",\"output\":\"{\\\"temperature\\\":72}\"}" }] },
          "noCustomToolsBehavior": "Requests without tools use the existing plain client-delegation voice behavior unless conversation_only is true. conversation_only uses fixed server-owned instructions and disables delegation. Voice Lab always registers its two local webpage tools.",
          "renderingNotes": [
            "Keep separate user and assistant drafts because events can interleave.",
            "Append each added fragment exactly once.",
            "The turn.done transcript is authoritative and replaces the draft; do not append it.",
            "Ignore unknown event types and sanitize error events."
          ]
        },
        "responses": {
          "201": { "description": "Frameless Bidi V3 WebRTC SDP answer created", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": ["sdp", "protocol"], "properties": { "sdp": { "type": "string" }, "protocol": { "type": "object", "required": ["transport", "architecture", "version", "experimental", "dataChannel", "model", "voice", "delegation"], "properties": { "transport": { "const": "webrtc" }, "architecture": { "const": "frameless-bidi" }, "version": { "const": 3 }, "experimental": { "const": true }, "dataChannel": { "const": "oai-events" }, "model": { "const": "gpt-live-1-codex" }, "voice": { "type": "string" }, "delegation": { "type": "string", "enum": ["client", "none"], "description": "client enables Frameless Bidi client delegations; none identifies a conversation_only session with delegation disabled." }, "responseModel": { "type": "string", "description": "Responses model selected for the adapter; present when tools were registered." }, "functionTransport": { "const": "responses-adapter" }, "toolChoice": { "$ref": "#/components/schemas/ResponseToolChoice" }, "toolCount": { "type": "integer", "minimum": 1, "maximum": 128 } } } } } } } },
          "400": { "description": "Invalid SDP, voice, instructions, tools, tool choice, response model, or JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "401": { "description": "Login or cxa API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "403": { "description": "Browser Origin rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "409": { "description": "Codex connection required or must be reconnected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "413": { "description": "Request body too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "429": { "description": "Per-owner session creation rate exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "502": { "description": "Sanitized upstream failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "503": { "description": "Upstream realtime service rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "504": { "description": "Upstream negotiation timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/v1/audio/speech": {
      "post": {
        "summary": "Generate speech with the API-key owner's Codex OAuth session",
        "description": "Uses Codex's GA realtime WebSocket output-audio stream server-side. The completed output transcript is checked against the input before audio is returned.",
        "operationId": "createSpeech",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["input"], "properties": { "model": { "type": "string", "enum": ["codex-tts", "gpt-4o-mini-tts", "gpt-realtime-1.5"], "default": "codex-tts" }, "input": { "type": "string", "minLength": 1, "maxLength": 1000, "pattern": ".*\\S.*" }, "voice": { "type": "string", "enum": ["alloy", "ash", "ballad", "cedar", "coral", "echo", "marin", "sage", "shimmer", "verse"], "default": "marin" }, "response_format": { "type": "string", "enum": ["wav", "pcm"], "default": "wav" }, "speed": { "const": 1, "default": 1 }, "instructions": { "type": "string", "maxLength": 500 } }, "additionalProperties": false } } } },
        "responses": {
          "200": { "description": "24 kHz mono 16-bit speech audio", "headers": { "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "audio/wav": { "schema": { "type": "string", "format": "binary" } }, "audio/pcm": { "schema": { "type": "string", "format": "binary" } } } },
          "400": { "description": "Invalid speech request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "403": { "description": "API-key owner has not connected Codex auth", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "409": { "description": "Codex reconnect required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "413": { "description": "JSON body too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "429": { "description": "Admission limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "502": { "description": "Sanitized upstream failure or incomplete speech", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "503": { "description": "Upstream rate limited or unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "504": { "description": "Generation timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/v1/audio/transcriptions": {
      "post": {
        "summary": "Transcribe audio with the API-key owner's Codex OAuth session",
        "description": "OpenAI-compatible multipart transcription subset backed by the same private batch transcription route used by the Codex prompt box. Audio and transcripts are not logged or stored.",
        "operationId": "createTranscription",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": ["file", "model"],
                "properties": {
                  "file": { "type": "string", "format": "binary", "description": "Audio file up to 25 MB. Supported containers: FLAC, M4A, MP3/MP4/MPEG/MPGA, OGA/OGG, WAV, and WebM." },
                  "model": { "type": "string", "enum": ["codex-transcribe", "gpt-4o-mini-transcribe"] },
                  "language": { "type": "string", "description": "Optional ISO language code such as en or en-US." },
                  "response_format": { "type": "string", "enum": ["json", "text"], "default": "json" }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Completed transcript", "headers": { "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": ["text"], "properties": { "text": { "type": "string" } } } }, "text/plain": { "schema": { "type": "string" } } } },
          "400": { "description": "Invalid multipart request, field, or audio format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "403": { "description": "API-key owner has not connected Codex auth", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "409": { "description": "Codex reconnect required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "413": { "description": "Audio file exceeds 25 MB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "429": { "description": "Local admission limit or upstream transcription rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "502": { "description": "Sanitized upstream failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "504": { "description": "Transcription timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/v1/health": {
      "get": {
        "summary": "Check the API key owner's Codex connection health",
        "description": "Authenticates with the normal bearer API key and verifies that its owner's Codex authorization can be refreshed. Credentials must be sent in the Authorization header, not in the URL.",
        "operationId": "checkUserConnectionHealth",
        "responses": {
          "200": { "description": "The API key and its owner's Codex authorization are valid", "content": { "application/json": { "schema": { "type": "object" } } } },
          "401": { "description": "Missing, invalid, or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "503": { "description": "The API key is valid but its owner must connect or reconnect Codex", "content": { "application/json": { "schema": { "type": "object" } } } }
        }
      }
    },
    "/v1/models": {
      "get": {
        "summary": "List available Codex models",
        "operationId": "listModels",
        "responses": {
          "200": {
            "description": "OpenAI-compatible model list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": { "const": "list" },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": { "type": "string" },
                          "object": { "const": "model" },
                          "created": { "type": "integer" },
                          "owned_by": { "type": "string" }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/v1/chat/completions": {
      "post": {
        "summary": "Create a chat completion",
        "description": "Set stream=true for OpenAI-compatible server-sent events ending with data: [DONE]. Native function tools are returned as message.tool_calls; streamed calls use indexed delta.tool_calls fragments and finish_reason=tool_calls.",
        "operationId": "createChatCompletion",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["messages"],
                "properties": {
                  "model": { "type": "string", "default": "gpt-5.6-sol" },
                  "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } },
                  "tools": { "type": "array", "maxItems": 128, "items": { "$ref": "#/components/schemas/ChatFunctionTool" } },
                  "tool_choice": { "$ref": "#/components/schemas/ChatToolChoice" },
                  "parallel_tool_calls": { "type": "boolean", "default": false },
                  "reasoning_effort": { "type": "string", "enum": ["low", "medium", "high", "xhigh", "max", "ultra"], "default": "medium" },
                  "stream": { "type": "boolean", "default": false }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Completion JSON or SSE stream",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionResponse" } },
              "text/event-stream": {
                "schema": { "type": "string", "description": "Each data line contains an indexed ChatCompletionChunk; the final line is data: [DONE]." },
                "example": "data: {\"id\":\"chatcmpl-example\",\"object\":\"chat.completion.chunk\",\"created\":1784563200,\"model\":\"gpt-5.6-sol\",\"choices\":[{\"index\":0,\"delta\":{\"tool_calls\":[{\"index\":0,\"id\":\"call_weather\",\"type\":\"function\",\"function\":{\"name\":\"get_weather\",\"arguments\":\"{\\\"city\\\"\"}}]},\"finish_reason\":null}]}\n\ndata: {\"id\":\"chatcmpl-example\",\"object\":\"chat.completion.chunk\",\"created\":1784563200,\"model\":\"gpt-5.6-sol\",\"choices\":[{\"index\":0,\"delta\":{\"tool_calls\":[{\"index\":0,\"function\":{\"arguments\":\":\\\"Paris\\\"}\"}}]},\"finish_reason\":null}]}\n\ndata: {\"id\":\"chatcmpl-example\",\"object\":\"chat.completion.chunk\",\"created\":1784563200,\"model\":\"gpt-5.6-sol\",\"choices\":[{\"index\":0,\"delta\":{},\"finish_reason\":\"tool_calls\"}]}\n\ndata: [DONE]\n\n"
              }
            }
          },
          "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/v1/responses": {
      "post": {
        "summary": "Create a response",
        "description": "OpenAI Responses-style endpoint with native function tools and function_call/function_call_output items. Set stream=true to preserve typed upstream events, including response.function_call_arguments.delta/done, through response.completed.",
        "operationId": "createResponse",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["input"],
                "properties": {
                  "model": { "type": "string", "default": "gpt-5.6-sol" },
                  "input": { "oneOf": [{ "type": "string" }, { "type": "array", "items": { "oneOf": [{ "$ref": "#/components/schemas/ResponseInputItem" }, { "$ref": "#/components/schemas/ResponseFunctionCallInput" }, { "$ref": "#/components/schemas/ResponseFunctionCallOutput" }] } }] },
                  "instructions": { "type": "string" },
                  "tools": { "type": "array", "maxItems": 128, "items": { "$ref": "#/components/schemas/ResponseFunctionTool" } },
                  "tool_choice": { "$ref": "#/components/schemas/ResponseToolChoice" },
                  "parallel_tool_calls": { "type": "boolean", "default": false },
                  "reasoning": { "type": "object", "properties": { "effort": { "type": "string" } } },
                  "stream": { "type": "boolean", "default": false }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Response JSON or SSE stream",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ResponseObject" },
                "example": { "id": "resp_example", "object": "response", "status": "completed", "output": [{ "id": "fc_example", "type": "function_call", "call_id": "call_weather", "name": "get_weather", "arguments": "{\"city\":\"Paris\"}", "status": "completed" }], "output_text": "", "usage": { "input_tokens": 12, "output_tokens": 8, "total_tokens": 20 } }
              },
              "text/event-stream": {
                "schema": { "type": "string", "description": "Typed Responses events. Event JSON matches response.output_item.added, response.function_call_arguments.delta/done, and response.completed schemas." },
                "example": "event: response.output_item.added\ndata: {\"type\":\"response.output_item.added\",\"output_index\":0,\"item\":{\"id\":\"fc_example\",\"type\":\"function_call\",\"call_id\":\"call_weather\",\"name\":\"get_weather\",\"arguments\":\"\",\"status\":\"in_progress\"}}\n\nevent: response.function_call_arguments.delta\ndata: {\"type\":\"response.function_call_arguments.delta\",\"item_id\":\"fc_example\",\"output_index\":0,\"delta\":\"{\\\"city\\\":\\\"Par\"}\n\nevent: response.function_call_arguments.done\ndata: {\"type\":\"response.function_call_arguments.done\",\"item_id\":\"fc_example\",\"output_index\":0,\"arguments\":\"{\\\"city\\\":\\\"Paris\\\"}\"}\n\n"
              }
            }
          }
        }
      }
    },
    "/v1/images/generations": {
      "post": {
        "summary": "Generate an image",
        "operationId": "generateImage",
        "parameters": [{ "name": "X-Request-Id", "in": "header", "required": false, "description": "Optional canonical UUID correlation ID. Invalid or unsafe values are replaced.", "schema": { "type": "string", "format": "uuid" } }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["prompt"],
                "properties": {
                  "model": { "type": "string", "default": "gpt-image-1" },
                  "prompt": { "type": "string" },
                  "size": { "type": "string", "default": "1024x1024" },
                  "quality": { "type": "string", "enum": ["low", "medium", "high"], "default": "medium" },
                  "output_format": { "type": "string", "default": "png" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Base64-encoded image result", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object" } } } },
          "400": { "$ref": "#/components/responses/ImageError" },
          "401": { "$ref": "#/components/responses/ImageError" },
          "403": { "$ref": "#/components/responses/ImageError" },
          "500": { "$ref": "#/components/responses/ImageError" },
          "502": { "$ref": "#/components/responses/ImageError" },
          "504": { "$ref": "#/components/responses/ImageError" }
        }
      }
    },
    "/v1/images/edits": {
      "post": {
        "summary": "Edit an image",
        "operationId": "editImage",
        "parameters": [{ "name": "X-Request-Id", "in": "header", "required": false, "description": "Optional canonical UUID correlation ID. Invalid or unsafe values are replaced.", "schema": { "type": "string", "format": "uuid" } }],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": ["image", "prompt"],
                "properties": {
                  "image": { "type": "string", "format": "binary" },
                  "prompt": { "type": "string" },
                  "size": { "type": "string" },
                  "quality": { "type": "string" }
                }
              }
            },
            "application/json": { "schema": { "type": "object" } }
          }
        },
        "responses": {
          "200": { "description": "Base64-encoded edited image", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object" } } } },
          "400": { "$ref": "#/components/responses/ImageError" },
          "401": { "$ref": "#/components/responses/ImageError" },
          "403": { "$ref": "#/components/responses/ImageError" },
          "500": { "$ref": "#/components/responses/ImageError" },
          "502": { "$ref": "#/components/responses/ImageError" },
          "504": { "$ref": "#/components/responses/ImageError" }
        }
      }
    }
  }
}