api-ninjas-com User Agent API

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