{
  "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.\n\nWhen 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.\n\nThis 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.\n\nEvery 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"
  }
}