Open History to see the last commit
1/**
2 * The service's own OpenAPI 3.1 document (PLAN.md task 4.1), hand-maintained.
3 * Single source of truth for three consumer surfaces: the generated TS client
4 * (task 7.4), the CLI (7.5), and the agent-auth capability list (5.1) — every
5 * operation MUST carry a unique operationId.
6 */
7
8const activityEnum = [
9 'chat',
10 'image',
11 'video',
12 'audio',
13 'embeddings',
14 'moderation',
15]
16
17const changeTypeEnum = [
18 'model.added',
19 'model.removed',
20 'model.updated',
21 'schema.added',
22 'schema.updated',
23 'endpoint.added',
24 'endpoint.removed',
25]
26
27const errorResponse = {
28 description: 'Error',
29 content: {
30 'application/json': {
31 schema: { $ref: '#/components/schemas/Error' },
32 },
33 },
34}
35
36const providerParam = {
37 name: 'provider',
38 in: 'path',
39 required: true,
40 description: 'Provider slug (see GET /v1/providers).',
41 schema: { type: 'string' },
42}
43
44const activityParam = {
45 name: 'activity',
46 in: 'path',
47 required: true,
48 description: 'Activity group.',
49 schema: { type: 'string', enum: activityEnum },
50}
51
52export const openApiDocument = {
53 openapi: '3.1.0',
54 info: {
55 title: 'modelschemas',
56 version: '0.1.0',
57 description:
58 'Live AI model schema service: per-endpoint request/response JSON ' +
59 'Schemas and model metadata for monitored providers, with ' +
60 'stale-while-revalidate caching and a change feed. Anonymous reads ' +
61 'are allowed at a low rate limit; register (agent-auth or API key) ' +
62 'for higher limits and webhook subscriptions.',
63 },
64 servers: [{ url: '/' }],
65 paths: {
66 '/v1': {
67 get: {
68 operationId: 'getServiceIndex',
69 summary: 'Service description and endpoint index',
70 responses: {
71 '200': {
72 description: 'Service index with _links to every surface.',
73 content: { 'application/json': { schema: { type: 'object' } } },
74 },
75 },
76 },
77 },
78 '/v1/status': {
79 get: {
80 operationId: 'getStatus',
81 summary: 'Per-provider sync status and row counts',
82 parameters: [
83 {
84 name: 'wait',
85 in: 'query',
86 description:
87 'Long-poll: hold up to N seconds (cap 60; "30s" form accepted) until new data exists, then return current data.',
88 schema: { type: 'string' },
89 },
90 ],
91 responses: {
92 '200': {
93 description: 'Service status.',
94 content: {
95 'application/json': {
96 schema: { $ref: '#/components/schemas/ServiceStatus' },
97 },
98 },
99 },
100 },
101 },
102 },
103 '/v1/providers': {
104 get: {
105 operationId: 'listProviders',
106 summary: 'List monitored providers with sync status',
107 responses: {
108 '200': {
109 description: 'Providers.',
110 content: { 'application/json': { schema: { type: 'object' } } },
111 },
112 },
113 },
114 },
115 '/v1/providers/{provider}/models': {
116 get: {
117 operationId: 'listProviderModels',
118 summary: 'List models for one provider',
119 parameters: [
120 providerParam,
121 {
122 name: 'provenance',
123 in: 'query',
124 description:
125 'Include recorded per-field sources by default; 0 omits them.',
126 schema: { type: 'string', enum: ['0', '1'], default: '1' },
127 },
128 ],
129 responses: {
130 '400': errorResponse,
131 '200': {
132 description: 'Models for the provider.',
133 content: { 'application/json': { schema: { type: 'object' } } },
134 },
135 '404': errorResponse,
136 },
137 },
138 },
139 '/v1/models': {
140 get: {
141 operationId: 'listModels',
142 summary: 'Cross-provider model catalog',
143 description:
144 'The headline "what can I use right now" endpoint. Filterable.',
145 parameters: [
146 {
147 name: 'activity',
148 in: 'query',
149 schema: { type: 'string', enum: activityEnum },
150 },
151 { name: 'provider', in: 'query', schema: { type: 'string' } },
152 {
153 name: 'capability',
154 in: 'query',
155 description:
156 'A capability flag the model is stated to support: matches rows whose capabilities map has this key set to true (capability=tools). Exact flag name, not a substring.',
157 schema: { type: 'string' },
158 },
159 {
160 name: 'q',
161 in: 'query',
162 description: 'Free-text match against id and display name.',
163 schema: { type: 'string' },
164 },
165 {
166 name: 'provenance',
167 in: 'query',
168 description:
169 'Per-field factSources are included by default. Set to 0 to omit them on list rows; 1 explicitly includes them. Model detail always includes factSources and OpenRouter discrepancies.',
170 schema: { type: 'string', enum: ['0', '1'], default: '1' },
171 },
172 {
173 name: 'pricing',
174 in: 'query',
175 description:
176 'Set to 1 to include the full rate card on each list row. Default is a compact summary: per-million base rates for token cards, otherwise the unit the card bills by.',
177 schema: { type: 'string', enum: ['1'] },
178 },
179 ],
180 responses: {
181 '200': {
182 description:
183 'Matching models. pricing is a compact token projection, a full RateCard when ?pricing=1, or null. OpenRouter-shaped vendor blobs are not served.',
184 content: {
185 'application/json': {
186 schema: { $ref: '#/components/schemas/ModelList' },
187 },
188 },
189 },
190 },
191 },
192 },
193 '/v1/models/{provider}/{modelId}': {
194 get: {
195 operationId: 'getModel',
196 summary: 'Full metadata for one model',
197 parameters: [
198 providerParam,
199 {
200 name: 'modelId',
201 in: 'path',
202 required: true,
203 description: 'Model slug or raw provider id.',
204 schema: { type: 'string' },
205 },
206 ],
207 responses: {
208 '200': {
209 description:
210 'Model metadata with activity, schemaEndpointId (canonical generation route on grain=provider catalogs), a RateCard or null for pricing, factSources (per-field provenance), OpenRouter discrepancies, and _links.schema when bound.',
211 content: {
212 'application/json': {
213 schema: { $ref: '#/components/schemas/Model' },
214 },
215 },
216 },
217 '404': errorResponse,
218 },
219 },
220 },
221 '/v1/schemas': {
222 get: {
223 operationId: 'listAllSchemas',
224 summary: 'System-wide schema index',
225 description:
226 'Every provider with extracted schemas, each with its activities and endpoint ids — the discovery entry point for all schemas on the system.',
227 responses: {
228 '200': {
229 description: 'Provider → activity → endpoint-id index.',
230 content: { 'application/json': { schema: { type: 'object' } } },
231 },
232 },
233 },
234 },
235 '/v1/schemas/{provider}': {
236 get: {
237 operationId: 'listProviderSchemas',
238 summary: 'Activities and endpoint ids for a provider',
239 parameters: [providerParam],
240 responses: {
241 '200': {
242 description: 'Activity → endpoint-id index.',
243 content: { 'application/json': { schema: { type: 'object' } } },
244 },
245 '404': errorResponse,
246 },
247 },
248 },
249 '/v1/schemas/{provider}/{activity}': {
250 get: {
251 operationId: 'getActivitySchemas',
252 summary: 'Endpoint-id-keyed schema map for one activity',
253 parameters: [providerParam, activityParam],
254 responses: {
255 '200': {
256 description:
257 'Map of endpoint id → { input, output } self-contained JSON Schemas (current versions).',
258 content: { 'application/json': { schema: { type: 'object' } } },
259 },
260 '404': errorResponse,
261 },
262 },
263 },
264 '/v1/schemas/{provider}/{activity}/{endpointId}': {
265 get: {
266 operationId: 'getSchema',
267 summary: 'One self-contained JSON Schema',
268 parameters: [
269 providerParam,
270 activityParam,
271 {
272 name: 'endpointId',
273 in: 'path',
274 required: true,
275 description:
276 "Path-derived endpoint id (URL-encode slashes), or a listed model rawId/slug which aliases onto that activity's generation route and pins the request `model` field.",
277 schema: { type: 'string' },
278 },
279 {
280 name: 'kind',
281 in: 'query',
282 description: 'Defaults to input.',
283 schema: { type: 'string', enum: ['input', 'output'] },
284 },
285 {
286 name: 'version',
287 in: 'query',
288 description: 'Content hash of a historical version.',
289 schema: { type: 'string' },
290 },
291 {
292 name: 'format',
293 in: 'query',
294 description:
295 'json (default) or types — a self-contained TypeScript module (schema const + generated types, tree-shakeable, zero imports). format=types on an input schema with a model property overlays the live catalog union plus ListedModelId; the schema const and content hash stay the bundled schema.',
296 schema: { type: 'string', enum: ['json', 'types'] },
297 },
298 {
299 name: 'optional',
300 in: 'query',
301 description:
302 'format=types only: optional-property style. exact (default) emits `foo?: T`; undefined emits `foo?: T | undefined`.',
303 schema: { type: 'string', enum: ['exact', 'undefined'] },
304 },
305 ],
306 responses: {
307 '200': {
308 description:
309 'Self-contained JSON Schema ($defs-bundled) — or, with format=types, a TypeScript module — served with ETag. ' +
310 'JSON responses carry `provenance` (upstream sourceUrl, sourceHash, fetchedAt, extractorVersion) so derivations are independently verifiable. ' +
311 '`provenance.derivation` grades how the content was arrived at — `upstream-spec` and `generated` are re-derived every sync and self-heal, while `probe-verified` (confirmed against live API calls on `provenance.verifiedAt`) and `docs-derived` (never confirmed) are point-in-time claims that can go stale.',
312 content: {
313 'application/json': { schema: { type: 'object' } },
314 'text/typescript': { schema: { type: 'string' } },
315 },
316 },
317 '404': errorResponse,
318 },
319 },
320 },
321 '/v1/openapi/{provider}': {
322 get: {
323 operationId: 'getProviderOpenApi',
324 summary: 'Generation-only OpenAPI document for one provider',
325 description:
326 'Assembled from classified endpoints plus the provider connect profile (servers, auth, required headers). ' +
327 'Not a raw upstream-spec mirror. Model-grained providers (today: FAL) require ?model=. ' +
328 'Selections over 40 classified endpoints, or a filter that matches none, return 400 spec_requires_selector. ' +
329 'An unsynced provider returns 404 no_endpoints. ?model= pins the live model enum on provider-grained specs; it does not drop endpoints.',
330 parameters: [
331 providerParam,
332 {
333 name: 'model',
334 in: 'query',
335 description:
336 'Pin to one model (raw id or slug). Required for model-grained providers.',
337 schema: { type: 'string' },
338 },
339 {
340 name: 'activity',
341 in: 'query',
342 description: 'Restrict to one activity group.',
343 schema: { type: 'string', enum: activityEnum },
344 },
345 ],
346 responses: {
347 '200': {
348 description: 'OpenAPI 3.1 document.',
349 content: {
350 'application/openapi+json': { schema: { type: 'object' } },
351 'application/json': { schema: { type: 'object' } },
352 },
353 },
354 '400': errorResponse,
355 '404': errorResponse,
356 '500': errorResponse,
357 },
358 },
359 },
360 '/v1/validate': {
361 post: {
362 operationId: 'validatePayload',
363 summary: 'Validate a payload against a provider endpoint schema',
364 requestBody: {
365 required: true,
366 content: {
367 'application/json': {
368 schema: { $ref: '#/components/schemas/ValidateRequest' },
369 },
370 },
371 },
372 responses: {
373 '200': {
374 description: 'Validation result.',
375 content: {
376 'application/json': {
377 schema: { $ref: '#/components/schemas/ValidateResult' },
378 },
379 },
380 },
381 '400': errorResponse,
382 '404': errorResponse,
383 },
384 },
385 },
386 '/v1/estimate': {
387 post: {
388 operationId: 'estimateCost',
389 summary: 'Evaluate a stored rate card against request and usage',
390 requestBody: {
391 required: true,
392 content: {
393 'application/json': {
394 schema: { $ref: '#/components/schemas/EstimateRequest' },
395 },
396 },
397 },
398 responses: {
399 '200': {
400 description:
401 'The amount for this call and its currency, the card source, which inputs (if any) were estimated or took a default, and which request keys the card ignored.',
402 content: {
403 'application/json': {
404 schema: { $ref: '#/components/schemas/EstimateResult' },
405 },
406 },
407 },
408 '400': errorResponse,
409 '404': errorResponse,
410 '422': errorResponse,
411 },
412 },
413 },
414 '/v1/changes': {
415 get: {
416 operationId: 'listChanges',
417 summary: 'Changelog feed (cursor-paginated)',
418 description: 'The polling-friendly alternative to webhooks.',
419 parameters: [
420 {
421 name: 'since',
422 in: 'query',
423 description: 'Unix epoch seconds lower bound.',
424 schema: { type: 'integer' },
425 },
426 { name: 'provider', in: 'query', schema: { type: 'string' } },
427 {
428 name: 'type',
429 in: 'query',
430 schema: { type: 'string', enum: changeTypeEnum },
431 },
432 { name: 'cursor', in: 'query', schema: { type: 'string' } },
433 {
434 name: 'wait',
435 in: 'query',
436 description:
437 'Long-poll: hold up to N seconds (cap 60; "30s" form accepted) until new data exists, then return current data.',
438 schema: { type: 'string' },
439 },
440 {
441 name: 'limit',
442 in: 'query',
443 schema: { type: 'integer', minimum: 1, maximum: 200 },
444 },
445 ],
446 responses: {
447 '200': {
448 description: 'Changes page with next cursor.',
449 content: {
450 'application/json': {
451 schema: { $ref: '#/components/schemas/ChangesPage' },
452 },
453 },
454 },
455 },
456 },
457 },
458 '/v1/admin/sync/{provider}': {
459 post: {
460 operationId: 'syncProvider',
461 summary: 'Manually trigger a provider spec sync (admin only)',
462 parameters: [providerParam],
463 security: [{ adminKey: [] }],
464 responses: {
465 '200': {
466 description: 'Sync outcome.',
467 content: { 'application/json': { schema: { type: 'object' } } },
468 },
469 '401': errorResponse,
470 '404': errorResponse,
471 '502': errorResponse,
472 },
473 },
474 },
475 '/v1/admin/extract/fal': {
476 post: {
477 operationId: 'extractFalPricing',
478 summary:
479 'Manually trigger the FAL llms.txt rate-card extract (admin only). Spec sync stays on POST /v1/admin/sync/fal.',
480 security: [{ adminKey: [] }],
481 responses: {
482 '200': {
483 description: 'Extract outcome.',
484 content: { 'application/json': { schema: { type: 'object' } } },
485 },
486 '401': errorResponse,
487 '502': errorResponse,
488 },
489 },
490 },
491 '/v1/admin/export': {
492 get: {
493 operationId: 'exportCatalog',
494 summary:
495 'The whole catalog in one streamed response, for the public git mirror (admin only)',
496 description:
497 'Returns `latestChange` (the newest change id and createdAt, or null), ' +
498 'then `models` (live and deprecated, full rate card), `providers`, and ' +
499 '`schemas` (each endpoint with its current input and output versions). ' +
500 'Object keys are sorted, and fields that change on every poll ' +
501 '(`lastSeenAt`, `lastPolledAt`, `lastSyncedAt`, `_links`) are left out; ' +
502 'provenance timestamps such as `factSources.*.fetchedAt` are kept and ' +
503 'can move without a value changing. The export is not one snapshot: ' +
504 'rows read after `latestChange` may already hold newer changes. To ' +
505 'catch up from an earlier export, read every page of ' +
506 'GET /v1/changes?since=<its latestChange.createdAt> and skip only its ' +
507 'latestChange.id (change ids are random, so do not stop at it). A ' +
508 'failure part way breaks the stream, so the body is not valid JSON.',
509 security: [{ adminKey: [] }],
510 responses: {
511 '200': {
512 description:
513 'Catalog export. `models[]` items are the Model shape without `lastSeenAt` and `_links`.',
514 content: {
515 'application/json': {
516 schema: {
517 type: 'object',
518 required: ['latestChange', 'models', 'providers', 'schemas'],
519 properties: {
520 latestChange: {
521 type: ['object', 'null'],
522 required: ['id', 'createdAt'],
523 properties: {
524 id: { type: 'string' },
525 createdAt: { type: 'integer' },
526 },
527 },
528 models: {
529 type: 'array',
530 items: { $ref: '#/components/schemas/Model' },
531 },
532 providers: {
533 type: 'array',
534 items: {
535 type: 'object',
536 required: [
537 'id',
538 'displayName',
539 'status',
540 'modelNamespaces',
541 ],
542 properties: {
543 id: { type: 'string' },
544 displayName: { type: 'string' },
545 specSourceUrl: { type: ['string', 'null'] },
546 modelsEndpoint: { type: ['string', 'null'] },
547 authEnvVar: { type: ['string', 'null'] },
548 status: { type: 'string' },
549 modelNamespaces: {
550 type: 'array',
551 items: { type: 'string' },
552 },
553 },
554 },
555 },
556 schemas: {
557 type: 'array',
558 items: {
559 type: 'object',
560 required: [
561 'provider',
562 'endpointId',
563 'activity',
564 'method',
565 'path',
566 'input',
567 'output',
568 ],
569 properties: {
570 provider: { type: 'string' },
571 endpointId: { type: 'string' },
572 activity: { type: 'string' },
573 method: { type: 'string' },
574 path: { type: 'string' },
575 description: { type: ['string', 'null'] },
576 input: {
577 $ref: '#/components/schemas/ExportSchemaVersion',
578 },
579 output: {
580 $ref: '#/components/schemas/ExportSchemaVersion',
581 },
582 },
583 },
584 },
585 },
586 },
587 },
588 },
589 },
590 '401': errorResponse,
591 },
592 },
593 },
594 },
595 components: {
596 securitySchemes: {
597 adminKey: {
598 type: 'apiKey',
599 in: 'header',
600 name: 'X-Admin-Key',
601 },
602 bearerAuth: {
603 type: 'http',
604 scheme: 'bearer',
605 description: 'Agent JWT (agent-auth) or API key.',
606 },
607 },
608 schemas: {
609 Error: {
610 type: 'object',
611 required: ['error'],
612 properties: {
613 error: {
614 type: 'object',
615 required: ['code', 'message'],
616 properties: {
617 code: { type: 'string' },
618 message: { type: 'string' },
619 },
620 },
621 },
622 },
623 ServiceStatus: {
624 type: 'object',
625 required: ['service', 'time', 'providers'],
626 properties: {
627 service: { type: 'string', const: 'modelschemas' },
628 time: { type: 'integer' },
629 completenessComputedAt: {
630 type: ['integer', 'null'],
631 description:
632 'Epoch seconds the completeness scores were computed, at the last models poll (every 15 minutes). null when none is stored yet, as after a deploy that changes the scorer; every score is then null.',
633 },
634 providers: {
635 type: 'array',
636 items: {
637 type: 'object',
638 properties: {
639 id: { type: 'string' },
640 displayName: { type: 'string' },
641 status: {
642 type: 'string',
643 enum: ['active', 'degraded', 'disabled', 'pending'],
644 },
645 lastPolledAt: { type: ['integer', 'null'] },
646 lastSyncedAt: { type: ['integer', 'null'] },
647 docsFailing: {
648 type: 'object',
649 description:
650 'Present only while the provider docs pages fail to load. Polls go on and models keep their stored docs-derived facts, which may be stale. Does not change status.',
651 required: [
652 'since',
653 'polls',
654 'lastAt',
655 'failed',
656 'skipped',
657 'sources',
658 'error',
659 ],
660 properties: {
661 since: {
662 type: 'integer',
663 description: 'Epoch seconds of the first failing poll.',
664 },
665 polls: {
666 type: 'integer',
667 description: 'Consecutive failing polls.',
668 },
669 lastAt: {
670 type: 'integer',
671 description: 'Epoch seconds of the latest failing poll.',
672 },
673 failed: {
674 type: 'integer',
675 description: 'Documents that failed in the latest poll.',
676 },
677 skipped: {
678 type: 'integer',
679 description:
680 'Documents not attempted after the failure budget.',
681 },
682 sources: {
683 type: 'array',
684 items: { type: 'string' },
685 description: 'The first few failing documents.',
686 },
687 error: {
688 type: 'string',
689 description:
690 'First error of the latest poll, at most 500 characters.',
691 },
692 },
693 },
694 updateStorm: {
695 type: 'object',
696 description:
697 'Present only while the latest poll wrote model.updated for more than half of the live rows, and at least 20. The updates are written; this only marks a catalog-wide rewrite. Does not change status. The next poll under that line clears it.',
698 required: ['since', 'polls', 'lastAt', 'updated', 'live'],
699 properties: {
700 since: {
701 type: 'integer',
702 description: 'Epoch seconds of the first storming poll.',
703 },
704 polls: {
705 type: 'integer',
706 description: 'Consecutive storming polls.',
707 },
708 lastAt: {
709 type: 'integer',
710 description: 'Epoch seconds of the latest storming poll.',
711 },
712 updated: {
713 type: 'integer',
714 description:
715 'model.updated rows written by the latest poll.',
716 },
717 live: {
718 type: 'integer',
719 description:
720 'Live rows, not deprecated, at the start of that poll.',
721 },
722 },
723 },
724 priceClearsRefused: {
725 type: 'object',
726 description:
727 'Present only while polls refuse to clear most of the stored prices of the provider at once. The stored prices stay and may be stale. Does not change status.',
728 required: ['since', 'polls', 'lastAt', 'refused', 'priced'],
729 properties: {
730 since: {
731 type: 'integer',
732 description: 'Epoch seconds of the first refusing poll.',
733 },
734 polls: {
735 type: 'integer',
736 description: 'Consecutive refusing polls.',
737 },
738 lastAt: {
739 type: 'integer',
740 description: 'Epoch seconds of the latest refusing poll.',
741 },
742 refused: {
743 type: 'integer',
744 description:
745 'Stored prices the latest poll asked to clear; none was cleared.',
746 },
747 priced: {
748 type: 'integer',
749 description:
750 'Listed models holding a stored price at that poll.',
751 },
752 },
753 },
754 completeness: {
755 type: 'object',
756 description:
757 'The gap-report score over the live chat models of the provider: the share filled of the eleven chat facts (contextWindow, maxOutput, modalities, priced, cacheRead, capabilities, reasoning, efforts, requestMap, endpoint, replayReasoningContent). Summed per model, each fact counted only where it applies; provider-wide and exact-model source-silent exceptions are excluded. Computed at the models poll (completenessComputedAt), not per request.',
758 required: ['score', 'chat', 'filled', 'needed', 'silent'],
759 properties: {
760 score: {
761 type: ['number', 'null'],
762 description:
763 'filled / needed, 0 to 1. 1 when every fact that applies is in silent. null when the provider has no live chat models (nothing to score, not a score of zero), when no score is stored yet, and when the chat models changed since the stored score.',
764 },
765 chat: {
766 type: 'integer',
767 description: 'Live chat models scored.',
768 },
769 filled: {
770 type: 'integer',
771 description:
772 'Facts carried, summed over those models; silent facts left out.',
773 },
774 needed: {
775 type: 'integer',
776 description:
777 'Facts that apply, summed over those models; silent facts left out.',
778 },
779 silent: {
780 type: 'array',
781 items: { type: 'string' },
782 description:
783 'Facts the provider does not publish, left out of the score.',
784 },
785 },
786 },
787 counts: {
788 type: 'object',
789 description:
790 'Model tallies count live models only: what GET /v1/models lists by default. Deprecated models are in deprecated and nowhere else.',
791 properties: {
792 models: { type: 'integer' },
793 deprecated: {
794 type: 'integer',
795 description:
796 'Models no longer listed upstream (GET /v1/models?deprecated=true).',
797 },
798 priced: {
799 type: 'integer',
800 description:
801 'Models with a stored rate card. priced / models is the price score.',
802 },
803 reasoning: {
804 type: 'integer',
805 description:
806 'Models with stored reasoning metadata. reasoning / chat is the reasoning score.',
807 },
808 chat: {
809 type: 'integer',
810 description: 'Models whose activity is chat.',
811 },
812 endpoints: { type: 'integer' },
813 schemas: { type: 'integer' },
814 },
815 },
816 },
817 },
818 },
819 },
820 },
821 Change: {
822 type: 'object',
823 required: [
824 'id',
825 'type',
826 'providerId',
827 'subjectId',
828 'summary',
829 'createdAt',
830 ],
831 properties: {
832 id: { type: 'string' },
833 type: { type: 'string', enum: changeTypeEnum },
834 providerId: { type: 'string' },
835 subjectId: { type: 'string' },
836 summary: { type: 'string' },
837 payload: {
838 type: 'object',
839 description:
840 'model.updated carries before, after, and changed. changed is the fact paths that differ and is never empty. A source hash, an extract time, the operand order of +, and the order of an input values list are not facts, so they do not appear here and do not produce an event. Schema events carry kind, contentHash, and previousHash instead.',
841 properties: {
842 before: {},
843 after: {},
844 changed: {
845 type: 'array',
846 minItems: 1,
847 items: { type: 'string' },
848 description:
849 'Fact paths that differ, present on model.updated. For example contextWindow or pricing.tables.rate.base.input_tokens.',
850 },
851 kind: { type: 'string', enum: ['input', 'output'] },
852 contentHash: { type: 'string' },
853 previousHash: { type: ['string', 'null'] },
854 },
855 },
856 createdAt: {
857 type: 'integer',
858 description: 'Unix epoch seconds.',
859 },
860 },
861 },
862 ChangesPage: {
863 type: 'object',
864 required: ['count', 'changes', 'nextCursor'],
865 properties: {
866 count: { type: 'integer' },
867 changes: {
868 type: 'array',
869 items: { $ref: '#/components/schemas/Change' },
870 },
871 nextCursor: { type: ['string', 'null'] },
872 _links: { type: 'object' },
873 },
874 },
875 ExportSchemaVersion: {
876 description: 'A current schema version, or null when there is none.',
877 type: ['object', 'null'],
878 required: ['contentHash', 'specRevision', 'provenance', 'schema'],
879 properties: {
880 contentHash: { type: 'string' },
881 specRevision: { type: ['string', 'null'] },
882 provenance: {
883 type: 'object',
884 properties: {
885 sourceUrl: { type: ['string', 'null'] },
886 sourceHash: { type: ['string', 'null'] },
887 fetchedAt: { type: 'integer' },
888 extractorVersion: { type: ['string', 'null'] },
889 derivation: { type: ['string', 'null'] },
890 verifiedAt: { type: ['string', 'null'] },
891 },
892 },
893 schema: { type: 'object' },
894 },
895 },
896 ValidateRequest: {
897 type: 'object',
898 required: ['provider', 'endpointId', 'payload'],
899 properties: {
900 provider: { type: 'string' },
901 endpointId: { type: 'string' },
902 kind: { type: 'string', enum: ['input', 'output'] },
903 payload: {},
904 },
905 },
906 ValidateResult: {
907 type: 'object',
908 required: ['valid', 'errors'],
909 properties: {
910 valid: { type: 'boolean' },
911 errors: {
912 type: 'array',
913 items: {
914 type: 'object',
915 properties: {
916 path: { type: 'string' },
917 message: { type: 'string' },
918 keyword: { type: 'string' },
919 },
920 },
921 },
922 },
923 },
924 CompactPricing: {
925 type: 'object',
926 description:
927 'List-row summary of a stored rate card. per=token cards carry per-million rates at the base tier (tiered marks a long-prompt re-quote above some threshold; fetch the card for it). Other values name the unit the card bills by; the full card is on the detail route or ?pricing=1.',
928 required: ['currency', 'per'],
929 properties: {
930 currency: {
931 type: 'string',
932 pattern: '^[A-Z]{3}$',
933 description:
934 'ISO-4217 code the rates are in. Rows in different currencies do not compare; nothing is converted.',
935 },
936 per: {
937 type: 'string',
938 enum: ['token', 'second', 'character', 'image', 'request', 'unit'],
939 },
940 inputPerMillion: { type: 'number' },
941 outputPerMillion: { type: 'number' },
942 tiered: { type: 'boolean', enum: [true] },
943 },
944 },
945 RateCardSource: {
946 type: 'object',
947 required: ['url', 'hash', 'extractedAt'],
948 properties: {
949 url: { type: 'string', format: 'uri' },
950 hash: { type: 'string', pattern: '^[0-9a-f]{64}$' },
951 extractedAt: { type: 'string', format: 'date-time' },
952 expiresAt: { type: 'string', format: 'date-time' },
953 },
954 },
955 RateCardExample: {
956 type: 'object',
957 required: ['params', 'usd', 'quote'],
958 properties: {
959 params: { type: 'object' },
960 usd: {
961 type: 'number',
962 description: "In the card's currency; the name predates currency.",
963 },
964 quote: { type: 'string' },
965 },
966 },
967 RateCardInput: {
968 type: 'object',
969 required: ['param', 'kind'],
970 properties: {
971 param: { type: 'string' },
972 bound: { type: 'string', enum: ['request', 'usage'] },
973 kind: {
974 type: 'string',
975 enum: ['number', 'enum', 'boolean', 'count', 'dimensions'],
976 },
977 estimate: {
978 type: 'object',
979 description:
980 'Number inputs only: the source-published way to estimate this value when the caller omits it. Its own inputs bind only then, and POST /v1/estimate lists the param under estimated. Estimate inputs never carry an estimate of their own.',
981 required: ['inputs', 'value', 'source'],
982 properties: {
983 inputs: {
984 type: 'object',
985 additionalProperties: {
986 $ref: '#/components/schemas/RateCardInput',
987 },
988 },
989 value: {
990 description: 'JSONLogic expression over the closed op set.',
991 },
992 source: {
993 type: 'object',
994 required: ['url', 'hash'],
995 properties: {
996 url: { type: 'string', format: 'uri' },
997 hash: { type: 'string', pattern: '^[0-9a-f]{64}$' },
998 },
999 },
1000 },
1001 },
1002 },
1003 },
1004 RateCard: {
1005 type: 'object',
1006 required: ['inputs', 'tables', 'price', 'examples', 'source'],
1007 properties: {
1008 inputs: {
1009 type: 'object',
1010 additionalProperties: {
1011 $ref: '#/components/schemas/RateCardInput',
1012 },
1013 },
1014 tables: { type: 'object' },
1015 price: {
1016 description:
1017 'JSONLogic expression over the closed op set, yielding USD. A card in another currency wraps it as { "currency": ["CNY", <expression>] } (ISO 4217); that wrapper is the only place a card states its currency, and an evaluator that does not know it refuses the card.',
1018 },
1019 examples: {
1020 type: 'array',
1021 items: { $ref: '#/components/schemas/RateCardExample' },
1022 },
1023 source: { $ref: '#/components/schemas/RateCardSource' },
1024 },
1025 },
1026 ChatRequestMap: {
1027 type: 'object',
1028 description:
1029 'Verified chat request wire map. A null field is unverified, not a guess. thinking.levels null means the level subset is unverified; a null level value means omit that field.',
1030 properties: {
1031 thinking: {
1032 oneOf: [
1033 {
1034 type: 'object',
1035 required: ['on', 'off', 'levels'],
1036 properties: {
1037 on: {
1038 type: 'object',
1039 description: 'Request body for thinking on at effort high.',
1040 additionalProperties: true,
1041 },
1042 off: {
1043 description:
1044 'Request body that turns thinking off, or null when silence is off.',
1045 },
1046 levels: {
1047 description:
1048 'Shared effort levels to the value this model accepts. null omits the field. The object itself is null when the subset is unverified.',
1049 oneOf: [
1050 {
1051 type: 'object',
1052 required: [
1053 'off',
1054 'minimal',
1055 'low',
1056 'medium',
1057 'high',
1058 'xhigh',
1059 'max',
1060 ],
1061 properties: {
1062 off: { type: ['string', 'null'] },
1063 minimal: { type: ['string', 'null'] },
1064 low: { type: ['string', 'null'] },
1065 medium: { type: ['string', 'null'] },
1066 high: { type: ['string', 'null'] },
1067 xhigh: { type: ['string', 'null'] },
1068 max: { type: ['string', 'null'] },
1069 },
1070 },
1071 { type: 'null' },
1072 ],
1073 },
1074 },
1075 },
1076 { type: 'null' },
1077 ],
1078 },
1079 maxTokensField: {
1080 type: ['string', 'null'],
1081 enum: ['max_completion_tokens', 'max_tokens', null],
1082 },
1083 developerRole: { type: ['boolean', 'null'] },
1084 replayReasoningContent: { type: ['boolean', 'null'] },
1085 store: { type: ['boolean', 'null'] },
1086 strictTools: { type: ['boolean', 'null'] },
1087 sessionAffinity: { type: ['boolean', 'null'] },
1088 cacheControl: {
1089 type: ['string', 'null'],
1090 enum: ['anthropic', null],
1091 },
1092 toolStream: { type: ['boolean', 'null'] },
1093 reasoningEffort: { type: ['boolean', 'null'] },
1094 },
1095 },
1096 Model: {
1097 type: 'object',
1098 properties: {
1099 id: { type: 'string' },
1100 provider: { type: 'string' },
1101 rawId: { type: 'string' },
1102 sameAs: {
1103 description:
1104 "The catalog row this provider's own listing or docs identify as the same upstream model. It does not change this row's facts. null when no upstream is stated, or the stated one matches no row or more than one. When set, factSources.sameAs records the source, with normalized: true when the id matched only after reading dots as hyphens.",
1105 oneOf: [
1106 {
1107 type: 'object',
1108 required: ['provider', 'rawId'],
1109 properties: {
1110 provider: { type: 'string' },
1111 rawId: { type: 'string' },
1112 },
1113 },
1114 { type: 'null' },
1115 ],
1116 },
1117 activity: { type: ['string', 'null'], enum: [...activityEnum, null] },
1118 displayName: { type: ['string', 'null'] },
1119 schemaEndpointId: { type: ['string', 'null'] },
1120 contextWindow: { type: ['integer', 'null'] },
1121 maxOutput: { type: ['integer', 'null'] },
1122 modalities: {},
1123 pricing: {
1124 description:
1125 'Full RateCard on detail and on list rows with ?pricing=1; a CompactPricing summary on list rows otherwise. null only when no card is stored.',
1126 oneOf: [
1127 { $ref: '#/components/schemas/RateCard' },
1128 { $ref: '#/components/schemas/CompactPricing' },
1129 { type: 'null' },
1130 ],
1131 },
1132 capabilities: {
1133 description:
1134 "Capability flags as a map. true: the provider states the model supports the flag. false: the provider states it does not. Key absent: unknown; never read a missing key as false. null: nothing is known. Test capabilities?.tools === true to offer a feature and === false to rule it out. factSources.capabilities holds one source per key, for a true and a false alike; a false whose source has path 'unlisted' comes from the provider publishing the model's whole flag list without that flag.",
1135 type: ['object', 'null'],
1136 additionalProperties: { type: 'boolean' },
1137 },
1138 providerMetadata: {
1139 description:
1140 "The provider's own listing object for the model, as published: not normalised, and different for every provider (fal category, BytePlus Ark features and task type, ElevenLabs languages, Replicate visibility). null when the provider lists none. Nothing in it is a capability flag; read capabilities for those.",
1141 type: ['object', 'null'],
1142 additionalProperties: true,
1143 },
1144 reasoning: {
1145 description:
1146 "How thinking is configured, or null when the model does not reason or its source names no request field for it. mode names the one control the request exposes: adaptive (the model decides; Anthropic thinking.type adaptive, or a switch with an auto value), budget (a token budget: thinking.budget_tokens, Gemini thinkingBudget), effort (a level: reasoning_effort, Gemini thinkingLevel) or toggle (an on/off switch and nothing else: thinking.type enabled|disabled, enable_thinking; it says nothing about the default when the field is omitted). mandatory has one meaning on every mode. true: the provider states thinking cannot be turned off for this model (on a toggle: the off value is rejected, so send on or omit the field). false: the provider states it can be, in prose or by an off value in this model's own schema or level list. null: unstated. null must not be read as false: test mandatory === false before offering an off option. A toggle is never stored with mandatory null. efforts: the accepted effort values as published, an off value such as none included; never present on toggle. Rows from some providers still carry a true inferred from a level list with no off value; the README release notes list them.",
1147 oneOf: [
1148 {
1149 type: 'object',
1150 required: ['mode', 'mandatory'],
1151 properties: {
1152 mode: {
1153 type: 'string',
1154 enum: ['adaptive', 'budget', 'effort', 'toggle'],
1155 },
1156 mandatory: { type: ['boolean', 'null'] },
1157 efforts: { type: 'array', items: { type: 'string' } },
1158 },
1159 },
1160 { type: 'null' },
1161 ],
1162 },
1163 serverTools: {
1164 description:
1165 "Provider-hosted tool type ids the model accepts in the request's tools array (web_search_20250305, google_search, x_search, …), or null when unknown. factSources.serverTools holds one source per id.",
1166 type: ['array', 'null'],
1167 items: { type: 'string' },
1168 },
1169 requestMap: {
1170 description:
1171 "How to build this chat model's request: thinking on/off and shared effort levels (null omits the field), max-token field name, developer vs system role, reasoning_content replay, and related flags. Null until verified. reasoning stays the readable fact (mode, mandatory, efforts).",
1172 oneOf: [
1173 { $ref: '#/components/schemas/ChatRequestMap' },
1174 { type: 'null' },
1175 ],
1176 },
1177 aliases: {
1178 description:
1179 'Caller ids that resolve to this row (for example claude-opus-4-5 → the dated snapshot). null when the provider documents none. GET /v1/models/{provider}/{id} accepts an alias and returns this row, whose rawId is the dated id.',
1180 type: ['array', 'null'],
1181 items: { type: 'string' },
1182 },
1183 factSources: {
1184 description:
1185 'Per-field provenance, included by default on detail and list responses (provenance=0 explicitly omits it on lists). A ledgered null chat fact carries derivation source-silent, with sourceUrl and checkedAt only when recorded. capabilities and serverTools normally contain per-item source maps; whole-field silence is a source-silent object. Missing cacheRead and efforts subfacts have separate provenance keys; endpoint silence is schemaEndpointId. Populated facts keep their existing provenance. Nulls without ledger evidence gain no entry.',
1186 },
1187 releasedAt: {
1188 description:
1189 "The provider's own stated release or creation date, epoch seconds. null when the provider reports none. Unlike firstSeenAt it is never our observation.",
1190 type: ['integer', 'null'],
1191 },
1192 knowledgeCutoff: {
1193 description:
1194 'Knowledge (training data) cutoff as the provider states it: YYYY-MM, or YYYY-MM-DD when the provider gives a day. Never padded to a day. null when unknown. factSources.knowledgeCutoff is its source.',
1195 type: ['string', 'null'],
1196 pattern: '^\\d{4}-\\d{2}(-\\d{2})?$',
1197 },
1198 openWeights: {
1199 description:
1200 'true when the provider itself states the weights can be openly downloaded, false when it states they cannot, null when it states neither. Never inferred from a model name. factSources.openWeights is its source.',
1201 type: ['boolean', 'null'],
1202 },
1203 weightsUrl: {
1204 description:
1205 'Where the provider says the weights are. Set only when openWeights is true.',
1206 type: ['string', 'null'],
1207 },
1208 firstSeenAt: {
1209 description:
1210 'The release date the provider reports when it reports one (the same date as releasedAt), otherwise when this service first observed the model. Read releasedAt to tell the two apart.',
1211 type: 'integer',
1212 },
1213 lastSeenAt: { type: 'integer' },
1214 deprecatedAt: { type: ['integer', 'null'] },
1215 },
1216 },
1217 ModelList: {
1218 type: 'object',
1219 properties: {
1220 count: { type: 'integer' },
1221 models: {
1222 type: 'array',
1223 items: { $ref: '#/components/schemas/Model' },
1224 },
1225 },
1226 },
1227 EstimateRequest: {
1228 type: 'object',
1229 required: ['provider', 'model'],
1230 properties: {
1231 provider: { type: 'string' },
1232 model: { type: 'string' },
1233 request: {
1234 type: 'object',
1235 description:
1236 'The provider request body. Request-bound levers read it; result.ignored names the keys the card does not read.',
1237 },
1238 usage: {
1239 type: 'object',
1240 description:
1241 "The provider's own usage object as returned (OpenAI Responses or Chat Completions usage, Anthropic usage, Gemini usageMetadata), or card levers. Native usage is mapped to card levers: OpenAI cached_tokens and cache_write_tokens move from the prompt total to cache_read_tokens and cache_write_tokens, and Gemini cachedContentTokenCount moves to cache_read_tokens; Anthropic cache_read_input_tokens and cache_creation_input_tokens become cache_read_tokens and cache_write_tokens (1-hour writes: cache_write_1h_tokens). Card lever counts do not overlap: input_tokens excludes the cache levers, and a count in reasoning_tokens, audio_tokens or image_tokens is not also in input_tokens or output_tokens. The model's pricing.inputs lists the levers its card reads. A payload that mixes native fields and card levers gets 422 mixed_usage; a usage key the card does not read gets 422 unknown_usage_key.",
1242 },
1243 },
1244 },
1245 EstimateResult: {
1246 type: 'object',
1247 required: [
1248 'amount',
1249 'currency',
1250 'cardSource',
1251 'estimated',
1252 'defaulted',
1253 'ignored',
1254 ],
1255 properties: {
1256 amount: {
1257 type: 'number',
1258 description: 'The price, in currency. Never converted.',
1259 },
1260 currency: {
1261 type: 'string',
1262 pattern: '^[A-Z]{3}$',
1263 description: "ISO-4217 code of the card's currency.",
1264 },
1265 usd: {
1266 type: 'number',
1267 deprecated: true,
1268 description:
1269 'Deprecated: read amount and currency. Repeats amount when currency is USD; absent for any other currency.',
1270 },
1271 cardSource: { $ref: '#/components/schemas/RateCardSource' },
1272 estimated: {
1273 type: 'array',
1274 items: { type: 'string' },
1275 description:
1276 'Params the caller omitted that the card estimated by its published method. Empty: amount is the price as billed for the supplied request and usage.',
1277 },
1278 defaulted: {
1279 type: 'array',
1280 items: { type: 'string' },
1281 description:
1282 "Params the caller omitted that took the card's default (an omitted list counts as empty). Supply them when the default does not match the call, such as cache_read_tokens on a call that read the cache.",
1283 },
1284 ignored: {
1285 type: 'array',
1286 items: { type: 'string' },
1287 description:
1288 'Request keys the card does not read. They do not change amount. A usage key the card does not read is a 422 unknown_usage_key instead, because a dropped usage count gives a wrong price.',
1289 },
1290 },
1291 },
1292 },
1293 },
1294} as const