openapi: 3.2.0
info:
title: Apifreaks Api Hub For Developers User Agent APIs API
version: 1.0.0
contact:
name: APIFreaks Support
url: https://apifreaks.com/contact
email: support@apifreaks.com
description: 'Operations tagged User Agent APIs across 2 of this provider''s published API definitions: apifreaks-api-hub-for-developers-bulk-user-agent-parser-openapi.json, apifreaks-api-hub-for-developers-user-agent-parser-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.apifreaks.com/v1.0
description: Bulk User Agent Parser API Server
security:
- ApiKeyAuthHeader: []
- ApiKeyAuthQuery: []
tags:
- name: User Agent APIs
paths:
/user-agent/lookup:
servers:
- url: https://api.apifreaks.com/v1.0
description: Bulk User Agent Parser API Server
post:
tags:
- User Agent APIs
summary: Parse multiple User-Agent strings in a single request to obtain browser, device, and operating system details
description: Parse up to 50,000 User-Agent strings simultaneously in a single request. Returns structured details about the browser, device, layout engine, and operating system for each string.
operationId: bulkParseUserAgent
parameters:
- name: format
in: query
required: false
description: 'Format of the response. Possible values: json, xml.'
schema:
type: string
enum:
- json
- xml
default: json
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BulkUserAgentRequest'
examples:
typicalRequest:
summary: Example request body
value:
uaStrings:
- Mozilla/5.0 (Linux; Android 8.0.0; SM-G960F Build/R16NW) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/62.0.3202.84 Mobile Safari/537.36
- Mozilla/5.0 (X11; U; Linux armv7l like Android; en-us) AppleWebKit/531.2+ (KHTML, like Gecko) Version/5.0 Safari/533.2+ Kindle/3.0+
- Mozilla/5.0 (Linux; U; en-US) AppleWebKit/528.5+ (KHTML, like Gecko, Safari/528.5+) Version/4.0 Kindle/3.0 (screen 600x800; rotate)
responses:
'200':
description: Successful response with parsed user agent data for each input string
content:
application/json:
schema:
$ref: '#/components/schemas/BulkUserAgentParserResponse'
examples:
typicalSuccess:
summary: Typical successful response
value:
- user_agent_string: Mozilla/5.0 (Linux; Android 8.0.0; SM-G960F Build/R16NW) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/62.0.3202.84 Mobile Safari/537.36
name: Chrome
type: Browser
version: 62.0.3202.84
version_major: '62'
device:
name: Samsung SM-G960F
type: Phone
brand: Samsung
cpu: Unknown
engine:
name: Blink
type: Browser
version: '62.0'
version_major: '62'
operating_system:
name: Android
type: Mobile
version: 8.0.0
version_major: '8'
build: R16NW
- user_agent_string: Mozilla/5.0 (X11; U; Linux armv7l like Android; en-us) AppleWebKit/531.2+ (KHTML, like Gecko) Version/5.0 Safari/533.2+ Kindle/3.0+
name: Kindle
type: Browser
version: '3.0'
version_major: '3'
device:
name: Amazon Kindle
type: eReader
brand: Amazon
cpu: ARMv7l
engine:
name: AppleWebKit
type: Browser
version: '531.2'
version_major: '531'
operating_system:
name: FireOS
type: Mobile
version: ??
version_major: ??
build: ??
- user_agent_string: Mozilla/5.0 (Linux; U; en-US) AppleWebKit/528.5+ (KHTML, like Gecko, Safari/528.5+) Version/4.0 Kindle/3.0 (screen 600x800; rotate)
name: Kindle
type: Browser
version: '3.0'
version_major: '3'
device:
name: Amazon Kindle
type: eReader
brand: Amazon
cpu: Unknown
engine:
name: AppleWebKit
type: Browser
version: '528.5'
version_major: '528'
operating_system:
name: FireOS
type: Mobile
version: ??
version_major: ??
build: ??
mixedWithUnparsable:
summary: Batch with a malformed (non-empty) string — still 200, that entry comes back as Hacker
value:
- user_agent_string: asdkjaslkdjaslkdj12312
name: Hacker
type: Hacker
version: Hacker
version_major: Hacker
device:
name: Hacker
type: Hacker
brand: Hacker
cpu: Unknown
engine:
name: Hacker
type: Hacker
version: Hacker
version_major: Hacker
operating_system:
name: Hacker
type: Hacker
version: Hacker
version_major: Hacker
build: ??
- user_agent_string: Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)
name: Googlebot
type: Robot
version: '2.1'
version_major: '2'
device:
name: Google
type: Robot
brand: Google
cpu: Unknown
engine:
name: Googlebot
type: Robot
version: ??
version_major: ??
operating_system:
name: Google Cloud
type: Cloud
version: ??
version_major: ??
build: ??
'400':
description: Bad Request — Invalid/missing request body, or an empty/null string anywhere in uaStrings (fails the whole batch, not a per-item error)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
missingRequestBody:
summary: Missing, empty, or wrong-type request body
value:
error: Invalid request body Exception
message: Please provide data in required format in request body
path: /v1.0/user-agent/lookup
status: 400
timestamp: '2026-07-24T10:16:11.030Z'
emptyUserAgentString:
summary: Empty string or null inside uaStrings array
value:
message: '''userAgentString'' must not be empty or null'
get:
tags:
- User Agent APIs
summary: Parse a User-Agent string to obtain browser, device, and operating system details
description: Parse any User-Agent string to obtain detailed information about the browser, device, layout engine, and operating system. Supports desktop, mobile, tablet, and crawler detection.
operationId: parseUserAgent
parameters:
- name: format
in: query
required: false
description: 'Format of the response. Possible values: json, xml.'
schema:
type: string
enum:
- json
- xml
default: json
- name: User-Agent
in: header
required: true
description: The User-Agent string to parse for browser, device, and operating system details.
schema:
type: string
responses:
'200':
description: Successful response with parsed user agent data
content:
application/json:
schema:
$ref: '#/components/schemas/UserAgentParserResponse'
examples:
typicalSuccess:
summary: Desktop browser User-Agent
value:
user_agent_string: Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:142.0) Gecko/20100101 Firefox/142.0
name: Firefox
type: Browser
version: '142.0'
version_major: '142'
device:
name: Linux Desktop
type: Desktop
brand: Unknown
cpu: Intel x86_64
engine:
name: Gecko
type: Browser
version: '142.0'
version_major: '142'
operating_system:
name: Ubuntu
type: Desktop
version: ??
version_major: ??
build: ??
crawlerUserAgent:
summary: Search engine crawler User-Agent — Robot/Cloud classification
value:
user_agent_string: Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)
name: Googlebot
type: Robot
version: '2.1'
version_major: '2'
device:
name: Google
type: Robot
brand: Google
cpu: Unknown
engine:
name: Googlebot
type: Robot
version: ??
version_major: ??
operating_system:
name: Google Cloud
type: Cloud
version: ??
version_major: ??
build: ??
unparsableUserAgent:
summary: Malformed/unparsable User-Agent — still 200, every field set to Hacker
value:
user_agent_string: asdkjaslkdjaslkdj12312
name: Hacker
type: Hacker
version: Hacker
version_major: Hacker
device:
name: Hacker
type: Hacker
brand: Hacker
cpu: Unknown
engine:
name: Hacker
type: Hacker
version: Hacker
version_major: Hacker
operating_system:
name: Hacker
type: Hacker
version: Hacker
version_major: Hacker
build: ??
'400':
description: Bad Request — Missing or empty User-Agent header
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse_2'
examples:
missingHeader:
summary: User-Agent header missing or empty
value:
error: Invalid Header Exception
message: Please provide correct headers
path: /v1.0/user-agent/lookup
status: 400
timestamp: '2026-07-24T10:12:15.828Z'
components:
schemas:
ErrorResponse_2:
type: object
description: Standard error envelope returned by the API on failed requests.
required:
- message
properties:
error:
type: string
description: Short error category or exception type.
message:
type: string
description: Human-readable error message describing the failure.
path:
type: string
description: API endpoint path that produced the error.
status:
type: integer
description: HTTP status code returned with the error.
timestamp:
type: string
format: date-time
description: Timestamp when the error occurred (ISO 8601).
Engine:
type: object
description: Layout or rendering engine information extracted from the User-Agent string.
required:
- name
- type
- version
- version_major
properties:
name:
type: string
description: Name of the layout or rendering engine (e.g., Blink, Gecko, WebKit).
type:
type: string
description: 'Engine category. Possible values: Browser, Mobile App, Hacker, Robot, Unknown.'
version:
type: string
description: Full version string of the layout engine. "??" when unknown; "Hacker" when the User-Agent string itself is malformed/unparsable.
version_major:
type: string
description: Major version number of the layout engine. "??" when unknown; "Hacker" when the User-Agent string itself is malformed/unparsable.
ErrorResponse:
type: object
description: Standard error envelope returned by the API on failed requests. Request-body-level errors (missing/empty/wrong-type body) include all five fields; per-item validation errors (empty/null string in uaStrings) include only message.
required:
- message
properties:
error:
type: string
description: Short error category or exception type.
message:
type: string
description: Human-readable error message describing the failure.
path:
type: string
description: API endpoint path that produced the error.
status:
type: integer
description: HTTP status code returned with the error.
timestamp:
type: string
format: date-time
description: Timestamp when the error occurred (ISO 8601).
UserAgentParserResponse:
type: object
description: Parsed User-Agent result containing browser, device, engine, and operating system information. When the User-Agent string is malformed or cannot be parsed, every field across this object and its nested device/engine/operating_system objects is set to the literal string "Hacker" instead of the request failing.
required:
- user_agent_string
- name
- type
- version
- version_major
- device
- engine
- operating_system
properties:
user_agent_string:
type: string
description: The raw User-Agent string that was parsed for browser, device, and operating system details.
name:
type: string
description: Name of the browser, crawler, or application identified from the User-Agent string.
type:
type: string
description: 'Category of the agent. Possible values: Browser, Browser Webview, Mobile App, Robot Mobile, Cloud Application, Email Client, Voice, Special, Testclient, Hacker, Unknown.'
version:
type: string
description: Full version string of the browser or application. "??" when the version could not be determined; "Hacker" when the User-Agent string itself is malformed/unparsable.
version_major:
type: string
description: Major version number extracted from the version string. "??" when the version could not be determined; "Hacker" when the User-Agent string itself is malformed/unparsable.
device:
$ref: '#/components/schemas/Device'
engine:
$ref: '#/components/schemas/Engine'
operating_system:
$ref: '#/components/schemas/OperatingSystem'
BulkUserAgentRequest:
type: object
description: Request body containing an array of User-Agent strings to parse.
required:
- uaStrings
properties:
uaStrings:
type: array
description: Array of User-Agent strings to parse. Maximum 50,000 strings per request.
maxItems: 50000
items:
type: string
BulkUserAgentParserResponse:
title: UserAgentParserResponse
type: array
description: 'Array of per-string parsed User-Agent results, one entry per input string, in the same order as the request. Unlike the bulk IP lookup endpoint, there is no per-item error variant here: a malformed (non-empty) string still parses to a full result with every field set to "Hacker" (see UserAgentParserResponse). An empty string or null anywhere in the request array fails the entire request with a 400 instead of producing a per-item error entry --- see the 400 response.'
items:
$ref: '#/components/schemas/UserAgentParserResponse'
OperatingSystem:
type: object
description: Operating system information extracted from the User-Agent string.
required:
- name
- type
- version
- version_major
- build
properties:
name:
type: string
description: Name of the operating system (e.g., Windows, Android, Ubuntu).
type:
type: string
description: 'Operating system category. Possible values: Desktop, Mobile, Game Console, Embedded, Cloud, Hacker, Anonymized, Unknown.'
version:
type: string
description: Full version string of the operating system. "??" when unknown; "Hacker" when the User-Agent string itself is malformed/unparsable.
version_major:
type: string
description: Major version number of the operating system. "??" when unknown; "Hacker" when the User-Agent string itself is malformed/unparsable.
build:
type: string
description: Build number or identifier of the operating system. "??" when unknown.
Device:
type: object
description: Hardware device information extracted from the User-Agent string.
required:
- name
- type
- brand
- cpu
properties:
name:
type: string
description: Device name or model identifier of the hardware used.
type:
type: string
description: 'Device category. Possible values: Desktop, Mobile, Tablet, Phone, Watch, Virtual Reality, eReader, Set-top box, TV, Game Console, Handheld Game Console, Voice, Robot, Robot Mobile, Robot Imitator, Hacker, Anonymized, Unknown.'
brand:
type: string
description: Device manufacturer or brand name.
cpu:
type: string
description: CPU architecture or model identifier of the device.
securitySchemes:
ApiKeyAuthHeader:
type: apiKey
in: header
name: X-apiKey
description: Pass your API key via the X-apiKey request header.
ApiKeyAuthQuery:
type: apiKey
in: query
name: apiKey
description: Pass your API key via the apiKey query parameter.
x-refined-from:
- apifreaks-api-hub-for-developers-bulk-user-agent-parser-openapi.json
- apifreaks-api-hub-for-developers-user-agent-parser-openapi.json