{
  "openapi": "3.1.0",
  "info": {
    "title": "names.dev public search",
    "version": "2.0.0",
    "description": "Public, read-only naming and domain evidence. No purchase or private-account operations. Amounts are USD cents unless an evidence price specifies a different currency."
  },
  "servers": [
    {
      "url": "https://api.names.dev"
    }
  ],
  "security": [],
  "paths": {
    "/v2/search": {
      "post": {
        "operationId": "names_search",
        "summary": "Search a domain, a name or a product brief",
        "description": "Exact domains are checked first; bare labels check the same name across endings. Relevance is gated before brief alternatives are shown. Read registration and marketplace evidence separately. Provider issues and unknown observations are explicit. Acquisition happens at the source provider.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SearchRequest"
              },
              "example": {
                "query": "a social running app",
                "tlds": [
                  "com",
                  "app"
                ],
                "budgetMaxUsdCents": 50000,
                "limit": 6
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Search evidence. Empty results are valid; inspect diagnostics.issues.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query, domain, ending, limit or budget."
          },
          "413": {
            "description": "Request body exceeds 16 KiB."
          },
          "429": {
            "description": "Public rate limit reached. Wait before retrying.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "503": {
            "description": "Search or request limiting is unavailable."
          },
          "504": {
            "description": "Search deadline reached."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SearchRequest": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "minLength": 2,
            "maxLength": 2000,
            "description": "One exact domain, a bare name, or a product brief. Preserve the user's intended naming category."
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 12,
            "description": "Maximum names to return, from 1 to 12. Fewer strong names may be returned."
          },
          "tlds": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 2,
              "maxLength": 40,
              "pattern": "^\\.?[a-z0-9-]+(?:\\.[a-z0-9-]+)*$"
            },
            "maxItems": 12,
            "description": "Preferred domain endings, for example com, app or co.uk, in preference order."
          },
          "budgetMaxUsdCents": {
            "type": "integer",
            "minimum": 0,
            "maximum": 1000000000000,
            "description": "Maximum acquisition budget in USD cents; $500 is 50000. Prices remain provider observations."
          }
        },
        "required": [
          "query"
        ],
        "additionalProperties": false
      },
      "SearchResponse": {
        "type": "object",
        "properties": {
          "version": {
            "type": "number",
            "const": 2
          },
          "requestId": {
            "type": "string"
          },
          "query": {
            "type": "string"
          },
          "mode": {
            "type": "string",
            "enum": [
              "EXACT_DOMAIN",
              "LABEL_ONLY",
              "MIXED_LABEL_AND_BRIEF",
              "BRIEF"
            ]
          },
          "seedLabel": {
            "type": "string"
          },
          "exactDomain": {
            "type": "string"
          },
          "results": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "label": {
                  "type": "string"
                },
                "meaning": {
                  "type": "string"
                },
                "why": {
                  "type": "string"
                },
                "origin": {
                  "type": "string",
                  "enum": [
                    "requested",
                    "generated",
                    "inventory"
                  ]
                },
                "primaryDomain": {
                  "type": "string"
                },
                "fit": {
                  "type": "string",
                  "enum": [
                    "strong",
                    "good"
                  ]
                },
                "domains": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "domain": {
                        "type": "string"
                      },
                      "registration": {
                        "type": "object",
                        "properties": {
                          "kind": {
                            "type": "string",
                            "const": "registration"
                          },
                          "domain": {
                            "type": "string"
                          },
                          "provider": {
                            "type": "string"
                          },
                          "sourceTrust": {
                            "type": "string",
                            "enum": [
                              "LIVE_REGISTRAR",
                              "RDAP_DNS_HINT",
                              "SEARCH_HINT"
                            ]
                          },
                          "state": {
                            "type": "string",
                            "enum": [
                              "registerable",
                              "taken",
                              "blocked",
                              "looks_clear",
                              "unknown"
                            ]
                          },
                          "checkedAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "expiresAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "price": {
                            "type": "object",
                            "properties": {
                              "amountCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "currency": {
                                "type": "string"
                              },
                              "termYears": {
                                "type": "integer",
                                "exclusiveMinimum": 0
                              }
                            },
                            "required": [
                              "amountCents",
                              "currency"
                            ],
                            "additionalProperties": false
                          },
                          "renewalPrice": {
                            "type": "object",
                            "properties": {
                              "amountCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "currency": {
                                "type": "string"
                              },
                              "termYears": {
                                "type": "integer",
                                "exclusiveMinimum": 0
                              }
                            },
                            "required": [
                              "amountCents",
                              "currency"
                            ],
                            "additionalProperties": false
                          },
                          "url": {
                            "type": "string",
                            "format": "uri"
                          },
                          "note": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "kind",
                          "domain",
                          "provider",
                          "sourceTrust",
                          "state",
                          "checkedAt"
                        ],
                        "additionalProperties": false
                      },
                      "offers": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "kind": {
                              "type": "string",
                              "const": "listing"
                            },
                            "domain": {
                              "type": "string"
                            },
                            "provider": {
                              "type": "string"
                            },
                            "sourceTrust": {
                              "type": "string",
                              "const": "LIVE_MARKETPLACE"
                            },
                            "state": {
                              "type": "string",
                              "enum": [
                                "active",
                                "unknown",
                                "removed"
                              ]
                            },
                            "listingType": {
                              "type": "string",
                              "enum": [
                                "buy_now",
                                "make_offer",
                                "auction",
                                "lease_to_own",
                                "unknown"
                              ]
                            },
                            "checkedAt": {
                              "type": "string",
                              "format": "date-time"
                            },
                            "expiresAt": {
                              "type": "string",
                              "format": "date-time"
                            },
                            "price": {
                              "type": "object",
                              "properties": {
                                "amountCents": {
                                  "type": "integer",
                                  "minimum": 0
                                },
                                "currency": {
                                  "type": "string"
                                },
                                "termYears": {
                                  "type": "integer",
                                  "exclusiveMinimum": 0
                                }
                              },
                              "required": [
                                "amountCents",
                                "currency"
                              ],
                              "additionalProperties": false
                            },
                            "minimumOffer": {
                              "type": "object",
                              "properties": {
                                "amountCents": {
                                  "type": "integer",
                                  "minimum": 0
                                },
                                "currency": {
                                  "type": "string"
                                },
                                "termYears": {
                                  "type": "integer",
                                  "exclusiveMinimum": 0
                                }
                              },
                              "required": [
                                "amountCents",
                                "currency"
                              ],
                              "additionalProperties": false
                            },
                            "listingId": {
                              "type": "string"
                            },
                            "url": {
                              "type": "string",
                              "format": "uri"
                            },
                            "note": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "kind",
                            "domain",
                            "provider",
                            "sourceTrust",
                            "state",
                            "listingType",
                            "checkedAt",
                            "url"
                          ],
                          "additionalProperties": false
                        }
                      },
                      "status": {
                        "type": "string",
                        "enum": [
                          "registerable",
                          "listed",
                          "checkout_required",
                          "taken",
                          "blocked",
                          "unknown"
                        ]
                      }
                    },
                    "required": [
                      "domain",
                      "offers",
                      "status"
                    ],
                    "additionalProperties": false
                  }
                }
              },
              "required": [
                "id",
                "label",
                "origin",
                "primaryDomain",
                "domains"
              ],
              "additionalProperties": false
            }
          },
          "diagnostics": {
            "type": "object",
            "properties": {
              "elapsedMs": {
                "type": "number",
                "minimum": 0
              },
              "generatedCount": {
                "type": "integer",
                "minimum": 0
              },
              "evaluatedCount": {
                "type": "integer",
                "minimum": 0
              },
              "verifiedCount": {
                "type": "integer",
                "minimum": 0
              },
              "evaluationProvider": {
                "type": "string",
                "enum": [
                  "jev",
                  "unavailable",
                  "not_needed"
                ]
              },
              "deadlineReached": {
                "type": "boolean"
              },
              "cacheHit": {
                "type": "boolean"
              },
              "issues": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "provider": {
                      "type": "string"
                    },
                    "operation": {
                      "type": "string",
                      "enum": [
                        "check",
                        "inventory",
                        "generate",
                        "evaluate"
                      ]
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "provider",
                    "operation",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            },
            "required": [
              "elapsedMs",
              "generatedCount",
              "evaluatedCount",
              "verifiedCount",
              "evaluationProvider",
              "deadlineReached",
              "issues"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "version",
          "requestId",
          "query",
          "mode",
          "results",
          "diagnostics"
        ],
        "additionalProperties": false
      }
    }
  },
  "x-mcp": {
    "transport": "streamable-http",
    "url": "https://api.names.dev/mcp",
    "authentication": "none"
  }
}