User-Agent API

API reference

User-Agent HTTP endpoints on api.syndaq.com.

All User-Agent endpoints are served from https://api.syndaq.com/v1/useragent/.

Authenticated requests require a valid User-Agent key. Lookup routes require your ua_sec_ secret key.

Endpoints overview

Method	Path	Auth	Purpose
GET	`/v1/useragent/lookup`	Secret key	Lookup by `?ua=` or `?user_agent=`
GET	`/v1/useragent/lookup/{ua}`	Secret key	Lookup by URL-encoded User-Agent in the path
POST	`/v1/useragent/lookup`	Secret key	Lookup with JSON body `ua` / `user_agent`
GET	`/v1/useragent/status`	Public or secret key	Plan limits and quota snapshot

Response headers

Successful and error responses may include:

Header	Description
`X-Request-Id`	Unique ID for support and log correlation
`X-RateLimit-Limit`	Plan requests per minute for this key
`X-RateLimit-Remaining`	Requests left in the current minute window
`X-RateLimit-Reset`	Unix timestamp when the minute window resets
`X-Quota-Limit`	Monthly quota for the subscription
`X-Quota-Remaining`	Lookups left this calendar month (UTC)
`X-Quota-Period`	Current quota month (`YYYY-MM`)
`Retry-After`	Seconds to wait after HTTP 429

GET /v1/useragent/lookup

Parses a User-Agent string into browser, OS, device, and bot fields.

Request

GET /v1/useragent/lookup?ua=Mozilla%2F5.0%20...

Headers:

Authorization: Bearer ua_sec_YOUR_SECRET_KEY

v1 scope

v1 parses the User-Agent string only. It does not validate that the client is genuine, fingerprint device hardware, or perform bot mitigation beyond keyword and heuristic flags.

Success response (200)

{
  "success": true,
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36",
  "cached": true,
  "browser": { "name": "Chrome", "version": "126.0.0.0" },
  "os": { "name": "Windows", "version": "10.0" },
  "device_type": "desktop",
  "is_bot": false,
  "engine": "Blink",
  "request_id": "e6d04020be9b57b1e1069d6e483c0443"
}

Response fields

Field	Type	Description
`user_agent`	string	Truncated sample of the input string
`cached`	boolean	`true` when Syndaq already holds a recent result for this lookup
`browser.name`	string	Detected browser name when recognized
`browser.version`	string	Detected browser version when available
`os.name`	string	Detected operating system name when recognized
`os.version`	string	Detected OS version when available
`device_type`	string	Device class such as `desktop`, `mobile`, or `tablet`
`is_bot`	boolean	`true` when bot/crawler heuristics match
`engine`	string	Rendering engine when detected

GET /v1/useragent/status

Returns key status, plan limits, and quota usage without performing a lookup.

Request

GET /v1/useragent/status
Authorization: Bearer ua_sec_YOUR_SECRET_KEY

The public key (ua_pub_) is accepted on this route.

Success response (200)

{
  "success": true,
  "status": "active",
  "product": "useragent",
  "plan": "starter",
  "rate_limit_per_minute": 120,
  "monthly_quota": 10000,
  "quota_unlimited": false,
  "quota_remaining": 9842,
  "quota_period": "2026-07"
}

Errors

Failed requests return JSON with success: false, error, error_code, and usually request_id.

HTTP	error_code	Typical cause
400	`invalid_user_agent`	Missing or empty User-Agent
401	`missing_credentials`	No API key provided
401	`invalid_api_key`	Unknown, inactive, or revoked key
401	`wrong_key_type`	Public key used on a lookup endpoint
403	`ip_not_allowed`	Caller IP not on the key allowlist
429	`rate_limit_exceeded`	Per-minute limit exceeded
429	`quota_exceeded`	Monthly quota exhausted
500	`internal_error`	Unexpected server error

Handle non-200 responses in your application and retry transient errors with exponential backoff.