{
	"openapi": "3.1.0",
	"info": {
		"title": "Stogas Gateway API",
		"summary": "OpenAI-compatible public API gateway.",
		"description": "The Stogas Gateway exposes an OpenAI-compatible surface. Authenticate requests with your Stogas API key, and the gateway will relay the request to the configured upstream provider.",
		"version": "1.0.0"
	},
	"jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
	"servers": [
		{
			"url": "{serverUrl}",
			"description": "Gateway origin. Endpoint paths include their API version.",
			"variables": {
				"serverUrl": {
					"default": "https://api.stogas.ai"
				}
			}
		}
	],
	"paths": {
		"/v1/responses": {
			"post": {
				"operationId": "createResponse",
				"tags": [
					"OpenAI-compatible"
				],
				"summary": "Responses",
				"description": "Create an OpenAI-compatible Responses API response. The gateway resolves the requested model and route through the compiled Stogas catalog, applies deployment facts such as implied service tier, rejects unsupported parameters, and then relays the request to the configured provider.",
				"parameters": [
					{
						"$ref": "#/components/parameters/ReturnExtraFields"
					}
				],
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"$ref": "#/components/schemas/ResponsesRequest"
							}
						}
					}
				},
				"responses": {
					"200": {
						"description": "Successful response. Non-streaming requests return JSON; streaming requests return Server-Sent Events.",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/ResponseObject"
								}
							},
							"text/event-stream": {
								"schema": {
									"type": "string",
									"description": "Server-Sent Events stream. Each `data:` frame contains a Responses API event; the stream ends with `data: [DONE]`."
								},
								"example": "data: {\"type\":\"response.created\",\"response\":{\"id\":\"8ee3487c-e5b1-4fe0-9dd6-84bc23ddd5f7\",\"object\":\"response\",\"created_at\":1714343120,\"status\":\"in_progress\",\"model\":\"gpt-5.5\",\"output\":[]}}\n\ndata: {\"type\":\"response.output_text.delta\",\"item_id\":\"msg_0192f217-35b0-7e2c-9be7-f4cc24f2a4b0\",\"output_index\":0,\"content_index\":0,\"delta\":\"Hello\"}\n\ndata: [DONE]\n\n"
							}
						}
					},
					"400": {
						"$ref": "#/components/responses/BadRequest"
					},
					"401": {
						"$ref": "#/components/responses/Unauthorized"
					},
					"402": {
						"$ref": "#/components/responses/PaymentRequired"
					},
					"403": {
						"$ref": "#/components/responses/Forbidden"
					},
					"404": {
						"$ref": "#/components/responses/NotFound"
					},
					"409": {
						"$ref": "#/components/responses/Conflict"
					},
					"413": {
						"$ref": "#/components/responses/PayloadTooLarge"
					},
					"429": {
						"$ref": "#/components/responses/RateLimited"
					},
					"500": {
						"$ref": "#/components/responses/InternalError"
					},
					"503": {
						"$ref": "#/components/responses/ServiceUnavailable"
					}
				}
			}
		}
	},
	"components": {
		"securitySchemes": {
			"bearerAuth": {
				"type": "http",
				"scheme": "bearer",
				"bearerFormat": "Stogas API key",
				"description": "Pass the Stogas API key as `Authorization: Bearer <token>`. This is the canonical OpenAI-compatible header."
			},
			"authorizationHeader": {
				"type": "apiKey",
				"in": "header",
				"name": "Authorization",
				"description": "Pass the Stogas API key directly as `Authorization: <token>`. The gateway normalizes this to the canonical Bearer authentication path."
			},
			"apiKeyHeader": {
				"type": "apiKey",
				"in": "header",
				"name": "api-key",
				"description": "Catalog-defined authentication alias. The gateway canonicalizes `api-key: <token>` to `Authorization: Bearer <token>`."
			},
			"xApiKeyHeader": {
				"type": "apiKey",
				"in": "header",
				"name": "x-api-key",
				"description": "Catalog-defined authentication alias. The gateway canonicalizes `x-api-key: <token>` to `Authorization: Bearer <token>`."
			},
			"xGoogApiKeyHeader": {
				"type": "apiKey",
				"in": "header",
				"name": "x-goog-api-key",
				"description": "Catalog-defined authentication alias. The gateway canonicalizes `x-goog-api-key: <token>` to `Authorization: Bearer <token>`."
			}
		},
		"parameters": {
			"ReturnExtraFields": {
				"name": "X-Stogas-Return-Extra-Fields",
				"in": "header",
				"schema": {
					"type": "string"
				},
				"description": "Comma-separated catalog-defined Stogas metadata fields to include under `stogas`, such as `provider`, `model_requested`, `model_deployment`, `latency`, `provider_response_headers`, `raw_request`, and `raw_response`."
			}
		},
		"schemas": {
			"ResponsesRequest": {
				"type": "object",
				"description": "OpenAI-compatible Responses API request fields parsed by the Stogas HTTP API.",
				"additionalProperties": false,
				"required": [
					"model",
					"input"
				],
				"properties": {
					"model": {
						"type": "string"
					},
					"provider": {
						"$ref": "#/components/schemas/ProviderRoutingPreference",
						"description": "Optional Stogas-owned routing preference used to select a provider when a public model slug is available from more than one provider. This field is never forwarded upstream."
					},
					"rules": {
						"$ref": "#/components/schemas/ProviderRoutingPreference",
						"description": "Alias for `provider`. Optional Stogas-owned routing preference used to select a provider when a public model slug is available from more than one provider. This field is never forwarded upstream."
					},
					"input": {
						"description": "Input for the Responses API. Stogas accepts a plain string or an array of Responses input/output items.",
						"oneOf": [
							{
								"type": "string"
							},
							{
								"type": "array",
								"items": {
									"$ref": "#/components/schemas/ResponsesRequestInputItem"
								}
							}
						]
					},
					"stream": {
						"type": "boolean",
						"default": false
					},
					"background": {
						"type": "boolean",
						"description": "Not supported. Background Responses require asynchronous lifecycle and reconciliation support, so Stogas rejects this field."
					},
					"conversation": {
						"type": "string",
						"description": "Not supported. Provider-side conversation state hides prompt reconstruction before hold placement, so Stogas rejects this field."
					},
					"fallbacks": {
						"type": "array",
						"description": "Not supported. Stogas fallback policy is server-owned and client-supplied fallbacks are rejected.",
						"items": {
							"type": "string"
						}
					},
					"container": {
						"description": "Not supported. Stateful provider containers require separate lifecycle, isolation, and pricing controls.",
						"oneOf": [
							{
								"type": "string"
							},
							{
								"type": "object"
							}
						]
					},
					"include": {
						"type": "array",
						"description": "Additional OpenAI Responses fields to request. Values are provider-owned and not enum-mirrored by Stogas; Anthropic-backed deployments reject this OpenAI-only field.",
						"items": {
							"type": "string"
						}
					},
					"instructions": {
						"type": "string"
					},
					"max_output_tokens": {
						"type": "integer",
						"minimum": 0,
						"description": "Maximum output token cap. Zero is only accepted for Anthropic cache prewarm requests that include an allowed cache_control marker."
					},
					"max_tool_calls": {
						"type": "integer",
						"minimum": 1,
						"description": "Optional cap for priced hosted Responses tools. If omitted for priced hosted tools, Stogas injects an effective cap of 50 before dispatch. On Anthropic Responses, this field is only accepted when Stogas can translate it to hosted-tool max_uses; token-priced function, custom, and MCP tools must omit it."
					},
					"metadata": {
						"type": "object",
						"description": "Application metadata for Stogas telemetry only. Stogas validates this object, logs it internally, and removes it before upstream dispatch.",
						"maxProperties": 16,
						"propertyNames": {
							"type": "string",
							"minLength": 1,
							"maxLength": 64
						},
						"additionalProperties": {
							"type": "string",
							"maxLength": 512
						}
					},
					"parallel_tool_calls": {
						"type": "boolean",
						"description": "Whether the model may call multiple tools in parallel."
					},
					"previous_response_id": {
						"type": "string",
						"description": "Not supported. Provider-side continuation state hides prompt reconstruction before hold placement, so Stogas rejects this field."
					},
					"task_budget": {
						"type": "object",
						"description": "Anthropic-only advisory token budget object forwarded as output_config.task_budget. Provider-owned details do not reduce Stogas billing holds.",
						"additionalProperties": true
					},
					"context_management": {
						"type": "object",
						"description": "Anthropic-only context management object forwarded as provider-owned runtime behavior. Stogas does not treat compaction as a hold reduction.",
						"additionalProperties": true
					},
					"inference_geo": {
						"type": "string",
						"description": "Anthropic-only deployment routing hint. `global` selects standard multi-region pricing, while `us` selects US-only inference pricing. Stogas sends the selected Anthropic `inference_geo` upstream.",
						"enum": [
							"global",
							"us"
						]
					},
					"prompt_cache_key": {
						"type": "string",
						"description": "OpenAI-only prompt cache key. Must be non-empty UTF-8 up to 256 bytes and must not contain NUL, CR, or LF. Anthropic deployments reject this field; use `cache_control` instead.",
						"minLength": 1,
						"maxLength": 256
					},
					"reasoning": {
						"type": "object",
						"description": "Reasoning configuration for models that expose reasoning controls.",
						"properties": {
							"effort": {
								"type": "string"
							},
							"summary": {
								"type": "string"
							},
							"generate_summary": {
								"type": "string",
								"description": "Deprecated upstream alias for `summary`."
							},
							"max_tokens": {
								"type": "integer",
								"minimum": 1
							}
						},
						"additionalProperties": false
					},
					"safety_identifier": {
						"type": "string",
						"description": "Client-supplied safety identifiers are not supported. Stogas sets provider-visible safety/user identifiers from the authenticated API key."
					},
					"service_tier": {
						"type": "string",
						"description": "Provider service tier selection preserved by the gateway. OpenAI accepts `auto`, `default`, `flex`, and `priority`; `scale` and `provisioned` are not available. Anthropic accepts `auto`, `priority`, `default`, `flex`, `standard`, and `standard_only`; all currently use standard-tier Stogas deployment rates. Anthropic `auto` / `priority` are sent upstream as `auto`, while `default` / `flex` / `standard` / `standard_only` are sent as `standard_only`.",
						"enum": [
							"auto",
							"default",
							"flex",
							"priority",
							"standard",
							"standard_only"
						]
					},
					"speed": {
						"type": "string",
						"description": "Anthropic-only deployment routing hint. `fast` selects cataloged fast-mode deployments where available; `standard` selects normal-speed deployments.",
						"enum": [
							"fast",
							"standard"
						]
					},
					"stream_options": {
						"type": "object",
						"description": "Additional options for streamed Responses. Requires `stream:true`. Stogas accepts `include_obfuscation`; `include_usage` is server-owned and rejected on this route.",
						"properties": {
							"include_obfuscation": {
								"type": "boolean"
							}
						},
						"additionalProperties": false
					},
					"store": {
						"type": "boolean",
						"description": "Not supported. Provider retention behavior is server-owned; requests that set store are rejected before upstream dispatch, and OpenAI-bound requests are forced to store:false."
					},
					"temperature": {
						"type": "number",
						"default": 1,
						"description": "Sampling temperature. Stogas validates JSON shape only; provider-owned numeric bounds are left to the selected provider. Anthropic deployments reject requests that set both `temperature` and `top_p`."
					},
					"frequency_penalty": {
						"type": "number",
						"description": "OpenAI-only Responses frequency penalty. Anthropic deployments reject this field."
					},
					"presence_penalty": {
						"type": "number",
						"description": "OpenAI-only Responses presence penalty. Anthropic deployments reject this field."
					},
					"text": {
						"type": "object",
						"description": "Text output configuration, including structured output format and verbosity.",
						"properties": {
							"format": {
								"type": "object",
								"description": "Provider-owned Responses text format. Stogas forwards supported OpenAI-compatible fields and leaves provider-specific format details to the selected upstream provider.",
								"properties": {
									"type": {
										"type": "string"
									},
									"name": {
										"type": "string"
									},
									"schema": {
										"type": "object"
									},
									"strict": {
										"type": "boolean"
									}
								},
								"additionalProperties": true
							},
							"verbosity": {
								"type": "string"
							}
						},
						"additionalProperties": true
					},
					"top_logprobs": {
						"type": "integer",
						"description": "Provider-owned Responses log probability detail. Anthropic deployments reject this OpenAI-only field."
					},
					"top_k": {
						"type": "integer",
						"description": "Anthropic-only sampling control passed through the explicit Stogas allowlist. Rejected for OpenAI deployments."
					},
					"top_p": {
						"type": "number",
						"description": "Nucleus sampling control. Stogas validates JSON shape only; provider-owned numeric bounds are left to the selected provider. Anthropic deployments reject requests that set both `temperature` and `top_p`."
					},
					"tool_choice": {
						"type": [
							"string",
							"object"
						],
						"description": "Tool choice, such as `auto`, `none`, `required`, or a named tool object."
					},
					"tools": {
						"type": "array",
						"description": "Responses API tool definitions accepted by compatible providers. Stogas admits function/custom tools, remote MCP tools with narrowed allowed_tools, priced provider-hosted web search tools, and Anthropic web_fetch tools. See the Model Tools guide for the current provider matrix and billing behavior.",
						"items": {
							"type": "object"
						}
					},
					"truncation": {
						"type": "string"
					},
					"user": {
						"type": "string",
						"description": "Client-supplied user identifiers are not supported. Stogas sets upstream user identity from the authenticated API key."
					},
					"prompt_cache_retention": {
						"type": "string",
						"description": "OpenAI-only prompt cache retention policy. Stogas validates that this is a string, normalizes known aliases before dispatch, and rejects this field on Anthropic deployments."
					},
					"stop_sequences": {
						"type": "array",
						"description": "Anthropic-only stop sequence alias passed through the explicit Stogas allowlist. Stogas rejects this field on OpenAI deployments. Responses does not admit top-level `stop`; Chat rejects requests that set both `stop` and `stop_sequences`.",
						"items": {
							"type": "string"
						}
					},
					"cache_control": {
						"type": "object",
						"description": "Anthropic-only prompt caching control. Stogas accepts `{type:\"ephemeral\"}` with optional `ttl:\"5m\"` or `\"1h\"`, validates explicit cache controls on input content/tool blocks, prices cache writes conservatively for holds, and rejects this field on OpenAI deployments.",
						"properties": {
							"type": {
								"type": "string",
								"enum": [
									"ephemeral"
								]
							},
							"ttl": {
								"type": "string",
								"enum": [
									"5m",
									"1h"
								]
							}
						},
						"required": [
							"type"
						],
						"additionalProperties": false
					},
					"reasoning.effort": {
						"type": "string"
					}
				},
				"example": {
					"model": "gpt-5.5-latest",
					"input": "Reflect on the issue of trusting trust",
					"temperature": 0.7
				}
			},
			"ResponseObject": {
				"type": "object",
				"description": "Non-streaming OpenAI-compatible Responses API response.",
				"properties": {
					"id": {
						"type": "string",
						"format": "uuid",
						"description": "Unique response identifier generated by the gateway."
					},
					"object": {
						"type": "string",
						"enum": [
							"response"
						],
						"description": "The object type, which is always `response`."
					},
					"created_at": {
						"type": "integer",
						"description": "Unix timestamp of response creation."
					},
					"completed_at": {
						"type": [
							"integer",
							"null"
						],
						"description": "Unix timestamp of response completion."
					},
					"status": {
						"type": "string",
						"enum": [
							"completed",
							"failed",
							"in_progress",
							"cancelled",
							"queued",
							"incomplete"
						]
					},
					"error": {
						"type": [
							"object",
							"null"
						],
						"properties": {
							"code": {
								"type": "string"
							},
							"message": {
								"type": "string"
							}
						}
					},
					"incomplete_details": {
						"type": [
							"object",
							"null"
						],
						"properties": {
							"reason": {
								"type": "string"
							}
						}
					},
					"model": {
						"type": "string",
						"description": "Model used for the response."
					},
					"output": {
						"type": "array",
						"description": "Response output items.",
						"items": {
							"$ref": "#/components/schemas/ResponsesInputItem"
						}
					},
					"output_text": {
						"type": "string",
						"description": "Convenience concatenation of output text content when available."
					},
					"background": {
						"type": "boolean"
					},
					"conversation": {
						"type": [
							"object",
							"null"
						],
						"properties": {
							"id": {
								"type": "string"
							}
						}
					},
					"include": {
						"type": "array",
						"items": {
							"type": "string"
						}
					},
					"instructions": {
						"type": [
							"string",
							"array",
							"null"
						]
					},
					"max_output_tokens": {
						"type": [
							"integer",
							"null"
						]
					},
					"max_tool_calls": {
						"type": [
							"integer",
							"null"
						]
					},
					"metadata": {
						"type": "object"
					},
					"parallel_tool_calls": {
						"type": "boolean"
					},
					"previous_response_id": {
						"type": [
							"string",
							"null"
						]
					},
					"prompt_cache_key": {
						"type": [
							"string",
							"null"
						]
					},
					"reasoning": {
						"type": "object"
					},
					"safety_identifier": {
						"type": [
							"string",
							"null"
						]
					},
					"service_tier": {
						"type": [
							"string",
							"null"
						]
					},
					"store": {
						"type": "boolean"
					},
					"temperature": {
						"type": "number"
					},
					"text": {
						"type": "object"
					},
					"tool_choice": {
						"type": [
							"string",
							"object"
						]
					},
					"tools": {
						"type": "array",
						"items": {
							"type": "object"
						}
					},
					"top_logprobs": {
						"type": "integer"
					},
					"top_p": {
						"type": "number"
					},
					"truncation": {
						"type": "string"
					},
					"usage": {
						"$ref": "#/components/schemas/ResponsesUsage"
					},
					"stogas": {
						"type": "object",
						"title": "Gateway Metadata",
						"description": "Optional Stogas metadata returned when requested with Stogas debug headers.",
						"properties": {
							"provider": {
								"type": "string",
								"description": "The upstream AI provider that served the request"
							},
							"latency": {
								"type": "integer",
								"description": "Total round-trip latency in milliseconds"
							},
							"model_requested": {
								"type": "string",
								"description": "The exact model alias or name requested"
							},
							"model_deployment": {
								"type": "string",
								"description": "The upstream model deployment selected by the gateway"
							},
							"provider_response_headers": {
								"type": "object",
								"additionalProperties": {
									"type": "string"
								},
								"description": "Catalog-approved response headers from the upstream provider"
							},
							"raw_request": {
								"type": [
									"object",
									"array",
									"string",
									"number",
									"boolean",
									"null"
								],
								"description": "The translated upstream provider request, returned when requested."
							},
							"raw_response": {
								"type": [
									"object",
									"array",
									"string",
									"number",
									"boolean",
									"null"
								],
								"description": "The raw upstream provider JSON body, returned when requested."
							}
						}
					}
				},
				"required": [
					"id",
					"object",
					"created_at",
					"model",
					"output",
					"status"
				],
				"example": {
					"id": "8ee3487c-e5b1-4fe0-9dd6-84bc23ddd5f7",
					"object": "response",
					"created_at": 1714343120,
					"completed_at": 1714343121,
					"status": "completed",
					"error": null,
					"incomplete_details": null,
					"model": "gpt-5.5",
					"output": [
						{
							"id": "msg_0192f217-35b0-7e2c-9be7-f4cc24f2a4b0",
							"type": "message",
							"status": "completed",
							"role": "assistant",
							"content": [
								{
									"type": "output_text",
									"text": "You can never fully trust code you did not write yourself."
								}
							]
						}
					],
					"output_text": "You can never fully trust code you did not write yourself.",
					"usage": {
						"input_tokens": 9,
						"output_tokens": 11,
						"total_tokens": 20
					}
				}
			},
			"ProviderRoutingPreference": {
				"oneOf": [
					{
						"type": "string",
						"description": "Known provider ID or provider slug, such as `openai`, `open-ai`, or `anthropic`."
					},
					{
						"type": "object",
						"additionalProperties": false,
						"anyOf": [
							{
								"required": [
									"only"
								]
							},
							{
								"required": [
									"order"
								]
							}
						],
						"properties": {
							"only": {
								"type": "array",
								"items": {
									"type": "string"
								},
								"minItems": 1,
								"description": "Provider IDs or provider slugs allowed to serve this request."
							},
							"order": {
								"type": "array",
								"items": {
									"type": "string"
								},
								"minItems": 1,
								"description": "Preferred provider order after the optional `only` filter is applied."
							}
						},
						"description": "Stogas-owned provider routing rules. At least one of `only` or `order` is required."
					}
				],
				"description": "Optional Stogas-owned routing preference used to select a provider when a public model slug is available from more than one provider. This field is never forwarded upstream."
			},
			"ResponsesRequestInputItem": {
				"type": "object",
				"description": "Text-only Responses API input item accepted by Stogas. Function calls, tool outputs, reasoning items, files, images, and audio inputs are rejected before upstream dispatch.",
				"properties": {
					"id": {
						"type": "string"
					},
					"type": {
						"type": "string",
						"enum": [
							"message",
							"input_text",
							"output_text",
							"refusal"
						]
					},
					"status": {
						"type": "string"
					},
					"role": {
						"type": "string",
						"enum": [
							"assistant",
							"user",
							"system",
							"developer"
						]
					},
					"content": {
						"$ref": "#/components/schemas/ResponsesRequestMessageContent"
					},
					"text": {
						"type": "string"
					},
					"refusal": {
						"type": "string"
					}
				}
			},
			"ResponsesInputItem": {
				"type": "object",
				"description": "Responses API input or previous output item. Supported item types include messages, function calls and outputs, tool calls, reasoning, and item references.",
				"properties": {
					"id": {
						"type": "string"
					},
					"type": {
						"type": "string",
						"enum": [
							"message",
							"web_search_call",
							"function_call",
							"function_call_output",
							"mcp_call",
							"custom_tool_call",
							"custom_tool_call_output",
							"mcp_list_tools",
							"mcp_approval_request",
							"mcp_approval_responses",
							"reasoning",
							"item_reference",
							"refusal"
						]
					},
					"status": {
						"type": "string"
					},
					"role": {
						"type": "string",
						"enum": [
							"assistant",
							"user",
							"system",
							"developer"
						]
					},
					"content": {
						"$ref": "#/components/schemas/ResponsesMessageContent"
					},
					"call_id": {
						"type": "string"
					},
					"name": {
						"type": "string"
					},
					"arguments": {
						"type": "string"
					},
					"output": {
						"description": "Tool output payload for function_call_output and related output items."
					},
					"summary": {
						"type": "array",
						"items": {
							"type": "object"
						}
					},
					"encrypted_content": {
						"type": "string"
					}
				}
			},
			"ResponsesUsage": {
				"type": "object",
				"description": "Responses API token usage statistics.",
				"properties": {
					"input_tokens": {
						"type": "integer",
						"description": "Number of input tokens."
					},
					"output_tokens": {
						"type": "integer",
						"description": "Number of output tokens."
					},
					"total_tokens": {
						"type": "integer",
						"description": "Total number of tokens."
					},
					"input_tokens_details": {
						"type": "object",
						"properties": {
							"text_tokens": {
								"type": "integer"
							},
							"audio_tokens": {
								"type": "integer"
							},
							"image_tokens": {
								"type": "integer"
							},
							"cached_tokens": {
								"type": "integer"
							},
							"cached_read_tokens": {
								"type": "integer"
							},
							"cached_write_tokens": {
								"type": "integer"
							}
						}
					},
					"output_tokens_details": {
						"type": "object",
						"properties": {
							"text_tokens": {
								"type": "integer"
							},
							"audio_tokens": {
								"type": "integer"
							},
							"image_tokens": {
								"type": "integer"
							},
							"reasoning_tokens": {
								"type": "integer"
							},
							"accepted_prediction_tokens": {
								"type": "integer"
							},
							"rejected_prediction_tokens": {
								"type": "integer"
							}
						}
					},
					"cost": {
						"type": [
							"number",
							"null"
						],
						"description": "Upstream inference cost when available."
					}
				},
				"required": [
					"input_tokens",
					"output_tokens",
					"total_tokens"
				]
			},
			"ErrorResponse": {
				"type": "object",
				"properties": {
					"error": {
						"type": "object",
						"properties": {
							"message": {
								"type": "string"
							},
							"type": {
								"type": "string"
							}
						}
					}
				}
			},
			"ResponsesRequestMessageContent": {
				"description": "Text-only Responses message content as either a string or an array of text content blocks.",
				"oneOf": [
					{
						"type": "string"
					},
					{
						"type": "array",
						"items": {
							"$ref": "#/components/schemas/ResponsesRequestContentBlock"
						}
					}
				]
			},
			"ResponsesMessageContent": {
				"description": "Responses message content as either a string or an array of content blocks.",
				"oneOf": [
					{
						"type": "string"
					},
					{
						"type": "array",
						"items": {
							"$ref": "#/components/schemas/ResponsesContentBlock"
						}
					}
				]
			},
			"ResponsesRequestContentBlock": {
				"type": "object",
				"description": "Text-only Responses content block accepted by Stogas.",
				"required": [
					"type"
				],
				"properties": {
					"type": {
						"type": "string",
						"enum": [
							"input_text",
							"output_text",
							"refusal"
						]
					},
					"text": {
						"type": "string"
					},
					"refusal": {
						"type": "string"
					}
				}
			},
			"ResponsesContentBlock": {
				"type": "object",
				"required": [
					"type"
				],
				"properties": {
					"type": {
						"type": "string",
						"enum": [
							"input_text",
							"output_text",
							"refusal",
							"reasoning_text",
							"rendered_content",
							"compaction"
						]
					},
					"text": {
						"type": "string"
					},
					"refusal": {
						"type": "string"
					},
					"annotations": {
						"type": "array",
						"items": {
							"type": "object"
						}
					},
					"logprobs": {
						"type": "array",
						"items": {
							"type": "object"
						}
					},
					"signature": {
						"type": "string"
					},
					"citations": {
						"type": "object"
					}
				}
			}
		},
		"responses": {
			"BadRequest": {
				"description": "<span className=\"text-red-500 font-bold\">Bad Request:</span> The request was malformed, missing required fields, or specifying an unavailable model.",
				"content": {
					"application/json": {
						"schema": {
							"$ref": "#/components/schemas/ErrorResponse"
						},
						"example": {
							"error": {
								"message": "Invalid text completion request: the 'messages' array cannot be empty.",
								"type": "invalid_request_error"
							}
						}
					}
				}
			},
			"Unauthorized": {
				"description": "<span className=\"text-red-500 font-bold\">Unauthorized:</span> The API key provided was missing or invalid.",
				"content": {
					"application/json": {
						"schema": {
							"$ref": "#/components/schemas/ErrorResponse"
						},
						"example": {
							"error": {
								"message": "Invalid API key",
								"type": "authentication_error"
							}
						}
					}
				}
			},
			"PaymentRequired": {
				"description": "<span className=\"text-red-500 font-bold\">Payment Required:</span> Returned when your account balance is insufficient or the API key lifetime or recurring spend limit is exhausted.",
				"content": {
					"application/json": {
						"schema": {
							"$ref": "#/components/schemas/ErrorResponse"
						},
						"example": {
							"error": {
								"message": "Insufficient balance. Please add funds to your Stogas account to continue making requests.",
								"type": "billing_error"
							}
						}
					}
				}
			},
			"Forbidden": {
				"description": "<span className=\"text-red-500 font-bold\">Forbidden:</span> The API key is disabled or expired. Expired keys are disabled automatically before the error is returned.",
				"content": {
					"application/json": {
						"schema": {
							"$ref": "#/components/schemas/ErrorResponse"
						},
						"example": {
							"error": {
								"message": "API key is disabled",
								"type": "permission_denied"
							}
						}
					}
				}
			},
			"NotFound": {
				"description": "<span className=\"text-red-500 font-bold\">Not Found:</span> The requested endpoint route does not exist.",
				"content": {
					"application/json": {
						"schema": {
							"$ref": "#/components/schemas/ErrorResponse"
						},
						"example": {
							"error": {
								"message": "Not Found: The requested endpoint '/v1/chat/compl' does not exist.",
								"type": "invalid_request_error"
							}
						}
					}
				}
			},
			"Conflict": {
				"description": "<span className=\"text-red-500 font-bold\">Conflict:</span> The gateway request ID was already finalized, expired, or reused with different hold parameters. Generate a new request ID and retry.",
				"content": {
					"application/json": {
						"schema": {
							"$ref": "#/components/schemas/ErrorResponse"
						},
						"example": {
							"error": {
								"message": "Request already finalized; generate a new requestId",
								"type": "invalid_request_error"
							}
						}
					}
				}
			},
			"PayloadTooLarge": {
				"description": "<span className=\"text-red-500 font-bold\">Payload Too Large:</span> The request body exceeds the gateway's maximum allowed size.",
				"content": {
					"application/json": {
						"schema": {
							"$ref": "#/components/schemas/ErrorResponse"
						},
						"example": {
							"error": {
								"message": "Payload Too Large: The request body exceeds the maximum allowed size of 100MB.",
								"type": "invalid_request_error"
							}
						}
					}
				}
			},
			"RateLimited": {
				"description": "<span className=\"text-red-500 font-bold\">Rate Limited:</span> The API key token bucket does not currently have capacity for another request.",
				"content": {
					"application/json": {
						"schema": {
							"$ref": "#/components/schemas/ErrorResponse"
						},
						"example": {
							"error": {
								"message": "API key rate limit exceeded",
								"type": "rate_limit_error"
							}
						}
					}
				}
			},
			"InternalError": {
				"description": "<span className=\"text-red-500 font-bold\">Internal Server Error:</span> An unexpected error occurred within the gateway or upstream provider.",
				"content": {
					"application/json": {
						"schema": {
							"$ref": "#/components/schemas/ErrorResponse"
						},
						"example": {
							"error": {
								"message": "Upstream provider error",
								"type": "gateway_error"
							}
						}
					}
				}
			},
			"ServiceUnavailable": {
				"description": "<span className=\"text-red-500 font-bold\">Service Unavailable:</span> The gateway could not reach the billing database while placing the authorization hold. The provider is not called and no usage telemetry is written.",
				"content": {
					"application/json": {
						"schema": {
							"$ref": "#/components/schemas/ErrorResponse"
						},
						"example": {
							"error": {
								"message": "Gateway billing database unavailable",
								"type": "gateway_error"
							}
						}
					}
				}
			}
		}
	},
	"tags": [
		{
			"name": "OpenAI-compatible",
			"description": "Model inference endpoints."
		}
	],
	"security": [
		{
			"bearerAuth": []
		},
		{
			"authorizationHeader": []
		},
		{
			"apiKeyHeader": []
		},
		{
			"xApiKeyHeader": []
		},
		{
			"xGoogApiKeyHeader": []
		}
	]
}