openapi: 3.0.1
info:
  title: Fingerprint Server Event Search API
  description: The Fingerprint Server API lets you get, search, update, and delete identification Events and Visitors in a server environment. Each event carries device attributes and the enabled Smart Signals (bot, VPN, proxy, Tor, IP blocklist, tampering, virtual machine, incognito, emulator, root, jailbreak, Frida, cloned app, factory reset, velocity). Requests are authenticated with the `Auth-API-Key` header carrying your workspace Secret API Key. The API is served from regional hosts; use the host that matches your workspace region (Global, EU, or Asia). The product also exposes a Related Visitors endpoint and Webhooks that POST the same event payload to a configured endpoint.
  termsOfService: https://fingerprint.com/terms-conditions/
  contact:
    name: Fingerprint Support
    email: support@fingerprint.com
  license:
    name: MIT
    url: https://github.com/fingerprintjs/fingerprint-pro-server-api-openapi/blob/main/LICENSE
  version: '3'
servers:
- url: https://api.fpjs.io
  description: Global
- url: https://eu.api.fpjs.io
  description: EU
- url: https://ap.api.fpjs.io
  description: Asia (Mumbai)
security:
- ApiKeyHeader: []
- ApiKeyQuery: []
tags:
- name: Event Search
  description: Search identification events with filters.
paths:
  /events/search:
    get:
      tags:
      - Event Search
      operationId: searchEvents
      summary: Get events via search
      description: Search identification events for your workspace using a wide range of built-in filters, including visitorId, linkedId, bot, IP address, time range, suspect, and individual Smart Signal flags. Results are paginated with a cursor.
      parameters:
      - name: limit
        in: query
        required: true
        description: Limit the number of events returned.
        schema:
          type: integer
          format: int32
          minimum: 1
      - name: pagination_key
        in: query
        description: Cursor used to fetch the next page of results.
        schema:
          type: string
      - name: visitor_id
        in: query
        description: Filter events by visitorId.
        schema:
          type: string
      - name: bot
        in: query
        description: Filter by bot detection result (good, bad, all, none).
        schema:
          type: string
          enum:
          - good
          - bad
          - all
          - none
      - name: ip_address
        in: query
        description: Filter events by IP address or CIDR range.
        schema:
          type: string
      - name: linked_id
        in: query
        description: Filter events by linkedId.
        schema:
          type: string
      - name: start
        in: query
        description: Filter events created after this Unix epoch time (ms).
        schema:
          type: integer
          format: int64
      - name: end
        in: query
        description: Filter events created before this Unix epoch time (ms).
        schema:
          type: integer
          format: int64
      - name: reverse
        in: query
        description: Sort events from oldest to newest.
        schema:
          type: boolean
      - name: suspect
        in: query
        description: Filter events flagged as suspect.
        schema:
          type: boolean
      - name: vpn
        in: query
        description: Filter events where a VPN was detected.
        schema:
          type: boolean
      - name: virtual_machine
        in: query
        description: Filter events where a virtual machine was detected.
        schema:
          type: boolean
      - name: tampering
        in: query
        description: Filter events where request tampering was detected.
        schema:
          type: boolean
      - name: incognito
        in: query
        description: Filter events where incognito/private browsing was detected.
        schema:
          type: boolean
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchEventsResponse'
        '403':
          description: Forbidden - invalid or missing API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code (e.g. TokenRequired, RequestNotFound).
            message:
              type: string
              description: Human-readable error message.
    SearchEventsResponse:
      type: object
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/EventsGetResponse'
        paginationKey:
          type: string
    Products:
      type: object
      description: Container for identification and Smart Signal product results.
      properties:
        identification:
          $ref: '#/components/schemas/SignalResponseIdentification'
        botd:
          $ref: '#/components/schemas/SignalResponseBotd'
        ipInfo:
          type: object
        incognito:
          type: object
        vpn:
          type: object
        proxy:
          type: object
        tor:
          type: object
        tampering:
          type: object
        virtualMachine:
          type: object
        emulator:
          type: object
        velocity:
          type: object
    BrowserDetails:
      type: object
      properties:
        browserName:
          type: string
        browserMajorVersion:
          type: string
        browserFullVersion:
          type: string
        os:
          type: string
        osVersion:
          type: string
        device:
          type: string
        userAgent:
          type: string
    Confidence:
      type: object
      properties:
        score:
          type: number
          format: float
          minimum: 0
          maximum: 1
    EventsGetResponse:
      type: object
      properties:
        products:
          $ref: '#/components/schemas/Products'
    SignalResponseIdentification:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Identification'
    SignalResponseBotd:
      type: object
      properties:
        data:
          type: object
          properties:
            bot:
              type: object
              properties:
                result:
                  type: string
                  enum:
                  - notDetected
                  - good
                  - bad
    Identification:
      type: object
      properties:
        visitorId:
          type: string
          description: Stable unique identifier for the visitor.
        requestId:
          type: string
          description: Unique identifier of the identification event.
        linkedId:
          type: string
        timestamp:
          type: integer
          format: int64
          description: Time of the event as a Unix epoch (ms).
        time:
          type: string
          format: date-time
        url:
          type: string
        ip:
          type: string
        confidence:
          $ref: '#/components/schemas/Confidence'
        visitorFound:
          type: boolean
        incognito:
          type: boolean
        browserDetails:
          $ref: '#/components/schemas/BrowserDetails'
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: Auth-API-Key
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key