Getting Started

The Userstack API is a RESTful service that provides real-time parsing of User-Agent strings. It allows you to accurately detect a user’s device, browser, and operating system, enabling you to enhance user experiences, deliver tailored content, and gain insights into your audience’s technology usage.

API Access Key & Authentication

Obtain Your API Key
After signing up, you can access your account dashboard to find your unique API access key—a 32-character hash used to authenticate requests to the userstack API.

Authenticate API Requests
To use the API, simply append your access key to the endpoint using the access_key parameter:

Protect Your API Key: Your API key provides full access to your account, so keep it secure and private. Do not share it publicly. You can reset your key at any time via the account dashboard, which immediately invalidates the previous key.

API Response

When an API request is successful, Userstack returns a structured response containing detailed information parsed from the submitted User-Agent string.

Responses can be delivered in JSON or XML format and are divided into four main modules:

• os – Operating system details
• device – Device type and manufacturer information
• browser – Browser name, version, and rendering engine
• crawler – Bot and crawler detection (available on the Basic Plan and higher)

In addition to these modules, the API response includes the original User-Agent string and several general metadata fields.

Example API Response (JSON)

Please note: To be able to completely illustrate a successful API request, Crawler data has been included in the API response above. To enable the Crawler module, you must be subscribed to the Basic Plan or higher.

Example API Response (XML)

Notes:

• The <category> and <last_seen> fields are represented as nil to indicate null values.
• All nested objects (like os, device, browser, crawler) are preserved as child elements.
• The root element <userstack> wraps the entire response, matching common REST XML response patterns.

Example Explained: The above example shows a response for a User-Agent string associated with an Apple iMac running macOS Mojave (10.14) and the Chrome browser (version 71). 

API Endpoints

The Userstack API provides two primary endpoints for parsing User-Agent strings: Single Lookup and Bulk Lookup

Single Lookup

Retrieve detailed information for a single User-Agent string. This is the most common use case and is ideal for real-time lookups within your application.

Example Request:

Bulk Lookup (HTTP POST only)

Process multiple User-Agent strings in a single API request. This endpoint is useful for analyzing logs or datasets containing large volumes of User-Agent data.

Note: Bulk lookups are available on the Business Plan

256-bit HTTPS Encryption

All userstack API requests support 256-bit SSL encryption to ensure secure data transmission. You can connect to the API using the HTTPS protocol by simply adding an “s” to http.

Example Secure Request:                                                                Available on: All Plans

Using HTTPS is strongly recommended to protect your API key and any sensitive data exchanged between your application and the userstack servers.

JSONP Callbacks

The Userstack API supports JSONP (JSON with Padding) for cross-domain requests.To use this feature, append the callback parameter to your API request and assign it your preferred JavaScript function name. The API will return the response wrapped inside that function call.

Example API Request:

Example API Response:

Note: JSONP responses are in JSON format only, and the userstack API also supports Access-Control (CORS) headers for cross-origin requests.

API Error Codes

If an API request fails, the response will include a JSON object describing the error.

Example Error Response:

Common API Errors