Just Domain Tlds API

openapi: 3.2.0
info:
  title: just-domain-mcp Tlds API
  version: 0.1.0
tags:
- name: Tlds
paths:
  /api/v1/tlds:
    get:
      summary: Get Tld Catalog
      operationId: get_tld_catalog_api_v1_tlds_get
      parameters:
      - name: refresh
        in: query
        required: false
        schema:
          type: boolean
          description: Bypass the in-process cache and rebuild.
          default: false
          title: Refresh
        description: Bypass the in-process cache and rebuild.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Tlds
  /api/v1/tlds/{tld}/requirements.schema.json:
    get:
      summary: What this registry demands of a registrant, as JSON Schema
      description: 'Serve one ending''s registrant-requirement schema, verbatim.


        Public, unauthenticated and cheap - it reads a file that ships with the

        package, makes no provider call, and so needs no rate limit of its own.


        **Why this is a URL rather than a field on the catalogue row.** The

        catalogue says `.us` needs `us_nexus_category`; it cannot say that the

        value must be one of five specific codes, what each code means, or which

        of them require a country. Publishing the real JSON Schema means an agent

        can BUILD the checkout form - correctly, and without asking us - and it

        means our own form and the published contract are the same document

        instead of two things that drift.


        The response is the schema plus the honesty envelope around it:

        `confidence` (`provisional` / `confirmed`) with a `confidence_note` says

        whether these field names were confirmed against a live registration or

        written from published documentation, `source_type` says what kind of

        source they came from, and `sellable` says whether satisfying the schema is

        currently enough to buy the ending. **They are all at their weakest value

        today for every ending here**, and a caller must not read "a schema exists"

        as "this is buyable" - `POST /api/buy-domain` will still refuse. See

        `catalog.may_register`.


        **The envelope names no supplier, deliberately.** This endpoint is public

        and unauthenticated, and it used to publish `provisional_reason` and

        `source` verbatim from the data file - which named the registrar we buy

        through and, in the `.us` entry, ran a paragraph of operator notes about

        what we had not yet confirmed. That provenance is kept on the entry and is

        never served; `tests/test_tld_requirements.py` fails the build if it comes

        back.'
      operationId: get_tld_requirements_schema_api_v1_tlds__tld__requirements_schema_json_get
      parameters:
      - name: tld
        in: path
        required: true
        schema:
          type: string
          description: 'Bare ending, no leading dot. Multi-label endings included: ''us'', ''co.il''.'
          title: Tld
        description: 'Bare ending, no leading dot. Multi-label endings included: ''us'', ''co.il''.'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Tlds
components:
  schemas:
    CatalogOut:
      properties:
        currency:
          type: string
          title: Currency
        count:
          type: integer
          title: Count
          description: Endings in this response.
        catalog_count:
          type: integer
          title: Catalog Count
          description: Endings the registrar listed, before the offered-set policy and the eligibility rules ran. The gap against `count` is the visible size of what we could sell but do not.
          default: 0
        sellable_count:
          type: integer
          title: Sellable Count
          default: 0
        policy_version:
          type: string
          title: Policy Version
          default: ''
        policy_source:
          type: string
          title: Policy Source
          default: ''
        synced_at:
          type: string
          title: Synced At
          default: ''
        source:
          type: string
          title: Source
          default: ''
        tlds:
          items:
            $ref: '#/components/schemas/CatalogTldOut'
          type: array
          title: Tlds
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
      type: object
      required:
      - currency
      - count
      title: CatalogOut
    CatalogTldOut:
      properties:
        tld:
          type: string
          title: Tld
          description: 'Bare ending, no leading dot: ''com'', ''co.il''.'
        register_minor:
          type: integer
          title: Register Minor
          description: 'What ONE registration term costs, in minor units, at the time of this response. Registry prices can change, and checkout shows the total before payment. NOT a per-year rate: see `term_years`.'
        register_formatted:
          type: string
          title: Register Formatted
        currency:
          type: string
          title: Currency
        renew_minor:
          anyOf:
          - type: integer
          - type: 'null'
          title: Renew Minor
          description: What ONE further term would cost at today's rate. None when the registrar did not quote one, which is what makes a multi-year order unpriceable.
        renew_formatted:
          anyOf:
          - type: string
          - type: 'null'
          title: Renew Formatted
        term_years:
          type: integer
          title: Term Years
          description: Length in years of ONE registration term. 1 on almost every ending, 2 on .ai, whose registry mandates a two-year term.
          default: 1
        min_period:
          anyOf:
          - type: integer
          - type: 'null'
          title: Min Period
        max_period:
          anyOf:
          - type: integer
          - type: 'null'
          title: Max Period
        requires_additional_data:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Requires Additional Data
          description: 'Does this registry demand extra registrant data? TRI-STATE, and the third state is the point: true / false / **null = the registrar never told us**. Null is NOT ''no'' - the sell gate (`catalog.may_register`) fails closed on it, which is why such a row is listed with `sellable: false`. A consumer that reads null as false will show an ending as safe to buy that we refuse to charge for.'
        required_fields:
          items:
            type: string
          type: array
          title: Required Fields
          description: Extra registrant fields this registry demands. These are OUR checkout form keys, not a registrar's wire field names.
        requirements_schema_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Requirements Schema Url
          description: 'The machine-readable version of `required_fields`: a JSON Schema describing exactly what this registry demands, with allowed values. Null when we have not published one. Non-null is a promise the document exists - build a checkout form from it.'
        requirement_note:
          anyOf:
          - type: string
          - type: 'null'
          title: Requirement Note
        tier:
          type: string
          title: Tier
          description: 'Eligibility: ''open'' (standard contacts only), ''extra_data'' (registry needs more registrant data), ''restricted'' (not sold), ''unknown''.'
        sellable:
          type: boolean
          title: Sellable
          description: Buyable today. An 'extra_data' ending is listed honestly with its requirement note but is NOT buyable until checkout can collect those fields and a failed registration auto-refunds.
        synced_at:
          type: string
          title: Synced At
      type: object
      required:
      - tld
      - register_minor
      - register_formatted
      - currency
      - tier
      - sellable
      - synced_at
      title: CatalogTldOut
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError