{"openapi":"3.0.0","info":{"title":"userstack","description":"userstack offers a real-time, easy-to-use REST API interface capable of parsing User-Agent strings to accurately detect device, browser and operating system information.","version":"1.0.0"},"servers":[{"url":"https://api.userstack.com"}],"paths":{"/detect":{"get":{"tags":["Endpoints"],"summary":"Userstack :- /detect (Single User-Agent Lookup)","description":"Look up a single User-Agent string by appending the ua parameter along with your API access key. Returns device, browser and operating system information.","operationId":"userstackDetect","parameters":[{"name":"access_key","in":"query","description":"Your API access key, available in your account dashboard.","required":true,"schema":{"type":"string"}},{"name":"ua","in":"query","description":"Specify the User-Agent string to be looked up.","required":true,"schema":{"type":"string","example":"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/89.0.4389.90 Safari/537.36"}},{"name":"callback","in":"query","description":"Specify a JSONP callback function name according to the JSONP Callbacks section.","required":false,"schema":{"type":"string","example":"Function_name"}},{"name":"fields","in":"query","description":"Specify API response field(s) according to the Specify Response Fields section.","required":false,"schema":{"type":"string"}},{"name":"output","in":"query","description":"Set to json or xml to choose between output formats.","required":false,"schema":{"type":"string","enum":["json","xml"],"example":"json"}},{"name":"legacy","in":"query","description":"Set to 1 to enable a legacy response format identical to the former UserAgent API response structure.","required":false,"schema":{"type":"integer","format":"int32","enum":[0,1],"example":1}}],"responses":{"200":{"description":"Successful User-Agent parse. Returns application/json (default) or application/xml.","content":{"application/xml":{"schema":{"type":"string"}},"application/json":{"schema":{"$ref":"#/components/schemas/UserAgentResponse"},"examples":{"example":{"summary":"Full response example (abridged)","value":{"ua":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36","type":"browser","brand":"Apple","name":"Mac","url":"https://www.google.com/about/company/","os":{"name":"macOS 10.14 Mojave","code":"macos_10_14","url":"https://en.wikipedia.org/wiki/MacOS_Mojave","family":"macOS","family_code":"macos","family_vendor":"Apple Inc.","icon":"https://assets.userstack.com/icons/os/macosx.png","icon_large":"https://assets.userstack.com/icons/os/macosx_big.png"},"device":{"is_mobile_device":false,"type":"desktop","brand":"Apple","brand_code":"apple","brand_url":"http://www.apple.com/","name":"Mac"},"browser":{"name":"Chrome","version":"71.0.3578.98","version_major":"71","engine":"WebKit/Blink"},"crawler":{"is_crawler":false,"category":null,"last_seen":null}}}}}}},"400":{"description":"Bad Request - validation error (e.g. missing_user_agent, invalid_fields, too_many_user_agents, batch_not_supported_on_plan).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"500":{"$ref":"#/components/responses/500"},"503":{"$ref":"#/components/responses/503"}}},"post":{"tags":["Endpoints"],"summary":"Bulk User-Agent Lookup","description":"Look up multiple User-Agent strings in one request by POSTing a JSON body containing a ua_batch array (max 100 items). Batch requests require a plan with batch support enabled.","operationId":"userstackDetectBulk","parameters":[{"name":"access_key","in":"query","description":"Your userstack API Access Key.","required":true,"schema":{"type":"string"}},{"name":"fields","in":"query","description":"Comma-separated list of fields to include in the response (reduces payload). Examples: `main`, `brand`, `os`, `device.icon`, `os.name,device.name`. See docs for the `fields` semantics and examples.","required":false,"schema":{"type":"string"}},{"name":"output","in":"query","description":"Output format: `json` (default) or `xml`.","required":false,"schema":{"type":"string","default":"json","enum":["json","xml"],"example":"json"}},{"name":"legacy","in":"query","description":"Set to `1` to enable legacy response format (backwards-compatible shape used by the former API). Use when migrating older integrations.","required":false,"schema":{"type":"integer","format":"int32","default":0,"enum":[0,1],"example":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["ua_batch"],"properties":{"ua_batch":{"type":"array","items":{"type":"string"},"maxItems":100,"example":["Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/89.0.4389.90 Safari/537.36","Mozilla/5.0 (iPhone; CPU iPhone OS 14_4 like Mac OS X) AppleWebKit/605.1.15"]}},"type":"object"}}}},"responses":{"200":{"description":"Bulk parse result — a JSON array with one user-agent result object per ua_batch entry, in the same order as the request.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/UserAgentResponse"}},"examples":{"bulk_example":{"value":[{"ua":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) ...","type":"browser","brand":"Microsoft","name":"Windows","url":"https://example.com","os":{"name":"Windows 10"},"device":{"type":"desktop"},"browser":{"name":"Chrome"}},{"ua":"Mozilla/5.0 (iPad; CPU OS 13_5 like Mac OS X) ...","type":"browser","brand":"Apple","name":"iPad","url":"","os":{"name":"iOS 13.5"},"device":{"type":"tablet"},"browser":{"name":"Safari"}}]}}}}},"400":{"description":"Bad Request - validation error (e.g. missing_user_agent, invalid_fields, too_many_user_agents, batch_not_supported_on_plan).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"500":{"$ref":"#/components/responses/500"},"503":{"$ref":"#/components/responses/503"}}}}},"components":{"schemas":{"OS":{"description":"Operating system detection.","properties":{"name":{"type":"string","example":"macOS 10.14 Mojave"},"code":{"type":"string","example":"macos_10_14"},"url":{"nullable":true,"type":"string","format":"uri"},"family":{"type":"string","example":"macOS"},"family_code":{"type":"string","example":"macos"},"family_vendor":{"nullable":true,"type":"string","example":"Apple Inc."},"icon":{"nullable":true,"type":"string","format":"uri"},"icon_large":{"nullable":true,"type":"string","format":"uri"}},"type":"object"},"Device":{"description":"Device detection.","properties":{"is_mobile_device":{"type":"boolean","example":false},"type":{"type":"string","example":"desktop"},"brand":{"nullable":true,"type":"string","example":"Apple"},"brand_code":{"nullable":true,"type":"string","example":"apple"},"brand_url":{"nullable":true,"type":"string","format":"uri"},"name":{"nullable":true,"type":"string","example":"Mac"}},"type":"object"},"Browser":{"description":"Browser detection.","properties":{"name":{"type":"string","example":"Chrome"},"version":{"nullable":true,"type":"string","example":"71.0.3578.98"},"version_major":{"nullable":true,"type":"string","example":"71"},"engine":{"nullable":true,"type":"string","example":"WebKit/Blink"}},"type":"object"},"Crawler":{"description":"Crawler (bot) detection.","properties":{"is_crawler":{"type":"boolean","example":false},"category":{"nullable":true,"type":"string"},"last_seen":{"nullable":true,"type":"string"}},"type":"object"},"UserAgentResponse":{"description":"Parsed User-Agent result.","properties":{"ua":{"type":"string","example":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) ..."},"type":{"type":"string","example":"browser"},"brand":{"type":"string","example":"Apple"},"name":{"type":"string","example":"Mac"},"url":{"nullable":true,"type":"string","format":"uri"},"os":{"$ref":"#/components/schemas/OS"},"device":{"$ref":"#/components/schemas/Device"},"browser":{"$ref":"#/components/schemas/Browser"},"crawler":{"$ref":"#/components/schemas/Crawler"}},"type":"object"},"Error":{"title":"Error","type":"object","required":["success","error"],"properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"integer","example":101},"type":{"type":"string","example":"invalid_access_key"},"info":{"type":"string","example":"You have not supplied a valid API Access Key. [Technical Support: support@apilayer.com]"}}}}}},"responses":{"401":{"description":"Unauthorized","content":{"application/json; Charset=UTF-8":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"account_on_hold":{"summary":"account_on_hold","value":{"success":false,"error":{"code":107,"type":"account_on_hold","info":"Your account currently has open invoices and API has been automatically disabled. Please settle your open balance or downgrade to the Free Plan to restore API access. [Support: support@apilayer.com]"}}},"invalid_access_key":{"summary":"invalid_access_key","value":{"success":false,"error":{"code":101,"type":"invalid_access_key","info":"You have not supplied a valid API Access Key. [Technical Support: support@apilayer.com]"}}},"missing_access_key":{"summary":"missing_access_key","value":{"success":false,"error":{"code":101,"type":"missing_access_key","info":"You have not supplied an API Access Key. [Required format: access_key=YOUR_ACCESS_KEY]"}}},"inactive_user":{"summary":"inactive_user","value":{"success":false,"error":{"code":102,"type":"inactive_user","info":"Permission denied - User not active."}}}}}}},"403":{"description":"Forbidden","content":{"application/json; Charset=UTF-8":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"https_access_restricted":{"summary":"https_access_restricted","value":{"success":false,"error":{"code":105,"type":"https_access_restricted","info":"Access Restricted - Your current Subscription Plan does not support HTTPS Encryption."}}},"function_access_restricted":{"summary":"function_access_restricted","value":{"success":false,"error":{"code":105,"type":"function_access_restricted","info":"Access Restricted - Your current Subscription Plan does not support this API Function."}}},"spread_access_restricted":{"summary":"spread_access_restricted","value":{"success":false,"error":{"code":403,"type":"spread_access_restricted","info":"Access Restricted - Your current Subscription Plan does not support Bid/Ask Data."}}},"source_currency_access_restricted":{"summary":"source_currency_access_restricted","value":{"success":false,"error":{"code":403,"type":"source_currency_access_restricted","info":"Access Restricted - Your current Subscription Plan does not support Source Currency Switching."}}},"api_access_blocked":{"summary":"api_access_blocked","value":{"success":false,"error":{"code":104,"type":"api_access_blocked","info":"Your API access has been temporarily disabled. Please upgrade your Subscription Plan or contact support."}}}}}}},"404":{"description":"Not Found","content":{"application/json; Charset=UTF-8":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_api_function":{"summary":"invalid_api_function","value":{"success":false,"error":{"code":103,"type":"invalid_api_function","info":"This API Function does not exist."}}},"404_not_found":{"summary":"404_not_found","value":{"success":false,"error":{"code":404,"type":"404_not_found","info":"404 - The requested resource could not be found. Please try again or contact support."}}}}}}},"429":{"description":"Too Many Requests","content":{"application/json; Charset=UTF-8":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"usage_limit_reached":{"summary":"usage_limit_reached","value":{"success":false,"error":{"code":104,"type":"usage_limit_reached","info":"Your monthly usage limit has been reached. Please upgrade your Subscription Plan."}}},"daily_usage_limit_reached":{"summary":"daily_usage_limit_reached","value":{"success":false,"error":{"code":104,"type":"daily_usage_limit_reached","info":"Your daily usage limit has been reached. Please try again tomorrow or upgrade your subscription plan."}}},"fair_use_limit_reached":{"summary":"fair_use_limit_reached","value":{"success":false,"error":{"code":104,"type":"fair_use_limit_reached","info":"Your fair use limit has been reached. [Please contact support: support@apilayer.com]"}}},"rate_limit_reached":{"summary":"rate_limit_reached","value":{"success":false,"error":{"code":106,"type":"rate_limit_reached","info":"You have exceeded the maximum rate limitation allowed on your subscription plan. Please refer to the \"Rate Limits\" section of the API Documentation for details. "}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json; Charset=UTF-8":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"internal_error","value":{"success":false,"error":{"code":0,"type":"internal_error","info":"An error has occured. [Technical Support: support@apilayer.com]"}}}}}}},"503":{"description":"Service Unavailable","content":{"application/json; Charset=UTF-8":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"maintenance_mode":{"summary":"maintenance_mode","value":{"success":false,"error":{"code":503,"type":"maintenance_mode","info":""}}}}}}}}}}