Reference

Response schema

• response object (SearchResponse)

  • asOf string (date-time) · Required
  • sources array · Required

    • item object (PartnerSource)

      • key string · Required
      • name string · Required
      • country string · Required
      • region string, nullable · Required
  • notice string · Required
  • query object · Required

    • name string
    • hometown string
    • division string
    • discipline string
  • candidates array · Required

    • item object (SearchCandidate)

      • id string (uuid) · Required
      • slug string · Required
      • name string · Required
      • hometown object (Hometown) · Required

        The tree stops here: this branch repeats a schema already open above it.

      • disciplines array · Required

        • item string · One of: BOXING, MMA, MUAY_THAI, KICKBOXING, BARE_KNUCKLE, SLAP, OTHER
      • commissions array · Required

        • item string
      • boutsOnFile integer · Required

        A count of verified bouts on file — never a record.

      • lastBoutDate string (date), nullable · Required
      • confidence string · Required · One of: high, medium, low
      • matched array · Required

        • item string · One of: name_exact, name_alias, name_partial, hometown, region, discipline, division

Response schema

No response body.

Response schema

No response body.

Response schema

No response body.

Response schema

• response object (ClaimedLookupView)

  The batched lookup answer. Not an envelope: this route answers the lookup shape, the same on both tiers. A cut list is never signalled — treat a batch answer as complete.

  • prefixLength integer · Required

    How many hex characters of the hash a `p` item carries.

  • matches array · Required

    • item object (ClaimedLookupMatch)

      One published subject whose name hash starts with an asked prefix. The flag, the name and the link: no fact list.

      • hash string · Required

        sha256 of the folded display name, 64 lower-case hex — match your own hash against this.

      • kind string · Required · One of: person, organization
      • handle string · Required
      • displayName string · Required
      • url string · Required

        The record's public page.

      • recordStatus object (ClaimedRecordStatus) · Required

        The tree stops here: this branch repeats a schema already open above it.

  • handles array · Required

    • item object (ClaimedLookupHandle)

      An asked (kind, handle) pair, echoed in the asked order. `found: false` is ONE shape — byte for byte — for an unknown, an unpublished, a taken-down, a reserved and an ill-shaped handle.

      • kind string · Required · One of: person, organization
      • handle string · Required
      • found boolean · Required
      • displayName string

        Present only when found.

      • url string

        Present only when found.

      • recordStatus object

        Present only when found.

        • status string · Required · One of: verified, reported, subject_confirmed, subject_corrected, disputed
        • label string · Required

          The status in words, as the page says it.

        • lastReviewed string (date-time), nullable · Required
        • document object, nullable · Required

          The tree stops here: this branch repeats a schema already open above it.

  • checkedAt string (date-time) · Required

    When this answer was read: every badge says when it was checked.

Response schema

No response body.

Response schema

No response body.

Response schema

No response body.

Response schema

No response body.

Response schema

No response body.

Response schema

• response object (FighterRecordResponse)

  • asOf string (date-time) · Required
  • sources array · Required

    • item object (PartnerSource)

      • key string · Required
      • name string · Required
      • country string · Required
      • region string, nullable · Required
  • notice string · Required
  • fighter object · Required

    • id string (uuid)
    • slug string
    • pagePath string
    • name string
    • aliases array

      • item string
    • hometown object (Hometown)

      • city string, nullable
      • region string, nullable
      • country string, nullable
    • division object, nullable

      • value string
      • publisher string
    • disciplines array

      • item string
    • claimedHandle string, nullable
  • record object · Required

    • status object · Required

      The status of the record as a whole: disputed if any fight is, else corrected if any fight is, else confirmed if the athlete is on file for the record, else verified.

      • status string · Required · One of: verified, reported, subject_confirmed, subject_corrected, disputed

        verified: read from the commission's own document. reported: compiled from the open web (the reported grade only). subject_confirmed: the athlete who claimed the record confirmed it. subject_corrected: a correction the athlete asked for was accepted. disputed: a dispute is open.

      • label string · Required

        The status in words, as a page says it.

      • lastReviewed string (date-time), nullable · Required

        The newest review on file: when the document was read, when the athlete confirmed the fight, when the athlete filed a correction that is still open, when an operator ruled on a correction (accepted or dismissed — a dismissal changes no status and is still a review); on a record, also when the athlete was put on file for it. Null when none is on file.

      • document object, nullable · Required

        The document the status rests on; null for a grade that has none. At record level, the newest document on the record.

        • url string · Required

          Relative to the base URL; streams the commission's own document.

        • sha256 string · Required
    • verified object · Required

      • tally object (VerifiedTally)

        • wins integer · Required
        • losses integer · Required
        • draws integer · Required
        • nc integer · Required
        • onFileFrom string (date), nullable · Required
        • label string · Required
        • bouts integer · Required
      • bouts array

        • item object (VerifiedBout)

          The tree stops here: this branch repeats a schema already open above it.

      • nextCursor string, nullable
    • reported object

      Present only when the reported grade is released on the server. Never summed into verified.

      • count integer
      • bouts array

        • item object (ReportedBout)

          The tree stops here: this branch repeats a schema already open above it.

    • statusLink object, nullable

      Additive: the signed receipt for `status`, so a row you store carries a token any holder of the published key can check offline. Null (never an error) when the signing key is unavailable or the page cannot be followed — the record is returned either way. A sandbox key answers null.

      • slug string · Required

        The LIVE slug the link was issued for (a page that moved is followed once).

      • fighterId string (uuid) · Required
      • recordStatus object (RecordStatusFlag) · Required

        The record status: DERIVED at read time from what is on file — the commission's document, the athlete's own confirmation, a correction the athlete filed and an operator accepted, a dispute that is open. It says only THAT a record or a fight is confirmed, corrected or disputed — never why, and never by whom. A dispute never removes the fact: a disputed fight stays in the list with its document. A value is never renamed or reused.

        • status string · Required · One of: verified, reported, subject_confirmed, subject_corrected, disputed

          verified: read from the commission's own document. reported: compiled from the open web (the reported grade only). subject_confirmed: the athlete who claimed the record confirmed it. subject_corrected: a correction the athlete asked for was accepted. disputed: a dispute is open.

        • label string · Required

          The status in words, as a page says it.

        • lastReviewed string (date-time), nullable · Required

          The newest review on file: when the document was read, when the athlete confirmed the fight, when the athlete filed a correction that is still open, when an operator ruled on a correction (accepted or dismissed — a dismissal changes no status and is still a review); on a record, also when the athlete was put on file for it. Null when none is on file.

        • document object, nullable · Required

          The tree stops here: this branch repeats a schema already open above it.

      • token string · Required

        The compact JWS: header.claims.signature, base64url.

      • expiresAt string (date-time) · Required
      • pageUrl string · Required

        Absolute: the subject's public page, carrying the token.

      • badgePath string · Required

        RELATIVE to the base URL: the SVG badge for this token.

      • vocabulary string · Required

        What the status value is a term of.

Response schema

No response body.

Response schema

No response body.

Response schema

No response body.

Response schema

• response object (BoutsPageResponse)

  • asOf string (date-time) · Required
  • sources array · Required

    • item object (PartnerSource)

      • key string · Required
      • name string · Required
      • country string · Required
      • region string, nullable · Required
  • notice string · Required
  • fighterId string
  • bouts array

    • item object (VerifiedBout)

      • date string (date) · Required
      • opponent object, nullable · Required

        • id string, nullable
        • slug string, nullable
        • name string
      • result string · Required · One of: W, L, D, NC, SCHEDULED, UNKNOWN
      • method string, nullable · Required
      • rounds object · Required

        • ended integer, nullable
      • discipline string · Required
      • amateur boolean · Required
      • commission string · Required
      • event object · Required

        • name string, nullable
        • city string, nullable
        • region string, nullable
        • date string (date)
      • document object · Required

        • url string

          Relative to the base URL; streams the commission's own document.

        • sha256 string
      • recordStatus object · Required

        This fight's record status. Its document is the same reference as `document`.

        • status string · Required · One of: verified, reported, subject_confirmed, subject_corrected, disputed

          verified: read from the commission's own document. reported: compiled from the open web (the reported grade only). subject_confirmed: the athlete who claimed the record confirmed it. subject_corrected: a correction the athlete asked for was accepted. disputed: a dispute is open.

        • label string · Required

          The status in words, as a page says it.

        • lastReviewed string (date-time), nullable · Required

          The newest review on file: when the document was read, when the athlete confirmed the fight, when the athlete filed a correction that is still open, when an operator ruled on a correction (accepted or dismissed — a dismissal changes no status and is still a review); on a record, also when the athlete was put on file for it. Null when none is on file.

        • document object, nullable · Required

          The tree stops here: this branch repeats a schema already open above it.

  • nextCursor string, nullable

Response schema

No response body.

Response schema

No response body.

Response schema

No response body.

Response schema

• response object (ClearanceResponse)

  • asOf string (date-time) · Required
  • sources array · Required

    • item object (PartnerSource)

      • key string · Required
      • name string · Required
      • country string · Required
      • region string, nullable · Required
  • notice string · Required
  • fighterId string · Required
  • state string · Required · One of: suspension_on_file, no_suspension_on_file, insufficient_coverage
  • suspensions array · Required

    • item object (Suspension)

      • until string (date)
      • reasonAsPrinted string, nullable
      • commission string
      • sourceDocument object

        • url string
        • sha256 string
      • readAt string (date-time)
      • bout object

        • date string (date)
        • opponentName string, nullable
      • current boolean
  • lastBout object, nullable · Required

    • date string
    • result string
    • method string, nullable
    • commission string
  • daysSinceLastBout integer, nullable · Required
  • koLossWithin90Days boolean · Required
  • coverage array · Required

    • item object (CoverageRow)

      • key string · Required
      • name string · Required
      • country string · Required
      • region string, nullable · Required
      • earliest string (date), nullable
      • latest string (date), nullable
      • bouts integer
  • regionAsked object, nullable · Required

    • region string
    • covered boolean
  • recordStatus object · Required

    The status of the fighter's record as a whole — the same answer `GET /fighters/{id}` gives in `record.status`.

    • status string · Required · One of: verified, reported, subject_confirmed, subject_corrected, disputed

      verified: read from the commission's own document. reported: compiled from the open web (the reported grade only). subject_confirmed: the athlete who claimed the record confirmed it. subject_corrected: a correction the athlete asked for was accepted. disputed: a dispute is open.

    • label string · Required

      The status in words, as a page says it.

    • lastReviewed string (date-time), nullable · Required

      The newest review on file: when the document was read, when the athlete confirmed the fight, when the athlete filed a correction that is still open, when an operator ruled on a correction (accepted or dismissed — a dismissal changes no status and is still a review); on a record, also when the athlete was put on file for it. Null when none is on file.

    • document object, nullable · Required

      The document the status rests on; null for a grade that has none. At record level, the newest document on the record.

      • url string · Required

        Relative to the base URL; streams the commission's own document.

      • sha256 string · Required

Response schema

No response body.

Response schema

No response body.

Response schema

No response body.

Response schema

• response object (ProviderClearanceResponse)

  The provider clearance answer: what NPPES and OIG LEIE say about one provider, as of the sources read. asOf/sources/notice are the envelope's own fields (asOf is this read's own time; sources names each source in the PartnerSource shape). listDate is the OIG LEIE file's own published date, the date `excluded` is answered as of. provenance lists the NPPES and OIG LEIE source files this answer was built from (issuer, file name, sha256 digest, publish date). receipt is minted over this response body (receipt itself excluded from what it digests).

  • asOf string (date-time) · Required
  • sources array · Required

    • item object (PartnerSource)

      • key string · Required
      • name string · Required
      • country string · Required
      • region string, nullable · Required
  • notice string · Required
  • npi string · Required
  • excluded oneOf · Required

    true when at least one NPI-matched exclusion is in force as of listDate (this read's date when listDate is null) — no reinstatement date, or one after it; "possible" when none is but at least one in-force name-only candidate is listed in possibleExclusions; false otherwise.

    • option 1 boolean
    • option 2 string · One of: possible
  • deactivated boolean · Required
  • exclusions array · Required

    • item object (ProviderExclusion)

      • grade string · Required · One of: published
      • lastName string, nullable · Required
      • firstName string, nullable · Required
      • middleName string, nullable · Required
      • businessName string, nullable · Required
      • general string, nullable · Required
      • specialty string, nullable · Required
      • npi string, nullable · Required
      • city string, nullable · Required
      • state string, nullable · Required
      • zip string, nullable · Required
      • exclusionType string, nullable · Required
      • exclusionDate string (date), nullable · Required
      • reinstatementDate string (date), nullable · Required
      • waiverDate string (date), nullable · Required
      • waiverState string, nullable · Required
  • possibleExclusions array · Required

    OIG LEIE rows with no NPI on file whose printed name matches this provider, listed only while in force as of listDate. A doubt, never a finding.

    • item object (ProviderPossibleExclusion)

      • grade string · Required · One of: possible
      • lastName string, nullable · Required
      • firstName string, nullable · Required
      • middleName string, nullable · Required
      • businessName string, nullable · Required
      • general string, nullable · Required
      • specialty string, nullable · Required
      • npi string, nullable · Required
      • city string, nullable · Required
      • state string, nullable · Required
      • zip string, nullable · Required
      • exclusionType string, nullable · Required
      • exclusionDate string (date), nullable · Required
      • reinstatementDate string (date), nullable · Required
      • waiverDate string (date), nullable · Required
      • waiverState string, nullable · Required
      • note string · Required

        Always the constant sentence 'A name match, not an NPI match. Check the list.' A name-only candidate is a separate array, never merged into `exclusions`: a candidate that may be someone else never removes what the list prints about this NPI.

  • listDate string (date), nullable · Required

    The OIG LEIE file's own published date, YYYY-MM-DD, or null when that source has never finished loading. The date `excluded` is answered as of.

  • provenance array · Required

    • item object (ProviderProvenance)

      • issuer string · Required · One of: NPPES, OIG_LEIE
      • fileName string · Required
      • sha256 string · Required
      • publishedAt string (date), nullable · Required

        The source file's own published date, YYYY-MM-DD, or null when that source has never finished loading.

  • receipt object (ClearanceReceipt) · Required

    • id string (uuid) · Required
    • issuedAt string (date-time) · Required
    • digest string · Required

      sha256 hex of the canonical (recursively key-sorted) JSON of the answer, with `receipt` itself omitted.

Response schema

No response body.

Response schema

No response body.

Response schema

No response body.

Response schema

No response body.

Response schema

No response body.

Response schema

• response object (IntakeResponse)

  • asOf string (date-time) · Required
  • sources array · Required

    • item object (PartnerSource)

      • key string · Required
      • name string · Required
      • country string · Required
      • region string, nullable · Required
  • notice string · Required
  • id string
  • partnerRef string
  • status string · One of: proposed, confirmed, cancelled, result
  • corners object

    • a string, nullable
    • b string, nullable
  • outcome string · One of: created, updated, validated
  • matched object, nullable

    • boutId string
    • leadDays integer, nullable
  • evidenceHash string

Response schema

No response body.

Response schema

No response body.

Response schema

No response body.

Response schema

• response object (UsageResponse)

  • asOf string (date-time) · Required
  • sources array · Required

    • item object (PartnerSource)

      • key string · Required
      • name string · Required
      • country string · Required
      • region string, nullable · Required
  • notice string · Required
  • key object

    • prefix string
    • sandbox boolean
    • scopes array

      • item string
  • partner object

    • name string
    • status string
  • budgets object

    • perMinute integer
    • monthlyQuota integer
    • global boolean
  • usage object

    • month string
    • calls integer
    • errors integer
    • byRoute array

      • item object

        • route string
        • calls integer
        • errors integer

Response schema

No response body.

Response schema

No response body.

Response schema

No response body.

Response schema

• response object (CorporaListResponse)

  • corpora array · Required

    • item object (CorpusDescription)

      • kind string · Required
      • description string · Required
      • searchHint string · Required
      • idExample string · Required
      • noun string, nullable

        Plural, lower-case, service-worded: "claimed people", "claimed organizations", "fighter records", "parcels". Null when the adapter names none.

      • count integer, nullable

        CHEAP: a pg_class.reltuples estimate, or an hourly-cached exact count. Never a live count(*) over parcels.

      • exact boolean

        false = count is an estimate (countWords then begins "about").

      • countWords string, nullable

        "about 18.8 million parcels" · "885 fighter records" · "no claimed organizations" — the service words it, the web prints it verbatim. Null when count or noun is null.

      • since string, nullable

        YYYY-MM-DD: the day the corpus's first row landed.

      • updatedAt string, nullable

        YYYY-MM-DD: the newest row's day.

      • homeUrl string, nullable

        Where that corpus's own page set lives.

      • browseUrl string, nullable

        A directory page of that corpus, if it has one; else null.

      • gap object, nullable

        CORPUS GAP INDEX R1 — this corpus's own scatter-risk and correction index, per CORPUS, never per record. Null when the index could not be computed this request.

        • kind string · Required

          The door kind this index describes (a GET /corpora kind) — per corpus, never per record.

        • risk object · Required

          The tree stops here: this branch repeats a schema already open above it.

        • correction object · Required

          The tree stops here: this branch repeats a schema already open above it.

        • asOf string · Required

          ISO timestamp this corpus's index was computed — per corpus, never per record.

Response schema

• response object (CorporaGapResponse)

  GET /corpora/gap — every visible corpus's scatter-risk and correction index, plus the rulings file that produced them. Per CORPUS, never per record or subject.

  • asOf string · Required

    ISO timestamp this index was computed.

  • rulings object · Required

    gap-rulings.yaml, parsed, verbatim — the owner's own hand-edited defaults; one edit plus a deploy changes every corpus's own numbers below.

  • formula object · Required

    • risk string · Required

      How each corpus's risk.value is computed, in words.

    • achieved string · Required

      gap-rulings.yaml's own correction.achieved formula string.

    • achievable string · Required

      gap-rulings.yaml's own correction.achievable formula string.

  • kinds array · Required

    One GapIndex per visible corpus kind, per CORPUS, never per record.

    • item object (GapIndex)

      CORPUS GAP INDEX R1 — a scatter-risk and correction index computed per CORPUS, never per record or subject.

      • kind string · Required

        The door kind this index describes (a GET /corpora kind) — per corpus, never per record.

      • risk object · Required

        • level string · Required · One of: minimal, low, medium, high, critical

          The published risk word for this corpus — the highest gap-rulings.yaml threshold its risk value clears, per corpus, never per record.

        • severity integer · Required · One of: 1, 2, 3, 4, 5

          Harm when a record of this corpus is missed, on the owner's 1-5 scale (gap-rulings.yaml severity.by_kind) — per corpus, never per record.

        • weight number · Required

          This corpus's severity level's own weight (gap-rulings.yaml severity.weights) — per corpus, never per record.

        • keepers integer · Required

          Distinct publishers holding this corpus's own catalogue entries — the fragmentation count, per corpus, never per record.

        • bucket integer · Required · One of: 0, 1, 2, 3, 4

          The fragmentation bucket this corpus's keepers count falls into (gap-rulings.yaml fragmentation.buckets) — per corpus, never per record.

        • value number · Required

          weight x (1 + bucket) for this corpus — the risk value its level word is read off, per corpus, never per record.

      • correction object · Required

        • achievable number · Required

          The share of this corpus's catalogue entries whose terms are already open or non_commercial (0..1) — per corpus, never per record.

        • achieved number · Required

          loaded share x (0.5 + 0.25 if a cross-register join exists + 0.25 if a correction rail exists); a fraction 0..1 — per corpus, never per record.

        • loadedShare number · Required

          Loaded entries over total family entries for this corpus (0..1) — per corpus, never per record.

        • publishableShare number · Required

          Entries with an open or non_commercial terms verdict over total family entries for this corpus (0..1) — per corpus, never per record.

        • joined boolean · Required

          Whether this corpus is cross-referenced against another held corpus (gap-rulings.yaml registration metadata) — per corpus, never per record.

        • rail boolean · Required

          Whether this corpus has a correction rail (a claim, dispute or flag path) today — per corpus, never per record.

      • asOf string · Required

        ISO timestamp this corpus's index was computed — per corpus, never per record.

Response schema

No response body.

Response schema

• response object (CorpusKeysPage)

  GET corpora/:kind/keys's own page — keyset, ORDER BY key ascending.

  • keys array · Required

    • item object

      • key string · Required
      • updatedAt string (date-time), nullable · Required

        The current row's created_at — null only when the row genuinely carries none.

  • next string, nullable · Required

    The last key of this page when it came back full (there may be more); null when this was the last page.

Response schema

No response body.

Response schema

No response body.

Response schema

No response body.

Response schema

No response body.

Response schema

• response object (CorpusSourcesPage)

  GET corpora/:kind/sources's own page — every provenance row for the kind's register, newest first (fetched_at DESC, id DESC); no cursor this round.

  • kind string · Required
  • sources array · Required

    • item object (SourceManifest)

      SOURCE RETENTION R1 — one stored (or store-refused) source. retained is true only when the bytes are on disk under their hash; retainedAt/staleAfter are omitted (never null) when there is nothing to say.

      • register string · Required
      • publisher string · Required
      • homeUrl string
      • sourceUrl string · Required
      • fileName string · Required
      • sha256 string · Required
      • bytes integer · Required
      • publishedAt string, nullable · Required
      • fetchedAt string · Required
      • terms object (RecordProvenanceTerms) · Required

        The tree stops here: this branch repeats a schema already open above it.

      • retained boolean · Required

        True only when the bytes behind sha256 are actually on disk under their hash.

      • retainedAt string (date-time)
      • staleAfter string (date-time)
      • supersedingPending boolean · Required

Response schema

No response body.

Response schema

No response body.

Response schema

No response body.

Response schema

No response body.

Response schema

• response object (RecordsSearchDocument)

  • results array · Required

    • item object (RecordsSearchResult)

      • id string · Required
      • title string · Required
      • url string · Required
      • kind string · Required

        The id's kind word (before the first colon), so the web groups results without parsing ids.

      • meta string

        An OPTIONAL one line, at most 160 characters, cheaply known about this hit (a fighter's disciplines and place, a parcel's jurisdiction and apn, a person's or an organization's handle). Absent when the adapter has nothing cheap to say.

  • notice string

    Present only when one source could not be searched: the other results stand, and this says so.

  • facets array · Required

    One entry per visible kind the fan-out searched (registry order), including a kind with zero hits. A kind whose adapter was unavailable this call is absent (named in `notice` instead).

    • item object (RecordsSearchFacet)

      • kind string · Required
      • hits integer · Required

        Results of this kind returned (at most cap).

      • cap integer · Required

        The registry's per-adapter cap (today 5).

Response schema

No response body.

Response schema

No response body.

Response schema

No response body.

Response schema

• response object (AnswerDocument)

  GET /records/answer's whole response — the record, in a sentence. Every sentence carries the record ids it rests on; a code checker drops anything the cited records did not print before this document is ever built.

  • query string · Required

    Trimmed, as searched.

  • state string · Required · One of: idle, answered, holdings_only, unavailable
  • sentences array · Required

    • item object (AnswerSentence)

      • text string · Required
      • ids array · Required

        Record ids from evidenceIds this sentence rests on — at least one, except the service-worded absence sentence's [] (it cites the holdings, not a record; always the last sentence).

        • item string
  • notFound array · Required

    Visible kinds the search returned nothing for, registry order.

    • item string
  • holdings array · Required

    The live holdings the absence clause was written from.

    • item object (AnswerHolding)

      • kind string · Required
      • noun string · Required
      • countWords string, nullable · Required

        "about 18.8 million parcels" · "885 fighter records" — the service words it, the web prints it verbatim. Null when GET corpora's own countWords would be.

  • renderer object, nullable · Required

    Null when no model call was made or the call failed (no items at all, a spent budget, a partial search, or a renderer outage); present on an unavailable answer whose call returned nothing the checker kept.

    • provider string · Required
    • model string · Required
  • evidenceIds array · Required

    Every record id in the evidence set, registry order, top-ranked first.

    • item string
  • evidence array · Required

    What the web needs to render each id as a link — no facts on the wire.

    • item object (AnswerEvidence)

      • id string · Required
      • kind string · Required
      • title string · Required
      • url string · Required
      • grade string · Required · One of: verified, reported, declared, published

        What the web needs to render this id as a link — no facts on the wire.

  • unavailable object, nullable · Required

    • reason string · Required · One of: budget, renderer, search
    • sentence string · Required

      A plain sentence, never a 5xx — the grouped results above still render on the web.

  • cached boolean · Required
  • checker object · Required

    Counts for this answer; reasons stay in the log, never on the wire.

    • rendered integer · Required

      Non-blank lines the model rendered for this answer (kept + rejected) — not the number kept alone.

    • rejected integer · Required

      Of those, the ones the checker dropped. Reasons stay in the log, never on the wire.

Response schema

No response body.

Response schema

No response body.

Response schema

No response body.

Response schema

• response oneOf

  • option 1 object (ConnectorDocument)

    • id string · Required
    • title string · Required
    • text string · Required
    • url string · Required
    • metadata object, open-ended · Required

      Adapter-specific beyond `kind`; the three built-in kinds carry recordStatus/citeAs/lastReviewed.

      • kind string · Required
  • option 2 object (RecordFieldsView)

    GET records/{id}?view=fields's own document — the door's structured record view, built by the adapter's EXISTING view builder, never a second derivation.

    • id string · Required
    • kind string · Required
    • key string · Required
    • title string · Required
    • url string · Required
    • status string
    • citeAs string · Required
    • fields array · Required

      • item object (RecordViewField)

        PUBLIC RECORD PAGES R1 — one row of RecordFieldsView.fields; the same EvidenceFact grade vocabulary facts() already carries, source dropped.

        • label string · Required
        • value string · Required
        • grade string · One of: verified, reported, declared, published
    • provenance object (RecordViewProvenance) · Required

      Ruling 1's provenance object. fileName/sha256 (and every other key besides register/publisher/fetchedAt) are optional — Ruling 3 allows an adapter with no single file/digest behind its record (fighter, claimed person/organization) to omit them rather than invent a value. sourceUrl/retainedAt/staleAfter (SOURCE RETENTION R1) are additive, omitted (never null) when unknown.

      • register string · Required
      • publisher string · Required
      • homeUrl string
      • fileName string
      • sha256 string
      • bytes oneOf

        • option 1 number
        • option 2 string
      • publishedAt string, nullable
      • fetchedAt string · Required
      • terms string
      • sourceUrl string

        Where the published file was fetched from. Present for every connector/spec corpus.

      • retainedAt string (date-time)

        When the write-once copy of the bytes behind sha256 was stamped — present only when the copy actually succeeded.

      • staleAfter string (date-time)

        fetchedAt plus the register's own refresh cadence — present only when the register states a cadence.

    • links array

      • item object (RecordViewLink)

        One link the record view names beside its fields.

        • label string · Required
        • url string · Required
  • option 3 object (RecordProvenanceView)

    GET records/{id}?view=provenance's own document — a SourceManifest (register, publisher, homeUrl?, sourceUrl, fileName, sha256, bytes, publishedAt, fetchedAt, terms, retained, retainedAt?, staleAfter?, supersedingPending) plus the record's id/kind/key and the verify recipe. download is null this round by design (serving bytes needs a public object store); the key is present so a client can feature-detect.

    • id string · Required
    • kind string · Required
    • key string · Required
    • register string · Required
    • publisher string · Required
    • homeUrl string
    • sourceUrl string · Required
    • fileName string · Required
    • sha256 string · Required
    • bytes integer · Required
    • publishedAt string, nullable · Required
    • fetchedAt string · Required
    • terms object (RecordProvenanceTerms) · Required

      SOURCE RETENTION R1 — the register's own reuse terms, as quoted in the spec. url/readOn are optional for a future adapter with no terms page of its own; every connector/spec corpus carries all three.

      • text string · Required
      • url string
      • readOn string

        YYYY-MM-DD — the date the terms were read.

    • retained boolean · Required

      True only when the bytes behind sha256 are actually on disk under their hash.

    • retainedAt string (date-time)
    • staleAfter string (date-time)
    • supersedingPending boolean · Required
    • verify object · Required

      • method string · Required · One of: sha256 of the published file
      • command string · Required

        curl -sL <sourceUrl> | sha256sum, with the record's own sourceUrl substituted.

    • download string, nullable · Required · One of:

      Always null this round — present so a client can feature-detect once serving bytes ships.

Response schema

No response body.

Response schema

No response body.

Response schema

• response object (RecordViewUnsupported)

  GET records/{id}?view=fields's 501 body: a kind whose adapter has no structured view — never a 500.

  • unsupported boolean · Required · One of:
  • id string · Required
  • kind string · Required

    The corpus kind the id parsed to.

Response schema

No response body.

Response schema

• response object (ReceiptSpecDocument)

  GET receipts/spec's own answer: the Receipt Specification v1 schema door. version the receipt object itself never carries; schema the emitted JSON Schema (draft 2020-12, served verbatim); document the human-readable specification page.

  • version string · Required · One of: 1
  • schema object, open-ended · Required

    The Receipt Specification v1 JSON Schema (draft 2020-12), byte-identical to the committed libs/connector/src/receipt/receipt.schema.json.

  • document string (uri) · Required

    The human-readable specification page.

Response schema

• response object (ReceiptValidationResponse)

  POST receipts/validate's own answer. valid is true exactly when no finding is severity:error.

  • valid boolean · Required
  • version string · Required · One of: 1
  • findings array · Required

    • item object (ReceiptFinding)

      One thing the validator checked and found wrong (error) or worth a second look (warning).

      • path string · Required

        The dotted path into the receipt this finding is about; empty string for the receipt as a whole.

      • rule string · Required

        schema | sha256-hex | date-format | terms-text | record-binding | fetched-after-published | source-length | source-length-unknown | fetch

      • message string · Required
      • severity string · Required · One of: error, warning
  • checked object · Required

    • schema boolean · Required

      Whether the schema check ran at all; false only when a {url} fetch never produced an object to check.

    • hashRecomputed boolean · Required

      Always false in v1: the validator never downloads the published file.

Response schema

No response body.

Response schema

No response body.

Response schema

No response body.

Response schema

No response body.

Response schema

• response object (ObservatoryRefreshesResponse)

  GET /observatory/refreshes — the refresh log, newest first, keyset-paged.

  • items array · Required

    • item object (ObservatoryRefreshItem)

      OBSERVATORY R1 — one connector_provenance row: a register and a file, never a subject or a person.

      • kind string, nullable · Required

        The spec registry's register -> subject kind; null when the register is unknown to the registry.

      • register string · Required
      • fileName string · Required
      • fetchedAt string (date-time) · Required
      • publishedAt string (date-time), nullable · Required
      • sha256 string · Required
      • bytes integer · Required
      • changed boolean · Required

        sha256 differs from the immediately preceding row of the same register; the first row of a register is always true.

      • retained boolean · Required

        source_stored_at IS NOT NULL — the fetched bytes are kept under the content-addressed store.

      • supersedingPending boolean · Required
  • next string, nullable · Required

    Opaque keyset cursor for the next page; null when this is the last page.

Response schema

No response body.

Response schema

No response body.

Response schema

• response object (ObservatoryCorrectionsResponse)

  GET /observatory/corrections — the corrections log, by month and corpus kind.

  • months array · Required

    • item object (ObservatoryCorrectionsMonth)

      OBSERVATORY R1 — one (month, kind) bucket of aggregate counts only: never an id, a subject or a person.

      • month string · Required
      • kind string · Required
      • flagsOpened integer · Required
      • flagsResolved integer · Required
      • claimsPublished integer · Required
      • disputesOpened integer · Required
      • disputesResolved integer · Required

Response schema

No response body.

Response schema

• response object (ObservatoryIssue)

  GET /observatory/state/latest and GET /observatory/state/{issue} — one frozen issue of The State of the Public Record, minted by a CLI and served verbatim; never recomputed at request time.

  • issue string · Required
  • issuedAt string (date-time) · Required
  • title string · Required
  • methodology object · Required

    • gap string · Required
    • gapRulingsSha256 string · Required
    • refresh string · Required
    • corrections string · Required
    • catalog string · Required
  • door object · Required

    • corpora integer · Required
    • records integer · Required
  • gap object (CorporaGapResponse) · Required

    GET /corpora/gap — every visible corpus's scatter-risk and correction index, plus the rulings file that produced them. Per CORPUS, never per record or subject.

    • asOf string · Required

      ISO timestamp this index was computed.

    • rulings object · Required

      gap-rulings.yaml, parsed, verbatim — the owner's own hand-edited defaults; one edit plus a deploy changes every corpus's own numbers below.

    • formula object · Required

      • risk string · Required

        How each corpus's risk.value is computed, in words.

      • achieved string · Required

        gap-rulings.yaml's own correction.achieved formula string.

      • achievable string · Required

        gap-rulings.yaml's own correction.achievable formula string.

    • kinds array · Required

      One GapIndex per visible corpus kind, per CORPUS, never per record.

      • item object (GapIndex)

        The tree stops here: this branch repeats a schema already open above it.

  • catalogue object · Required

    • cataloged integer · Required
    • public integer · Required
    • loadedDark integer · Required
    • specWritten integer · Required
    • probed integer · Required
    • candidate integer · Required
    • refused integer · Required
    • termsVerdicts object · Required

      • open integer · Required
      • non_commercial integer · Required
      • unknown integer · Required
      • refused integer · Required
    • openedSince array · Required

      • item object

        • register string · Required
        • publisher string · Required
        • on string (date) · Required
        • status string · Required
  • refresh object · Required

    • windowDays integer · Required
    • last30d object · Required

      • runs integer · Required
      • changed integer · Required
      • unchanged integer · Required
      • bytesRetained integer · Required
      • registers integer · Required
  • corrections object · Required

    • windowDays integer · Required
    • last30d object · Required

      • flagsOpened integer · Required
      • flagsResolved integer · Required
      • claimsPublished integer · Required
      • disputesOpened integer · Required
      • disputesResolved integer · Required
  • sources object · Required

    • gap string · Required
    • coverage string · Required
    • refreshes string · Required
    • corrections string · Required

Response schema

No response body.

Response schema

• response object (ObservatoryIssue)

  GET /observatory/state/latest and GET /observatory/state/{issue} — one frozen issue of The State of the Public Record, minted by a CLI and served verbatim; never recomputed at request time.

  • issue string · Required
  • issuedAt string (date-time) · Required
  • title string · Required
  • methodology object · Required

    • gap string · Required
    • gapRulingsSha256 string · Required
    • refresh string · Required
    • corrections string · Required
    • catalog string · Required
  • door object · Required

    • corpora integer · Required
    • records integer · Required
  • gap object (CorporaGapResponse) · Required

    GET /corpora/gap — every visible corpus's scatter-risk and correction index, plus the rulings file that produced them. Per CORPUS, never per record or subject.

    • asOf string · Required

      ISO timestamp this index was computed.

    • rulings object · Required

      gap-rulings.yaml, parsed, verbatim — the owner's own hand-edited defaults; one edit plus a deploy changes every corpus's own numbers below.

    • formula object · Required

      • risk string · Required

        How each corpus's risk.value is computed, in words.

      • achieved string · Required

        gap-rulings.yaml's own correction.achieved formula string.

      • achievable string · Required

        gap-rulings.yaml's own correction.achievable formula string.

    • kinds array · Required

      One GapIndex per visible corpus kind, per CORPUS, never per record.

      • item object (GapIndex)

        The tree stops here: this branch repeats a schema already open above it.

  • catalogue object · Required

    • cataloged integer · Required
    • public integer · Required
    • loadedDark integer · Required
    • specWritten integer · Required
    • probed integer · Required
    • candidate integer · Required
    • refused integer · Required
    • termsVerdicts object · Required

      • open integer · Required
      • non_commercial integer · Required
      • unknown integer · Required
      • refused integer · Required
    • openedSince array · Required

      • item object

        • register string · Required
        • publisher string · Required
        • on string (date) · Required
        • status string · Required
  • refresh object · Required

    • windowDays integer · Required
    • last30d object · Required

      • runs integer · Required
      • changed integer · Required
      • unchanged integer · Required
      • bytesRetained integer · Required
      • registers integer · Required
  • corrections object · Required

    • windowDays integer · Required
    • last30d object · Required

      • flagsOpened integer · Required
      • flagsResolved integer · Required
      • claimsPublished integer · Required
      • disputesOpened integer · Required
      • disputesResolved integer · Required
  • sources object · Required

    • gap string · Required
    • coverage string · Required
    • refreshes string · Required
    • corrections string · Required

Response schema

No response body.

Response schema

• response object (DoorStatusResponse)

  GET /door/status — the service's own self-measured availability: per-target availability and latency, corpus freshness, and incident runs. Cached in-process 60s.

  • asOf string (date-time) · Required
  • targets object · Required

    • corpora object (DoorTargetStatus) · Required

      • availability object (DoorTargetAvailability) · Required

        The tree stops here: this branch repeats a schema already open above it.

      • latency object (DoorTargetLatency) · Required

        The tree stops here: this branch repeats a schema already open above it.

    • search object (DoorTargetStatus) · Required

      • availability object (DoorTargetAvailability) · Required

        The tree stops here: this branch repeats a schema already open above it.

      • latency object (DoorTargetLatency) · Required

        The tree stops here: this branch repeats a schema already open above it.

    • provenance object (DoorTargetStatus) · Required

      • availability object (DoorTargetAvailability) · Required

        The tree stops here: this branch repeats a schema already open above it.

      • latency object (DoorTargetLatency) · Required

        The tree stops here: this branch repeats a schema already open above it.

  • corpora array · Required

    • item object (DoorCorpusStatus)

      DOOR DEPTH R1 — one visible kind: its holdings (same as GET corpora) plus its connector freshness, when it has a connector register at all.

      • kind string · Required
      • count integer, nullable · Required
      • updatedAt string (date-time), nullable · Required
      • staleAfter string (date-time), nullable · Required

        null when the register states no cadence, or there is no connector register for this kind at all.

      • fresh boolean, nullable · Required

        null when staleAfter is null.

      • lastRefresh object, nullable · Required

        null for a corpus with no connector register (fighter, parcel, ...).

        • at string (date-time) · Required
        • changed boolean · Required
  • incidents array · Required

    • item object (DoorIncident)

      DOOR DEPTH R1 — a run of >= 2 consecutive failed checks of one target, within the last 30 days.

      • from string (date-time) · Required
      • to string (date-time), nullable · Required

        null when the run is still open.

      • target string · Required · One of: corpora, search, provenance

Response schema

No response body.

Response schema

No response body.

Response schema

No response body.

Response schema

• response object (DoorChangelogResponse)

  GET /door/changelog — docs/changelog/CHANGELOG.json verbatim: every merge note's title/date/summary, newest first.

  • generatedAt string (date-time) · Required
  • count integer · Required
  • entries array · Required

    • item object (DoorChangelogEntry)

      DOOR DEPTH R1 — one docs/features/*-MERGE-NOTE.md, reduced to its title, date and "what shipped" summary.

      • title string · Required
      • date string (date) · Required

        YYYY-MM-DD, the first such date found anywhere in the note, read top-down.

      • summary string · Required

        Collapsed to one line, cut at 600 characters on a sentence boundary. Empty when the note yielded no summary.

      • note string · Required

        The merge note's own file basename — the site names the note, links nothing.

Response schema

No response body.