Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we
store it to create your key and to recognise you if you sign in with another
provider. See our Privacy Policy and
Terms.
openapi: 3.2.0
info:
title: Ninjas User Agent API
description: 'Combined OpenAPI specification for every API Ninjas endpoint. Requests go to https://api.api-ninjas.com with an `X-Api-Key` header; get a free key at https://api-ninjas.com/register. Human-readable docs: https://api-ninjas.com/api. Index for LLMs: https://api-ninjas.com/llms.txt.'
version: 1.0.0
contact:
name: API Ninjas
url: https://api-ninjas.com
license:
name: Proprietary
servers:
- url: https://api.api-ninjas.com
description: API Ninjas Production
security:
- ApiKeyAuth: []
tags:
- name: User Agent
paths:
/v2/useragentparse:
get:
tags:
- User Agent
summary: Parse User Agent String
description: Parses a user agent string to extract device, OS, and browser information. All response fields are top-level. Invalid or unrecognized user agents return HTTP 200 with is_valid false and invalid_reason set, and still return whatever browser, OS and device information could be parsed. A version newer than the latest known release is reported in warnings rather than treated as invalid.
operationId: parseUserAgent
parameters:
- name: useragent
in: query
required: true
schema:
type: string
description: User agent string to parse.
responses:
'200':
description: Parse result. Check is_valid; when false, invalid_reason explains why, and the parsed fields are still populated where possible.
content:
application/json:
schema:
$ref: '#/components/schemas/UserAgentParseResponse'
'400':
description: Bad Request (e.g. missing useragent parameter).
'401':
description: Unauthorized
'500':
description: Internal Server Error
security:
- ApiKeyAuth: []
/v1/useragentgenerate:
get:
tags:
- User Agent
summary: Generate User Agent String
description: Generates a user agent string, optionally matching a device `brand`, `model`, `os` and `browser`. To parse an existing user agent string instead use /v2/useragentparse.
operationId: generateUserAgent
parameters:
- name: brand
in: query
required: false
schema:
type: string
description: Device brand (e.g. Apple, Samsung)
- name: model
in: query
required: false
schema:
type: string
description: Device model (e.g. iPhone, Galaxy)
- name: os
in: query
required: false
schema:
type: string
description: Operating system (e.g. Windows, iOS, Android)
- name: browser
in: query
required: false
schema:
type: string
description: Browser name (e.g. Chrome, Firefox, Safari)
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/UserAgentGenerateResponse'
'400':
description: Bad Request
'401':
description: Unauthorized
'500':
description: Internal Server Error
security:
- ApiKeyAuth: []
components:
schemas:
UserAgentParseResponse:
type: object
description: Parse response with top-level fields. The browser/OS/device fields are populated whenever the string could be parsed, whether or not it validates. invalid_reason is always present (empty when valid); warnings lists non-fatal anomalies.
properties:
browser_family:
type:
- string
- 'null'
description: Browser name (e.g. Chrome, Safari).
browser_version:
type:
- string
- 'null'
description: Browser version string.
os_family:
type:
- string
- 'null'
description: Operating system family (e.g. Windows, Mac OS X, iOS).
os_version:
type:
- string
- 'null'
description: OS version string.
device_family:
type:
- string
- 'null'
description: Device family (e.g. Other, iPhone, Samsung SM-G991B).
device_brand:
type:
- string
- 'null'
description: Device brand.
device_model:
type:
- string
- 'null'
description: Device model.
device_type:
type:
- string
- 'null'
enum:
- computer
- tablet
- mobile
- null
description: High-level device type.
is_valid:
type: boolean
description: True if the user agent passed validation; false for invalid/unrecognized UAs.
invalid_reason:
type: string
description: Always present. Empty string when valid; when is_valid is false, explains why the user agent was rejected.
warnings:
type: array
items:
type: string
description: Non-fatal anomalies that did not invalidate the string, such as a browser version newer than the most recent release we know of, or an unusual token combination. Always present.
required:
- is_valid
- invalid_reason
- warnings
UserAgentGenerateResponse:
type: object
properties:
user_agent:
type: string
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-Api-Key
externalDocs:
description: API Ninjas documentation
url: https://api-ninjas.com/api