openapi: 3.0.1 info: title: LangDB AI Gateway Analytics Chat API description: OpenAI-compatible REST API for the LangDB AI Gateway. A single, project-scoped endpoint routes chat completions, embeddings, and image generation across 250+ models from providers such as OpenAI, Anthropic, Google, Meta, Mistral, and DeepSeek, while adding routing, guardrails, tracing, cost control, and an MCP (Model Context Protocol) gateway. Requests are authenticated with a Bearer API key and scoped to a project either by embedding the project id in the path (`/{project_id}/v1/...`) or by sending an `X-Project-Id` header. Tracing and session headers (`X-Thread-Id`, `X-Run-Id`, `X-Label`) attach observability metadata to each call. termsOfService: https://langdb.ai/terms contact: name: LangDB Support url: https://langdb.ai email: support@langdb.ai version: '1.0' servers: - url: https://api.us-east-1.langdb.ai/{project_id}/v1 description: Project-scoped OpenAI-compatible base (US East 1). variables: project_id: default: your-langdb-project-id description: LangDB project id. May instead be supplied via the X-Project-Id header. - url: https://api.us-east-1.langdb.ai description: Root base URL for analytics, usage, and thread management endpoints (US East 1). security: - bearerAuth: [] tags: - name: Chat description: OpenAI-compatible chat completions and model routing. paths: /chat/completions: post: operationId: createChatCompletion tags: - Chat summary: Create a chat completion description: OpenAI-compatible chat completion across any model routable by the gateway (e.g. `openai/gpt-4o`, `anthropic/claude-sonnet-4`, `gemini/gemini-2.5-pro`). Supports streaming via Server-Sent Events when `stream` is true, tool/function calling, structured outputs, and attaching MCP servers through the `mcp_servers` array. Tracing metadata can be attached via the X-Thread-Id, X-Run-Id, and X-Label headers. parameters: - $ref: '#/components/parameters/ProjectIdHeader' - $ref: '#/components/parameters/ThreadIdHeader' - $ref: '#/components/parameters/RunIdHeader' - $ref: '#/components/parameters/LabelHeader' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ChatCompletionRequest' responses: '200': description: A chat completion, or an SSE stream when stream is true. content: application/json: schema: $ref: '#/components/schemas/ChatCompletionResponse' text/event-stream: schema: type: string description: 'Server-Sent Events stream of ChatCompletionChunk objects terminated by `data: [DONE]`.' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/RateLimited' components: responses: Unauthorized: description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' RateLimited: description: Rate limit or cost limit exceeded. content: application/json: schema: $ref: '#/components/schemas/Error' schemas: McpServer: type: object properties: slug: type: string name: type: string type: type: string enum: - sse - ws description: Transport type for the MCP server. server_url: type: string format: uri ChatCompletionResponse: type: object properties: id: type: string object: type: string example: chat.completion created: type: integer model: type: string choices: type: array items: type: object properties: index: type: integer message: $ref: '#/components/schemas/ChatMessage' finish_reason: type: string usage: $ref: '#/components/schemas/Usage' ChatCompletionRequest: type: object required: - model - messages properties: model: type: string description: Provider-prefixed model identifier (e.g. openai/gpt-4o, anthropic/claude-sonnet-4) or a LangDB virtual model name. example: openai/gpt-4o-mini messages: type: array items: $ref: '#/components/schemas/ChatMessage' temperature: type: number format: float default: 1 top_p: type: number format: float max_tokens: type: integer stream: type: boolean default: false description: When true, partial deltas are streamed as Server-Sent Events. stop: oneOf: - type: string - type: array items: type: string tools: type: array description: Function/tool definitions in OpenAI tool-calling format. items: type: object tool_choice: oneOf: - type: string - type: object response_format: type: object description: Structured-output controls (e.g. a JSON object type). mcp_servers: type: array description: MCP servers to attach to the request, exposing their tools to the model. items: $ref: '#/components/schemas/McpServer' router: type: object description: LangDB routing configuration (fallbacks, load balancing, model targets). extra: type: object description: Additional gateway-specific routing or guardrail options. ChatMessage: type: object required: - role - content properties: role: type: string enum: - system - user - assistant - tool content: oneOf: - type: string - type: array items: type: object name: type: string tool_call_id: type: string Usage: type: object properties: prompt_tokens: type: integer completion_tokens: type: integer total_tokens: type: integer Error: type: object properties: error: type: object properties: message: type: string type: type: string code: type: string parameters: ThreadIdHeader: name: X-Thread-Id in: header required: false description: Groups related requests under the same conversation thread for tracing and session continuity. schema: type: string LabelHeader: name: X-Label in: header required: false description: Attaches a custom label/tag to the model call for categorization and tracing. schema: type: string ProjectIdHeader: name: X-Project-Id in: header required: false description: LangDB project id. Optional when the project id is embedded in the request path. schema: type: string RunIdHeader: name: X-Run-Id in: header required: false description: Tracks a single workflow execution (model call or tool invocation) for observability. schema: type: string securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: 'LangDB API key (project access token) sent as `Authorization: Bearer `.'