Skip to content

7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encrypted keys. Personal experimentation only.

TypeScript

feat(docs): self-hosted OpenAPI reference at /v1/docs and /v1/openapi.json (#482)

Tashfeend0f2768cbd0e
diff --git a/README.md b/README.md
index 88833b62..bbe1abb7 100644
--- a/README.md
+++ b/README.md
@@ -851,6 +851,7 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full migration CLI and workflow
<a href="https://github.com/xsfhacg"><img src="https://images.weserv.nl/?url=github.com/xsfhacg.png&w=60&h=60&fit=cover&mask=circle" width="60" alt="@xsfhacg" /></a>
<a href="https://github.com/noobix"><img src="https://images.weserv.nl/?url=github.com/noobix.png&w=60&h=60&fit=cover&mask=circle" width="60" alt="@noobix" /></a>
<a href="https://github.com/nandukmelath"><img src="https://images.weserv.nl/?url=github.com/nandukmelath.png&w=60&h=60&fit=cover&mask=circle" width="60" alt="@nandukmelath" /></a>
+<a href="https://github.com/coffcoe"><img src="https://images.weserv.nl/?url=github.com/coffcoe.png&w=60&h=60&fit=cover&mask=circle" width="60" alt="@coffcoe" /></a>
## Terms of Service review
diff --git a/server/src/__tests__/routes/docs.test.ts b/server/src/__tests__/routes/docs.test.ts
new file mode 100644
index 00000000..32d76f2c
--- /dev/null
+++ b/server/src/__tests__/routes/docs.test.ts
@@ -0,0 +1,98 @@
+import { describe, it, expect, beforeAll } from 'vitest';
+import type { Express } from 'express';
+import { createApp } from '../../app.js';
+import { initDb } from '../../db/index.js';
+import { openapiSpec } from '../../docs/openapi.js';
+
+async function request(app: Express, method: string, path: string, headers: Record<string, string> = {}) {
+ const server = app.listen(0);
+ const addr = server.address() as any;
+ const url = `http://127.0.0.1:${addr.port}${path}`;
+ const res = await fetch(url, { method, headers });
+ const raw = await res.text();
+ server.close();
+ return { status: res.status, contentType: res.headers.get('content-type') || '', raw };
+}
+
+describe('OpenAPI docs routes', () => {
+ let app: Express;
+
+ beforeAll(() => {
+ process.env.ENCRYPTION_KEY = '0'.repeat(64);
+ initDb(':memory:');
+ app = createApp();
+ });
+
+ it('serves the spec as valid JSON at GET /v1/openapi.json', async () => {
+ const { status, contentType, raw } = await request(app, 'GET', '/v1/openapi.json');
+ expect(status).toBe(200);
+ expect(contentType).toContain('application/json');
+
+ const spec = JSON.parse(raw); // throws (fails the test) if not valid JSON
+ expect(spec.openapi).toMatch(/^3\.0\./);
+ expect(spec.info?.title).toBe('FreeLLMAPI');
+ expect(Object.keys(spec.paths).length).toBeGreaterThan(0);
+ });
+
+ it('serves the reference viewer as HTML at GET /v1/docs', async () => {
+ const { status, contentType, raw } = await request(app, 'GET', '/v1/docs');
+ expect(status).toBe(200);
+ expect(contentType).toContain('text/html');
+ // Self-hosted: the page fetches the local spec, not a CDN asset.
+ expect(raw).toContain('openapi.json');
+ expect(raw).not.toContain('unpkg.com');
+ expect(raw).not.toContain('cdn.');
+ });
+
+ it('does not require an API key for the docs (they expose no secrets)', async () => {
+ // No Authorization / x-api-key header supplied.
+ const spec = await request(app, 'GET', '/v1/openapi.json');
+ const page = await request(app, 'GET', '/v1/docs');
+ expect(spec.status).toBe(200);
+ expect(page.status).toBe(200);
+ });
+
+ // The spec is the product: every documented path must resolve to a real route.
+ // A missing route returns 404; a present-but-unauthenticated route returns
+ // 401/400. We assert "not 404" so the check is auth-agnostic.
+ it('documents only paths that exist in the app router', async () => {
+ const base = openapiSpec.servers[0].url; // "/v1"
+ for (const [path, item] of Object.entries(openapiSpec.paths)) {
+ for (const method of Object.keys(item as Record<string, unknown>)) {
+ const { status } = await request(app, method.toUpperCase(), base + path);
+ expect(status, `${method.toUpperCase()} ${base}${path} should exist`).not.toBe(404);
+ }
+ }
+ });
+
+ // Guard against re-introducing the stale fork endpoint: the fork's spec
+ // documented GET /v1/usage, which has never existed on this router.
+ it('does not expose a phantom /v1/usage endpoint', async () => {
+ const { status } = await request(app, 'GET', '/v1/usage');
+ expect(status).toBe(404);
+ });
+
+ it('has internally consistent $ref pointers', () => {
+ const refs: string[] = [];
+ const walk = (node: unknown) => {
+ if (Array.isArray(node)) { node.forEach(walk); return; }
+ if (node && typeof node === 'object') {
+ for (const [key, value] of Object.entries(node)) {
+ if (key === '$ref' && typeof value === 'string') refs.push(value);
+ else walk(value);
+ }
+ }
+ };
+ walk(openapiSpec);
+
+ const resolve = (ref: string): unknown => {
+ if (!ref.startsWith('#/')) return undefined;
+ return ref.slice(2).split('/').reduce<any>((acc, part) => (acc == null ? acc : acc[part]), openapiSpec);
+ };
+
+ expect(refs.length).toBeGreaterThan(0);
+ for (const ref of refs) {
+ expect(resolve(ref), `unresolved $ref: ${ref}`).toBeDefined();
+ }
+ });
+});
diff --git a/server/src/app.ts b/server/src/app.ts
index 1f64e1e5..815d955d 100644
--- a/server/src/app.ts
+++ b/server/src/app.ts
@@ -18,6 +18,7 @@ import { settingsRouter } from './routes/settings.js';
import { premiumRouter } from './routes/premium.js';
import { cacheRouter } from './routes/cache.js';
import { authRouter } from './routes/auth.js';
+import { docsRouter } from './routes/docs.js';
import { requireAuth } from './middleware/requireAuth.js';
import { createProxyRateLimiter } from './middleware/rateLimit.js';
import { errorHandler } from './middleware/errorHandler.js';
@@ -80,6 +81,12 @@ export function createApp(config?: Config) {
app.use('/api/premium', requireAuth, premiumRouter);
app.use('/api/cache', requireAuth, cacheRouter);
+ // Static, unauthenticated API reference: GET /v1/docs (viewer) and
+ // GET /v1/openapi.json (spec). Mounted before the rate limiter so the docs
+ // are always reachable and don't draw down a caller's request budget. It only
+ // owns those two paths; everything else falls through to the routers below.
+ app.use('/v1', docsRouter);
+
// OpenAI-compatible proxy. Per-IP rate limiting (#35 item #6) runs first so
// it throttles unauthenticated brute-force / flood attempts before any
// routing work. Tune via PROXY_RATE_LIMIT_RPM; 0 disables it.
diff --git a/server/src/docs/docs-page.ts b/server/src/docs/docs-page.ts
new file mode 100644
index 00000000..609318ea
--- /dev/null
+++ b/server/src/docs/docs-page.ts
@@ -0,0 +1,319 @@
+// Self-contained API reference page served at `GET /v1/docs`.
+//
+// No CDN, no external scripts/styles/fonts, no `node_modules` served from disk:
+// the whole viewer is inline and fetches the spec from `openapi.json` (relative
+// to `/v1/docs`, which resolves to `/v1/openapi.json`). This is deliberate. The
+// server ships as a `tsc` build, a `tsx` dev process, and an esbuild single-file
+// bundle for the desktop app that carries no server `node_modules` — so pulling
+// Swagger UI from `node_modules` at runtime would 404 in the desktop build, and
+// vendoring its ~1.5 MB of assets into the repo would be bloat. A compact
+// hand-rolled renderer keeps the docs offline-capable and identical across all
+// three run targets. It is stored as a `.ts` string module (not an `.html`
+// file) for the same reason the spec is: `.ts` compiles and bundles everywhere,
+// while a static file is not copied into `dist/` and is absent from the bundle.
+//
+// Rendered client-side from the OpenAPI JSON via DOM APIs (no innerHTML
+// templating), so nothing in the spec can inject markup.
+
+export const DOCS_HTML = `<!DOCTYPE html>
+<html lang="en">
+<head>
+ <meta charset="UTF-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1" />
+ <title>FreeLLMAPI - API reference</title>
+ <style>
+ :root {
+ --bg: #ffffff; --fg: #1b1f24; --muted: #5b6472; --border: #e4e8ee;
+ --card: #f7f9fc; --accent: #2f6feb; --code-bg: #f0f3f8;
+ --get: #1f883d; --post: #2f6feb; --put: #9a6700; --delete: #cf222e;
+ }
+ @media (prefers-color-scheme: dark) {
+ :root {
+ --bg: #0d1117; --fg: #e6edf3; --muted: #8b949e; --border: #21262d;
+ --card: #161b22; --accent: #4c8dff; --code-bg: #161b22;
+ --get: #3fb950; --post: #4c8dff; --put: #d29922; --delete: #f85149;
+ }
+ }
+ * { box-sizing: border-box; }
+ body {
+ margin: 0; background: var(--bg); color: var(--fg);
+ font: 15px/1.55 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+ }
+ code, pre, .mono { font-family: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace; }
+ header.top {
+ position: sticky; top: 0; z-index: 5; background: var(--bg);
+ border-bottom: 1px solid var(--border); padding: 18px 24px;
+ }
+ header.top h1 { margin: 0; font-size: 20px; display: inline-block; }
+ .ver { margin-left: 10px; font-size: 12px; color: var(--muted); border: 1px solid var(--border);
+ border-radius: 999px; padding: 2px 8px; vertical-align: middle; }
+ .wrap { max-width: 900px; margin: 0 auto; padding: 24px; }
+ p.desc { color: var(--muted); margin: 8px 0 0; }
+ .auth { background: var(--card); border: 1px solid var(--border); border-radius: 10px;
+ padding: 14px 16px; margin: 22px 0; }
+ .auth h2 { margin: 0 0 6px; font-size: 14px; text-transform: uppercase; letter-spacing: .04em; color: var(--muted); }
+ .group h2 { font-size: 16px; margin: 30px 0 6px; padding-bottom: 6px; border-bottom: 1px solid var(--border); }
+ .op { border: 1px solid var(--border); border-radius: 10px; margin: 12px 0; overflow: hidden; }
+ .op > summary { list-style: none; cursor: pointer; padding: 12px 14px; display: flex; gap: 12px;
+ align-items: center; user-select: none; }
+ .op > summary::-webkit-details-marker { display: none; }
+ .op[open] > summary { border-bottom: 1px solid var(--border); }
+ .method { font-weight: 700; font-size: 12px; letter-spacing: .05em; text-transform: uppercase;
+ color: #fff; border-radius: 6px; padding: 3px 9px; flex: 0 0 auto; }
+ .m-get { background: var(--get); } .m-post { background: var(--post); }
+ .m-put { background: var(--put); } .m-delete { background: var(--delete); }
+ .path { font-size: 14px; font-weight: 600; }
+ .sum { color: var(--muted); font-size: 13px; margin-left: auto; text-align: right; }
+ .body { padding: 6px 16px 16px; }
+ .body h3 { font-size: 12px; text-transform: uppercase; letter-spacing: .05em; color: var(--muted);
+ margin: 18px 0 8px; }
+ .op p.opdesc { color: var(--muted); margin: 10px 0 0; }
+ table.params { width: 100%; border-collapse: collapse; font-size: 13px; }
+ table.params td { border-top: 1px solid var(--border); padding: 7px 8px; vertical-align: top; }
+ .pill { display: inline-block; font-size: 11px; padding: 1px 6px; border-radius: 5px;
+ border: 1px solid var(--border); color: var(--muted); margin-left: 6px; }
+ .req { color: var(--delete); font-size: 11px; margin-left: 6px; }
+ .schema { background: var(--code-bg); border: 1px solid var(--border); border-radius: 8px;
+ padding: 12px 14px; overflow-x: auto; }
+ .schema ul { list-style: none; margin: 0; padding-left: 16px; }
+ .schema > ul { padding-left: 0; }
+ .field { padding: 2px 0; }
+ .fname { font-weight: 600; }
+ .ftype { color: var(--accent); font-size: 12px; }
+ .fdesc { color: var(--muted); font-size: 12px; }
+ .resp { display: flex; gap: 10px; align-items: baseline; padding: 5px 0; font-size: 13px; }
+ .code { font-weight: 700; }
+ .c2 { color: var(--get); } .c4 { color: var(--put); } .c5 { color: var(--delete); }
+ a { color: var(--accent); }
+ .loading, .error { color: var(--muted); padding: 40px 0; text-align: center; }
+ .error { color: var(--delete); }
+ </style>
+</head>
+<body>
+ <header class="top"><div class="wrap" style="padding:0;"><h1 id="doc-title">FreeLLMAPI</h1><span class="ver" id="doc-ver"></span></div></header>
+ <main class="wrap"><div id="root"><p class="loading">Loading API reference…</p></div></main>
+ <script>
+ (function () {
+ var root = document.getElementById('root');
+ var spec = null;
+
+ function el(tag, cls, text) {
+ var n = document.createElement(tag);
+ if (cls) n.className = cls;
+ if (text != null) n.textContent = text;
+ return n;
+ }
+
+ function resolveRef(ref) {
+ if (typeof ref !== 'string' || ref.indexOf('#/') !== 0) return null;
+ var parts = ref.slice(2).split('/');
+ var cur = spec;
+ for (var i = 0; i < parts.length; i++) {
+ if (cur == null) return null;
+ cur = cur[parts[i]];
+ }
+ return cur || null;
+ }
+
+ function typeLabel(schema) {
+ if (!schema) return 'any';
+ if (schema.$ref) {
+ var name = schema.$ref.split('/').pop();
+ return name;
+ }
+ if (schema.oneOf || schema.anyOf) {
+ var list = schema.oneOf || schema.anyOf;
+ return list.map(typeLabel).join(' | ');
+ }
+ if (schema.enum) return schema.enum.map(function (v) { return JSON.stringify(v); }).join(' | ');
+ if (schema.type === 'array') return typeLabel(schema.items) + '[]';
+ return schema.type || 'object';
+ }
+
+ // Render a schema as a nested field list. depth guards against cycles.
+ function renderSchema(schema, depth) {
+ depth = depth || 0;
+ var container = el('div');
+ if (!schema) { container.appendChild(el('div', 'fdesc', 'any')); return container; }
+ if (schema.$ref) {
+ var resolved = resolveRef(schema.$ref);
+ if (depth > 6 || !resolved) { container.appendChild(el('div', 'ftype', typeLabel(schema))); return container; }
+ return renderSchema(resolved, depth + 1);
+ }
+ if (schema.oneOf || schema.anyOf) {
+ var opts = schema.oneOf || schema.anyOf;
+ container.appendChild(el('div', 'fdesc', 'One of: ' + opts.map(typeLabel).join(', ')));
+ return container;
+ }
+ if (schema.type === 'array') {
+ container.appendChild(el('div', 'ftype', typeLabel(schema.items) + '[]'));
+ if (schema.items && (schema.items.properties || schema.items.$ref)) {
+ container.appendChild(renderSchema(schema.items, depth + 1));
+ }
+ return container;
+ }
+ if (schema.properties) {
+ var required = schema.required || [];
+ var ul = el('ul');
+ Object.keys(schema.properties).forEach(function (key) {
+ var prop = schema.properties[key];
+ var li = el('li', 'field');
+ var line = el('div');
+ var nameEl = el('span', 'fname mono', key);
+ line.appendChild(nameEl);
+ line.appendChild(el('span', 'ftype', ' ' + typeLabel(prop)));
+ if (required.indexOf(key) !== -1) line.appendChild(el('span', 'req', 'required'));
+ li.appendChild(line);
+ if (prop.description) li.appendChild(el('div', 'fdesc', prop.description));
+ if (prop.default !== undefined) li.appendChild(el('div', 'fdesc', 'default: ' + JSON.stringify(prop.default)));
+ // Expand one level of nested object/array-of-object properties.
+ var nested = prop.$ref ? resolveRef(prop.$ref) : (prop.type === 'array' ? prop.items : prop);
+ if (depth < 3 && nested && nested.properties && prop !== nested) {
+ li.appendChild(renderSchema(prop, depth + 1));
+ }
+ ul.appendChild(li);
+ });
+ container.appendChild(ul);
+ return container;
+ }
+ container.appendChild(el('div', 'ftype', typeLabel(schema)));
+ if (schema.description) container.appendChild(el('div', 'fdesc', schema.description));
+ return container;
+ }
+
+ function schemaFromContent(content) {
+ if (!content) return null;
+ var key = content['application/json'] ? 'application/json' : Object.keys(content)[0];
+ return content[key] ? content[key].schema : null;
+ }
+
+ function methodClass(m) { return 'm-' + m; }
+ function codeClass(code) { return 'c' + String(code).charAt(0); }
+
+ function renderOperation(path, method, op) {
+ var details = el('details', 'op');
+ var summary = el('summary');
+ var badge = el('span', 'method ' + methodClass(method), method);
+ summary.appendChild(badge);
+ summary.appendChild(el('span', 'path mono', path));
+ if (op.summary) summary.appendChild(el('span', 'sum', op.summary));
+ details.appendChild(summary);
+
+ var body = el('div', 'body');
+ if (op.description) body.appendChild(el('p', 'opdesc', op.description));
+
+ if (op.parameters && op.parameters.length) {
+ body.appendChild(el('h3', null, 'Query parameters'));
+ var table = el('table', 'params');
+ op.parameters.forEach(function (p) {
+ var tr = el('tr');
+ var td1 = el('td');
+ td1.appendChild(el('span', 'fname mono', p.name));
+ if (p.required) td1.appendChild(el('span', 'req', 'required'));
+ var td2 = el('td');
+ td2.appendChild(el('div', 'ftype', typeLabel(p.schema)));
+ if (p.description) td2.appendChild(el('div', 'fdesc', p.description));
+ tr.appendChild(td1); tr.appendChild(td2);
+ table.appendChild(tr);
+ });
+ body.appendChild(table);
+ }
+
+ if (op.requestBody) {
+ body.appendChild(el('h3', null, 'Request body' + (op.requestBody.required ? ' (required)' : '')));
+ var reqSchema = schemaFromContent(op.requestBody.content);
+ var box = el('div', 'schema');
+ box.appendChild(renderSchema(reqSchema, 0));
+ body.appendChild(box);
+ }
+
+ body.appendChild(el('h3', null, 'Responses'));
+ Object.keys(op.responses || {}).forEach(function (code) {
+ var r = op.responses[code];
+ if (r.$ref) r = resolveRef(r.$ref) || r;
+ var row = el('div', 'resp');
+ row.appendChild(el('span', 'code mono ' + codeClass(code), code));
+ row.appendChild(el('span', 'fdesc', r.description || ''));
+ body.appendChild(row);
+ var respSchema = schemaFromContent(r.content);
+ if (respSchema && (respSchema.$ref || respSchema.properties)) {
+ var rbox = el('div', 'schema');
+ rbox.style.margin = '2px 0 8px';
+ rbox.appendChild(renderSchema(respSchema, 0));
+ body.appendChild(rbox);
+ }
+ });
+
+ details.appendChild(body);
+ return details;
+ }
+
+ function render() {
+ document.title = (spec.info && spec.info.title ? spec.info.title : 'API') + ' - API reference';
+ var titleEl = document.getElementById('doc-title');
+ var verEl = document.getElementById('doc-ver');
+ if (spec.info) {
+ titleEl.textContent = spec.info.title || 'API';
+ if (spec.info.version) verEl.textContent = 'v' + spec.info.version;
+ }
+ root.innerHTML = '';
+
+ if (spec.info && spec.info.description) root.appendChild(el('p', 'desc', spec.info.description));
+
+ // Auth summary from the declared security schemes.
+ var schemes = spec.components && spec.components.securitySchemes;
+ if (schemes) {
+ var authBox = el('div', 'auth');
+ authBox.appendChild(el('h2', null, 'Authentication'));
+ Object.keys(schemes).forEach(function (name) {
+ var s = schemes[name];
+ authBox.appendChild(el('div', 'fdesc', s.description || (s.type + (s.scheme ? ' ' + s.scheme : ''))));
+ });
+ root.appendChild(authBox);
+ }
+
+ // Group operations by their first tag, in the order tags are declared.
+ var tagOrder = (spec.tags || []).map(function (t) { return t.name; });
+ var groups = {};
+ var order = [];
+ Object.keys(spec.paths || {}).forEach(function (path) {
+ var item = spec.paths[path];
+ Object.keys(item).forEach(function (method) {
+ var op = item[method];
+ if (!op || typeof op !== 'object') return;
+ var tag = (op.tags && op.tags[0]) || 'Endpoints';
+ if (!groups[tag]) { groups[tag] = []; order.push(tag); }
+ groups[tag].push({ path: path, method: method.toUpperCase(), op: op });
+ });
+ });
+ order.sort(function (a, b) {
+ var ia = tagOrder.indexOf(a), ib = tagOrder.indexOf(b);
+ return (ia === -1 ? 999 : ia) - (ib === -1 ? 999 : ib);
+ });
+
+ order.forEach(function (tag) {
+ var g = el('div', 'group');
+ g.appendChild(el('h2', null, tag));
+ groups[tag].forEach(function (entry) {
+ g.appendChild(renderOperation(entry.path, entry.method, entry.op));
+ });
+ root.appendChild(g);
+ });
+ }
+
+ // Relative fetch: from /v1/docs this resolves to /v1/openapi.json, so the
+ // page keeps working behind any path prefix or reverse proxy.
+ fetch('openapi.json', { headers: { accept: 'application/json' } })
+ .then(function (res) {
+ if (!res.ok) throw new Error('HTTP ' + res.status);
+ return res.json();
+ })
+ .then(function (data) { spec = data; render(); })
+ .catch(function (err) {
+ root.innerHTML = '';
+ root.appendChild(el('p', 'error', 'Failed to load the API spec: ' + err.message));
+ });
+ })();
+ </script>
+</body>
+</html>`;
diff --git a/server/src/docs/openapi.ts b/server/src/docs/openapi.ts
new file mode 100644
index 00000000..27e2c47b
--- /dev/null
+++ b/server/src/docs/openapi.ts
@@ -0,0 +1,715 @@
+// Hand-written OpenAPI 3.0 description of the public `/v1` surface.
+//
+// Why a TypeScript module and not a raw `openapi.json`: the server ships three
+// ways — `tsc` build then `node dist/index.js` (Docker / npm), `tsx` (dev), and
+// an esbuild single-file bundle for the desktop app (which carries no server
+// `node_modules`). A raw `.json` served from disk breaks the compiled and
+// bundled targets (tsc does not copy `.json` into `dist/`, and the bundle has
+// no file to read). Exporting the spec from a `.ts` module compiles, bundles,
+// and type-checks in every one of those targets with zero extra build wiring.
+//
+// Served as JSON at `GET /v1/openapi.json`. Keep it in sync with the routers in
+// `routes/proxy.ts`, `routes/responses.ts`, and `routes/anthropic.ts` — the
+// docs route test asserts every path here resolves to a real route.
+
+// A relative server URL keeps the docs correct on any host or port (localhost,
+// LAN, container) and avoids baking an address into the repo.
+export const openapiSpec = {
+ openapi: '3.0.3',
+ info: {
+ title: 'FreeLLMAPI',
+ version: '0.4.1',
+ description:
+ 'OpenAI-compatible proxy that aggregates free LLM provider tiers behind a single /v1 endpoint. ' +
+ 'A router picks an available model per request and fails over when a provider is rate-limited. ' +
+ 'The same /v1 router also speaks the OpenAI Responses API and the Anthropic Messages API.',
+ license: { name: 'MIT', url: 'https://github.com/tashfeenahmed/freellmapi/blob/main/LICENSE' },
+ },
+ servers: [
+ { url: '/v1', description: 'This proxy instance' },
+ ],
+ security: [
+ { bearerAuth: [] },
+ { apiKeyAuth: [] },
+ ],
+ tags: [
+ { name: 'Chat', description: 'OpenAI-compatible chat and completion endpoints' },
+ { name: 'Media', description: 'Image generation and text-to-speech' },
+ { name: 'Responses', description: 'OpenAI Responses API (Codex CLI wire format)' },
+ { name: 'Anthropic', description: 'Anthropic Messages API (Claude Code and the Anthropic SDKs)' },
+ { name: 'Models', description: 'Model discovery' },
+ ],
+ paths: {
+ '/chat/completions': {
+ post: {
+ tags: ['Chat'],
+ operationId: 'createChatCompletion',
+ summary: 'Create a chat completion',
+ description:
+ 'OpenAI-compatible chat completions. Set `model` to `auto` (the default) to let the router ' +
+ 'pick a free model, or pass a specific model id. Supports streaming, tools, and vision.',
+ requestBody: {
+ required: true,
+ content: {
+ 'application/json': {
+ schema: { $ref: '#/components/schemas/ChatCompletionRequest' },
+ },
+ },
+ },
+ responses: {
+ '200': {
+ description:
+ 'A chat completion. When `stream: true`, the body is a `text/event-stream` of ' +
+ 'OpenAI-style `chat.completion.chunk` events terminated by `data: [DONE]`.',
+ content: {
+ 'application/json': {
+ schema: { $ref: '#/components/schemas/ChatCompletionResponse' },
+ },
+ },
+ },
+ '400': { $ref: '#/components/responses/BadRequest' },
+ '401': { $ref: '#/components/responses/Unauthorized' },
+ '429': { $ref: '#/components/responses/RateLimited' },
+ '502': { $ref: '#/components/responses/UpstreamError' },
+ },
+ },
+ },
+ '/completions': {
+ post: {
+ tags: ['Chat'],
+ operationId: 'createCompletion',
+ summary: 'Create a legacy text completion',
+ description:
+ 'OpenAI-compatible legacy completions. Editor ghost-text clients still send `prompt`/`suffix` ' +
+ 'here; requests are routed through chat models while preserving the `text_completion` shape.',
+ requestBody: {
+ required: true,
+ content: {
+ 'application/json': {
+ schema: { $ref: '#/components/schemas/CompletionRequest' },
+ },
+ },
+ },
+ responses: {
+ '200': {
+ description: 'A text completion (`object: "text_completion"`), or an SSE stream when `stream: true`.',
+ content: {
+ 'application/json': {
+ schema: { $ref: '#/components/schemas/CompletionResponse' },
+ },
+ },
+ },
+ '400': { $ref: '#/components/responses/BadRequest' },
+ '401': { $ref: '#/components/responses/Unauthorized' },
+ '429': { $ref: '#/components/responses/RateLimited' },
+ '502': { $ref: '#/components/responses/UpstreamError' },
+ },
+ },
+ },
+ '/embeddings': {
+ post: {
+ tags: ['Chat'],
+ operationId: 'createEmbedding',
+ summary: 'Create embeddings',
+ description: 'OpenAI-compatible embeddings. `input` accepts a string or an array of strings.',
+ requestBody: {
+ required: true,
+ content: {
+ 'application/json': {
+ schema: { $ref: '#/components/schemas/EmbeddingRequest' },
+ },
+ },
+ },
+ responses: {
+ '200': {
+ description: 'A list of embedding vectors.',
+ content: {
+ 'application/json': {
+ schema: { $ref: '#/components/schemas/EmbeddingResponse' },
+ },
+ },
+ },
+ '400': { $ref: '#/components/responses/BadRequest' },
+ '401': { $ref: '#/components/responses/Unauthorized' },
+ '429': { $ref: '#/components/responses/RateLimited' },
+ '502': { $ref: '#/components/responses/UpstreamError' },
+ },
+ },
+ },
+ '/images/generations': {
+ post: {
+ tags: ['Media'],
+ operationId: 'createImage',
+ summary: 'Generate images',
+ description:
+ 'OpenAI-compatible image generation, routed through the media catalog. Omit `model` (or set ' +
+ '`auto`) to try every enabled image provider in order; pass a provider model id to pin one.',
+ requestBody: {
+ required: true,
+ content: {
+ 'application/json': {
+ schema: { $ref: '#/components/schemas/ImageRequest' },
+ },
+ },
+ },
+ responses: {
+ '200': {
+ description: 'Generated image(s), as URLs or base64 depending on `response_format`.',
+ content: {
+ 'application/json': {
+ schema: { $ref: '#/components/schemas/ImageResponse' },
+ },
+ },
+ },
+ '400': { $ref: '#/components/responses/BadRequest' },
+ '401': { $ref: '#/components/responses/Unauthorized' },
+ '429': { $ref: '#/components/responses/RateLimited' },
+ '502': { $ref: '#/components/responses/UpstreamError' },
+ },
+ },
+ },
+ '/audio/speech': {
+ post: {
+ tags: ['Media'],
+ operationId: 'createSpeech',
+ summary: 'Generate speech (text-to-speech)',
+ description:
+ 'OpenAI-compatible text-to-speech, routed through the media catalog. Returns raw audio bytes; ' +
+ 'the `Content-Type` reflects the chosen `response_format`.',
+ requestBody: {
+ required: true,
+ content: {
+ 'application/json': {
+ schema: { $ref: '#/components/schemas/SpeechRequest' },
+ },
+ },
+ },
+ responses: {
+ '200': {
+ description: 'Raw audio bytes.',
+ content: {
+ 'audio/mpeg': { schema: { type: 'string', format: 'binary' } },
+ },
+ },
+ '400': { $ref: '#/components/responses/BadRequest' },
+ '401': { $ref: '#/components/responses/Unauthorized' },
+ '429': { $ref: '#/components/responses/RateLimited' },
+ '502': { $ref: '#/components/responses/UpstreamError' },
+ },
+ },
+ },
+ '/responses': {
+ post: {
+ tags: ['Responses'],
+ operationId: 'createResponse',
+ summary: 'Create a model response (OpenAI Responses API)',
+ description:
+ 'The OpenAI Responses wire format that current Codex CLI versions require, implemented as a ' +
+ 'translating shim over the same router. Supports streaming events and tool calls. Image input ' +
+ 'is not supported here; use /chat/completions with an image_url content part instead.',
+ requestBody: {
+ required: true,
+ content: {
+ 'application/json': {
+ schema: { $ref: '#/components/schemas/ResponseRequest' },
+ },
+ },
+ },
+ responses: {
+ '200': {
+ description: 'A response object, or an SSE stream of Responses events when `stream: true`.',
+ content: {
+ 'application/json': {
+ schema: { $ref: '#/components/schemas/ResponseObject' },
+ },
+ },
+ },
+ '400': { $ref: '#/components/responses/BadRequest' },
+ '401': { $ref: '#/components/responses/Unauthorized' },
+ '429': { $ref: '#/components/responses/RateLimited' },
+ '502': { $ref: '#/components/responses/UpstreamError' },
+ },
+ },
+ },
+ '/messages': {
+ post: {
+ tags: ['Anthropic'],
+ operationId: 'createMessage',
+ summary: 'Create a message (Anthropic Messages API)',
+ description:
+ "Anthropic's Messages wire format over the same router, so Claude Code and the official " +
+ 'Anthropic SDKs run against your free pool. Claude family names (opus / sonnet / haiku / ' +
+ 'default) map to `auto` or a pinned model on the Keys page. Send the key via the `x-api-key` ' +
+ 'header (Anthropic style) or an Authorization bearer token.',
+ requestBody: {
+ required: true,
+ content: {
+ 'application/json': {
+ schema: { $ref: '#/components/schemas/AnthropicMessageRequest' },
+ },
+ },
+ },
+ responses: {
+ '200': {
+ description: 'An Anthropic message, or an SSE stream of Anthropic events when `stream: true`.',
+ content: {
+ 'application/json': {
+ schema: { $ref: '#/components/schemas/AnthropicMessageResponse' },
+ },
+ },
+ },
+ '400': { $ref: '#/components/responses/BadRequest' },
+ '401': { $ref: '#/components/responses/Unauthorized' },
+ '429': { $ref: '#/components/responses/RateLimited' },
+ '502': { $ref: '#/components/responses/UpstreamError' },
+ },
+ },
+ },
+ '/messages/count_tokens': {
+ post: {
+ tags: ['Anthropic'],
+ operationId: 'countTokens',
+ summary: 'Count input tokens (Anthropic Messages API)',
+ description: 'Estimates the input token count for an Anthropic Messages request without running it.',
+ requestBody: {
+ required: true,
+ content: {
+ 'application/json': {
+ schema: { $ref: '#/components/schemas/AnthropicMessageRequest' },
+ },
+ },
+ },
+ responses: {
+ '200': {
+ description: 'An estimated input token count.',
+ content: {
+ 'application/json': {
+ schema: { $ref: '#/components/schemas/CountTokensResponse' },
+ },
+ },
+ },
+ '400': { $ref: '#/components/responses/BadRequest' },
+ '401': { $ref: '#/components/responses/Unauthorized' },
+ },
+ },
+ },
+ '/models': {
+ get: {
+ tags: ['Models'],
+ operationId: 'listModels',
+ summary: 'List available models',
+ description:
+ 'Lists the catalog, one row per model id, each tagged with whether it is usable right now, ' +
+ 'plus the virtual `auto` id. Content-negotiated: sending an `anthropic-version` header returns ' +
+ 'the Anthropic model-list shape; otherwise the OpenAI shape is returned. `?available=true` ' +
+ 'filters to models that can serve a request now.',
+ parameters: [
+ {
+ name: 'available',
+ in: 'query',
+ required: false,
+ description: 'When `true`, return only models that are currently usable.',
+ schema: { type: 'boolean' },
+ },
+ ],
+ responses: {
+ '200': {
+ description: 'The model list.',
+ content: {
+ 'application/json': {
+ schema: { $ref: '#/components/schemas/ModelList' },
+ },
+ },
+ },
+ '401': { $ref: '#/components/responses/Unauthorized' },
+ },
+ },
+ },
+ },
+ components: {
+ securitySchemes: {
+ // The unified API key from the Keys page. Send it as either an OpenAI-style
+ // bearer token or an Anthropic-style x-api-key header — both are accepted.
+ bearerAuth: {
+ type: 'http',
+ scheme: 'bearer',
+ description: 'Unified API key as `Authorization: Bearer <key>`.',
+ },
+ apiKeyAuth: {
+ type: 'apiKey',
+ in: 'header',
+ name: 'x-api-key',
+ description: 'Unified API key as `x-api-key: <key>` (Anthropic-style clients).',
+ },
+ },
+ responses: {
+ BadRequest: {
+ description: 'The request was malformed.',
+ content: { 'application/json': { schema: { $ref: '#/components/schemas/Error' } } },
+ },
+ Unauthorized: {
+ description: 'Missing or invalid API key.',
+ content: { 'application/json': { schema: { $ref: '#/components/schemas/Error' } } },
+ },
+ RateLimited: {
+ description: 'Rate limit exceeded.',
+ content: { 'application/json': { schema: { $ref: '#/components/schemas/Error' } } },
+ },
+ UpstreamError: {
+ description: 'Every candidate provider failed to serve the request.',
+ content: { 'application/json': { schema: { $ref: '#/components/schemas/Error' } } },
+ },
+ },
+ schemas: {
+ ChatCompletionRequest: {
+ type: 'object',
+ required: ['messages'],
+ properties: {
+ model: { type: 'string', description: "Model id, or 'auto' for automatic routing.", default: 'auto' },
+ messages: { type: 'array', minItems: 1, items: { $ref: '#/components/schemas/Message' } },
+ temperature: { type: 'number', minimum: 0, maximum: 2 },
+ max_tokens: { type: 'integer', description: 'Values <= 0 are treated as "no limit".' },
+ top_p: { type: 'number', minimum: 0, maximum: 1 },
+ stop: {
+ description: 'Up to a few stop sequences.',
+ oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }],
+ },
+ stream: { type: 'boolean', default: false },
+ tools: { type: 'array', items: { $ref: '#/components/schemas/Tool' }, nullable: true },
+ tool_choice: {
+ nullable: true,
+ oneOf: [
+ { type: 'string', enum: ['none', 'auto', 'required', 'any'] },
+ { $ref: '#/components/schemas/ToolChoiceObject' },
+ ],
+ },
+ parallel_tool_calls: { type: 'boolean', nullable: true },
+ },
+ },
+ Message: {
+ type: 'object',
+ required: ['role'],
+ properties: {
+ role: { type: 'string', enum: ['system', 'developer', 'user', 'assistant', 'tool', 'function'] },
+ content: {
+ description: 'A string, or an array of content parts (text and image_url) for vision.',
+ oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'object' } }],
+ nullable: true,
+ },
+ name: { type: 'string' },
+ tool_calls: { type: 'array', items: { $ref: '#/components/schemas/ToolCall' } },
+ tool_call_id: { type: 'string' },
+ },
+ },
+ Tool: {
+ type: 'object',
+ required: ['type', 'function'],
+ properties: {
+ type: { type: 'string', enum: ['function'] },
+ function: {
+ type: 'object',
+ required: ['name'],
+ properties: {
+ name: { type: 'string' },
+ description: { type: 'string' },
+ parameters: { type: 'object', description: 'JSON Schema for the function arguments.' },
+ strict: { type: 'boolean' },
+ },
+ },
+ },
+ },
+ ToolChoiceObject: {
+ type: 'object',
+ required: ['type', 'function'],
+ properties: {
+ type: { type: 'string', enum: ['function'] },
+ function: { type: 'object', required: ['name'], properties: { name: { type: 'string' } } },
+ },
+ },
+ ToolCall: {
+ type: 'object',
+ properties: {
+ id: { type: 'string' },
+ type: { type: 'string', enum: ['function'] },
+ function: {
+ type: 'object',
+ properties: {
+ name: { type: 'string' },
+ arguments: { type: 'string', description: 'JSON-encoded arguments.' },
+ },
+ },
+ },
+ },
+ 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/Message' },
+ finish_reason: { type: 'string', nullable: true },
+ },
+ },
+ },
+ usage: { $ref: '#/components/schemas/Usage' },
+ },
+ },
+ CompletionRequest: {
+ type: 'object',
+ required: ['prompt'],
+ properties: {
+ model: { type: 'string', default: 'auto' },
+ prompt: { type: 'string' },
+ suffix: { type: 'string', description: 'Text after the cursor, for fill-in-the-middle clients.' },
+ temperature: { type: 'number', minimum: 0, maximum: 2 },
+ max_tokens: { type: 'integer' },
+ top_p: { type: 'number', minimum: 0, maximum: 1 },
+ stop: { oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }] },
+ stream: { type: 'boolean', default: false },
+ },
+ },
+ CompletionResponse: {
+ type: 'object',
+ properties: {
+ id: { type: 'string' },
+ object: { type: 'string', example: 'text_completion' },
+ created: { type: 'integer' },
+ model: { type: 'string' },
+ choices: {
+ type: 'array',
+ items: {
+ type: 'object',
+ properties: {
+ text: { type: 'string' },
+ index: { type: 'integer' },
+ logprobs: { nullable: true },
+ finish_reason: { type: 'string', nullable: true },
+ },
+ },
+ },
+ },
+ },
+ EmbeddingRequest: {
+ type: 'object',
+ required: ['input'],
+ properties: {
+ model: { type: 'string', default: 'auto' },
+ input: { oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }] },
+ dimensions: { type: 'integer', minimum: 1, description: 'Requested output dimensionality, if the model supports it.' },
+ },
+ },
+ EmbeddingResponse: {
+ type: 'object',
+ properties: {
+ object: { type: 'string', enum: ['list'] },
+ data: {
+ type: 'array',
+ items: {
+ type: 'object',
+ properties: {
+ object: { type: 'string', enum: ['embedding'] },
+ index: { type: 'integer' },
+ embedding: { type: 'array', items: { type: 'number' } },
+ },
+ },
+ },
+ model: { type: 'string' },
+ provider: { type: 'string' },
+ usage: { $ref: '#/components/schemas/Usage' },
+ },
+ },
+ ImageRequest: {
+ type: 'object',
+ required: ['prompt'],
+ properties: {
+ model: { type: 'string', default: 'auto' },
+ prompt: { type: 'string', minLength: 1 },
+ n: { type: 'integer', minimum: 1, maximum: 4 },
+ size: { type: 'string', example: '1024x1024' },
+ response_format: { type: 'string', enum: ['url', 'b64_json'] },
+ },
+ },
+ ImageResponse: {
+ type: 'object',
+ properties: {
+ created: { type: 'integer' },
+ data: {
+ type: 'array',
+ items: {
+ type: 'object',
+ properties: {
+ url: { type: 'string' },
+ b64_json: { type: 'string' },
+ },
+ },
+ },
+ model: { type: 'string' },
+ provider: { type: 'string' },
+ },
+ },
+ SpeechRequest: {
+ type: 'object',
+ required: ['input'],
+ properties: {
+ model: { type: 'string', default: 'auto' },
+ input: { type: 'string', minLength: 1 },
+ voice: { type: 'string' },
+ response_format: { type: 'string', example: 'mp3' },
+ },
+ },
+ ResponseRequest: {
+ type: 'object',
+ required: ['input'],
+ properties: {
+ model: { type: 'string', default: 'auto' },
+ instructions: { type: 'string', nullable: true, description: 'System-level guidance, sent as a system message.' },
+ input: {
+ description: 'A string, or an array of Responses input items.',
+ oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'object' } }],
+ },
+ stream: { type: 'boolean', default: false },
+ max_output_tokens: { type: 'integer', minimum: 1, nullable: true },
+ tools: { type: 'array', items: { type: 'object' } },
+ },
+ },
+ ResponseObject: {
+ type: 'object',
+ properties: {
+ id: { type: 'string' },
+ object: { type: 'string', example: 'response' },
+ created_at: { type: 'integer' },
+ model: { type: 'string' },
+ status: { type: 'string', example: 'completed' },
+ output: { type: 'array', items: { type: 'object' } },
+ output_text: { type: 'string' },
+ usage: { type: 'object' },
+ },
+ },
+ AnthropicMessageRequest: {
+ type: 'object',
+ required: ['messages'],
+ properties: {
+ model: { type: 'string', description: 'Anthropic model name; mapped to your free pool. Defaults to `auto`.' },
+ max_tokens: { type: 'integer', description: 'Anthropic-required; non-positive values fall back to a default.' },
+ messages: {
+ type: 'array',
+ minItems: 1,
+ items: {
+ type: 'object',
+ required: ['role', 'content'],
+ properties: {
+ role: { type: 'string', enum: ['user', 'assistant', 'system'] },
+ content: {
+ oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'object' } }],
+ },
+ },
+ },
+ },
+ system: {
+ description: 'System prompt, as a string or an array of content blocks.',
+ oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'object' } }],
+ },
+ temperature: { type: 'number', minimum: 0, maximum: 2 },
+ top_p: { type: 'number', minimum: 0, maximum: 1 },
+ stream: { type: 'boolean', default: false },
+ stop_sequences: { type: 'array', items: { type: 'string' } },
+ tools: {
+ type: 'array',
+ items: {
+ type: 'object',
+ required: ['name'],
+ properties: {
+ name: { type: 'string' },
+ description: { type: 'string' },
+ input_schema: { type: 'object' },
+ },
+ },
+ },
+ tool_choice: {
+ type: 'object',
+ properties: {
+ type: { type: 'string', enum: ['auto', 'any', 'tool', 'none'] },
+ name: { type: 'string' },
+ },
+ },
+ },
+ },
+ AnthropicMessageResponse: {
+ type: 'object',
+ properties: {
+ id: { type: 'string' },
+ type: { type: 'string', enum: ['message'] },
+ role: { type: 'string', enum: ['assistant'] },
+ model: { type: 'string' },
+ content: { type: 'array', items: { type: 'object' } },
+ stop_reason: {
+ type: 'string',
+ nullable: true,
+ enum: ['end_turn', 'max_tokens', 'stop_sequence', 'tool_use'],
+ },
+ stop_sequence: { type: 'string', nullable: true },
+ usage: {
+ type: 'object',
+ properties: {
+ input_tokens: { type: 'integer' },
+ output_tokens: { type: 'integer' },
+ },
+ },
+ },
+ },
+ CountTokensResponse: {
+ type: 'object',
+ properties: {
+ input_tokens: { type: 'integer' },
+ },
+ },
+ Usage: {
+ type: 'object',
+ properties: {
+ prompt_tokens: { type: 'integer' },
+ completion_tokens: { type: 'integer' },
+ total_tokens: { type: 'integer' },
+ },
+ },
+ ModelList: {
+ type: 'object',
+ properties: {
+ object: { type: 'string', enum: ['list'] },
+ data: { type: 'array', items: { $ref: '#/components/schemas/Model' } },
+ },
+ },
+ Model: {
+ type: 'object',
+ properties: {
+ id: { type: 'string' },
+ object: { type: 'string', enum: ['model'] },
+ created: { type: 'integer' },
+ owned_by: { type: 'string' },
+ },
+ },
+ Error: {
+ type: 'object',
+ properties: {
+ error: {
+ type: 'object',
+ properties: {
+ message: { type: 'string' },
+ type: { type: 'string' },
+ param: { type: 'string', nullable: true },
+ code: { type: 'string', nullable: true },
+ },
+ },
+ },
+ },
+ },
+ },
+} as const;
+
+export type OpenApiSpec = typeof openapiSpec;
diff --git a/server/src/routes/docs.ts b/server/src/routes/docs.ts
new file mode 100644
index 00000000..4f442205
--- /dev/null
+++ b/server/src/routes/docs.ts
@@ -0,0 +1,23 @@
+import { Router, type Request, type Response } from 'express';
+import { openapiSpec } from '../docs/openapi.js';
+import { DOCS_HTML } from '../docs/docs-page.js';
+
+// Static, unauthenticated API reference for the public `/v1` surface:
+// GET /v1/openapi.json — the OpenAPI 3.0 spec (served as JSON)
+// GET /v1/docs — a self-contained viewer that renders that spec
+//
+// Both are static and expose no secrets, so they are intentionally not gated by
+// the unified API key. Mounted before the proxy rate limiter in app.ts so the
+// docs stay available and never consume a caller's request budget.
+export const docsRouter = Router();
+
+docsRouter.get('/openapi.json', (_req: Request, res: Response) => {
+ // Long-cacheable: the spec only changes when the server binary does.
+ res.setHeader('Cache-Control', 'public, max-age=3600');
+ res.json(openapiSpec);
+});
+
+docsRouter.get('/docs', (_req: Request, res: Response) => {
+ res.setHeader('Cache-Control', 'public, max-age=3600');
+ res.type('html').send(DOCS_HTML);
+});