Skip to main content
GET
/
v1
/
openapi.json
OpenAPI Specification
curl --request GET \
  --url https://api.example.com/v1/openapi.json
{
  "openapi": "<string>",
  "info": {},
  "servers": [
    {}
  ],
  "paths": {},
  "components": {}
}

​
Endpoint

GET /v1/openapi.json

​
Authentication

No authentication required.

​
Response

Returns the complete OpenAPI 3.1.0 specification document in JSON format.
​
openapi
string
required
OpenAPI specification version. Always "3.1.0".
​
info
object
required
API metadata information.
  • title (string): API title - “Open Chat Widget API”
  • version (string): API version - “1.0.0”
  • description (string): API description
​
servers
array
required
Array of server objects. Contains the base URL dynamically determined from the request.
​
paths
object
required
All available API endpoints with their operations, parameters, and responses.
​
components
object
required
Reusable components including security schemes:
  • ApiKeyAuth: Widget API key authentication (x-api-key header)
  • AdminApiKeyAuth: Admin API key authentication (x-admin-api-key header)

​
Success Response (200)

{
  "openapi": "3.1.0",
  "info": {
    "title": "Open Chat Widget API",
    "version": "1.0.0",
    "description": "Headless chat and conversation APIs for custom frontends."
  },
  "servers": [
    {
      "url": "https://your-api-domain.com"
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "summary": "Health check",
        "responses": {
          "200": {
            "description": "Service is healthy"
          }
        }
      }
    },
    "/v1/chat": {
      "post": {
        "summary": "Non-streaming chat response",
        "security": [{"ApiKeyAuth": []}],
        "responses": {
          "200": {
            "description": "Assistant response"
          }
        }
      }
    },
    "/v1/chat/stream": {
      "post": {
        "summary": "Streaming chat response (NDJSON)",
        "security": [{"ApiKeyAuth": []}],
        "responses": {
          "200": {
            "description": "NDJSON stream events"
          }
        }
      }
    },
    "/v1/admin/conversations": {
      "get": {
        "summary": "List conversations",
        "security": [{"AdminApiKeyAuth": []}],
        "responses": {
          "200": {
            "description": "Conversation list"
          }
        }
      }
    },
    "/v1/admin/conversations/{conversationId}": {
      "get": {
        "summary": "Get conversation thread",
        "security": [{"AdminApiKeyAuth": []}],
        "parameters": [
          {
            "name": "conversationId",
            "in": "path",
            "required": true,
            "schema": {"type": "string"}
          }
        ],
        "responses": {
          "200": {
            "description": "Conversation with messages"
          },
          "404": {
            "description": "Conversation not found"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key"
      },
      "AdminApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-admin-api-key"
      }
    }
  }
}

​
Example Requests

cURL
curl https://your-api-domain.com/v1/openapi.json
JavaScript
const response = await fetch('https://your-api-domain.com/v1/openapi.json');
const spec = await response.json();

console.log(spec.info.title); // "Open Chat Widget API"
console.log(Object.keys(spec.paths)); // List all endpoints
Python
import requests

response = requests.get('https://your-api-domain.com/v1/openapi.json')
spec = response.json()

print(spec['info']['title'])  # "Open Chat Widget API"
print(spec['paths'].keys())   # List all endpoints

​
Use Cases

​
API Documentation Tools

Import the OpenAPI specification into tools like:
  • Swagger UI: Interactive API documentation
  • Postman: API testing and collection generation
  • Insomnia: REST client with OpenAPI support
  • Redoc: Beautiful API documentation renderer

​
Code Generation

Generate client SDKs in various languages: 
# Generate TypeScript client
openapi-generator-cli generate \
  -i https://your-api-domain.com/v1/openapi.json \
  -g typescript-fetch \
  -o ./src/api-client

# Generate Python client
openapi-generator-cli generate \
  -i https://your-api-domain.com/v1/openapi.json \
  -g python \
  -o ./api-client

​
API Testing

Use the specification for automated API testing: 
import SwaggerParser from '@apidevtools/swagger-parser';

const spec = await SwaggerParser.validate(
  'https://your-api-domain.com/v1/openapi.json'
);

console.log('API specification is valid!');

​
Notes

  • The server URL is dynamically generated based on the incoming request
  • The specification is generated at runtime, not served from a static file
  • Includes all public and admin endpoints
  • Documents authentication requirements for each endpoint
  • Compatible with OpenAPI 3.1.0 specification

Build docs developers (and LLMs) love

Get started for freeTalk to us