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
activityon each row andschemaEndpointIdpointing at the shared generation route (v1/images/generations,images/generations, …).pricingis 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.currencyis ISO 4217 (mostly USD; nothing is converted, so compare only like with like);?pricing=1returns the full card./v1/statuscounts livepricedmodels per provider and scorescompleteness(the share of chat facts filled;scoreis null with no chat models). A provider there carriesdocsFailing,priceClearsRefused, orupdateStormwhile 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 requestmodelfield 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)
- GET /v1 — endpoint index.
- GET /v1/models?activity=chat — cross-provider catalog of chat models.
- GET /v1/schemas — system-wide index: every provider's activities and endpoint ids in one response (all schemas on the system).
- GET /v1/schemas/anthropic — activities + endpoint ids for one provider.
- 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. - 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).
- POST /v1/validate {"provider","endpointId","payload"} — check a payload.
- 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.
- GET /v1/changes?since= — 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 .
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).