{"openapi":"3.1.0","info":{"title":"RightRank API","version":"v1","description":"Aggregated AI model benchmarks, normalized scores, pricing, and task recommendations. Read-only JSON, no authentication. Any origin may call it (CORS Access-Control-Allow-Origin: *). Each IP may make 300 requests per minute across the API (RateLimit-Policy: 300;w=60); beyond that it gets 429 with an Error body and a Retry-After header in seconds. Full field semantics: https://rightrank.com/llms.txt"},"servers":[{"url":"https://rightrank.com"}],"paths":{"/api/v1":{"get":{"operationId":"getApiIndex","summary":"API discovery document with the dimension vocabulary","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Index"}}}}}}},"/api/v1/openapi":{"get":{"operationId":"getOpenApiSpec","summary":"This OpenAPI spec (request it as /api/v1/openapi.json)","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/models":{"get":{"operationId":"listModels","summary":"List canonical models with pricing, variants, and dimension coverage","description":"Historical and non-destructive catalog. Pagination metadata is in the X-Total-Count, X-Page, and X-Per-Page headers.","parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PerPage"},{"name":"q","in":"query","description":"Search words; each must appear in the name, slug, or a source model ID, for example opus 4.5","schema":{"type":"string"}},{"name":"provider_model_id","in":"query","description":"Exact model ID returned by a provider API, for example claude-haiku-4-5-20251001","schema":{"type":"string"}},{"name":"scored","in":"query","description":"Any value requires at least one benchmark score","schema":{"type":"string"}},{"name":"benchmark","in":"query","description":"Benchmark slug; ranks by that benchmark and adds score to each item","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","headers":{"X-Total-Count":{"schema":{"type":"integer"}},"X-Page":{"schema":{"type":"integer"}},"X-Per-Page":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ModelSummary"}}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/models/{slug}":{"get":{"operationId":"getModel","summary":"Model metadata, pricing, lifecycle, benchmark scores by dimension, and provider-reported scores","parameters":[{"$ref":"#/components/parameters/Slug"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Model"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/benchmarks":{"get":{"operationId":"listBenchmarks","summary":"List benchmark definitions","parameters":[{"name":"category","in":"query","description":"Dimension name","schema":{"$ref":"#/components/schemas/Dimension"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Benchmark"}}}}}}}},"/api/v1/benchmarks/{slug}":{"get":{"operationId":"getBenchmark","summary":"Benchmark metadata with its score count and recorded range","parameters":[{"$ref":"#/components/parameters/Slug"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BenchmarkDetail"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/benchmarks/{slug}/leaderboard":{"get":{"operationId":"getBenchmarkLeaderboard","summary":"Alias of /api/v1/rankings/{slug}; rank models by one benchmark","parameters":[{"$ref":"#/components/parameters/Slug"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"Benchmark rankings, or dimension rankings with cost and value (default limit 50)","content":{"application/json":{"schema":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/BenchmarkRanking"}},{"type":"array","items":{"$ref":"#/components/schemas/DimensionRanking"}}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/providers":{"get":{"operationId":"listProviders","summary":"List providers with stable slugs and catalog model counts","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Provider"}}}}}}}},"/api/v1/pricing":{"get":{"operationId":"listPricing","summary":"Current pricing of every priced model, with source and captured_at","description":"Pagination metadata is in the X-Total-Count, X-Page, and X-Per-Page headers.","parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PerPage"}],"responses":{"200":{"description":"OK","headers":{"X-Total-Count":{"schema":{"type":"integer"}},"X-Page":{"schema":{"type":"integer"}},"X-Per-Page":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ModelPricing"}}}}}}}},"/api/v1/provider_reports":{"get":{"operationId":"listProviderReports","summary":"List dated provider evaluation reports (annotations; they do not affect rankings)","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ProviderReportSummary"}}}}}}}},"/api/v1/provider_reports/{slug}":{"get":{"operationId":"getProviderReport","summary":"Every captured result from one provider report","parameters":[{"$ref":"#/components/parameters/Slug"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderReport"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/dimensions":{"get":{"operationId":"listDimensions","summary":"Data availability for every published dimension","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/DimensionStatus"}}}}}}}},"/api/v1/rankings":{"get":{"operationId":"listRankings","summary":"Top models for every populated dimension","parameters":[{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"Dimension name to ranked models (default 10 each)","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"array","items":{"$ref":"#/components/schemas/DimensionRanking"}}}}}}}}},"/api/v1/rankings/{slug}":{"get":{"operationId":"getRanking","summary":"Rank models by one benchmark (benchmark slug) or one dimension (hyphenated dimension name, for example long-context)","parameters":[{"$ref":"#/components/parameters/Slug"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"Benchmark rankings, or dimension rankings with cost and value (default limit 50)","content":{"application/json":{"schema":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/BenchmarkRanking"}},{"type":"array","items":{"$ref":"#/components/schemas/DimensionRanking"}}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/recommend":{"get":{"operationId":"recommendModels","summary":"Recommend models for a free-text task; the preferred endpoint for choosing a model","parameters":[{"name":"task","in":"query","required":true,"description":"Free-text task, for example coding or image generation","schema":{"type":"string"}},{"name":"minimize","in":"query","description":"Free text; cost terms (cost, price, cheap) weight performance 80% and affordability 20%","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":10}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Recommendations"}}}},"422":{"description":"task is missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"parameters":{"Slug":{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},"Limit":{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500}},"Page":{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},"PerPage":{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}}},"responses":{"NotFound":{"description":"Unknown resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"Dimension":{"type":"string","enum":["general","coding","reasoning","multimodal","safety","specialized","agentic","language","long-context","speed","text-to-image","image-editing","text-to-video","image-to-video"]},"Dimensions":{"type":"array","items":{"$ref":"#/components/schemas/Dimension"}},"ProviderModelIds":{"type":"array","items":{"type":"string"},"description":"Model IDs to send to the provider API; a variant reports its base model's IDs"},"NullableString":{"type":["string","null"]},"NullableDate":{"type":["string","null"],"format":"date"},"NullableNumber":{"type":["number","null"]},"Coverage":{"type":"object","required":["measured","of","fraction"],"properties":{"measured":{"type":"integer"},"of":{"type":"integer"},"fraction":{"type":"number","minimum":0,"maximum":1}}},"Pricing":{"type":"object","description":"USD per million tokens, per image, or per video second. A price is null when the source does not publish it. Without any price, every price is null and reason says why.","required":["input_per_million_tokens","output_per_million_tokens","cached_input_per_million_tokens","cache_write_per_million_tokens","batch_input_per_million_tokens","batch_output_per_million_tokens","per_image","per_video_second","source","captured_at","withdrawn_on"],"properties":{"input_per_million_tokens":{"$ref":"#/components/schemas/NullableNumber"},"output_per_million_tokens":{"$ref":"#/components/schemas/NullableNumber"},"cached_input_per_million_tokens":{"$ref":"#/components/schemas/NullableNumber"},"cache_write_per_million_tokens":{"$ref":"#/components/schemas/NullableNumber"},"batch_input_per_million_tokens":{"$ref":"#/components/schemas/NullableNumber"},"batch_output_per_million_tokens":{"$ref":"#/components/schemas/NullableNumber"},"per_image":{"$ref":"#/components/schemas/NullableNumber"},"per_video_second":{"$ref":"#/components/schemas/NullableNumber"},"source":{"type":["string","null"],"description":"provider, openrouter, or artificial_analysis"},"captured_at":{"type":["string","null"],"format":"date-time"},"withdrawn_on":{"type":["string","null"],"format":"date","description":"Set when the provider removed the offer; the price is history and is not used for value or affordability"},"sources":{"type":"object","description":"Present only when a media unit comes from another source than source","properties":{"per_image":{"type":"string"},"per_video_second":{"type":"string"}}},"reason":{"type":"string","enum":["subscription_only","conversion_unknown","open_weights_only","no_priced_offer"],"description":"Present only when no price is known"}}},"ModelSummary":{"type":"object","required":["slug","name","provider","provider_model_ids","base_model_slug","variants","release_date","release_date_source","knowledge_cutoff","expiration_date","availability_status","availability_source","availability_checked_at","pricing","benchmarks_scored","provider_reported_score_count","dimensions_available","dimensions_missing","coverage"],"properties":{"slug":{"type":"string"},"name":{"type":"string"},"provider":{"type":"string"},"provider_model_ids":{"$ref":"#/components/schemas/ProviderModelIds"},"base_model_slug":{"type":["string","null"],"description":"Base API model of a variant (a run configuration such as reasoning effort); null for a base model"},"variants":{"type":"array","items":{"type":"string"},"description":"Slugs of this base model's variants"},"release_date":{"$ref":"#/components/schemas/NullableDate"},"release_date_source":{"$ref":"#/components/schemas/NullableString"},"knowledge_cutoff":{"$ref":"#/components/schemas/NullableDate"},"expiration_date":{"$ref":"#/components/schemas/NullableDate"},"availability_status":{"type":"string","enum":["unknown","active","deprecated","retiring","withdrawn"]},"availability_source":{"$ref":"#/components/schemas/NullableString"},"availability_checked_at":{"type":["string","null"],"format":"date-time"},"pricing":{"$ref":"#/components/schemas/Pricing"},"benchmarks_scored":{"type":"integer"},"provider_reported_score_count":{"type":"integer"},"dimensions_available":{"$ref":"#/components/schemas/Dimensions"},"dimensions_missing":{"$ref":"#/components/schemas/Dimensions"},"coverage":{"$ref":"#/components/schemas/Coverage"},"score":{"type":"number","description":"Present only with ?benchmark=: the model's raw score on that benchmark"}}},"Model":{"type":"object","required":["slug","name","provider","provider_model_ids","base_model_slug","variants","release_date","release_date_source","knowledge_cutoff","expiration_date","availability_status","availability_source","availability_checked_at","pricing","benchmarks_scored","provider_reported_score_count","dimensions_available","dimensions_missing","coverage","context_window","modality","description","provider_reported_scores","dimensions"],"properties":{"slug":{"type":"string"},"name":{"type":"string"},"provider":{"type":"string"},"provider_model_ids":{"$ref":"#/components/schemas/ProviderModelIds"},"base_model_slug":{"type":["string","null"],"description":"Base API model of a variant (a run configuration such as reasoning effort); null for a base model"},"variants":{"type":"array","items":{"type":"string"},"description":"Slugs of this base model's variants"},"release_date":{"$ref":"#/components/schemas/NullableDate"},"release_date_source":{"$ref":"#/components/schemas/NullableString"},"knowledge_cutoff":{"$ref":"#/components/schemas/NullableDate"},"expiration_date":{"$ref":"#/components/schemas/NullableDate"},"availability_status":{"type":"string","enum":["unknown","active","deprecated","retiring","withdrawn"]},"availability_source":{"$ref":"#/components/schemas/NullableString"},"availability_checked_at":{"type":["string","null"],"format":"date-time"},"pricing":{"$ref":"#/components/schemas/Pricing"},"benchmarks_scored":{"type":"integer"},"provider_reported_score_count":{"type":"integer"},"dimensions_available":{"$ref":"#/components/schemas/Dimensions"},"dimensions_missing":{"$ref":"#/components/schemas/Dimensions"},"coverage":{"$ref":"#/components/schemas/Coverage"},"context_window":{"type":["integer","null"]},"modality":{"$ref":"#/components/schemas/NullableString"},"description":{"$ref":"#/components/schemas/NullableString"},"provider_reported_scores":{"type":"array","items":{"type":"object","required":["report","report_title","publisher","source_url","published_at","benchmark","category","value","unit","higher_is_better","configuration","internal","notes"],"properties":{"report":{"type":"string"},"report_title":{"type":"string"},"publisher":{"type":"string"},"source_url":{"type":"string"},"published_at":{"type":"string","format":"date"},"benchmark":{"type":"string"},"category":{"type":"string"},"value":{"type":"number"},"unit":{"type":"string"},"higher_is_better":{"type":"boolean"},"configuration":{"$ref":"#/components/schemas/NullableString"},"internal":{"type":"boolean"},"notes":{"$ref":"#/components/schemas/NullableString"}}}},"dimensions":{"type":"object","description":"Dimension name (or uncategorized) to benchmark scores","additionalProperties":{"type":"array","items":{"$ref":"#/components/schemas/Score"}}}}},"Score":{"type":"object","required":["benchmark","name","value","normalized_value","scoring_method","higher_is_better","source","scored_at","metadata"],"properties":{"benchmark":{"type":"string"},"name":{"type":"string"},"value":{"type":"number","description":"Raw benchmark-native value; do not compare across benchmarks"},"normalized_value":{"type":"number","description":"Direction-adjusted 0-100 value relative to the benchmark's current recorded range (log scale for speed)"},"scoring_method":{"$ref":"#/components/schemas/NullableString"},"higher_is_better":{"type":["boolean","null"]},"source":{"type":["string","null"],"description":"Speed scores: artificial_analysis or rightrank_probe"},"scored_at":{"type":["string","null"],"format":"date-time"},"metadata":{"type":["object","null"],"description":"Source detail. rightrank_probe has p90 (slow tail), runs, samples, outcomes, max_tokens, history, region, route; Artificial Analysis media scores have rank, ci95, appearances","additionalProperties":true,"properties":{"samples":{"type":"array","items":{"type":"number"},"description":"rightrank_probe: each run's value in the latest probe"},"outcomes":{"type":"object","additionalProperties":{"type":"integer"},"description":"rightrank_probe: run counts by outcome (ok, truncated, no_answer_within_budget, no_answer) in the latest probe"},"max_tokens":{"type":"integer","description":"rightrank_probe: the scenario's requested max_tokens, reasoning included"},"history":{"type":"array","description":"rightrank_probe: the last 12 probes, oldest first","items":{"type":"object","required":["at","median","p90"],"properties":{"at":{"type":"string","format":"date-time"},"median":{"type":"number"},"p90":{"type":"number"}}}}}}}},"Benchmark":{"type":"object","required":["slug","name","category","higher_is_better","models_scored"],"properties":{"slug":{"type":"string"},"name":{"type":"string"},"category":{"$ref":"#/components/schemas/NullableString"},"higher_is_better":{"type":["boolean","null"]},"models_scored":{"type":"integer"}}},"BenchmarkDetail":{"type":"object","required":["slug","name","category","higher_is_better","models_scored","description","scoring_method","source","url","minimum","maximum","last_scored_at"],"properties":{"slug":{"type":"string"},"name":{"type":"string"},"category":{"$ref":"#/components/schemas/NullableString"},"higher_is_better":{"type":["boolean","null"]},"models_scored":{"type":"integer"},"description":{"$ref":"#/components/schemas/NullableString"},"scoring_method":{"$ref":"#/components/schemas/NullableString"},"source":{"$ref":"#/components/schemas/NullableString"},"url":{"$ref":"#/components/schemas/NullableString"},"minimum":{"type":["number","null"],"description":"Lowest recorded raw value"},"maximum":{"type":["number","null"],"description":"Highest recorded raw value"},"last_scored_at":{"type":["string","null"],"format":"date-time"}}},"Provider":{"type":"object","required":["slug","name","url","models"],"properties":{"slug":{"type":"string","description":"Stable provider identifier"},"name":{"type":"string","description":"The provider value on model","ranking":null,"and recommendation items":null},"url":{"$ref":"#/components/schemas/NullableString"},"models":{"type":"integer","description":"Catalog models from this provider"}}},"ProviderReportSummary":{"type":"object","required":["slug","title","publisher","source_url","published_at","score_count"],"properties":{"slug":{"type":"string"},"title":{"type":"string"},"publisher":{"type":"string"},"source_url":{"type":"string"},"published_at":{"type":"string","format":"date"},"score_count":{"type":"integer"}}},"ProviderReport":{"type":"object","required":["slug","title","publisher","source_url","published_at","scores"],"properties":{"slug":{"type":"string"},"title":{"type":"string"},"publisher":{"type":"string"},"source_url":{"type":"string"},"published_at":{"type":"string","format":"date"},"scores":{"type":"array","items":{"type":"object","required":["model","model_name","provider","benchmark","category","value","unit","higher_is_better","configuration","internal","notes"],"properties":{"benchmark":{"type":"string"},"category":{"type":"string"},"value":{"type":"number"},"unit":{"type":"string"},"higher_is_better":{"type":"boolean"},"configuration":{"$ref":"#/components/schemas/NullableString"},"internal":{"type":"boolean"},"notes":{"$ref":"#/components/schemas/NullableString"},"model":{"type":"string","description":"Model slug"},"model_name":{"type":"string"},"provider":{"type":"string"}}}}}},"DimensionStatus":{"type":"object","required":["name","benchmarks","benchmarks_with_results","models_scored","populated"],"properties":{"name":{"$ref":"#/components/schemas/Dimension"},"benchmarks":{"type":"integer"},"benchmarks_with_results":{"type":"integer"},"models_scored":{"type":"integer"},"populated":{"type":"boolean","description":"false means no model has a result, not that models scored poorly"}}},"BenchmarkRanking":{"type":"object","required":["rank","model","model_slug","provider","provider_model_ids","variant_of","score","pricing"],"properties":{"rank":{"type":"integer"},"model":{"type":"string","description":"Model name"},"model_slug":{"type":"string"},"provider":{"type":"string"},"provider_model_ids":{"$ref":"#/components/schemas/ProviderModelIds"},"variant_of":{"type":["string","null"],"description":"Base model slug of a variant; null for a base model"},"pricing":{"$ref":"#/components/schemas/Pricing"},"score":{"type":"number","description":"Raw benchmark-native value"}}},"DimensionRanking":{"type":"object","required":["model","model_slug","provider","provider_model_ids","variant_of","avg_score","scores","pricing","cost","cost_unit","value"],"properties":{"model":{"type":"string","description":"Model name"},"model_slug":{"type":"string"},"provider":{"type":"string"},"provider_model_ids":{"$ref":"#/components/schemas/ProviderModelIds"},"variant_of":{"type":["string","null"],"description":"Base model slug of a variant; null for a base model"},"pricing":{"$ref":"#/components/schemas/Pricing"},"avg_score":{"type":"number","description":"Mean normalized 0-100 score across the dimension's benchmarks"},"scores":{"type":"object","description":"Benchmark slug to raw and normalized value","additionalProperties":{"type":"object","required":["raw","normalized"],"properties":{"raw":{"type":"number"},"normalized":{"type":"number"}}}},"cost":{"type":["number","null"],"description":"USD in cost_unit (input plus output for million_tokens)"},"cost_unit":{"type":"string","enum":["million_tokens","image","video_second"]},"value":{"type":["number","null"],"description":"avg_score per unit of cost; null without a current price"}}},"ModelPricing":{"type":"object","required":["model","model_slug","provider","provider_model_ids","variant_of","pricing"],"properties":{"model":{"type":"string","description":"Model name"},"model_slug":{"type":"string"},"provider":{"type":"string"},"provider_model_ids":{"$ref":"#/components/schemas/ProviderModelIds"},"variant_of":{"type":["string","null"],"description":"Base model slug of a variant; null for a base model"},"pricing":{"$ref":"#/components/schemas/Pricing"}}},"Recommendations":{"type":"object","required":["categories","minimize","measurement_status","dimensions_available","unmeasured_categories","recommendations"],"properties":{"categories":{"type":"object","description":"Requested dimension to weight","additionalProperties":{"type":"integer"}},"minimize":{"$ref":"#/components/schemas/NullableString"},"measurement_status":{"type":"string","enum":["complete","partial","unavailable"]},"dimensions_available":{"$ref":"#/components/schemas/Dimensions"},"unmeasured_categories":{"$ref":"#/components/schemas/Dimensions"},"message":{"type":"string","description":"Present only when measurement_status is unavailable"},"recommendations":{"type":"array","items":{"type":"object","required":["model","model_slug","provider","provider_model_ids","variant_of","recommendation_score","category_scores","category_coverage","dimensions_missing","coverage_fraction","coverage","pricing"],"properties":{"model":{"type":"string","description":"Model name"},"model_slug":{"type":"string"},"provider":{"type":"string"},"provider_model_ids":{"$ref":"#/components/schemas/ProviderModelIds"},"variant_of":{"type":["string","null"],"description":"Base model slug of a variant; null for a base model"},"pricing":{"$ref":"#/components/schemas/Pricing"},"recommendation_score":{"type":"number","description":"0-100 task-fit score; higher is better"},"category_scores":{"type":"object","additionalProperties":{"type":"number"}},"category_coverage":{"$ref":"#/components/schemas/Dimensions"},"dimensions_missing":{"$ref":"#/components/schemas/Dimensions"},"coverage_fraction":{"type":"number","minimum":0,"maximum":1},"coverage":{"$ref":"#/components/schemas/Coverage"}}}}}},"Index":{"type":"object","required":["name","documentation","openapi","dimensions","endpoints","dimension_value","normalized_value","pricing","speed_sources","recommendation_score","measurement_status","cors","rate_limit"],"properties":{"name":{"type":"string"},"documentation":{"type":"string","description":"URL of llms.txt"},"openapi":{"type":"string","description":"URL of this spec"},"dimensions":{"$ref":"#/components/schemas/Dimensions"},"endpoints":{"type":"object","additionalProperties":{"type":"string"}},"dimension_value":{"type":"string"},"normalized_value":{"type":"string"},"pricing":{"type":"string"},"speed_sources":{"type":"string"},"recommendation_score":{"type":"string"},"measurement_status":{"type":"string"},"cors":{"type":"string"},"rate_limit":{"type":"string"}}}}}}