{"openapi":"3.0.3","info":{"title":"User-Agent & AI Bot Parser API","version":"1.0.0","description":"Parses User-Agent strings into browser, OS, and device metadata and classifies official AI crawlers, search bots, scrapers, and headless browsers."},"servers":[{"url":"https://api.tinplate.dev","description":"Production Edge Gateway"}],"components":{"schemas":{"UaBotParseResponse":{"type":"object","properties":{"user_agent":{"type":"string"},"is_bot":{"type":"boolean","example":true},"is_ai_bot":{"type":"boolean","example":true},"category":{"type":"string","enum":["human","ai_crawler","ai_assistant","search_crawler","social_preview","seo_crawler","monitoring","http_client","headless_browser","unknown_bot"],"example":"ai_crawler"},"bot":{"type":"object","nullable":true,"properties":{"name":{"type":"string","example":"GPTBot"},"operator":{"type":"string","example":"OpenAI"},"category":{"type":"string","enum":["human","ai_crawler","ai_assistant","search_crawler","social_preview","seo_crawler","monitoring","http_client","headless_browser","unknown_bot"],"example":"ai_crawler"},"intent":{"type":"string","enum":["training","search_index","user_fetch","preview","seo","monitoring","automation","unknown"],"example":"training"},"docs_url":{"type":"string","nullable":true,"example":"https://platform.openai.com/docs/bots"},"rule_id":{"type":"string","example":"ai_openai_gptbot"}},"required":["name","operator","category","intent","docs_url","rule_id"]},"client":{"type":"object","properties":{"browser":{"type":"object","properties":{"name":{"type":"string","nullable":true,"example":"Chrome"},"version":{"type":"string","nullable":true,"example":"130.0.0.0"}},"required":["name","version"]},"os":{"type":"object","properties":{"name":{"type":"string","nullable":true,"example":"Linux"},"version":{"type":"string","nullable":true,"example":null}},"required":["name","version"]},"engine":{"type":"string","nullable":true,"example":"Blink"},"device_type":{"type":"string","enum":["desktop","mobile","tablet","bot","server","unknown"],"example":"bot"}},"required":["browser","os","engine","device_type"]},"rules_version":{"type":"string","example":"2026.11.1"}},"required":["user_agent","is_bot","is_ai_bot","category","bot","client","rules_version"]},"UaBotParseRequest":{"type":"object","properties":{"user_agent":{"type":"string","minLength":1,"maxLength":2048,"example":"Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; GPTBot/1.2; +https://openai.com/gptbot","description":"Raw HTTP User-Agent header value (max 2048 characters)."}},"required":["user_agent"]},"ResponseMeta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","format":"uuid"},"ms":{"type":"integer","minimum":0},"version":{"type":"string","example":"1.0.0"}}},"ErrorEnvelope":{"type":"object","required":["ok","error","meta"],"properties":{"ok":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"invalid_input"},"message":{"type":"string","example":"Request body failed validation"}}},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}}},"parameters":{}},"paths":{"/v1/ua-bot-parser":{"post":{"tags":["08_UA_BOT_PARSER"],"summary":"Parse a User-Agent string and classify AI/search/automation bots","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UaBotParseRequest"}}}},"responses":{"200":{"description":"Parsed User-Agent and bot classification","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/UaBotParseResponse"},"meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["ok","data","meta"]}}}},"400":{"description":"Invalid input or malformed JSON request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid authentication credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request payload exceeds subscribed plan byte cap","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}