{"openapi":"3.1.0","info":{"title":"AI Model Rankings API","version":"1.4.0","description":"Workspace-scoped, source-cited rankings, item facts, comparisons, metric discovery, dataset planning, and review-gated source imports."},"servers":[{"url":"https://www.optisift.com"}],"externalDocs":{"description":"Workspace-aware agent guide","url":"https://www.optisift.com/llms.txt?workspace=ai-models"},"x-apex-workspace":{"slug":"ai-models","name":"AI Model Rankings","vertical":"ai-models","resolution":"deployment"},"x-mcp":{"endpoint":"https://www.optisift.com/api/mcp?workspace=ai-models","transport":"streamable-http","tools":["rank","compare","explain","decide","sources","plan_dataset","preview_source","import_source","columns","saved_comparisons","watch_findings","ingest"],"clientConfig":{"url":"https://www.optisift.com/api/mcp","headers":{"Authorization":"Bearer apex_<your-key>"}},"auth":"Authorization: Bearer apex_<your-key>","rateLimit":"300 requests/hour per API key"},"components":{"securitySchemes":{"ApexApiKey":{"type":"http","scheme":"bearer","bearerFormat":"apex_<key>"}},"schemas":{"Constraint":{"type":"object","required":["metric"],"properties":{"metric":{"type":"string"},"min":{"type":"number"},"max":{"type":"number"},"equals":{"oneOf":[{"type":"number"},{"type":"boolean"}]}},"anyOf":[{"required":["min"]},{"required":["max"]},{"required":["equals"]}]}}},"paths":{"/api/v1":{"get":{"summary":"Discover the workspace API and MCP surface","parameters":[{"name":"workspace","in":"query","required":false,"description":"OptiSift workspace slug. May also be supplied as the x-apex-workspace header.","schema":{"type":"string"}},{"name":"x-apex-workspace","in":"header","required":false,"description":"Alternative workspace selector.","schema":{"type":"string"}}],"responses":{"200":{"description":"Machine-readable API index","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/v1/health":{"get":{"summary":"Check workspace readiness","parameters":[{"name":"workspace","in":"query","required":false,"description":"OptiSift workspace slug. May also be supplied as the x-apex-workspace header.","schema":{"type":"string"}},{"name":"x-apex-workspace","in":"header","required":false,"description":"Alternative workspace selector.","schema":{"type":"string"}}],"responses":{"200":{"description":"Workspace is ready"},"503":{"description":"Workspace or database is unavailable"}}}},"/api/v1/metrics":{"get":{"summary":"List workspace metrics and decision operators","parameters":[{"name":"workspace","in":"query","required":false,"description":"OptiSift workspace slug. May also be supplied as the x-apex-workspace header.","schema":{"type":"string"}},{"name":"x-apex-workspace","in":"header","required":false,"description":"Alternative workspace selector.","schema":{"type":"string"}}],"responses":{"200":{"description":"Metric dictionary","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/v1/sources":{"get":{"summary":"Discover free evidence sources, runnable adapters, rights manifests, and connector health","parameters":[{"name":"q","in":"query","description":"Free-text topic, entity, geography, or join-key search.","schema":{"type":"string"}},{"name":"criterion","in":"query","description":"Repeat for criterion-by-criterion source plans.","schema":{"type":"array","items":{"type":"string"}}}],"responses":{"200":{"description":"Source profiles, explainable criterion matches, runnable connector manifests, and latest scheduled verification","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/v1/rankings":{"get":{"summary":"Return ranked published workspace items","security":[{"ApexApiKey":[]}],"parameters":[{"name":"workspace","in":"query","required":false,"description":"OptiSift workspace slug. May also be supplied as the x-apex-workspace header.","schema":{"type":"string"}},{"name":"x-apex-workspace","in":"header","required":false,"description":"Alternative workspace selector.","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"category","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Ranked items"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Key does not belong to workspace"},"429":{"description":"Rate limit exceeded"}}}},"/api/v1/items/{slug}":{"get":{"summary":"Return one published item with evidence","security":[{"ApexApiKey":[]}],"parameters":[{"name":"workspace","in":"query","required":false,"description":"OptiSift workspace slug. May also be supplied as the x-apex-workspace header.","schema":{"type":"string"}},{"name":"x-apex-workspace","in":"header","required":false,"description":"Alternative workspace selector.","schema":{"type":"string"}},{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Published item"},"404":{"description":"Item not found"}}}},"/api/v1/compare":{"get":{"summary":"Compare two or three workspace items","security":[{"ApexApiKey":[]}],"parameters":[{"name":"workspace","in":"query","required":false,"description":"OptiSift workspace slug. May also be supplied as the x-apex-workspace header.","schema":{"type":"string"}},{"name":"x-apex-workspace","in":"header","required":false,"description":"Alternative workspace selector.","schema":{"type":"string"}},{"name":"items","in":"query","required":true,"description":"Comma-separated item slugs","schema":{"type":"string"}}],"responses":{"200":{"description":"Comparison"}}}},"/api/v1/comparisons/{id}/findings":{"get":{"summary":"Return what changed in a tracked saved comparison","description":"Findings from each scheduled snapshot, newest first: score_change, rank_change, better_fit, new_item and source_alert. The comparison must belong to the API key's user.","security":[{"ApexApiKey":[]}],"parameters":[{"name":"workspace","in":"query","required":false,"description":"OptiSift workspace slug. May also be supplied as the x-apex-workspace header.","schema":{"type":"string"}},{"name":"x-apex-workspace","in":"header","required":false,"description":"Alternative workspace selector.","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Saved comparison id, as listed by the MCP saved_comparisons tool.","schema":{"type":"string"}}],"responses":{"200":{"description":"Snapshots with their findings and the thresholds used"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Key does not belong to workspace"},"404":{"description":"No such comparison for this key's user"},"429":{"description":"Rate limit exceeded"}}}},"/api/v1/decide":{"post":{"summary":"Choose the best workspace item under hard constraints","security":[{"ApexApiKey":[]}],"parameters":[{"name":"workspace","in":"query","required":false,"description":"OptiSift workspace slug. May also be supplied as the x-apex-workspace header.","schema":{"type":"string"}},{"name":"x-apex-workspace","in":"header","required":false,"description":"Alternative workspace selector.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["constraints"],"properties":{"constraints":{"type":"array","minItems":1,"maxItems":10,"items":{"$ref":"#/components/schemas/Constraint"}},"category":{"type":"string"},"limit":{"type":"integer","minimum":1,"maximum":25}}}}}},"responses":{"200":{"description":"Signed, citable decision result. `decision.alternates` lists, per lens (a decision preset or `lowest_cost`), another surviving item worth considering with a note: close, cheaper, faster, no_good_fit or ungraded. The envelope is signed as `apex-hmac-v2`, which covers the decision, provenance, generatedAt, siteId and workspace."},"400":{"description":"Invalid or unknown constraints"}}}}}}