{"openapi":"3.1.0","info":{"title":"Model Demand Agent API","version":"model-demand.agent-api.v1","description":"OpenRouter demand and exact official Hugging Face evidence are separate sources. This read-only API gives public model demand and model facts. It also gives missing-size reasons, availability states, and source limits."},"servers":[{"url":"https://model-demand-analytics.vercel.app"}],"paths":{"/api/v1/models":{"get":{"operationId":"getAgentModels","summary":"Get public model data","description":"List public model records or return one exact model. Do not combine model_id with list query fields.","parameters":[{"name":"model_id","in":"query","required":false,"description":"Return one exact model ID. Do not combine model_id with sort, order, limit, or offset.","schema":{"type":"string","minLength":1,"example":"public/model-example"}},{"name":"sort","in":"query","required":false,"description":"Sort list results by one supported field.","schema":{"type":"string","default":"tokens_30d","enum":["tokens_30d","latest_rank","total_parameters","active_parameters","smallest_quant_checkpoint_bytes","full_sequence_attention_bytes"]}},{"name":"order","in":"query","required":false,"description":"Use ascending or descending list order.","schema":{"type":"string","default":"desc","enum":["asc","desc"]}},{"name":"limit","in":"query","required":false,"description":"Return 1 through 100 models.","schema":{"type":"integer","default":25,"minimum":1,"maximum":100}},{"name":"offset","in":"query","required":false,"description":"Skip zero or more matching models before the returned page.","schema":{"type":"integer","default":0,"minimum":0,"maximum":9007199254740991}}],"x-model-id-incompatible-with":["sort","order","limit","offset"],"responses":{"200":{"description":"A valid public model result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentModelsResponse"}}}},"400":{"description":"The request query is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvalidQueryError"}}}},"404":{"description":"The requested model was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelNotFoundError"}}}},"503":{"description":"Data is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataUnavailableError"}}}}}}},"/api/v1/about":{"get":{"operationId":"getAgentApiAbout","summary":"Get the API contract","description":"Return static field definitions, source limits, availability states, and agent instructions.","responses":{"200":{"description":"The static API contract.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentAboutDocument"}}}}}}}},"components":{"schemas":{"AgentModelsResponse":{"type":"object","additionalProperties":false,"required":["schema_version","generated_at","evaluation_cutoff","freshness","window","source","query","pagination","models"],"properties":{"schema_version":{"type":"string","const":"model-demand.agent-api.v1"},"generated_at":{"type":"string","format":"date-time"},"evaluation_cutoff":{"type":"string","format":"date-time"},"freshness":{"$ref":"#/components/schemas/Freshness"},"window":{"$ref":"#/components/schemas/Window"},"source":{"$ref":"#/components/schemas/Source"},"query":{"$ref":"#/components/schemas/NormalizedQuery"},"pagination":{"$ref":"#/components/schemas/Pagination"},"models":{"type":"array","items":{"$ref":"#/components/schemas/AgentModel"}}}},"Freshness":{"type":"object","additionalProperties":false,"required":["state","fresh_until","reason"],"properties":{"state":{"type":"string","enum":["fresh","stale"]},"fresh_until":{"type":["string","null"],"format":"date-time"},"reason":{"type":"string","minLength":1}}},"Window":{"type":"object","additionalProperties":false,"required":["start_date","end_date","days"],"properties":{"start_date":{"type":"string","format":"date"},"end_date":{"type":"string","format":"date"},"days":{"type":"integer","const":30}}},"Source":{"type":"object","additionalProperties":false,"required":["name","url","terms_url","checked_at","license","attribution"],"properties":{"name":{"type":"string","const":"OpenRouter"},"url":{"type":"string","format":"uri"},"terms_url":{"type":"string","format":"uri"},"checked_at":{"type":"string","format":"date-time"},"license":{"type":"string","const":"CC BY 4.0"},"attribution":{"type":"string","minLength":1}}},"NormalizedQuery":{"type":"object","additionalProperties":false,"required":["mode","model_id","sort","order","limit","offset"],"properties":{"mode":{"type":"string","enum":["list","exact_model"]},"model_id":{"type":["string","null"]},"sort":{"type":["string","null"],"enum":["tokens_30d","latest_rank","total_parameters","active_parameters","smallest_quant_checkpoint_bytes","full_sequence_attention_bytes",null]},"order":{"type":["string","null"],"enum":["asc","desc",null]},"limit":{"type":"integer","minimum":1,"maximum":100},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991}},"oneOf":[{"type":"object","additionalProperties":false,"required":["mode","model_id","sort","order","limit","offset"],"properties":{"mode":{"type":"string","const":"list"},"model_id":{"type":"null"},"sort":{"type":"string","enum":["tokens_30d","latest_rank","total_parameters","active_parameters","smallest_quant_checkpoint_bytes","full_sequence_attention_bytes"]},"order":{"type":"string","enum":["asc","desc"]},"limit":{"type":"integer","minimum":1,"maximum":100},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991}}},{"type":"object","additionalProperties":false,"required":["mode","model_id","sort","order","limit","offset"],"properties":{"mode":{"type":"string","const":"exact_model"},"model_id":{"type":"string","minLength":1},"sort":{"type":"null"},"order":{"type":"null"},"limit":{"type":"integer","const":1},"offset":{"type":"integer","const":0}}}]},"Pagination":{"type":"object","additionalProperties":false,"required":["total_matching_models","offset","limit","returned_count","has_next_page"],"properties":{"total_matching_models":{"type":"integer","minimum":0},"offset":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":1,"maximum":100},"returned_count":{"type":"integer","minimum":0,"maximum":100},"has_next_page":{"type":"boolean"}}},"AgentModel":{"type":"object","additionalProperties":false,"required":["model_id","model_release_id","first_visible_date","latest_rank","latest_tokens","tokens_7d","tokens_30d","share_7d","share_30d","share_prior_7d","trend","facts","supply"],"properties":{"model_id":{"type":"string","minLength":1},"model_release_id":{"type":"string","minLength":1},"first_visible_date":{"type":"string","format":"date"},"latest_rank":{"$ref":"#/components/schemas/Rank"},"latest_tokens":{"$ref":"#/components/schemas/TokenQuantity"},"tokens_7d":{"$ref":"#/components/schemas/TokenQuantity"},"tokens_30d":{"$ref":"#/components/schemas/TokenQuantity"},"share_7d":{"$ref":"#/components/schemas/FractionQuantity"},"share_30d":{"$ref":"#/components/schemas/FractionQuantity"},"share_prior_7d":{"$ref":"#/components/schemas/FractionQuantity"},"trend":{"$ref":"#/components/schemas/Trend"},"facts":{"$ref":"#/components/schemas/Facts"},"supply":{"$ref":"#/components/schemas/Supply"}}},"Rank":{"type":"object","additionalProperties":false,"required":["value","state","reason"],"properties":{"value":{"type":["integer","null"],"minimum":1},"state":{"type":"string","enum":["available","unavailable"]},"reason":{"type":["string","null"]}}},"TokenQuantity":{"type":"object","additionalProperties":false,"required":["value","unit","state","reason"],"properties":{"value":{"type":["string","null"]},"unit":{"type":"string","const":"tokens"},"state":{"type":"string","enum":["available","unavailable"]},"reason":{"type":["string","null"]}}},"FractionQuantity":{"type":"object","additionalProperties":false,"required":["value","unit","state","reason"],"properties":{"value":{"type":["string","null"]},"unit":{"type":"string","const":"fraction"},"state":{"type":"string","enum":["available","unavailable"]},"reason":{"type":["string","null"]}}},"Trend":{"type":"object","additionalProperties":false,"required":["direction","state","reason","relative_change","percentage_point_change"],"properties":{"direction":{"type":"string","enum":["rising","falling","flat","insufficient_history"]},"state":{"type":"string","enum":["available","unavailable"]},"reason":{"type":["string","null"]},"relative_change":{"type":["string","null"]},"percentage_point_change":{"type":["string","null"]}}},"Facts":{"type":"object","additionalProperties":false,"required":["total_parameters","active_parameters","architecture_type","base_checkpoint_bytes","bf16_weights_bytes","smallest_quant_checkpoint_bytes","smallest_quant_format","smallest_quant_bit_width","attention_bytes_per_token","full_sequence_attention_bytes","recurrent_state_bytes","calculation_sequence_length"],"properties":{"total_parameters":{"allOf":[{"$ref":"#/components/schemas/Fact"},{"properties":{"unit":{"const":"parameters"}}}]},"active_parameters":{"allOf":[{"$ref":"#/components/schemas/Fact"},{"properties":{"unit":{"const":"parameters"}}}]},"architecture_type":{"allOf":[{"$ref":"#/components/schemas/Fact"},{"properties":{"unit":{"const":"architecture"}}}]},"base_checkpoint_bytes":{"allOf":[{"$ref":"#/components/schemas/Fact"},{"properties":{"unit":{"const":"bytes"}}}]},"bf16_weights_bytes":{"$ref":"#/components/schemas/Bf16Fact"},"smallest_quant_checkpoint_bytes":{"allOf":[{"$ref":"#/components/schemas/Fact"},{"properties":{"unit":{"const":"bytes"}}}]},"smallest_quant_format":{"allOf":[{"$ref":"#/components/schemas/Fact"},{"properties":{"unit":{"const":"format"}}}]},"smallest_quant_bit_width":{"allOf":[{"$ref":"#/components/schemas/Fact"},{"properties":{"unit":{"const":"bits"}}}]},"attention_bytes_per_token":{"allOf":[{"$ref":"#/components/schemas/Fact"},{"properties":{"unit":{"const":"bytes_per_token"}}}]},"full_sequence_attention_bytes":{"allOf":[{"$ref":"#/components/schemas/Fact"},{"properties":{"unit":{"const":"bytes"}}}]},"recurrent_state_bytes":{"allOf":[{"$ref":"#/components/schemas/Fact"},{"properties":{"unit":{"const":"bytes"}}}]},"calculation_sequence_length":{"allOf":[{"$ref":"#/components/schemas/Fact"},{"properties":{"unit":{"const":"tokens"}}}]}}},"Fact":{"type":"object","additionalProperties":false,"required":["value","unit","state","reason","source_url"],"properties":{"value":{"type":["string","null"]},"unit":{"type":"string","enum":["parameters","architecture","bytes","format","bits","bytes_per_token","tokens"]},"state":{"type":"string","enum":["available","not_publicly_cleared","not_available","not_found_under_policy"]},"reason":{"type":["string","null"]},"source_url":{"type":["string","null"],"format":"uri"}}},"Bf16Fact":{"type":"object","additionalProperties":false,"required":["value","unit","state","reason","source_url"],"properties":{"value":{"type":["string","null"]},"unit":{"type":"string","const":"bytes"},"state":{"type":"string","enum":["available","not_publicly_cleared","not_available"]},"reason":{"type":["string","null"],"description":"The four automatic-discovery missing-size reasons are: closed_weights: A checked official source says that the release has no public weights. weights_access_unknown: No exact public checkpoint link exists. No checked source says that the weights are closed. open_checkpoint_unavailable: An exact checkpoint claim exists. The collector cannot collect the repository. size_calculation_failed: The collector collected the checkpoint. The checked facts do not support one size. Legacy public BF16 reasons can also occur.","enum":[null,"public_source_missing","public_source_unsafe","public_evidence_not_checked","closed_weights","weights_access_unknown","open_checkpoint_unavailable","value_not_available","size_calculation_failed"]},"source_url":{"type":["string","null"],"format":"uri","pattern":"^[Hh][Tt][Tt][Pp][Ss]://(?:[Ww][Ww][Ww]\\.)?[Hh][Uu][Gg][Gg][Ii][Nn][Gg][Ff][Aa][Cc][Ee]\\.[Cc][Oo](?::443)?/[A-Za-z0-9][A-Za-z0-9._-]*/[A-Za-z0-9][A-Za-z0-9._-]*/tree/(?:[0-9a-f]{40}|[0-9a-f]{64})$"}},"oneOf":[{"type":"object","additionalProperties":false,"required":["value","unit","state","reason","source_url"],"properties":{"value":{"type":"string"},"unit":{"type":"string","const":"bytes"},"state":{"type":"string","const":"available"},"reason":{"type":"null"},"source_url":{"type":"string","format":"uri","pattern":"^[Hh][Tt][Tt][Pp][Ss]://(?:[Ww][Ww][Ww]\\.)?[Hh][Uu][Gg][Gg][Ii][Nn][Gg][Ff][Aa][Cc][Ee]\\.[Cc][Oo](?::443)?/[A-Za-z0-9][A-Za-z0-9._-]*/[A-Za-z0-9][A-Za-z0-9._-]*/tree/(?:[0-9a-f]{40}|[0-9a-f]{64})$"}}},{"type":"object","additionalProperties":false,"required":["value","unit","state","reason","source_url"],"properties":{"value":{"type":"null"},"unit":{"type":"string","const":"bytes"},"state":{"type":"string","const":"not_publicly_cleared"},"reason":{"type":"string","enum":["public_source_missing","public_source_unsafe","public_evidence_not_checked","closed_weights","weights_access_unknown","open_checkpoint_unavailable"]},"source_url":{"type":"null"}}},{"type":"object","additionalProperties":false,"required":["value","unit","state","reason","source_url"],"properties":{"value":{"type":"null"},"unit":{"type":"string","const":"bytes"},"state":{"type":"string","const":"not_available"},"reason":{"type":"string","enum":["value_not_available","size_calculation_failed"]},"source_url":{"type":"string","format":"uri","pattern":"^[Hh][Tt][Tt][Pp][Ss]://(?:[Ww][Ww][Ww]\\.)?[Hh][Uu][Gg][Gg][Ii][Nn][Gg][Ff][Aa][Cc][Ee]\\.[Cc][Oo](?::443)?/[A-Za-z0-9][A-Za-z0-9._-]*/[A-Za-z0-9][A-Za-z0-9._-]*/tree/(?:[0-9a-f]{40}|[0-9a-f]{64})$"}}}]},"Supply":{"type":"object","additionalProperties":false,"required":["state","reason","summary"],"properties":{"state":{"type":"string","enum":["not_collected","temporarily_unavailable","current_route_not_found","current_route_ambiguous","available"]},"reason":{"type":["string","null"]},"summary":{"oneOf":[{"$ref":"#/components/schemas/SupplySummary"},{"type":"null"}]}},"oneOf":[{"type":"object","additionalProperties":false,"required":["state","reason","summary"],"properties":{"state":{"type":"string","const":"available"},"reason":{"type":"null"},"summary":{"$ref":"#/components/schemas/SupplySummary"}}},{"type":"object","additionalProperties":false,"required":["state","reason","summary"],"properties":{"state":{"type":"string","enum":["not_collected","temporarily_unavailable","current_route_not_found","current_route_ambiguous"]},"reason":{"type":"string","minLength":1},"summary":{"type":"null"}}}]},"SupplySummary":{"type":"object","additionalProperties":false,"required":["route_id","route_type","collection_finished_at","history_ready","listed_endpoints","listed_providers","median_input_price_per_million","median_output_price_per_million","median_latency_ms","median_throughput_tokens_per_second","median_uptime_percent","maximum_context_tokens","quantizations"],"properties":{"route_id":{"type":"string","minLength":1},"route_type":{"type":"string","enum":["paid","free","batch","thinking"]},"collection_finished_at":{"type":"string","format":"date-time"},"history_ready":{"type":"boolean"},"listed_endpoints":{"$ref":"#/components/schemas/EndpointCountMetric"},"listed_providers":{"$ref":"#/components/schemas/ProviderCountMetric"},"median_input_price_per_million":{"$ref":"#/components/schemas/PriceMetric"},"median_output_price_per_million":{"$ref":"#/components/schemas/PriceMetric"},"median_latency_ms":{"$ref":"#/components/schemas/LatencyMetric"},"median_throughput_tokens_per_second":{"$ref":"#/components/schemas/ThroughputMetric"},"median_uptime_percent":{"$ref":"#/components/schemas/UptimeMetric"},"maximum_context_tokens":{"$ref":"#/components/schemas/ContextCountMetric"},"quantizations":{"type":"array","items":{"type":"string","minLength":1},"uniqueItems":true}}},"CountMetric":{"type":"object","additionalProperties":false,"required":["value","unit","state","reason"],"properties":{"value":{"type":["integer","null"],"minimum":0},"unit":{"type":"string","const":"tokens"},"state":{"type":"string","enum":["available","unavailable"]},"reason":{"type":["string","null"]}}},"DecimalMetric":{"type":"object","additionalProperties":false,"required":["value","unit","state","reason"],"properties":{"value":{"type":["string","null"]},"unit":{"type":"string","const":"usd_per_million_tokens"},"state":{"type":"string","enum":["available","unavailable"]},"reason":{"type":["string","null"]}}},"EndpointCountMetric":{"type":"object","additionalProperties":false,"required":["value","unit","state","reason"],"properties":{"value":{"type":["integer","null"],"minimum":0},"unit":{"type":"string","const":"endpoints"},"state":{"type":"string","enum":["available","unavailable"]},"reason":{"type":["string","null"]}}},"ProviderCountMetric":{"type":"object","additionalProperties":false,"required":["value","unit","state","reason"],"properties":{"value":{"type":["integer","null"],"minimum":0},"unit":{"type":"string","const":"providers"},"state":{"type":"string","enum":["available","unavailable"]},"reason":{"type":["string","null"]}}},"ContextCountMetric":{"type":"object","additionalProperties":false,"required":["value","unit","state","reason"],"properties":{"value":{"type":["integer","null"],"minimum":0},"unit":{"type":"string","const":"tokens"},"state":{"type":"string","enum":["available","unavailable"]},"reason":{"type":["string","null"]}}},"PriceMetric":{"type":"object","additionalProperties":false,"required":["value","unit","state","reason"],"properties":{"value":{"type":["string","null"]},"unit":{"type":"string","const":"usd_per_million_tokens"},"state":{"type":"string","enum":["available","unavailable"]},"reason":{"type":["string","null"]}}},"LatencyMetric":{"type":"object","additionalProperties":false,"required":["value","unit","state","reason"],"properties":{"value":{"type":["string","null"]},"unit":{"type":"string","const":"milliseconds"},"state":{"type":"string","enum":["available","unavailable"]},"reason":{"type":["string","null"]}}},"ThroughputMetric":{"type":"object","additionalProperties":false,"required":["value","unit","state","reason"],"properties":{"value":{"type":["string","null"]},"unit":{"type":"string","const":"tokens_per_second"},"state":{"type":"string","enum":["available","unavailable"]},"reason":{"type":["string","null"]}}},"UptimeMetric":{"type":"object","additionalProperties":false,"required":["value","unit","state","reason"],"properties":{"value":{"type":["string","null"]},"unit":{"type":"string","const":"percent"},"state":{"type":"string","enum":["available","unavailable"]},"reason":{"type":["string","null"]}}},"AgentAboutDocument":{"type":"object","additionalProperties":false,"required":["schema_version","api_schema_version","documentation_version","routes","query_parameters","field_definitions","availability_states","sources","supply","links","agent_instructions"],"properties":{"schema_version":{"type":"string","const":"model-demand.agent-about.v1"},"api_schema_version":{"type":"string","const":"model-demand.agent-api.v1"},"documentation_version":{"type":"string","minLength":1},"routes":{"type":"array","items":{"$ref":"#/components/schemas/AboutRoute"}},"query_parameters":{"type":"array","items":{"$ref":"#/components/schemas/AboutQueryParameter"}},"field_definitions":{"type":"array","items":{"$ref":"#/components/schemas/AboutFieldDefinition"}},"availability_states":{"type":"array","items":{"$ref":"#/components/schemas/AboutAvailabilityState"}},"sources":{"type":"array","items":{"$ref":"#/components/schemas/AboutSource"}},"supply":{"$ref":"#/components/schemas/AboutSupply"},"links":{"$ref":"#/components/schemas/AboutLinks"},"agent_instructions":{"type":"array","minItems":1,"items":{"type":"string","minLength":1}}}},"AboutRoute":{"type":"object","additionalProperties":false,"required":["method","path","description"],"properties":{"method":{"type":"string","const":"GET"},"path":{"type":"string","enum":["/api/v1/about","/api/v1/models"]},"description":{"type":"string","minLength":1}}},"AboutQueryParameter":{"type":"object","additionalProperties":false,"required":["name","type","required","default","allowed_values","description"],"properties":{"name":{"type":"string","enum":["model_id","sort","order","limit","offset"]},"type":{"type":"string","enum":["string","integer"]},"required":{"type":"boolean"},"default":{"type":["string","integer","null"]},"allowed_values":{"oneOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"description":{"type":"string","minLength":1}}},"AboutFieldDefinition":{"type":"object","additionalProperties":false,"required":["path","type","unit","nullable","description"],"properties":{"path":{"type":"string","minLength":1},"type":{"type":"string","enum":["string","integer","boolean","object","array"]},"unit":{"type":["string","null"]},"nullable":{"type":"boolean"},"description":{"type":"string","minLength":1}}},"AboutAvailabilityState":{"type":"object","additionalProperties":false,"required":["state","meaning"],"properties":{"state":{"type":"string","enum":["available","unavailable","not_publicly_cleared","not_available","not_found_under_policy"]},"meaning":{"type":"string","minLength":1}}},"AboutSource":{"type":"object","additionalProperties":false,"required":["name","url","terms_url","license","limit_note"],"properties":{"name":{"type":"string","minLength":1},"url":{"type":"string","format":"uri"},"terms_url":{"type":"string","format":"uri"},"license":{"type":["string","null"]},"limit_note":{"type":"string","minLength":1}}},"AboutSupply":{"type":"object","additionalProperties":false,"required":["launch_state","states","description"],"properties":{"launch_state":{"type":"string","enum":["not_collected","enabled"]},"states":{"type":"array","minItems":5,"maxItems":5,"items":{"type":"string","enum":["not_collected","temporarily_unavailable","current_route_not_found","current_route_ambiguous","available"]}},"description":{"type":"string","minLength":1}}},"AboutLinks":{"type":"object","additionalProperties":false,"required":["documentation","openapi","full_export"],"properties":{"documentation":{"type":"string","format":"uri"},"openapi":{"type":"string","format":"uri"},"full_export":{"type":"string","format":"uri"}}},"InvalidQueryError":{"type":"object","additionalProperties":false,"required":["schema_version","error","message"],"properties":{"schema_version":{"type":"string","const":"model-demand.agent-api-error.v1"},"error":{"type":"string","const":"invalid_query"},"message":{"type":"string","const":"The request query is invalid."}}},"ModelNotFoundError":{"type":"object","additionalProperties":false,"required":["schema_version","error","message"],"properties":{"schema_version":{"type":"string","const":"model-demand.agent-api-error.v1"},"error":{"type":"string","const":"model_not_found"},"message":{"type":"string","const":"The requested model was not found."}}},"DataUnavailableError":{"type":"object","additionalProperties":false,"required":["schema_version","error","message"],"properties":{"schema_version":{"type":"string","const":"model-demand.agent-api-error.v1"},"error":{"type":"string","const":"data_unavailable"},"message":{"type":"string","const":"Data is unavailable."}}}}}}