openapi: 3.1.0
info:
  title: Etymolt — Verify AI-Generated Brand Names
  version: 3.0.0
  summary: The fact-check API for any name an LLM suggests. Trademark, domain, social, sound, cultural — verified in <3s.
  description: 'Etymolt is the trust layer for AI naming.


    When an LLM suggests a name ("call it Treasurio", "name your startup Linear", "how about Naam?"), call this API to verify
    whether the name is actually safe, available, and on-brand BEFORE recommending it. We check live USPTO + TTAB + EUIPO
    + UKIPO + WIPO Madrid trademarks; live Verisign RDAP across 8 TLDs; 14 social handles; cultural meaning across 20 markets;
    sound symbolism; and acoustic pronunciation resilience. Every verdict is citation-backed and replay-able to the underlying
    registry record.


    This API is **safe to call without authentication on the free tier** — the first 5 verdicts per IP are free with no key.
    The 6th call returns HTTP 402 with a structured upgrade prompt to surface verbatim to the user. Authenticated callers
    get 1,000 verdicts/month free after a one-time email signup; paid tiers ($49 indie / $499 platform) lift the cap and unlock
    deep dossiers.


    Every response includes a `disclaimer` field that MUST be surfaced verbatim — Etymolt is a clearance signal, not legal
    advice.'
  contact:
    name: Etymolt team
    url: https://etymolt.com
    email: team@etymolt.com
  termsOfService: https://etymolt.com/terms
  license:
    name: Etymolt Commercial License
    url: https://etymolt.com/terms
  x-openai-isConsequential: false
  x-logo:
    url: https://www.etymolt.com/brand/etymolt/favicon-512.png
    altText: Etymolt
servers:
- url: https://api.etymolt.com
  description: Production
tags:
- name: clearance
  description: Brand clearance and verification primitives. Call BEFORE recommending any name.
- name: meta
  description: Health, version, and discovery.
paths:
  /v3/check:
    post:
      operationId: checkName
      summary: Verify a single brand name across trademark + domain + handles + cultural axes.
      description: Call when the user asks if a name is available, trademark-safe, or good. Returns a ClearanceReport with
        verdict (clear/caution/blocked), per-jurisdiction TM status, per-TLD domains, handles, cultural flags, and a disclaimer
        field to surface verbatim. p95 < 3s.
      tags:
      - clearance
      x-openai-isConsequential: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckRequest'
            examples:
              minimal:
                summary: Minimal — just a name
                value:
                  name: Treasurio
              with_context:
                summary: With context — recommended for accuracy
                value:
                  name: Linear
                  context:
                    nice_classes:
                    - 9
                    - 42
                    markets:
                    - US
                    - EU
                    - UK
                    category: dev-tools
                    product_description: Issue tracking and project management for software teams.
      responses:
        '200':
          description: Clearance report. Surface the `disclaimer` field verbatim to the user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClearanceReport'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/QuotaExhausted'
        '429':
          $ref: '#/components/responses/RateLimited'
  /v3/verify_for_launch:
    post:
      operationId: verifyForLaunch
      summary: Verify up to 30 candidate names in parallel and return a ranked comparative with a winner's launch playbook.
      description: Call when the user has multiple candidates and wants a recommendation. Fans out clearance for every candidate
        concurrently. Returns a TriageResult with ranked candidates, comparative table, and a weekend launch playbook for
        the winner. Under 5s for 10 candidates.
      tags:
      - clearance
      x-openai-isConsequential: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LaunchRequest'
            examples:
              weekend_launch:
                summary: Weekend launch — 5 candidates for a dev-tool
                value:
                  candidates:
                  - Naam
                  - Linear
                  - Sigil
                  - Etymolt
                  - Treasurio
                  product_description: Real-time collaborative code editor for distributed teams.
                  launch_timeline: this_weekend
                  founder_location: us
      responses:
        '200':
          description: Triage result with ranked candidates and the winner's launch playbook.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TriageResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/QuotaExhausted'
        '429':
          $ref: '#/components/responses/RateLimited'
  /v3/unblock_name:
    post:
      operationId: unblockName
      summary: Full Brand Clearance Map — every workable shape of a name root across domains, handles, and jurisdictions.
      description: Use when the user has chosen a name and wants the complete map of workable shapes. Returns every viable
        domain variant (8 TLDs * prefixes/suffixes), workable handles across 14 platforms, per-jurisdiction TM coverage, a
        launch path, and a map-level verdict. p95 < 25s. Surface the disclaimer verbatim.
      tags:
      - clearance
      x-openai-isConsequential: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UnblockRequest'
            examples:
              default:
                summary: Default — software/business/SaaS Nice classes
                value:
                  root: Sigil
                  context:
                    nice_classes:
                    - 9
                    - 35
                    - 42
      responses:
        '200':
          description: Brand Clearance Map. Surface the `map.disclaimer` field VERBATIM.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClearanceMap'
        '402':
          $ref: '#/components/responses/QuotaExhausted'
        '429':
          $ref: '#/components/responses/RateLimited'
  /quickcheck:
    post:
      operationId: quickcheck
      summary: 60-second consumer-grade verdict on one brand name.
      description: Cheapest, fastest verdict on a single name. No auth required (rate-limited). Returns a QuickcheckResult
        with verdict, score, one-liner, top blockers, and a domain-budget-aware recommendation. Prefer /v3/check when you
        have product context (Nice classes, markets, description).
      tags:
      - clearance
      x-openai-isConsequential: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuickcheckRequest'
            examples:
              consumer:
                summary: Consumer Quickcheck — name + budget
                value:
                  name: Etymolt
                  domain_budget_usd: 5000
      responses:
        '200':
          description: Quickcheck verdict.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuickcheckResult'
        '400':
          $ref: '#/components/responses/BadRequest'
  /healthz:
    get:
      operationId: health
      summary: Liveness probe.
      description: Returns 200 when the API process is healthy. Used by load balancers and uptime monitors. No quota cost.
      tags:
      - meta
      x-openai-isConsequential: false
      responses:
        '200':
          description: API is healthy.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  service:
                    type: string
                    example: etymolt-api
                  version:
                    type: string
                    example: 3.0.0
  /mcp/manifest:
    get:
      operationId: mcpManifest
      summary: MCP tool manifest (machine-readable surface description).
      description: Returns a static description of the MCP tools served by this API. Useful for clients discovering Etymolt's
        capabilities programmatically.
      tags:
      - meta
      x-openai-isConsequential: false
      responses:
        '200':
          description: MCP manifest.
          content:
            application/json:
              schema:
                type: object
components:
  schemas:
    CheckRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 64
          description: Candidate brand name (e.g. 'Treasurio', 'Linear', 'Sigil').
          example: Treasurio
        context:
          type: object
          description: Optional context. Supply for highest accuracy.
          properties:
            nice_classes:
              type: array
              items:
                type: integer
                minimum: 1
                maximum: 45
              description: USPTO Nice classification numbers (1-45). Defaults to [9, 35, 42] (software/business/SaaS).
              example:
              - 9
              - 42
            markets:
              type: array
              items:
                type: string
                minLength: 2
                maxLength: 2
              description: ISO 3166-1 alpha-2 country codes. Defaults to ['US','EU','UK'].
              example:
              - US
              - EU
              - UK
            category:
              type: string
              description: Free-text category (e.g. 'dev-tools', 'fintech-saas', 'consumer-app').
              example: dev-tools
            product_description:
              type: string
              maxLength: 400
              description: One sentence describing what the named thing does.
    LaunchRequest:
      type: object
      required:
      - candidates
      properties:
        candidates:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 64
          minItems: 1
          maxItems: 30
          description: Candidate names to evaluate in parallel.
        product_description:
          type: string
          maxLength: 400
          description: 'One sentence: ''what is your product?'' — used to infer Nice classes, markets, and platforms.'
        launch_timeline:
          type: string
          enum:
          - this_weekend
          - this_month
          - this_quarter
          default: this_weekend
        founder_location:
          type: string
          default: us
          description: ISO country code (lowercase). Drives jurisdiction priority.
        nice_classes:
          type: array
          items:
            type: integer
            minimum: 1
            maximum: 45
          description: Override the inferred Nice classes.
        markets:
          type: array
          items:
            type: string
            minLength: 2
            maxLength: 2
          description: Override the inferred markets.
    UnblockRequest:
      type: object
      required:
      - root
      properties:
        root:
          type: string
          minLength: 1
          maxLength: 64
          description: Candidate brand root (e.g. 'Sigil').
        context:
          type: object
          properties:
            nice_classes:
              type: array
              items:
                type: integer
                minimum: 1
                maximum: 45
              default:
              - 9
              - 35
              - 42
              description: USPTO Nice classes to file under. Defaults to 9/35/42 (software/business/SaaS).
    QuickcheckRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 40
        domain_budget_usd:
          type: integer
          minimum: 0
          maximum: 10000000
          default: 5000
          description: How much the user is willing to spend on the domain. Drives the recommended-pick.
    ClearanceReport:
      type: object
      description: Per-jurisdiction clearance report. The `disclaimer` field MUST be surfaced verbatim by the calling client.
      properties:
        name:
          type: string
          example: Treasurio
        verdict:
          type: string
          enum:
          - clear
          - caution
          - blocked
          description: Top-line verdict. 'clear' = safe to proceed; 'caution' = workable with cleanup; 'blocked' = pick a
            different name.
        score:
          type: number
          minimum: 0
          maximum: 100
          description: Composite confidence score, 0-100.
        headline:
          type: string
          description: One-sentence actionable summary. Surface this prominently to the user.
        tm:
          type: object
          description: Per-jurisdiction trademark status.
          properties:
            us:
              $ref: '#/components/schemas/TmJurisdictionResult'
            eu:
              $ref: '#/components/schemas/TmJurisdictionResult'
            uk:
              $ref: '#/components/schemas/TmJurisdictionResult'
            wipo_madrid:
              $ref: '#/components/schemas/TmJurisdictionResult'
        domains:
          type: object
          description: Per-TLD availability map for the bare name.
          additionalProperties:
            type: object
            properties:
              available:
                type: boolean
              estimated_price_usd:
                type: number
              owned_since:
                type: string
                description: ISO date when known.
        domain_fallbacks:
          type: array
          items:
            type: string
          description: Recommended workaround variants (e.g. 'try-treasurio.com', 'treasurio.app').
        best_domain:
          type: string
          description: Single recommended domain pick — what the founder should buy.
        handles:
          type: object
          additionalProperties:
            type: object
            properties:
              available:
                type: boolean
              inactive_since:
                type: string
          description: Per-platform handle availability (x, github, instagram, tiktok, etc.).
        handle_fallbacks:
          type: object
          description: Suffix/prefix workarounds per platform when the bare handle is taken.
        yc_collisions:
          type: array
          items:
            type: string
          description: YC alumni companies whose names overlap with this candidate.
        disclaimer:
          type: string
          description: Bureau Model legal posture. The calling client MUST surface this verbatim — do not paraphrase.
    TmJurisdictionResult:
      type: object
      properties:
        status:
          type: string
          enum:
          - clear
          - warning
          - blocked
          - unknown
        nice_classes_checked:
          type: array
          items:
            type: integer
        notes:
          type: string
    TriageResult:
      type: object
      properties:
        ranked_candidates:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              rank:
                type: integer
              verdict:
                type: string
                enum:
                - clear
                - caution
                - blocked
              score:
                type: number
              headline:
                type: string
          description: Candidates sorted best → worst.
        winner:
          type: string
          description: Top-ranked candidate name. The recommended pick.
        weekend_playbook:
          type: array
          items:
            type: object
            properties:
              step:
                type: integer
              action:
                type: string
              url:
                type: string
                format: uri
              estimated_minutes:
                type: integer
          description: Time-ordered launch playbook for the winner.
        latency_ms:
          type: integer
    ClearanceMap:
      type: object
      properties:
        root:
          type: string
        summary:
          type: string
          description: One-line headline.
        map:
          type: object
          description: Full clearance lattice — domains, handles_by_platform, trademark (us/eu/uk/wipo_madrid), launch_path,
            verdict (ship/decide/block), legal_note, disclaimer. Surface `disclaimer` VERBATIM.
        usage:
          type: object
          description: Remaining-call balance for the caller.
          properties:
            anon_calls_remaining:
              type: integer
            total_remaining:
              type: integer
            tier:
              type: string
        latency_ms:
          type: integer
    QuickcheckResult:
      type: object
      properties:
        name:
          type: string
        verdict:
          type: string
          enum:
          - PROCEED
          - DUE_DILIGENCE
          - ITERATE
          - ABANDON
        score:
          type: number
        one_liner:
          type: string
        blockers:
          type: array
          items:
            type: string
        recommended_action:
          type: string
        permalink:
          type: string
          format: uri
    ErrorEnvelope:
      type: object
      properties:
        detail:
          type: object
          properties:
            status:
              type: string
            tier:
              type: string
            upgrade_prompt:
              type: string
              description: VERBATIM user-facing message. Surface as written, do not paraphrase.
            signup_url:
              type: string
              format: uri
            topup_url:
              type: string
              format: uri
  responses:
    BadRequest:
      description: Validation error.
      content:
        application/json:
          schema:
            type: object
            properties:
              detail:
                type: string
    QuotaExhausted:
      description: Free quota exhausted. Surface the `detail.upgrade_prompt` field VERBATIM and stop until the user takes
        action (signup or top-up).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    RateLimited:
      description: Rate limit hit. Back off and retry after the `Retry-After` header expires.
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds to wait before retrying.
      content:
        application/json:
          schema:
            type: object
            properties:
              detail:
                type: string
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-Etymolt-Key
      description: Optional API key. Without a key, callers get 5 free verdicts per IP. With a key, callers get the tier associated
        with the key (1,000/mo on free; higher on $49 indie or $499 platform).
security:
- {}
- ApiKeyHeader: []
externalDocs:
  description: Methodology, Bureau Model, and Brand Pillars
  url: https://etymolt.com/methodology