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, and which inputs (if any) were estimated.',
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 },
492 components: {
493 securitySchemes: {
494 adminKey: {
495 type: 'apiKey',
496 in: 'header',
497 name: 'X-Admin-Key',
498 },
499 bearerAuth: {
500 type: 'http',
501 scheme: 'bearer',
502 description: 'Agent JWT (agent-auth) or API key.',
503 },
504 },
505 schemas: {
506 Error: {
507 type: 'object',
508 required: ['error'],
509 properties: {
510 error: {
511 type: 'object',
512 required: ['code', 'message'],
513 properties: {
514 code: { type: 'string' },
515 message: { type: 'string' },
516 },
517 },
518 },
519 },
520 ServiceStatus: {
521 type: 'object',
522 required: ['service', 'time', 'providers'],
523 properties: {
524 service: { type: 'string', const: 'modelschemas' },
525 time: { type: 'integer' },
526 completenessComputedAt: {
527 type: ['integer', 'null'],
528 description:
529 '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.',
530 },
531 providers: {
532 type: 'array',
533 items: {
534 type: 'object',
535 properties: {
536 id: { type: 'string' },
537 displayName: { type: 'string' },
538 status: {
539 type: 'string',
540 enum: ['active', 'degraded', 'disabled', 'pending'],
541 },
542 lastPolledAt: { type: ['integer', 'null'] },
543 lastSyncedAt: { type: ['integer', 'null'] },
544 docsFailing: {
545 type: 'object',
546 description:
547 '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.',
548 required: [
549 'since',
550 'polls',
551 'lastAt',
552 'failed',
553 'skipped',
554 'sources',
555 'error',
556 ],
557 properties: {
558 since: {
559 type: 'integer',
560 description: 'Epoch seconds of the first failing poll.',
561 },
562 polls: {
563 type: 'integer',
564 description: 'Consecutive failing polls.',
565 },
566 lastAt: {
567 type: 'integer',
568 description: 'Epoch seconds of the latest failing poll.',
569 },
570 failed: {
571 type: 'integer',
572 description: 'Documents that failed in the latest poll.',
573 },
574 skipped: {
575 type: 'integer',
576 description:
577 'Documents not attempted after the failure budget.',
578 },
579 sources: {
580 type: 'array',
581 items: { type: 'string' },
582 description: 'The first few failing documents.',
583 },
584 error: {
585 type: 'string',
586 description:
587 'First error of the latest poll, at most 500 characters.',
588 },
589 },
590 },
591 updateStorm: {
592 type: 'object',
593 description:
594 '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.',
595 required: ['since', 'polls', 'lastAt', 'updated', 'live'],
596 properties: {
597 since: {
598 type: 'integer',
599 description: 'Epoch seconds of the first storming poll.',
600 },
601 polls: {
602 type: 'integer',
603 description: 'Consecutive storming polls.',
604 },
605 lastAt: {
606 type: 'integer',
607 description: 'Epoch seconds of the latest storming poll.',
608 },
609 updated: {
610 type: 'integer',
611 description:
612 'model.updated rows written by the latest poll.',
613 },
614 live: {
615 type: 'integer',
616 description:
617 'Live rows, not deprecated, at the start of that poll.',
618 },
619 },
620 },
621 priceClearsRefused: {
622 type: 'object',
623 description:
624 '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.',
625 required: ['since', 'polls', 'lastAt', 'refused', 'priced'],
626 properties: {
627 since: {
628 type: 'integer',
629 description: 'Epoch seconds of the first refusing poll.',
630 },
631 polls: {
632 type: 'integer',
633 description: 'Consecutive refusing polls.',
634 },
635 lastAt: {
636 type: 'integer',
637 description: 'Epoch seconds of the latest refusing poll.',
638 },
639 refused: {
640 type: 'integer',
641 description:
642 'Stored prices the latest poll asked to clear; none was cleared.',
643 },
644 priced: {
645 type: 'integer',
646 description:
647 'Listed models holding a stored price at that poll.',
648 },
649 },
650 },
651 completeness: {
652 type: 'object',
653 description:
654 '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.',
655 required: ['score', 'chat', 'filled', 'needed', 'silent'],
656 properties: {
657 score: {
658 type: ['number', 'null'],
659 description:
660 '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.',
661 },
662 chat: {
663 type: 'integer',
664 description: 'Live chat models scored.',
665 },
666 filled: {
667 type: 'integer',
668 description:
669 'Facts carried, summed over those models; silent facts left out.',
670 },
671 needed: {
672 type: 'integer',
673 description:
674 'Facts that apply, summed over those models; silent facts left out.',
675 },
676 silent: {
677 type: 'array',
678 items: { type: 'string' },
679 description:
680 'Facts the provider does not publish, left out of the score.',
681 },
682 },
683 },
684 counts: {
685 type: 'object',
686 description:
687 'Model tallies count live models only: what GET /v1/models lists by default. Deprecated models are in deprecated and nowhere else.',
688 properties: {
689 models: { type: 'integer' },
690 deprecated: {
691 type: 'integer',
692 description:
693 'Models no longer listed upstream (GET /v1/models?deprecated=true).',
694 },
695 priced: {
696 type: 'integer',
697 description:
698 'Models with a stored rate card. priced / models is the price score.',
699 },
700 reasoning: {
701 type: 'integer',
702 description:
703 'Models with stored reasoning metadata. reasoning / chat is the reasoning score.',
704 },
705 chat: {
706 type: 'integer',
707 description: 'Models whose activity is chat.',
708 },
709 endpoints: { type: 'integer' },
710 schemas: { type: 'integer' },
711 },
712 },
713 },
714 },
715 },
716 },
717 },
718 Change: {
719 type: 'object',
720 required: [
721 'id',
722 'type',
723 'providerId',
724 'subjectId',
725 'summary',
726 'createdAt',
727 ],
728 properties: {
729 id: { type: 'string' },
730 type: { type: 'string', enum: changeTypeEnum },
731 providerId: { type: 'string' },
732 subjectId: { type: 'string' },
733 summary: { type: 'string' },
734 payload: {
735 type: 'object',
736 description:
737 '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.',
738 properties: {
739 before: {},
740 after: {},
741 changed: {
742 type: 'array',
743 minItems: 1,
744 items: { type: 'string' },
745 description:
746 'Fact paths that differ, present on model.updated. For example contextWindow or pricing.tables.rate.base.input_tokens.',
747 },
748 kind: { type: 'string', enum: ['input', 'output'] },
749 contentHash: { type: 'string' },
750 previousHash: { type: ['string', 'null'] },
751 },
752 },
753 createdAt: {
754 type: 'integer',
755 description: 'Unix epoch seconds.',
756 },
757 },
758 },
759 ChangesPage: {
760 type: 'object',
761 required: ['count', 'changes', 'nextCursor'],
762 properties: {
763 count: { type: 'integer' },
764 changes: {
765 type: 'array',
766 items: { $ref: '#/components/schemas/Change' },
767 },
768 nextCursor: { type: ['string', 'null'] },
769 _links: { type: 'object' },
770 },
771 },
772 ValidateRequest: {
773 type: 'object',
774 required: ['provider', 'endpointId', 'payload'],
775 properties: {
776 provider: { type: 'string' },
777 endpointId: { type: 'string' },
778 kind: { type: 'string', enum: ['input', 'output'] },
779 payload: {},
780 },
781 },
782 ValidateResult: {
783 type: 'object',
784 required: ['valid', 'errors'],
785 properties: {
786 valid: { type: 'boolean' },
787 errors: {
788 type: 'array',
789 items: {
790 type: 'object',
791 properties: {
792 path: { type: 'string' },
793 message: { type: 'string' },
794 keyword: { type: 'string' },
795 },
796 },
797 },
798 },
799 },
800 CompactPricing: {
801 type: 'object',
802 description:
803 '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.',
804 required: ['currency', 'per'],
805 properties: {
806 currency: {
807 type: 'string',
808 pattern: '^[A-Z]{3}$',
809 description:
810 'ISO-4217 code the rates are in. Rows in different currencies do not compare; nothing is converted.',
811 },
812 per: {
813 type: 'string',
814 enum: ['token', 'second', 'character', 'image', 'request', 'unit'],
815 },
816 inputPerMillion: { type: 'number' },
817 outputPerMillion: { type: 'number' },
818 tiered: { type: 'boolean', enum: [true] },
819 },
820 },
821 RateCardSource: {
822 type: 'object',
823 required: ['url', 'hash', 'extractedAt'],
824 properties: {
825 url: { type: 'string', format: 'uri' },
826 hash: { type: 'string', pattern: '^[0-9a-f]{64}$' },
827 extractedAt: { type: 'string', format: 'date-time' },
828 expiresAt: { type: 'string', format: 'date-time' },
829 },
830 },
831 RateCardExample: {
832 type: 'object',
833 required: ['params', 'usd', 'quote'],
834 properties: {
835 params: { type: 'object' },
836 usd: {
837 type: 'number',
838 description: "In the card's currency; the name predates currency.",
839 },
840 quote: { type: 'string' },
841 },
842 },
843 RateCardInput: {
844 type: 'object',
845 required: ['param', 'kind'],
846 properties: {
847 param: { type: 'string' },
848 bound: { type: 'string', enum: ['request', 'usage'] },
849 kind: {
850 type: 'string',
851 enum: ['number', 'enum', 'boolean', 'count', 'dimensions'],
852 },
853 estimate: {
854 type: 'object',
855 description:
856 '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.',
857 required: ['inputs', 'value', 'source'],
858 properties: {
859 inputs: {
860 type: 'object',
861 additionalProperties: {
862 $ref: '#/components/schemas/RateCardInput',
863 },
864 },
865 value: {
866 description: 'JSONLogic expression over the closed op set.',
867 },
868 source: {
869 type: 'object',
870 required: ['url', 'hash'],
871 properties: {
872 url: { type: 'string', format: 'uri' },
873 hash: { type: 'string', pattern: '^[0-9a-f]{64}$' },
874 },
875 },
876 },
877 },
878 },
879 },
880 RateCard: {
881 type: 'object',
882 required: ['inputs', 'tables', 'price', 'examples', 'source'],
883 properties: {
884 inputs: {
885 type: 'object',
886 additionalProperties: {
887 $ref: '#/components/schemas/RateCardInput',
888 },
889 },
890 tables: { type: 'object' },
891 price: {
892 description:
893 '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.',
894 },
895 examples: {
896 type: 'array',
897 items: { $ref: '#/components/schemas/RateCardExample' },
898 },
899 source: { $ref: '#/components/schemas/RateCardSource' },
900 },
901 },
902 ChatRequestMap: {
903 type: 'object',
904 description:
905 '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.',
906 properties: {
907 thinking: {
908 oneOf: [
909 {
910 type: 'object',
911 required: ['on', 'off', 'levels'],
912 properties: {
913 on: {
914 type: 'object',
915 description: 'Request body for thinking on at effort high.',
916 additionalProperties: true,
917 },
918 off: {
919 description:
920 'Request body that turns thinking off, or null when silence is off.',
921 },
922 levels: {
923 description:
924 'Shared effort levels to the value this model accepts. null omits the field. The object itself is null when the subset is unverified.',
925 oneOf: [
926 {
927 type: 'object',
928 required: [
929 'off',
930 'minimal',
931 'low',
932 'medium',
933 'high',
934 'xhigh',
935 'max',
936 ],
937 properties: {
938 off: { type: ['string', 'null'] },
939 minimal: { type: ['string', 'null'] },
940 low: { type: ['string', 'null'] },
941 medium: { type: ['string', 'null'] },
942 high: { type: ['string', 'null'] },
943 xhigh: { type: ['string', 'null'] },
944 max: { type: ['string', 'null'] },
945 },
946 },
947 { type: 'null' },
948 ],
949 },
950 },
951 },
952 { type: 'null' },
953 ],
954 },
955 maxTokensField: {
956 type: ['string', 'null'],
957 enum: ['max_completion_tokens', 'max_tokens', null],
958 },
959 developerRole: { type: ['boolean', 'null'] },
960 replayReasoningContent: { type: ['boolean', 'null'] },
961 store: { type: ['boolean', 'null'] },
962 strictTools: { type: ['boolean', 'null'] },
963 sessionAffinity: { type: ['boolean', 'null'] },
964 cacheControl: {
965 type: ['string', 'null'],
966 enum: ['anthropic', null],
967 },
968 toolStream: { type: ['boolean', 'null'] },
969 reasoningEffort: { type: ['boolean', 'null'] },
970 },
971 },
972 Model: {
973 type: 'object',
974 properties: {
975 id: { type: 'string' },
976 provider: { type: 'string' },
977 rawId: { type: 'string' },
978 sameAs: {
979 description:
980 "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.",
981 oneOf: [
982 {
983 type: 'object',
984 required: ['provider', 'rawId'],
985 properties: {
986 provider: { type: 'string' },
987 rawId: { type: 'string' },
988 },
989 },
990 { type: 'null' },
991 ],
992 },
993 activity: { type: ['string', 'null'], enum: [...activityEnum, null] },
994 displayName: { type: ['string', 'null'] },
995 schemaEndpointId: { type: ['string', 'null'] },
996 contextWindow: { type: ['integer', 'null'] },
997 maxOutput: { type: ['integer', 'null'] },
998 modalities: {},
999 pricing: {
1000 description:
1001 '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.',
1002 oneOf: [
1003 { $ref: '#/components/schemas/RateCard' },
1004 { $ref: '#/components/schemas/CompactPricing' },
1005 { type: 'null' },
1006 ],
1007 },
1008 capabilities: {
1009 description:
1010 "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.",
1011 type: ['object', 'null'],
1012 additionalProperties: { type: 'boolean' },
1013 },
1014 providerMetadata: {
1015 description:
1016 "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.",
1017 type: ['object', 'null'],
1018 additionalProperties: true,
1019 },
1020 reasoning: {
1021 description:
1022 "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.",
1023 oneOf: [
1024 {
1025 type: 'object',
1026 required: ['mode', 'mandatory'],
1027 properties: {
1028 mode: {
1029 type: 'string',
1030 enum: ['adaptive', 'budget', 'effort', 'toggle'],
1031 },
1032 mandatory: { type: ['boolean', 'null'] },
1033 efforts: { type: 'array', items: { type: 'string' } },
1034 },
1035 },
1036 { type: 'null' },
1037 ],
1038 },
1039 serverTools: {
1040 description:
1041 "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.",
1042 type: ['array', 'null'],
1043 items: { type: 'string' },
1044 },
1045 requestMap: {
1046 description:
1047 "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).",
1048 oneOf: [
1049 { $ref: '#/components/schemas/ChatRequestMap' },
1050 { type: 'null' },
1051 ],
1052 },
1053 aliases: {
1054 description:
1055 '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.',
1056 type: ['array', 'null'],
1057 items: { type: 'string' },
1058 },
1059 factSources: {
1060 description:
1061 '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.',
1062 },
1063 releasedAt: {
1064 description:
1065 "The provider's own stated release or creation date, epoch seconds. null when the provider reports none. Unlike firstSeenAt it is never our observation.",
1066 type: ['integer', 'null'],
1067 },
1068 knowledgeCutoff: {
1069 description:
1070 '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.',
1071 type: ['string', 'null'],
1072 pattern: '^\\d{4}-\\d{2}(-\\d{2})?$',
1073 },
1074 openWeights: {
1075 description:
1076 '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.',
1077 type: ['boolean', 'null'],
1078 },
1079 weightsUrl: {
1080 description:
1081 'Where the provider says the weights are. Set only when openWeights is true.',
1082 type: ['string', 'null'],
1083 },
1084 firstSeenAt: {
1085 description:
1086 '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.',
1087 type: 'integer',
1088 },
1089 lastSeenAt: { type: 'integer' },
1090 deprecatedAt: { type: ['integer', 'null'] },
1091 },
1092 },
1093 ModelList: {
1094 type: 'object',
1095 properties: {
1096 count: { type: 'integer' },
1097 models: {
1098 type: 'array',
1099 items: { $ref: '#/components/schemas/Model' },
1100 },
1101 },
1102 },
1103 EstimateRequest: {
1104 type: 'object',
1105 required: ['provider', 'model'],
1106 properties: {
1107 provider: { type: 'string' },
1108 model: { type: 'string' },
1109 request: { type: 'object' },
1110 usage: { type: 'object' },
1111 },
1112 },
1113 EstimateResult: {
1114 type: 'object',
1115 required: ['amount', 'currency', 'cardSource', 'estimated'],
1116 properties: {
1117 amount: {
1118 type: 'number',
1119 description: 'The price, in currency. Never converted.',
1120 },
1121 currency: {
1122 type: 'string',
1123 pattern: '^[A-Z]{3}$',
1124 description: "ISO-4217 code of the card's currency.",
1125 },
1126 usd: {
1127 type: 'number',
1128 deprecated: true,
1129 description:
1130 'Deprecated: read amount and currency. Repeats amount when currency is USD; absent for any other currency.',
1131 },
1132 cardSource: { $ref: '#/components/schemas/RateCardSource' },
1133 estimated: {
1134 type: 'array',
1135 items: { type: 'string' },
1136 description:
1137 '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.',
1138 },
1139 },
1140 },
1141 },
1142 },
1143} as const