{ "openapi": "3.1.0", "info": { "title": "Accountable Gateway API", "version": "1.1.0-preview", "description": "Text completions, SSE streaming, structured JSON and customer-executed function tools on supported routes. Capability support does not imply healthcare approval. Customer PHI access remains closed." }, "servers": [ { "url": "https://gateway.accountablehq.com", "description": "Production and sandbox keys (invitation-only preview)." }, { "url": "http://127.0.0.1:4317", "description": "Local demo with simulated models." } ], "security": [ { "GatewayKey": [] } ], "tags": [ { "name": "Inference" }, { "name": "Models" } ], "paths": { "/v1/models": { "get": { "operationId": "listModels", "summary": "List models visible to the authenticated key", "tags": [ "Models" ], "responses": { "200": { "description": "Key-scoped configured aliases, excluding unavailable models. Not a PHI-eligibility certificate.", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Model" } } } } } } }, "401": { "description": "Invalid, revoked, paused, or wrong-environment API key.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Model, account, or healthcare-policy restriction.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/chat/completions": { "post": { "operationId": "createChatCompletion", "summary": "Generate text, structured JSON or tool calls; optionally stream on supported routes", "tags": [ "Inference" ], "description": "Maximum request body 4 MiB (4,194,304 bytes). Additional per-model input/output bounds apply. Duplicate idempotency keys return 409; response content is not stored for replay.", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,100}$" }, "description": "Opaque non-PHI logical request identifier, scoped to the API key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompletionRequest" }, "example": { "model": "care-small", "messages": [ { "role": "user", "content": "Explain an AI gateway in one sentence." } ], "max_tokens": 64, "data_classification": "synthetic", "use_case": "administrative_support" } } } }, "responses": { "200": { "description": "Settled text completion.", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "X-Gateway-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompletionResponse" } }, "text/event-stream": { "schema": { "type": "string" }, "description": "SSE chat.completion.chunk events, terminal billing metadata, optional usage-only event, and [DONE]. Errors after headers are sent in-band." } } }, "400": { "description": "Invalid request or unsupported feature.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid, revoked, paused, or wrong-environment API key.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient available credits or budget.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Model, account, or healthcare-policy restriction.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Duplicate or conflicting idempotency key.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 4 MiB.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Content-Type must be application/json.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Synthetic output withheld; completed usage is charged.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure; inspect request metadata before retrying.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Known provider rejection or uncertain outcome; inspect error.code.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "GatewayKey": { "type": "http", "scheme": "bearer", "bearerFormat": "Gateway API key", "description": "Environment-specific Accountable Gateway key; never a provider key." } }, "schemas": { "Message": { "type": "object", "additionalProperties": false, "required": [ "role" ], "properties": { "role": { "type": "string", "enum": [ "system", "user", "assistant", "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tool_call_id": { "type": "string" }, "tool_calls": { "type": "array", "minItems": 1, "maxItems": 16, "items": { "type": "object" } } }, "description": "Text roles require non-empty string content. Assistant calls may use null content; tool results require a matching pending tool_call_id." }, "CompletionRequest": { "type": "object", "additionalProperties": false, "required": [ "model", "messages" ], "properties": { "model": { "type": "string", "description": "Exact alias returned by GET /v1/models. Public roadmap entries may not be available." }, "messages": { "type": "array", "minItems": 1, "maxItems": 64, "items": { "$ref": "#/components/schemas/Message" } }, "max_tokens": { "type": "integer", "minimum": 1, "default": 4096, "description": "Defaults to 4,096 or the route output cap if lower. Must not exceed the configured model output cap." }, "temperature": { "type": "number", "minimum": 0, "maximum": 2, "default": 0.2 }, "stream": { "type": "boolean", "default": false, "description": "Requires streaming capability." }, "data_classification": { "type": "string", "enum": [ "synthetic", "phi" ], "description": "Healthcare keys always enforce PHI policy. Demo/staging default to synthetic; live defaults to phi. This field never grants data permissions." }, "use_case": { "type": "string", "enum": [ "administrative_support", "document_summarization" ], "default": "administrative_support" }, "stream_options": { "type": "object", "additionalProperties": false, "properties": { "include_usage": { "type": "boolean" } }, "description": "Requires stream:true." }, "response_format": { "type": "object", "description": "text, json_object, or json_schema with a name, strict:true, and the supported schema subset." }, "tools": { "type": "array", "minItems": 1, "maxItems": 16, "items": { "type": "object" }, "description": "Customer-executed function definitions. Requires tools capability." }, "tool_choice": { "description": "auto, none, required, or a declared function selector." }, "parallel_tool_calls": { "type": "boolean" } } }, "CompletionResponse": { "type": "object", "required": [ "id", "object", "created", "model", "choices", "usage", "gateway" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "created": { "type": "integer", "description": "Unix timestamp in seconds." }, "model": { "type": "string" }, "choices": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "required": [ "index", "message", "finish_reason" ], "properties": { "index": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "assistant" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tool_calls": { "type": "array", "items": { "type": "object" } }, "refusal": { "type": "string" } }, "required": [ "role", "content" ] }, "finish_reason": { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter" ] } } } }, "usage": { "type": "object", "required": [ "prompt_tokens", "completion_tokens", "total_tokens" ], "properties": { "prompt_tokens": { "type": "integer", "minimum": 0 }, "completion_tokens": { "type": "integer", "minimum": 0 }, "total_tokens": { "type": "integer", "minimum": 0 } } }, "gateway": { "type": "object", "required": [ "mode", "charged_usd", "markup_percent", "request_id", "usage_review", "healthcare_policy" ], "properties": { "mode": { "type": "string", "enum": [ "demo", "staging", "live", "evaluation" ] }, "charged_usd": { "type": "number", "minimum": 0 }, "markup_percent": { "type": "number", "enum": [ 15 ] }, "request_id": { "type": "string" }, "usage_review": { "type": "boolean" }, "healthcare_policy": { "type": "object", "required": [ "version", "hash", "classification", "use_case" ], "properties": { "version": { "type": "string" }, "hash": { "type": "string" }, "classification": { "type": "string" }, "use_case": { "type": "string" } } } } } } }, "Model": { "type": "object", "required": [ "id", "object", "owned_by" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "model" ] }, "owned_by": { "type": "string", "enum": [ "gateway" ] }, "capabilities": { "type": "object", "properties": { "streaming": { "type": "boolean" }, "structuredOutputs": { "type": "boolean" }, "tools": { "type": "boolean" } }, "required": [ "streaming", "structuredOutputs", "tools" ] } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }