{"openapi":"3.1.0","info":{"title":"The One, public disclosure API","version":"1.0.0","summary":"Machine-readable face of The One's quarterly graduation disclosure (COMMITMENTS.md §7).","description":"Read-only, unauthenticated, rate-limited (10 req/min per IP). Every response carries X-API-Version and X-Commitments-Hash headers so consumers can detect a change in the canonical commitments file without parsing the body.","contact":{"name":"The One","url":"https://theonecompass.app"},"license":{"name":"Public disclosure, free to read, redistribute, and analyze.","identifier":"CC-BY-4.0"}},"servers":[{"url":"https://data.theonecompass.app","description":"Production"}],"paths":{"/v1/disclosures":{"get":{"summary":"List all published quarterly disclosures","operationId":"listDisclosures","description":"Returns one entry per quarter that has been published, newest quarter first. Returns an empty array (HTTP 200) before the first quarterly snapshot has been written; that empty state is the honest pre-launch answer.","responses":{"200":{"description":"Disclosure list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisclosureListResponse"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/disclosures/{quarter}":{"get":{"summary":"Full disclosure for one quarter","operationId":"getDisclosureByQuarter","parameters":[{"$ref":"#/components/parameters/QuarterPath"}],"responses":{"200":{"description":"Full disclosure record","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisclosureResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/disclosures/{quarter}/cohorts":{"get":{"summary":"Cohort breakdowns for one quarter","operationId":"getCohortsByQuarter","description":"Slice of the disclosure that contains only the cohort_breakdowns array. Convenient when an analyst only wants the cohort-level numbers.","parameters":[{"$ref":"#/components/parameters/QuarterPath"}],"responses":{"200":{"description":"Cohort breakdowns","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CohortsResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/methodology":{"get":{"summary":"Methodology document","operationId":"getMethodology","description":"Canonical definitions: what counts as a released match, what counts as a graduation, the year-one verification process, cohort definitions, and how rates are derived from the counts.","responses":{"200":{"description":"Methodology document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MethodologyResponse"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/commitments":{"get":{"summary":"COMMITMENTS.md content + continuity hashes","operationId":"getCommitments","description":"Returns the verbatim text of COMMITMENTS.md, its sha256, and the most recent commitments_hash recorded in disclosure_snapshots. A divergence between hash and last_published_hash means the commitments file has been edited since the last quarterly publication.","responses":{"200":{"description":"Commitments document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommitmentsResponse"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/openapi.json":{"get":{"summary":"This OpenAPI 3.1 spec","operationId":"getOpenApi","responses":{"200":{"description":"OpenAPI document","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"parameters":{"QuarterPath":{"name":"quarter","in":"path","required":true,"description":"Quarter identifier in the format YYYYQ[1-4], e.g. \"2026Q3\".","schema":{"$ref":"#/components/schemas/QuarterId"},"example":"2026Q3"}},"responses":{"BadRequest":{"description":"Invalid input (e.g. malformed quarter parameter).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No disclosure has been published for the requested quarter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Caller has exceeded 10 requests per minute.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix epoch seconds at which the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"QuarterId":{"type":"string","pattern":"^\\d{4}Q[1-4]$","examples":["2026Q1","2026Q3"]},"DisclosureListItem":{"type":"object","required":["quarter","snapshot_at","total_matches_released","total_graduations","total_year_one_sustained","published_url","api_dataset_url","commitments_hash"],"properties":{"quarter":{"$ref":"#/components/schemas/QuarterId"},"snapshot_at":{"type":"string","format":"date-time"},"total_matches_released":{"type":"integer","minimum":0},"total_graduations":{"type":"integer","minimum":0},"total_year_one_sustained":{"type":"integer","minimum":0},"published_url":{"type":"string","format":"uri"},"api_dataset_url":{"type":"string","format":"uri"},"commitments_hash":{"type":"string","pattern":"^[a-f0-9]{64}$"}}},"DisclosureFull":{"allOf":[{"$ref":"#/components/schemas/DisclosureListItem"},{"type":"object","required":["cohort_breakdowns","computed_by_version"],"properties":{"cohort_breakdowns":{"type":"array","items":{"$ref":"#/components/schemas/CohortBreakdown"}},"computed_by_version":{"type":"string","description":"Git SHA of the cron build that wrote this row."}}}]},"CohortBreakdown":{"type":"object","required":["cohort","matches_released","graduations","year_one_eligible","year_one_sustained","year_one_separated","year_one_unreachable"],"properties":{"cohort":{"$ref":"#/components/schemas/QuarterId"},"matches_released":{"type":"integer","minimum":0},"graduations":{"type":"integer","minimum":0},"year_one_eligible":{"type":"integer","minimum":0},"year_one_sustained":{"type":"integer","minimum":0},"year_one_separated":{"type":"integer","minimum":0},"year_one_unreachable":{"type":"integer","minimum":0}}},"DisclosureListResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DisclosureListItem"}},"meta":{"type":"object","required":["count"],"properties":{"count":{"type":"integer","minimum":0}}}}},"DisclosureResponse":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/DisclosureFull"}}},"CohortsResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["quarter","snapshot_at","cohort_breakdowns"],"properties":{"quarter":{"$ref":"#/components/schemas/QuarterId"},"snapshot_at":{"type":"string","format":"date-time"},"cohort_breakdowns":{"type":"array","items":{"$ref":"#/components/schemas/CohortBreakdown"}}}}}},"MethodologyResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["version","last_updated","title","summary","sections","changelog"],"properties":{"version":{"type":"string"},"last_updated":{"type":"string","format":"date"},"title":{"type":"string"},"summary":{"type":"string"},"sections":{"type":"array","items":{"type":"object","required":["id","title","body"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"body":{"type":"array","items":{"type":"string"}}}}},"changelog":{"type":"array","items":{"type":"object","required":["version","date","note"],"properties":{"version":{"type":"string"},"date":{"type":"string","format":"date"},"note":{"type":"string"}}}}}}}},"CommitmentsResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["filename","content","hash","algorithm","last_published_hash"],"properties":{"filename":{"type":"string","examples":["COMMITMENTS.md"]},"content":{"type":"string","description":"Verbatim COMMITMENTS.md text."},"hash":{"type":"string","pattern":"^[a-f0-9]{64}$","description":"sha256 of the served content."},"algorithm":{"type":"string","examples":["sha256"]},"last_published_hash":{"type":["string","null"],"pattern":"^[a-f0-9]{64}$","description":"commitments_hash from the most recent disclosure snapshot, or null if no snapshot has been published yet."},"last_published_quarter":{"type":["string","null"],"description":"Quarter of the snapshot whose hash is reported above."},"matches_last_published":{"type":"boolean","description":"true iff hash === last_published_hash. false means COMMITMENTS.md has been edited since the last quarterly snapshot, by design, that change is publicly visible."}}}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}}}}}}}}