API docs

JSON over HTTPS. CORS is open (*). Errors are {"error":{"code","message"}} with a matching HTTP status. Version 0.3.2, bot list 2026-10-08 (151 bots, 43 AI crawlers, 9 of them AI agent names acting for a user: 8 current plus the retired Google-NotebookLM), parser ua-parser-js 1.0.41.

POST /v1/parse (recommended) · GET /v1/parse

curl -X POST -H "content-type: application/json" \
  -d '{"ua":"Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; GPTBot/1.1; +https://openai.com/gptbot"}' \
  https://<host>/v1/parse

curl "https://<host>/v1/parse?ua=Mozilla%2F5.0%20(compatible%3B%20ClaudeBot%2F1.0)"
curl "https://<host>/v1/parse"            # no ua → parses the request's own User-Agent header

• Body: {"ua":"…"}, Content-Type: application/json, at most 8 KB (413 above). Omitting ua (e.g. {}) parses the caller's own User-Agent.
• ua must be 1–2,048 characters.
• Response header X-Cache: HIT|MISS shows the per-isolate result cache (keyed by SHA-256 of the UA).

Response:

{
  "ua": "Mozilla/5.0 … GPTBot/1.1; +https://openai.com/gptbot",
  "browser": { "name": "WebKit", "version": "537.36", "major": "537" },
  "engine":  { "name": "WebKit", "version": "537.36" },
  "os":      { "name": null, "version": null },
  "device":  { "type": "bot", "vendor": null, "model": null },
  "cpu":     { "architecture": null },
  "is_bot": true,
  "is_ai_crawler": true,
  "is_ai_agent": false,
  "is_search_crawler": false,
  "bot": {
    "is_bot": true, "is_ai_crawler": true, "is_ai_agent": false, "is_search_crawler": false,
    "category": "ai_crawler", "category_label": "AI crawler",
    "name": "GPTBot", "operator": "OpenAI", "ai_purpose": "training", "ai_agent_kind": null,
    "robots_token": "GPTBot", "token_only": false,
    "info_url": "https://developers.openai.com/api/docs/bots",
    "match": "list", "verified": false
  },
  "list_version": "2026-10-08",
  "parser": "ua-parser-js 1.0.41"
}

POST /v1/bulk (API key)

curl -X POST -H "Authorization: Bearer up_live_…" -H "content-type: application/json" \
  -d '{"uas":["Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)","curl/8.5.0"]}' \
  https://<host>/v1/bulk

• Needs an API key (401 api_key_required without one). Body at most 64 KB; at most 100 UAs per call. Free keys may send up to 10 per call (403 plan_bulk_limit above that); larger batches are the planned paid-plan shape.
• Each UA counts as one lookup against the key's daily quota; the call is all-or-nothing.
• Response: {"count", "list_version", "results":[…same object as /v1/parse…]}.

Other endpoints

• GET /v1/bots: the curated bot list (name, category, operator, AI purpose, is_ai_agent, ai_agent_kind, robots token, docs link). Not counted.
• GET /v1/meta: version, build, list version, counts (bot_count, ai_crawler_count, ai_agent_count) and limits.
• GET /health: {"ok":true,…}.
• POST /mcp: remote MCP server for AI agents (tool parse_user_agent, same keys and limits as /v1/parse); see For AI agents. Machine-readable: llms.txt · OpenAPI 3.1 spec.

AI agents acting for a user

Rule: is_ai_agent is true only for User-Agents that the operator's own documentation describes as acting live for an individual end user of an AI assistant or agent product. That covers both user-initiated fetchers (ai_purpose: user_fetch, ai_agent_kind: fetch) and agents that navigate and act (ai_purpose: agent, ai_agent_kind: browsing). It is false for bulk or scheduled crawls (training, search indexing), for business-side crawlers labelled agent (Google-CloudVertexBot, FirecrawlAgent), and for legacy tokens the operator no longer documents (Claude-Web, cohere-ai).

9 names: 8 current plus the retired Google-NotebookLM name (Google now documents Google-GeminiNotebook; the old name is still detected so older logs classify correctly).

What UAParse cannot see: many personal agents browse in a real browser and publish no User-Agent token. Meta says its Muse agent uses "a real up-to-date Chromium based browser"; as of 2026-10-08 Meta publishes no Muse User-Agent. We also found no operator-published User-Agent token for ChatGPT Atlas agent mode or Perplexity Comet. These requests are reported as a normal human browser. That is a limit of User-Agent parsing, not a bug. UAParse is independent and not affiliated with Meta, OpenAI, Google, Anthropic, Amazon, Perplexity or Mistral AI.

Signed agents (not checked): some operators identify agent traffic with HTTP Message Signatures (RFC 9421, the IETF "Web Bot Auth" work) instead of a User-Agent token. OpenAI's ChatGPT cloud browser sends Signature-Agent: "https://chatgpt.com", and Google is experimenting with the https://agent.bot.goog identity. Meta, Sierra and partners announced the Personal Agent Protocol (OAuth-based) on 2026-10-06, but its v0.1 specification has not been published yet and defines no User-Agent token. UAParse only reads the User-Agent string, so it does not verify signatures or OAuth sessions, and verified stays false.

Limits

Keyed responses carry X-Quota-Limit, X-Quota-Remaining and X-Quota-Reset. Error codes: 400 missing_ua/empty_ua/ua_too_long/invalid_body/invalid_json/too_many_uas/invalid_ua_item, 401 invalid_api_key/api_key_required, 403 plan_bulk_limit, 405, 413 body_too_large, 415, 429 rate_limited/quota_exceeded/daily_capacity_reached/too_many_failed_auth, 503.

Pricing

Free: web tool, anonymous API (about 20/min), free key with 1,000 lookups/day. Keys are issued by request during early access: digitalpromohub.support@gmail.com.

Pro (planned, about $9/month, not on sale yet): 50,000 lookups/day and bulk up to 100 UAs per call.

Limitations

• User-Agent strings are self-reported. A bot can claim to be Chrome and a person can claim to be GPTBot. Use IP / reverse-DNS verification from the operator's docs before you trust a crawler claim.
• Browsers are reducing UA detail (Chrome UA reduction): Windows 11 reports "Windows NT 10.0", macOS versions freeze at 10.15.7, Android device models show as "K". UAParse reports what the string contains.
• The bot list is curated and dated (2026-10-08). New crawlers are missed until added; a generic heuristic flags unlisted UAs containing bot / crawler / spider as unknown_bot.
• AI agents that browse in a real browser and publish no token (e.g. Meta Muse; Meta publishes no Muse User-Agent) are indistinguishable from people here; see AI agents. UAParse is independent and not affiliated with Meta, OpenAI, Google, Anthropic, Amazon, Perplexity or Mistral AI.
• For bots, ua-parser-js may still report an engine or "browser" (e.g. WebKit) taken from the string.

Privacy

See /privacy. Short version: no logs, no cookies, no analytics; User-Agent strings are never stored with IP addresses.