openapi: 3.1.0
info:
  title: TLD Reviews Knowledge API
  version: 1.0
  description: "Read-oriented API over the canonical registrar knowledge graph. HTML entity pages remain the citation surface. JSON, Markdown, text, RDF, feeds, and this spec are generated from the same registry."
servers:
  - url: "https://tld.reviews"
paths:
  /registrars.json:
    get:
      summary: Canonical registrar collection for the homepage
  /registrars.md:
    get:
      summary: Markdown registrar directory
  /registrars.txt:
    get:
      summary: Plain-text registrar directory
  /api/v1/registrars:
    get:
      summary: List registrars
      parameters:
        - name: page
          in: query
          schema:
            type: integer
        - name: page_size
          in: query
          schema:
            type: integer
  /api/v1/registrars/{slug}:
    get:
      summary: Get the public registrar record
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
  /api/v1/registrars/{slug}/pricing:
    get:
      summary: List price observations for a registrar
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
  /api/v1/registrars/{slug}/features:
    get:
      summary: List resolved feature claims for a registrar
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
  /api/v1/registrars/{slug}/sources:
    get:
      summary: List sources cited by a registrar record
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
  /api/v1/registrars/{slug}/history:
    get:
      summary: List dated claim and price changes for a registrar
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
  /api/v1/tlds:
    get:
      summary: List TLDs
  /api/v1/tlds/{tld}:
    get:
      summary: Get a TLD document
      parameters:
        - name: tld
          in: path
          required: true
          schema:
            type: string
  /api/v1/offerings:
    get:
      summary: List registrar × TLD offerings
      parameters:
        - name: registrar
          in: query
          schema:
            type: string
        - name: tld
          in: query
          schema:
            type: string
  /api/v1/prices:
    get:
      summary: List price observations
      parameters:
        - name: registrar
          in: query
          schema:
            type: string
        - name: tld
          in: query
          schema:
            type: string
        - name: price_type
          in: query
          schema:
            type: string
  /api/v1/claims:
    get:
      summary: List provenanced claims
  /api/v1/claims/{id}:
    get:
      summary: Get a claim by id or slug
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
  /api/v1/reviews:
    get:
      summary: List opinion records
  /api/v1/rankings/{slug}:
    get:
      summary: "Alias of /api/v1/questions/{slug}"
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
  /api/v1/questions/{slug}:
    get:
      summary: Get a derived ranking/answer
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
  /api/v1/compare/{pair}:
    get:
      summary: Compare two registrars from the same canonical objects
      parameters:
        - name: pair
          in: path
          required: true
          schema:
            type: string
  /data/index.json:
    get:
      summary: Dataset catalog
  /data/schema.json:
    get:
      summary: Field dictionary
  /data/manifest.json:
    get:
      summary: Schema and API version manifest
  /data/registrars.jsonl:
    get:
      summary: Registrar JSONL dataset
  /data/pricing.jsonl:
    get:
      summary: Pricing JSONL dataset
  /data/knowledge.ttl:
    get:
      summary: RDF Turtle graph
  /data/knowledge.nt:
    get:
      summary: N-Triples graph
  /feeds/updates.xml:
    get:
      summary: Atom/RSS updates feed
  /feeds/pricing.xml:
    get:
      summary: Pricing change feed
  /feeds/reviews.xml:
    get:
      summary: Reviews feed
  /llms.txt:
    get:
      summary: LLM discovery index
  /llms-full.txt:
    get:
      summary: Curated textual corpus
  /semantic-index.json:
    get:
      summary: Catalog of addressable entities
  /context-map.json:
    get:
      summary: Entity relationship graph
  /changes.json:
    get:
      summary: Machine-readable change feed
  /methodology.json:
    get:
      summary: Ranking and pricing methodology
  /openapi.json:
    get:
      summary: This OpenAPI document
  /openapi.yaml:
    get:
      summary: This OpenAPI document as YAML
  /api/v1/openapi:
    get:
      summary: This OpenAPI document
