{"openapi":"3.0.3","info":{"title":"Orbator Public API","version":"1.0.0","description":"Open data endpoints for agents, tools, and AI platforms: the validated directory catalog, the AI Recommendation Index (what ChatGPT/Claude/Gemini/Perplexity recommend per category), canonical product facts, and fact-by-fact comparisons. Anonymous: 60 requests/hour per IP. Keyed: 1,000 requests/hour (X-Api-Key header or Bearer token). Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers; 429 responses include Retry-After. Request a key via https://www.orbator.io/developers","contact":{"email":"support@orbator.io","url":"https://www.orbator.io/developers"}},"servers":[{"url":"https://api.orbator.io"}],"security":[{},{"ApiKeyAuth":[]},{"BearerAuth":[]}],"paths":{"/api/directory-catalog":{"get":{"operationId":"getDirectoryCatalog","summary":"Validated directory catalog","description":"Stable JSON of the validated (customer-visible) startup/SaaS submission directory set. Every entry is verified by Orbator (form-mapped). Free to use with attribution to orbator.io. Also mirrored at https://www.orbator.io/api/directory-catalog","tags":["Directories"],"responses":{"200":{"description":"Directory catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DirectoryCatalog"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/index/categories":{"get":{"operationId":"listAiIndexCategories","summary":"AI Recommendation Index — published categories","description":"Every published Index category with its engines and 4-week sample size (answer runs in the current window). Start here to discover valid slugs for /api/index/{slug}.","tags":["AI Index"],"responses":{"200":{"description":"Published categories with sample sizes, window, and methodology URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IndexCategoryList"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/index/{slug}":{"get":{"operationId":"getAiIndexCategory","summary":"AI Recommendation Index — category rankings","description":"Per-category recommendation share, average position, per-engine breakdown and 4-week trend for every product AI engines recommend in the category. Categories with fewer runs than the minimum sample return status \"insufficient_data\" instead of noisy numbers.","tags":["AI Index"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Category slug, e.g. crm-for-freelancers"}],"responses":{"200":{"description":"Category index payload (share, trend, per-engine breakdown, sample size, methodology URL)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryIndex"}}}},"404":{"description":"Unknown or unpublished category"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/index/{slug}.csv":{"get":{"operationId":"getAiIndexCategoryCsv","summary":"AI Recommendation Index — category rankings (flat CSV)","description":"The same category payload flattened to CSV: one row per ranked product, per-engine shares as columns; sample size, window, and methodology URL repeat on every row and ride the X-Sample-Size / X-Window-From / X-Window-To / X-Methodology-Url response headers.","tags":["AI Index"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Category slug, e.g. crm-for-freelancers"}],"responses":{"200":{"description":"Flat CSV of category rankings","content":{"text/csv":{"schema":{"type":"string"}}}},"404":{"description":"Unknown or unpublished category"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/facts/{product}":{"get":{"operationId":"getProductFacts","summary":"Canonical product facts","description":"Sourced and dated facts (pricing, features, integrations, platform, HQ, limits) for one product. Every fact carries source_url and last_verified_at. PLANNED — documented ahead of launch (ships with the facts/compare wave, ARI-033/ARI-034); returns 404 until then.","tags":["Facts"],"x-status":"planned","parameters":[{"name":"product","in":"path","required":true,"schema":{"type":"string"},"description":"Product slug or canonical domain, e.g. hubspot.com"}],"responses":{"200":{"description":"Product facts with provenance"},"404":{"description":"Unknown product — or endpoint not yet launched"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/compare/{pair}":{"get":{"operationId":"getComparison","summary":"Fact-by-fact product comparison","description":"Side-by-side data for a published comparison pair: both entities, their sourced/dated facts grouped by type, each side's per-engine recommendation share, and shared category context. Pair slugs are the two canonical domains joined by \"-vs-\", alphabetically ordered, e.g. asana.com-vs-trello.com. A pair returns 404 until it is published and both sides carry at least five sourced facts.","tags":["Facts"],"x-status":"live","parameters":[{"name":"pair","in":"path","required":true,"schema":{"type":"string"},"description":"Canonical pair slug (alphabetical by domain), e.g. asana.com-vs-trello.com"}],"responses":{"200":{"description":"Comparison payload (facts per side, sources, verified dates, per-engine share)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Comparison"},"example":{"source":"https://www.orbator.io/vs","license":"Free to use with attribution to orbator.io","methodology_url":"https://www.orbator.io/ai-index/methodology","pair":"asana.com-vs-trello.com","window":{"weeks":4,"from":"2026-05-16T00:00:00.000Z","to":"2026-06-13T00:00:00.000Z"},"entities":{"a":{"index_product_id":"4b1c9e02-1f3a-4c77-9c2e-2a1d6f0b5e10","name":"Asana","canonical_domain":"asana.com","claimed":true,"facts":{"pricing":[{"value":{"plan":"Starter","monthly_usd":10.99,"key":"starter"},"source_url":"https://asana.com/pricing","last_verified_at":"2026-06-01T00:00:00.000Z","verified_by":"agent_research"}]},"per_engine":[{"engine":"anthropic","runs":120,"mentions":54,"share":45},{"engine":"openai","runs":120,"mentions":48,"share":40},{"engine":"perplexity","runs":120,"mentions":60,"share":50}],"categories":[{"slug":"project-management-for-teams","label":"Project management for teams","sample_size":360,"share":45,"trend":{"direction":"up","delta":3.2,"prior_share":41.8}}]},"b":{"index_product_id":"9f7a2c44-0b8e-4d11-8c33-7e5a1b9c2d44","name":"Trello","canonical_domain":"trello.com","claimed":false,"facts":{"pricing":[{"value":{"plan":"Standard","monthly_usd":5,"key":"standard"},"source_url":"https://trello.com/pricing","last_verified_at":"2026-06-02T00:00:00.000Z","verified_by":"agent_research"}]},"per_engine":[{"engine":"anthropic","runs":120,"mentions":30,"share":25},{"engine":"openai","runs":120,"mentions":36,"share":30},{"engine":"perplexity","runs":120,"mentions":24,"share":20}],"categories":[{"slug":"project-management-for-teams","label":"Project management for teams","sample_size":360,"share":25,"trend":{"direction":"flat","delta":-0.4,"prior_share":25.4}}]}}}}}},"404":{"description":"Unknown pair, unpublished pair, or either side under the facts gate"},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"Optional — raises the rate limit from 60 to 1,000 req/h."},"BearerAuth":{"type":"http","scheme":"bearer","description":"Same API key, passed as a Bearer token."}},"responses":{"RateLimited":{"description":"Hourly quota exceeded for the current tier. Retry after the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}}}}},"DirectoryCatalog":{"type":"object","properties":{"source":{"type":"string","example":"https://www.orbator.io"},"description":{"type":"string"},"license":{"type":"string","example":"Free to use with attribution to orbator.io"},"updated_at":{"type":"string","format":"date-time"},"count":{"type":"integer"},"directories":{"type":"array","items":{"$ref":"#/components/schemas/DirectoryEntry"}}}},"DirectoryEntry":{"type":"object","properties":{"name":{"type":"string","example":"Product Hunt"},"url":{"type":"string","nullable":true},"submit_url":{"type":"string","nullable":true},"category":{"type":"string","nullable":true},"surface_type":{"type":"string","nullable":true,"description":"What kind of AI citation surface this is","enum":["review_platform","alternatives_engine","entity_anchor","community","ai_directory","launch_directory","owned_surface","listicle"]},"domain_authority":{"type":"integer","nullable":true},"requires_payment":{"type":"boolean"},"requires_backlink":{"type":"boolean"},"free_tier_conditions":{"type":"array","items":{"type":"string"}}}},"IndexWindow":{"type":"object","description":"4-week rolling measurement window","properties":{"weeks":{"type":"integer","example":4},"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"},"prior_from":{"type":"string","format":"date-time","description":"Start of the prior window trends compare against"}}},"IndexCategoryList":{"type":"object","properties":{"source":{"type":"string","example":"https://www.orbator.io/ai-index"},"license":{"type":"string","example":"Free to use with attribution to orbator.io"},"methodology_url":{"type":"string"},"window":{"$ref":"#/components/schemas/IndexWindow"},"count":{"type":"integer"},"categories":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string","example":"crm-for-freelancers"},"label":{"type":"string"},"engines":{"type":"array","items":{"type":"string"}},"sample_size":{"type":"integer","description":"Answer runs in the current 4-week window"},"url":{"type":"string"},"csv_url":{"type":"string"}}}}}},"CategoryIndex":{"type":"object","properties":{"status":{"type":"string","enum":["ok","insufficient_data"]},"category":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"label":{"type":"string"}}},"window":{"$ref":"#/components/schemas/IndexWindow"},"sample_size":{"type":"integer","description":"Answer runs in the current window"},"prior_sample_size":{"type":"integer"},"min_sample":{"type":"integer","description":"Runs required before numbers are published"},"methodology_url":{"type":"string"},"license":{"type":"string"},"entries":{"type":"array","items":{"$ref":"#/components/schemas/CategoryIndexEntry"}}}},"CategoryIndexEntry":{"type":"object","properties":{"index_product_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"domain":{"type":"string","nullable":true},"recommendation_share":{"type":"number","description":"% of runs in the window recommending this product"},"avg_position":{"type":"number","nullable":true,"description":"Average 1-based rank when answers are lists"},"per_engine":{"type":"object","additionalProperties":{"type":"object","properties":{"mentions":{"type":"number"},"runs":{"type":"number"},"share":{"type":"number"}}}},"trend":{"type":"object","nullable":true,"properties":{"direction":{"type":"string","enum":["up","down","flat","new"]},"delta":{"type":"number","description":"Share change vs the prior window, in percentage points"},"prior_share":{"type":"number","nullable":true}}},"is_orbator_customer":{"type":"boolean","description":"Disclosure flag — measurement is unaffected by customer status"}}},"Comparison":{"type":"object","properties":{"source":{"type":"string","example":"https://www.orbator.io/vs"},"license":{"type":"string","example":"Free to use with attribution to orbator.io"},"methodology_url":{"type":"string"},"pair":{"type":"string","description":"Canonical pair slug (alphabetical by domain)","example":"asana.com-vs-trello.com"},"window":{"$ref":"#/components/schemas/IndexWindow"},"entities":{"type":"object","description":"Both sides, keyed a/b — a is the alphabetically-first domain","properties":{"a":{"$ref":"#/components/schemas/ComparisonEntity"},"b":{"$ref":"#/components/schemas/ComparisonEntity"}}}}},"ComparisonEntity":{"type":"object","properties":{"index_product_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"canonical_domain":{"type":"string","nullable":true},"claimed":{"type":"boolean","description":"A verified owner claim exists for this entity"},"facts":{"type":"object","description":"Sourced facts grouped by fact type (pricing, feature, integration, founded, hq, platform, limit)","additionalProperties":{"type":"array","items":{"$ref":"#/components/schemas/ComparisonFact"}}},"per_engine":{"type":"array","description":"Per-engine recommendation share over the 4-week window","items":{"type":"object","properties":{"engine":{"type":"string"},"runs":{"type":"integer"},"mentions":{"type":"integer"},"share":{"type":"number","description":"% of this engine's runs recommending the entity"}}}},"categories":{"type":"array","description":"Published categories where the entity is recommended, with its share + trend","items":{"type":"object","properties":{"slug":{"type":"string"},"label":{"type":"string"},"sample_size":{"type":"integer"},"share":{"type":"number"},"trend":{"type":"object","nullable":true,"properties":{"direction":{"type":"string","enum":["up","down","flat","new"]},"delta":{"type":"number"},"prior_share":{"type":"number","nullable":true}}}}}}}},"ComparisonFact":{"type":"object","properties":{"value":{"type":"object","description":"Fact value (JSON); multi-valued types carry a \"key\""},"source_url":{"type":"string"},"last_verified_at":{"type":"string","format":"date-time"},"verified_by":{"type":"string","enum":["agent_research","launch_kit","vendor_claim","admin"]}}}}}}