{ "openapi": "3.0.3", "info": { "title": "Qubrid Chat API", "version": "1.0.0", "description": "Generate text responses using large language models via the OpenAI-compatible chat completions API." }, "servers": [ { "url": "https://platform.qubrid.com/v1" } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key" } }, "schemas": { "ChatRequest": { "type": "object", "required": [ "model", "messages" ], "properties": { "model": { "type": "string", "example": "openai/gpt-oss-120b", "description": "The language model to use." }, "messages": { "type": "array", "description": "Conversation messages in chat format.", "items": { "type": "object", "required": [ "role", "content" ], "properties": { "role": { "type": "string", "example": "user", "description": "Role of the message sender (system, user, assistant)." }, "content": { "type": "string", "example": "Summarize this support ticket into bullet-point next steps for the agent." } } } }, "max_tokens": { "type": "integer", "default": 4096, "description": "Maximum number of tokens to generate." }, "temperature": { "type": "number", "default": 0.7, "description": "Controls randomness in output." }, "top_p": { "type": "number", "default": 1, "description": "Nucleus sampling parameter." }, "stream": { "type": "boolean", "default": true, "description": "Whether to stream responses incrementally." } } }, "ChatResponse": { "type": "object", "description": "Standard OpenAI-compatible chat completion response or streamed chunks.", "properties": { "id": { "type": "string", "example": "chatcmpl-abc123" }, "object": { "type": "string", "example": "chat.completion" }, "created": { "type": "integer", "example": 1710000000 }, "model": { "type": "string", "example": "openai/gpt-oss-120b" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "example": 0 }, "message": { "type": "object", "properties": { "role": { "type": "string", "example": "assistant" }, "content": { "type": "string", "example": "- Identify customer issue\n- Provide resolution steps\n- Follow up with confirmation" } } }, "finish_reason": { "type": "string", "example": "stop" } } } }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "integer", "example": 20 }, "completion_tokens": { "type": "integer", "example": 10 }, "total_tokens": { "type": "integer", "example": 30 } } }, "x_metrics": { "type": "object", "description": "Performance metrics for the request.", "properties": { "ttft_seconds": { "type": "number", "example": 0.38 }, "tps": { "type": "number", "example": 42.1 }, "total_time_seconds": { "type": "number", "example": 1.24 } } } } }, "ErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "message", "type", "code", "request_id" ], "properties": { "message": { "type": "string", "example": "Missing required parameter: 'model'." }, "type": { "type": "string", "example": "invalid_request_error", "description": "Machine-readable error category." }, "code": { "type": "string", "example": "invalid_request", "description": "Specific machine-readable error code." }, "param": { "type": "string", "nullable": true, "example": "model", "description": "The request field that caused the error, or null." }, "request_id": { "type": "string", "example": "req-qubrid-abc123", "description": "Unique request identifier for debugging and support." } } } } }, "ModelNotFoundErrorResponse": { "type": "object", "description": "Returned when the specified model does not exist or is not available.", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "message", "type", "code", "request_id" ], "properties": { "message": { "type": "string", "example": "The model 'gpt-99' does not exist or is not available." }, "type": { "type": "string", "example": "invalid_request_error" }, "code": { "type": "string", "example": "model_not_found" }, "param": { "type": "string", "nullable": true, "example": "model" }, "request_id": { "type": "string", "example": "req-qubrid-abc123" } } } } }, "ContextLengthExceededErrorResponse": { "type": "object", "description": "Returned when the input exceeds the model's maximum context window.", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "message", "type", "code", "request_id" ], "properties": { "message": { "type": "string", "example": "Context length exceeded: The input exceeds the model's maximum context length." }, "type": { "type": "string", "example": "invalid_request_error" }, "code": { "type": "string", "example": "context_length_exceeded" }, "param": { "type": "string", "nullable": true, "example": "messages" }, "request_id": { "type": "string", "example": "req-qubrid-abc123" } } } } }, "InsufficientQuotaErrorResponse": { "type": "object", "description": "Returned when the account does not have enough credits to complete the request.", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "message", "type", "code", "request_id" ], "properties": { "message": { "type": "string", "example": "Insufficient credits to process this request. Please recharge your account." }, "type": { "type": "string", "example": "insufficient_quota" }, "code": { "type": "string", "example": "insufficient_quota" }, "param": { "type": "string", "nullable": true, "example": null }, "request_id": { "type": "string", "example": "req-qubrid-abc123" } } } } }, "RateLimitErrorResponse": { "type": "object", "description": "Returned when request rate limits are exceeded.", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "message", "type", "code", "request_id" ], "properties": { "message": { "type": "string", "example": "Rate limit exceeded. Please try again later." }, "type": { "type": "string", "example": "rate_limit_error" }, "code": { "type": "string", "example": "rate_limit_exceeded" }, "param": { "type": "string", "nullable": true, "example": null }, "request_id": { "type": "string", "example": "req-qubrid-abc123" } } } } }, "AuthenticationErrorResponse": { "type": "object", "description": "Returned when authentication fails.", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "message", "type", "code", "request_id" ], "properties": { "message": { "type": "string", "example": "Missing authentication credentials." }, "type": { "type": "string", "example": "authentication_error" }, "code": { "type": "string", "example": "missing_api_key" }, "param": { "type": "string", "nullable": true, "example": null }, "request_id": { "type": "string", "example": "req-qubrid-abc123" } } } } }, "PermissionErrorResponse": { "type": "object", "description": "Returned when the authenticated account does not have permission to access the resource.", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "message", "type", "code", "request_id" ], "properties": { "message": { "type": "string", "example": "Permission denied: You do not have permission to access this model." }, "type": { "type": "string", "example": "permission_error" }, "code": { "type": "string", "example": "insufficient_quota" }, "param": { "type": "string", "nullable": true, "example": null }, "request_id": { "type": "string", "example": "req-qubrid-abc123" } } } } }, "ServerErrorResponse": { "type": "object", "description": "Returned when an internal or upstream server error occurs.", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "message", "type", "code", "request_id" ], "properties": { "message": { "type": "string", "example": "An unexpected error occurred while processing the request." }, "type": { "type": "string", "example": "server_error" }, "code": { "type": "string", "example": "internal_error" }, "param": { "type": "string", "nullable": true, "example": null }, "request_id": { "type": "string", "example": "req-qubrid-abc123" } } } } }, "BackendUnavailableErrorResponse": { "type": "object", "description": "Returned when the upstream AI provider is temporarily unavailable or could not be reached.", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "message", "type", "code", "request_id" ], "properties": { "message": { "type": "string", "example": "The backend service is temporarily unavailable." }, "type": { "type": "string", "example": "server_error" }, "code": { "type": "string", "example": "backend_unavailable" }, "param": { "type": "string", "nullable": true, "example": null }, "request_id": { "type": "string", "example": "req-qubrid-abc123" } } } } }, "GatewayTimeoutErrorResponse": { "type": "object", "description": "Returned when the upstream AI provider took too long to respond.", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "message", "type", "code", "request_id" ], "properties": { "message": { "type": "string", "example": "The request timed out while waiting for the backend service." }, "type": { "type": "string", "example": "server_error" }, "code": { "type": "string", "example": "backend_error" }, "param": { "type": "string", "nullable": true, "example": null }, "request_id": { "type": "string", "example": "req-qubrid-abc123" } } } } } } }, "security": [ { "BearerAuth": [] } ], "paths": { "/chat/completions": { "post": { "summary": "Create Chat Completion", "description": "Generate text responses using a large language model.", "operationId": "createChatCompletion", "tags": [ "Chat" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatRequest" }, "examples": { "Basic Chat": { "summary": "Generate a response from a prompt", "value": { "model": "openai/gpt-oss-120b", "messages": [ { "role": "user", "content": "Summarize this support ticket into bullet-point next steps for the agent." } ], "max_tokens": 4096, "temperature": 0.7, "top_p": 1, "stream": true } } } } } }, "responses": { "200": { "description": "Chat completion generated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatResponse" }, "example": { "id": "chatcmpl-abc123", "object": "chat.completion", "created": 1710000000, "model": "openai/gpt-oss-120b", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "- Identify issue\n- Provide solution\n- Confirm resolution with user" }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 20, "completion_tokens": 10, "total_tokens": 30 }, "x_metrics": { "ttft_seconds": 0.38, "tps": 42.1, "total_time_seconds": 1.24 } } } } }, "400": { "description": "Bad request - missing required fields, invalid values, or malformed JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationErrorResponse" } } } }, "402": { "description": "Insufficient credits to process the request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientQuotaErrorResponse" } } } }, "403": { "description": "Forbidden - authenticated but not allowed to access this model or resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "Model not found - the specified model does not exist or is not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelNotFoundErrorResponse" } } } }, "413": { "description": "Payload too large - input exceeds the model context window", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextLengthExceededErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerErrorResponse" } } } }, "502": { "description": "Bad gateway - upstream AI provider is unavailable or returned an error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackendUnavailableErrorResponse" } } } }, "504": { "description": "Gateway timeout - upstream AI provider took too long to respond", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayTimeoutErrorResponse" } } } } } } } } }