{"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 4-week sample size (answer runs in the current window), the engines that contributed at least one of those runs (`engines`), and the engines configured for the category (`engines_configured`). An engine configured but absent from `engines` logged zero runs in the 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/products/{id}":{"get":{"operationId":"getAiIndexProduct","summary":"AI Recommendation Index — canonical identity of one product row","description":"The registry row the Index ranks for a product id. Where two rows are one company (a spelling variant whose domain redirects, e.g. OpusClip -> Opus Clip) the alias id resolves to the canonical row and `resolved_from` carries the id that was asked for.","tags":["AI Index"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The canonical product row","content":{"application/json":{"schema":{"type":"object","properties":{"index_product_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"domain":{"type":"string","nullable":true},"resolved_from":{"type":"string","format":"uuid","nullable":true,"description":"The alias id the request named, when it was one"}}}}}},"400":{"description":"Not a UUID"},"404":{"description":"Unknown, merged, or rejected product id"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/index/methodology":{"get":{"operationId":"getAiIndexMethodology","summary":"AI Recommendation Index — measurement disclosure","description":"What the Index actually measures, read live from the collectors: the effective model per engine (env override or default), sampling cadence, the 28-day window and minimum-sample gate, current extraction version, and the trend comparability guardrails. Backs the human methodology page at https://www.orbator.io/ai-index/methodology","tags":["AI Index"],"responses":{"200":{"description":"Measurement parameters currently in effect","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IndexMethodology"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/index/methodology/changelog":{"get":{"operationId":"getAiIndexMethodologyChangelog","summary":"AI Recommendation Index — methodology changelog","description":"Every methodology change, dated and described: extraction-rule eras, metric redefinitions, sampling-design changes. Committed repo history merged with admin-appended entries, newest first, each entry carrying a stable anchor into https://www.orbator.io/ai-index/methodology#changelog — series breaks are disclosed, not discovered.","tags":["AI Index"],"responses":{"200":{"description":"Dated changelog entries, newest first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MethodologyChangelog"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/index/data-stats":{"get":{"operationId":"getAiIndexDataStats","summary":"AI Recommendation Index — live dataset statistics","description":"The live statistics behind https://www.orbator.io/data: categories measured, products tracked, answers in the 28-day window, engines with their effective models, the engine-agreement rate (share of categories where one product leads every engine, 3+ engines present), the vendor-owned citation share (registry-domain match, unresolved vertexaisearch redirectors excluded), the most-omnipresent products, and the statistical-robustness block (prompts-per-category and per-category sample-size distributions, plus the confidence-interval method). Every stat carries its n. Cached 1 hour.","tags":["AI Index"],"responses":{"200":{"description":"Live dataset statistics, each stat with its n and the measurement window","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IndexDataStats"}}}},"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"},{"name":"by_intent","in":"query","required":false,"schema":{"type":"string","enum":["1"]},"description":"Set to 1 to include intent_shares: recommendation shares grouped by the buyer prompt's intent (best_in_category, alternatives, problem_solving, ...). Omitted otherwise."}],"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}/as-of/{date}":{"get":{"operationId":"getAiIndexCategoryAsOf","summary":"AI Recommendation Index — the category as PUBLISHED on a date","description":"Reads the immutable archive: the rankings this Index actually published on or before the requested date, at their latest revision. This is a record, not a recomputation — the API never re-derives a historical window under current extraction rules and presents it as history. Every response discloses `source` (\"cron\" = captured live that day; \"backfill\" = reconstructed later from run history), the `extraction_version` the underlying sightings were produced under, and the `revision` (a correction supersedes the original for the same date and carries a correction_note). Dates before the archive begins return status \"no_record\" with the earliest date on file.","tags":["AI Index"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Category slug, e.g. crm-for-freelancers"},{"name":"date","in":"path","required":true,"schema":{"type":"string","format":"date"},"description":"YYYY-MM-DD. Returns the latest snapshot at or before this date."}],"responses":{"200":{"description":"The archived category payload, or status \"no_record\" when the date precedes the archive"},"400":{"description":"Malformed or impossible date"},"404":{"description":"Unknown or unpublished category"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/index/{slug}/history":{"get":{"operationId":"getAiIndexCategoryHistory","summary":"AI Recommendation Index — archive dates, dated rankings, and the change log","description":"How this category's AI recommendations changed over time. Returns every date the category has an archived snapshot for (newest first, with earliest/latest bounds — use them for /api/index/{slug}/as-of/{date}), the recent dated rankings trimmed to the top band, and a change log computed by diffing adjacent snapshots at read time: who entered the ranking, who left it, rank moves, and share moves that clear the aggregator's flat band (sub-noise moves are deliberately omitted). Each step also flags an extraction_version change between the two dates, so a methodology shift never reads as a silent reshuffle.","tags":["AI Index"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Category slug, e.g. crm-for-freelancers"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":90,"default":30},"description":"How many recent snapshots carry rankings + change-log steps. The full date list is unaffected."},{"name":"top","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":25,"default":10},"description":"Ranking band: entries returned per date, and the band entered/left events are measured against."}],"responses":{"200":{"description":"Archive index (count, earliest, latest, dates), timeline of dated rankings, and the change log"},"404":{"description":"Unknown or unpublished category"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/index/{slug}/answers":{"get":{"operationId":"getAiIndexCategoryAnswers","summary":"AI Recommendation Index — dated answer excerpts per engine","description":"What each engine actually said for this category on one date, grouped by engine: the run date, the prompt INTENT (never the prompt text), a short excerpt of at most 400 characters, and server-computed {start, end, name} highlight offsets for the entities the extractor recorded. Only Index category runs are archived — customer scans never appear at any granularity — and full engine output is never served. Engines outside the verbatim allowlist (ARCHIVE_VERBATIM_ENGINES; Perplexity is excluded by default under its terms) are reported as having answered with excerpt_withheld: true rather than hidden. Defaults to the most recent archived date; available_dates lists the rest, and every dated view is a stable ?date= URL.","tags":["AI Index"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Category slug, e.g. crm-for-freelancers"},{"name":"date","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"YYYY-MM-DD. Defaults to the most recent date with archived answers."},{"name":"engine","in":"query","required":false,"schema":{"type":"string"},"description":"Restrict to one engine id, e.g. openai, anthropic, gemini, perplexity."}],"responses":{"200":{"description":"Answer excerpts for the date, grouped by engine (capped at 50, highest-sample prompts first), with the available dates and the published exposure policy"},"400":{"description":"Malformed date or engine id"},"404":{"description":"Unknown or unpublished category"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/index/archive-manifest":{"get":{"operationId":"getAiIndexArchiveManifest","summary":"AI Recommendation Index — which categories have an archive","description":"Every published category with at least one archived snapshot, with its snapshot count and its earliest/latest snapshot dates. Powers honest lastmod dates for the archive pages and lets a client discover the archive surface in one request instead of probing per category.","tags":["AI Index"],"responses":{"200":{"description":"Categories with an archive, each with snapshot_count and date bounds"},"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"}}},"IndexMethodology":{"type":"object","properties":{"source":{"type":"string","example":"https://www.orbator.io/ai-index"},"license":{"type":"string"},"methodology_url":{"type":"string"},"window":{"type":"object","properties":{"weeks":{"type":"integer","example":4},"days":{"type":"integer","example":28}}},"min_sample":{"type":"integer","description":"Runs required in the window before a category publishes"},"sampling_cadence":{"type":"string","example":"~monthly per engine per category at current budget"},"extraction_version":{"type":"integer","description":"Current extraction pipeline version stamped on stored sightings"},"sampling":{"type":"object","description":"Repeated-sampling design currently in effect (samples per prompt-engine pair per cycle)","properties":{"samples_per_prompt":{"type":"integer","description":"Global N per prompt-engine pair; 1 = single-draw"},"per_engine":{"type":"object","additionalProperties":{"type":"integer"},"description":"Effective N per engine (env override or engine default)"},"sampled_categories_limit":{"type":"integer","description":"Only the top-N categories by exposure sample at N>1"},"customer_samples_per_prompt":{"type":"integer","description":"N for customer-lane visibility runs"}}},"engines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"anthropic"},"model":{"type":"string","description":"Effective measured model (env override or default)"},"available":{"type":"boolean","description":"API key configured — the engine is collecting"},"era_filter":{"type":"string","nullable":true,"description":"Model prefix public aggregation is restricted to during a changeover; null when none"}}}},"trend_guardrails":{"type":"object","description":"Windows must be comparable before a trend publishes (else suppressed)","properties":{"min_engine_runs":{"type":"integer","description":"Minimum runs per configured engine in both windows"},"low_engine_runs":{"type":"integer","description":"Below this per-engine run count a passing trend is graded low confidence"},"volume_ratio":{"type":"array","items":{"type":"number"},"description":"Allowed current/prior run-volume ratio range"},"flat_band_pp":{"type":"number","description":"Share deltas within ± this band report as flat"},"small_sample_flat_band_pp":{"type":"number","description":"Widened flat band under small samples"},"small_sample_runs":{"type":"integer","description":"Sample size below which the widened band applies"},"confidence_levels":{"type":"array","items":{"type":"string"}}}}}},"MethodologyChangelog":{"type":"object","properties":{"methodology_url":{"type":"string"},"entries":{"type":"array","description":"Dated methodology changes, newest first","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"version":{"type":"string","nullable":true,"description":"Version tag the entry documents, e.g. extraction-v7; null for non-versioned changes"},"title":{"type":"string"},"change":{"type":"string","description":"What changed and why it matters to published numbers"},"affects":{"type":"array","items":{"type":"string"},"description":"Published numbers/series the change affects"},"source":{"type":"string","enum":["file","admin"],"description":"Committed repo history vs admin-appended overlay"},"anchor":{"type":"string","description":"Stable anchor on the public methodology page"}}}}}},"IndexDataStats":{"type":"object","properties":{"source":{"type":"string","example":"https://www.orbator.io/data"},"license":{"type":"string","example":"Free to use with attribution to orbator.io"},"methodology_url":{"type":"string"},"generated_at":{"type":"string","format":"date-time"},"window":{"$ref":"#/components/schemas/IndexWindow"},"categories_measured":{"type":"integer","description":"Active Index categories"},"products_tracked":{"type":"integer","description":"Canonical entities in the registry (merged/rejected excluded)"},"answers_in_window":{"type":"integer","description":"Category answer runs in the 28-day window"},"categories_in_window":{"type":"integer","description":"Categories with at least one answer run in the window"},"engines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"anthropic"},"model":{"type":"string","description":"Effective measured model"},"available":{"type":"boolean"}}}},"engine_agreement":{"type":"object","description":"Share of categories (3+ engines present) where the same product leads every engine","properties":{"agree_pct":{"type":"number","nullable":true},"disagree_pct":{"type":"number","nullable":true},"categories_agree":{"type":"integer"},"categories_eligible":{"type":"integer"},"min_engines":{"type":"integer"},"n":{"type":"integer"}}},"vendor_owned_citations":{"type":"object","description":"Share of window citations pointing at domains owned by vendors in the Index registry (unresolved vertexaisearch redirectors excluded — pre-2026-07-18 gemini rows; later gemini citations are resolved to real sources at ingest)","properties":{"share_pct":{"type":"number","nullable":true},"vendor_owned":{"type":"integer"},"total_citations":{"type":"integer"},"n":{"type":"integer"},"basis":{"type":"string"}}},"prompts_per_category":{"type":"object","description":"Buyer-shaped prompts carried per active category, distributed (STR-002)","properties":{"min":{"type":"integer","nullable":true},"median":{"type":"integer","nullable":true},"max":{"type":"integer","nullable":true},"n":{"type":"integer","description":"Active categories with a written prompt set"},"basis":{"type":"string"}}},"sample_size":{"type":"object","description":"Independent sampled answers per category in the window, distributed (STR-002)","properties":{"min":{"type":"integer","nullable":true},"median":{"type":"integer","nullable":true},"max":{"type":"integer","nullable":true},"n":{"type":"integer","description":"Categories with at least one run in the window"},"min_sample":{"type":"integer","description":"Live minimum-sample publishing gate"},"categories_at_min_sample":{"type":"integer"},"basis":{"type":"string"}}},"confidence_interval":{"type":"object","description":"Interval method applied to every published recommendation share","properties":{"method":{"type":"string","example":"wilson"},"level_pct":{"type":"number","example":95},"z":{"type":"number","example":1.96},"basis":{"type":"string"}}},"most_omnipresent":{"type":"array","description":"Products recommended across the most categories in the window (top 5)","items":{"type":"object","properties":{"name":{"type":"string"},"domain":{"type":"string","nullable":true},"categories_present":{"type":"integer"},"engines_present":{"type":"integer"},"mention_runs":{"type":"integer"},"n":{"type":"integer","description":"Categories measured in the window (the denominator)"}}}}}},"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"},"description":"Engines with at least one answer run for this category in the current 4-week window (the same runs behind the category payload's engine_samples)"},"engines_configured":{"type":"array","items":{"type":"string"},"description":"Engines configured to sample this category; one listed here but absent from engines logged zero runs in the window"},"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"},"engine_samples":{"type":"object","description":"Per-engine audit trail (MTH-006): current-window run counts (they sum to sample_size) plus each engine's newest run date across the current + prior windows — rotation lag is disclosed, not hidden.","additionalProperties":{"type":"object","properties":{"runs":{"type":"integer","description":"Answer runs in the current window"},"last_run_at":{"type":"string","format":"date-time","nullable":true}}}},"volatility":{"type":"object","description":"Ranking-wide stability score (MTH-006): median of the top entries' MTH-002 volatility scores, rounded toward the worse level; null with no scored history.","properties":{"score":{"type":"string","enum":["stable","moderate","volatile"],"nullable":true}}},"methodology_url":{"type":"string"},"license":{"type":"string"},"entries":{"type":"array","items":{"$ref":"#/components/schemas/CategoryIndexEntry"}},"intent_shares":{"type":"array","description":"Present only when requested with ?by_intent=1: recommendation shares grouped by the buyer prompt's intent, so cuts can say \"best for X\" with data behind it. Runs whose prompt no longer matches any current category prompt group under intent \"other\".","items":{"$ref":"#/components/schemas/IntentShareGroup"}},"editorial":{"type":"array","description":"Editorial sections written from this window's measured data only (the page's own entries, per-engine shares, mention breakdown, sourced facts, archive). Rows with review_status \"generated\" are unreviewed and disclosed as such on the page; \"approved\" rows passed founder review; rejected rows are never served. Empty until the category's enrichment batch is released.","items":{"$ref":"#/components/schemas/EditorialSection"}}}},"EditorialSection":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"section":{"type":"string","enum":["how_to_choose","top_products","engine_disagreement","what_moved"]},"body_md":{"type":"string","description":"Markdown paragraphs; every figure is traceable to the window's data"},"window_to":{"type":"string","format":"date","description":"End of the 4-week window the section was written from"},"review_status":{"type":"string","enum":["generated","approved"]},"generated_at":{"type":"string","format":"date-time"}}},"IntentShareGroup":{"type":"object","properties":{"intent":{"type":"string","description":"Prompt intent, e.g. best_in_category, alternatives, problem_solving; \"other\" for unmatched prompts"},"runs":{"type":"integer","description":"Answer runs for this intent in the window"},"entries":{"type":"array","items":{"type":"object","properties":{"index_product_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"domain":{"type":"string","nullable":true},"mentions":{"type":"integer"},"share":{"type":"number","description":"% of this intent's runs recommending the product"},"avg_position":{"type":"number","nullable":true}}}}}},"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"},"ci_low":{"type":"number","nullable":true,"description":"Lower bound of the 95% Wilson confidence interval on recommendation_share (STR-001)"},"ci_high":{"type":"number","nullable":true,"description":"Upper bound of the 95% Wilson confidence interval on recommendation_share (STR-001)"},"mention_runs":{"type":"number","description":"Answers in the window recommending this product (CI numerator)"},"first_rec_runs":{"type":"number","description":"Recommending answers where this product was named first"},"first_rec_rate":{"type":"number","nullable":true,"description":"% of this product's recommending answers where it was the #1 recommendation"},"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"},"product_facts":{"type":"object","nullable":true,"description":"Sourced facts grouped by fact type (pricing, feature, platform, integration). Present only when the product has facts; every fact carries source_url + last_verified_at. Same store as /api/compare/{pair}.","additionalProperties":{"type":"array","items":{"$ref":"#/components/schemas/ComparisonFact"}}},"best_for":{"type":"object","nullable":true,"description":"Data-derived buyer use-case this product over-indexes on: the category prompt where it is recommended most strongly, straight from the answer corpus (no model calls). Present only when the signal clears the sample + over-index guardrails; omitted otherwise.","properties":{"prompt":{"type":"string","description":"The verbatim buyer question (the use-case)"},"share":{"type":"number","description":"% of that prompt's answers recommending the product"},"mentions":{"type":"integer"},"runs":{"type":"integer","description":"Answer runs for that prompt in the window"}}}}},"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"]}}}}}}