# modelschemas

Live AI model schema service. Per-endpoint request/response JSON Schemas and
model metadata for 30+ monitored providers (OpenAI, Anthropic, Gemini, xAI
Grok, Mistral, Groq, DeepSeek, and more — GET /v1/providers for the full
roster), refreshed automatically: model lists every 15 minutes, full OpenAPI
spec syncs daily. Responses are JSON unless noted (`text/typescript`,
`application/openapi+json`).

## Why use this

- Discover which models exist *right now*, across providers, by activity
  (chat, image, video, audio, embeddings, moderation). Grain=provider
  catalogs (Grok, OpenAI, …) set `activity` on each row and
  `schemaEndpointId` pointing at the shared generation route
  (`v1/images/generations`, `images/generations`, …). `pricing` is a
  RateCard (or null when no price is stored). List rows carry a summary:
  `{currency, per: 'token', inputPerMillion, outputPerMillion, tiered?}`
  at the base rate, or `{currency, per: 'second' | 'character' | 'image' | …}`
  for a card billed by unit. `currency` is ISO 4217 (mostly USD; nothing
  is converted, so compare only like with like); `?pricing=1` returns
  the full card. `/v1/status` counts live `priced` models per provider
  and scores `completeness` (the share of chat facts filled; `score` is
  null with no chat models). A provider there carries `docsFailing`,
  `priceClearsRefused`, or `updateStorm` while its stored docs facts or
  prices may be stale, or one poll rewrote most of its live rows.
- Fetch a self-contained JSON Schema (refs bundled under $defs) for any
  provider generation endpoint — request (input) and response (output).
  A listed model rawId also works as `{endpointId}`: it aliases onto that
  route and pins the request `model` field to the one id.
- Validate a payload server-side before spending tokens on a provider call.
- Estimate the cost of a call from the stored rate card, in the card's
  currency (`POST /v1/estimate`).
- Poll /v1/changes (or subscribe via webhooks) to hear about new models and
  API revisions.

## Quickstart (no auth needed for reads)

1. GET /v1 — endpoint index.
2. GET /v1/models?activity=chat — cross-provider catalog of chat models.
3. GET /v1/schemas — system-wide index: every provider's activities and
   endpoint ids in one response (all schemas on the system).
4. GET /v1/schemas/anthropic — activities + endpoint ids for one provider.
5. GET /v1/schemas/anthropic/chat/{endpointId}?kind=input — the JSON Schema
   for a request body (endpoint ids contain slashes; URL-encode them).
   Grain=provider models also accept the raw id:
   `/v1/schemas/grok/image/grok-imagine-image-2.0?kind=input`.
6. GET /v1/openapi/{provider} — generation-only OpenAPI (servers, auth,
   paths). FAL requires ?model=. Over 40 endpoints, or a filter that
   matches none: 400 spec_requires_selector. HTTP only (no MCP tool).
7. POST /v1/validate {"provider","endpointId","payload"} — check a payload.
8. POST /v1/estimate {"provider","model","request"?,"usage"?} — {amount,
   currency} for a call from the stored rate card. Missing levers → 422;
   no card → 404 unknown_pricing.
9. GET /v1/changes?since=<unix epoch> — what changed.

## TypeScript types

Add `?format=types` to a schema read
(GET /v1/schemas/{provider}/{activity}/{endpointId}) to get a self-contained
TypeScript module instead of JSON: the schema as a pure const plus generated
interfaces (`text/typescript`, zero imports, tree-shakeable, same ETag
discipline). `?optional=undefined` widens optional properties to
`T | undefined` for exactOptionalPropertyTypes consumers; default is
`foo?: T`. A request `model` field is the live catalog union plus
`ListedModelId<'provider'>` (still branded when the catalog is empty).
Minted by `listModels` / `listProviderModels` / `getModel` (or
`asListedModelId`). Arbitrary `string` values do not assign.

## Hypermedia (HAL, extended)

Every JSON read response carries `_links`: HAL link objects extended with
`method`, `contentType`, and an inline `example` (a resolvable URL for
GETs, a request body for POSTs) so you can follow the API without consulting
docs. Templated hrefs (RFC 6570) set `"templated": true` and always include
an example. Start at GET /v1 and follow `_links`.

## Long-polling

No sleep tool? Add `?wait=30` (seconds, cap 60, `30s` form accepted) to
GET /v1/changes or GET /v1/status: the request holds until new data lands or
the window expires, then returns whatever is current. One request, one
rate-limit token.

## Caching

Read responses carry ETag (content hash), Last-Modified, Cache-Control with
stale-while-revalidate, X-Fetched-At and X-Stale-At (unix epoch seconds).
Send If-None-Match to get 304s.

## Auth (optional — unlocks higher rate limits + webhooks)

- Agent-auth protocol: discovery at /.well-known/agent-configuration,
  register at POST /api/auth/agent/register, then execute capabilities with
  short-lived JWTs.
- Simple alternative: POST /v1/agents/register-key { "name" } returns an API
  key once; send it as Authorization: Bearer <key>.

## Machine-readable spec

GET /openapi.json — OpenAPI 3.1 for this service; every operation has an
operationId. GET /skill — installable agent skill (SKILL.md) teaching this
full workflow.

## Errors

All errors are JSON: { "error": { "code", "message" } }. Messages include
remedies (e.g. valid provider ids on a 404).
