tracetail-io Service API

openapi: 3.2.0
info:
  title: TraceTail Service 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: Service
  description: Health and first-party proxy checks.
paths:
  /api/proxy/status:
    get:
      operationId: getProxyStatus
      tags:
      - Service
      summary: Check a first-party proxy
      description: 'What a first-party proxy''s `/health` answers: whether TraceTail accepts the proxy secret it sends.'
      responses:
        '200':
          description: Proxy status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProxyStatus'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                RATE_LIMITED:
                  value:
                    error: Rate limited
                    code: RATE_LIMITED
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
  /api/health:
    get:
      operationId: getHealth
      tags:
      - Service
      summary: API health
      responses:
        '200':
          description: Healthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Health'
        '503':
          description: Degraded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Health'
components:
  schemas:
    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.
    ProxyStatus:
      oneOf:
      - type: object
        required:
        - proxy
        - domain
        - visitorIp
        properties:
          proxy:
            const: trusted
          domain:
            type: string
          visitorIp:
            type:
            - string
            - 'null'
      - type: object
        required:
        - proxy
        - reason
        properties:
          proxy:
            const: untrusted
          reason:
            type: string
            enum:
            - no-secret
            - unknown-secret
    Health:
      type: object
      required:
      - status
      - timestamp
      - version
      - checks
      properties:
        status:
          type: string
          enum:
          - healthy
          - degraded
        timestamp:
          type: string
          format: date-time
        version:
          type: string
        checks:
          type: object
          additionalProperties:
            type: string
  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