tracetail-io Identification API

openapi: 3.2.0
info:
  title: TraceTail Identification API
  version: 3.1.2
  summary: 'Browser fingerprinting: a stable visitor ID for each browser, without cookies.'
  description: 'TraceTail is a browser fingerprinting API for recognizing returning visitors without cookies. Its JavaScript SDK (a script tag or the npm package @tracetail/js) turns 40+ browser signals into a stable visitor ID with 99.6% accuracy, the same in normal and incognito windows. It works without an API key for a quick start; with a key, every identification is registered with the API, checked for automation and shown in a dashboard. 1,000 identification requests are free every month, then $0.10 per 1,000.


    The browser SDK calls the identification endpoints; customers'' servers verify what the browser sent with the Server API (secret server keys). Rate limits: 100 requests a second per API key, 600 a minute per IP address and 600 a minute per server key.'
  termsOfService: https://tracetail.io/terms-and-conditions
  contact:
    name: TraceTail support
    email: support@tracetail.io
    url: https://tracetail.io/contact
servers:
- url: https://tracetail.io
tags:
- name: Identification
  description: What the browser SDK calls.
paths:
  /api/id:
    post:
      operationId: identify
      tags:
      - Identification
      summary: Register an identification
      description: 'Called by the TraceTail browser SDK after it computes the visitor ID, from a page on the API key''s domain: the browser''s Origin (or Referer) header must match the domain the key was created for. Non-browser clients can forge these headers. Each successful call counts toward usage. Integrate with the SDK rather than calling it directly.'
      security:
      - publicKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdentificationRequest'
            example:
              visitorId: fp3_e8fc80d60f8c3571
              components:
                basic:
                  browser: chrome
                  os: macos
                  language: en-US
                  platform: MacIntel
                  cookieEnabled: true
                  screen:
                  - 1440
                  - 900
                  colorDepth: 30
                  timezone: Europe/Berlin
                hardware:
                  hardwareConcurrency: 8
                  maxTouchPoints: 0
                  deviceMemory: 8
                canvas:
                  hash: example
                  samples:
                  - 12480
                  - 9216
                  - 14111
                  - 7340
                webgl:
                  vendor: WebKit
                  renderer: WebKit WebGL
                  version: WebGL 1.0
                  unmaskedVendor: Apple Inc.
                  unmaskedRenderer: Apple GPU
                fonts:
                  detected:
                  - Arial
                  - Helvetica
                  count: 2
                  hash: example
                automation:
                  webdriver: false
              confidence: 1
      responses:
        '200':
          description: Registered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Identification'
        '400':
          description: Invalid request body or ID/component mismatch
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                VALIDATION_ERROR:
                  value:
                    error: Invalid request body or ID/component mismatch
                    code: VALIDATION_ERROR
                ID_COMPONENT_MISMATCH:
                  value:
                    error: Invalid request body or ID/component mismatch
                    code: ID_COMPONENT_MISMATCH
        '401':
          description: Invalid key or wrong domain
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                INVALID_KEY:
                  value:
                    error: Invalid key or wrong domain
                    code: INVALID_KEY
                DOMAIN_MISMATCH:
                  value:
                    error: Invalid key or wrong domain
                    code: DOMAIN_MISMATCH
        '402':
          description: Subscription unpaid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                PAYMENT_REQUIRED:
                  value:
                    error: Subscription unpaid
                    code: PAYMENT_REQUIRED
        '409':
          description: Request token reused with different data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                IDEMPOTENCY_CONFLICT:
                  value:
                    error: Request token reused with different data
                    code: IDEMPOTENCY_CONFLICT
        '413':
          description: Signals too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                PAYLOAD_TOO_LARGE:
                  value:
                    error: Signals too large
                    code: PAYLOAD_TOO_LARGE
        '429':
          description: Rate limited, or the free allowance is used up
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                RATE_LIMITED:
                  value:
                    error: Rate limited, or the free allowance is used up
                    code: RATE_LIMITED
                QUOTA_EXCEEDED:
                  value:
                    error: Rate limited, or the free allowance is used up
                    code: QUOTA_EXCEEDED
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
  /api/id/detail:
    post:
      operationId: identifyDetailed
      tags:
      - Identification
      summary: Register an identification, with the risk assessment
      description: 'Called by the TraceTail browser SDK after it computes the visitor ID, from a page on the API key''s domain: the browser''s Origin (or Referer) header must match the domain the key was created for. Non-browser clients can forge these headers. Each successful call counts toward usage. Integrate with the SDK rather than calling it directly.'
      security:
      - publicKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdentificationRequest'
            example:
              visitorId: fp3_e8fc80d60f8c3571
              components:
                basic:
                  browser: chrome
                  os: macos
                  language: en-US
                  platform: MacIntel
                  cookieEnabled: true
                  screen:
                  - 1440
                  - 900
                  colorDepth: 30
                  timezone: Europe/Berlin
                hardware:
                  hardwareConcurrency: 8
                  maxTouchPoints: 0
                  deviceMemory: 8
                canvas:
                  hash: example
                  samples:
                  - 12480
                  - 9216
                  - 14111
                  - 7340
                webgl:
                  vendor: WebKit
                  renderer: WebKit WebGL
                  version: WebGL 1.0
                  unmaskedVendor: Apple Inc.
                  unmaskedRenderer: Apple GPU
                fonts:
                  detected:
                  - Arial
                  - Helvetica
                  count: 2
                  hash: example
                automation:
                  webdriver: false
              confidence: 1
      responses:
        '200':
          description: Registered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailedIdentification'
        '400':
          description: Invalid request body or ID/component mismatch
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                VALIDATION_ERROR:
                  value:
                    error: Invalid request body or ID/component mismatch
                    code: VALIDATION_ERROR
                ID_COMPONENT_MISMATCH:
                  value:
                    error: Invalid request body or ID/component mismatch
                    code: ID_COMPONENT_MISMATCH
        '401':
          description: Invalid key or wrong domain
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                INVALID_KEY:
                  value:
                    error: Invalid key or wrong domain
                    code: INVALID_KEY
                DOMAIN_MISMATCH:
                  value:
                    error: Invalid key or wrong domain
                    code: DOMAIN_MISMATCH
        '402':
          description: Subscription unpaid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                PAYMENT_REQUIRED:
                  value:
                    error: Subscription unpaid
                    code: PAYMENT_REQUIRED
        '409':
          description: Request token reused with different data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                IDEMPOTENCY_CONFLICT:
                  value:
                    error: Request token reused with different data
                    code: IDEMPOTENCY_CONFLICT
        '413':
          description: Signals too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                PAYLOAD_TOO_LARGE:
                  value:
                    error: Signals too large
                    code: PAYLOAD_TOO_LARGE
        '429':
          description: Rate limited, or the free allowance is used up
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                RATE_LIMITED:
                  value:
                    error: Rate limited, or the free allowance is used up
                    code: RATE_LIMITED
                QUOTA_EXCEEDED:
                  value:
                    error: Rate limited, or the free allowance is used up
                    code: QUOTA_EXCEEDED
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
components:
  schemas:
    DetailedIdentification:
      allOf:
      - $ref: '#/components/schemas/Identification'
      - type: object
        required:
        - riskAssessment
        - botDetection
        properties:
          riskAssessment:
            type: object
            required:
            - level
            - score
            - signals
            properties:
              level:
                type: string
                enum:
                - low
                - medium
                - high
              score:
                type: number
                minimum: 0
                maximum: 1
              signals:
                type: array
                items:
                  type: object
                  required:
                  - type
                  - detail
                  properties:
                    type:
                      type: string
                      enum:
                      - headless_browser
                      - webdriver
                      - user_agent_mismatch
                      - platform_mismatch
                      - software_renderer
                      - virtual_machine
                      - insufficient_signals
                    detail:
                      type: string
          botDetection:
            type: object
            required:
            - isBot
            - verdict
            - automationTools
            properties:
              isBot:
                type: boolean
              verdict:
                type: string
                enum:
                - detected
                - not_detected
                - unknown
              automationTools:
                type: array
                items:
                  type: string
    Error:
      type: object
      required:
      - error
      - code
      properties:
        error:
          type: string
          description: What went wrong, for people.
        code:
          type: string
          description: What went wrong, for code.
    Identification:
      type: object
      required:
      - requestId
      - visitorId
      - confidence
      - quality
      - verification
      - isBot
      properties:
        requestId:
          type: string
          format: uuid
          description: The ID of one registered identification.
          examples:
          - 3f8c2a1e-6b4d-4c7a-9e21-5d0f7b8a9c13
        visitorId:
          type: string
          pattern: ^(?:fp3_|(?:free_)?fp2_)[0-9a-f]{16}$
          description: '`fp3_` followed by 16 hex characters, computed by the TraceTail SDK (IDs from 2.x SDKs start with `fp2_`).'
          examples:
          - fp3_8f14e45fceea167a
        confidence:
          type: number
          minimum: 0
          maximum: 1
          deprecated: true
          description: Alias of quality.score, not match probability.
        quality:
          type: object
          required:
          - score
          - reasons
          description: Signal completeness, not match probability or physical-device uniqueness.
          properties:
            score:
              type: number
              minimum: 0
              maximum: 1
            reasons:
              type: array
              items:
                type: string
        verification:
          type: string
          enum:
          - consistent
          - unverified
          description: consistent means the server recomputed the ID from the signals. It does not authenticate a device. Legacy requests are unverified.
        isBot:
          type: boolean
          description: 'True for automated browsers: a headless user agent or navigator.webdriver.'
    IdentificationRequest:
      type: object
      required:
      - visitorId
      - components
      properties:
        visitorId:
          type: string
          pattern: ^(?:fp3_|(?:free_)?fp2_)[0-9a-f]{16}$
          description: '`fp3_` followed by 16 hex characters, computed by the TraceTail SDK (IDs from 2.x SDKs start with `fp2_`).'
          examples:
          - fp3_8f14e45fceea167a
        components:
          type: object
          required:
          - basic
          - hardware
          - canvas
          - webgl
          - fonts
          - automation
          additionalProperties: true
          description: Complete SDK v3 signals (at most 32 KB as UTF-8 JSON). Generate with the SDK; the server recomputes visitorId. Legacy v2 requests are accepted without verification.
        confidence:
          type: number
          minimum: 0
          maximum: 1
          deprecated: true
          description: Ignored; the server computes signal quality.
        requestToken:
          type: string
          format: uuid
          description: SDK-generated retry token. Reuse only for the same logical request. Receipts last for the API log retention period.
  securitySchemes:
    publicKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'Public API key (`tt_` followed by 64 hex characters). It ships in page HTML and only works from pages on its domain. Also accepted as `Authorization: Bearer`.'
    serverKey:
      type: http
      scheme: bearer
      description: 'Secret server key (`tts_` followed by 64 hex characters) from Settings → API keys. Server-side only: requests with an Origin header are refused.'
    setupToken:
      type: http
      scheme: bearer
      description: 'The token creating the setup link returned (`tt_setup_` followed by 64 hex characters). Keep it to the agent: it collects the keys.'
externalDocs:
  description: 'Documentation (also as Markdown: /docs.md)'
  url: https://tracetail.io/docs