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.mdindex 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 reviewdiff --git a/server/src/__tests__/routes/docs.test.ts b/server/src/__tests__/routes/docs.test.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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);+});