tracetail-io Setup links API

openapi: 3.2.0
info:
  title: TraceTail Setup links 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: Setup links
  description: 'How an AI agent gets API keys for the person it works for: a link they open to sign in and add a card or continue without a card.'
paths:
  /api/v1/setup-links:
    post:
      operationId: createSetupLink
      tags:
      - Setup links
      summary: Create a setup link
      description: 'Give the returned setupUrl to the person you work for: they sign in with an emailed code, then add a card or continue without a card. Then check the link with its token every few seconds; the first check after they finish returns the keys, once. Links work for 24 hours. No authentication; refused from browsers.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetupLinkRequest'
            example:
              domains:
              - example.com
              - localhost
              serverKey: true
      responses:
        '201':
          description: The link, and the token to check it with (shown only now)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatedSetupLink'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                VALIDATION_ERROR:
                  value:
                    error: Invalid request
                    code: VALIDATION_ERROR
        '403':
          description: Called from a browser
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                BROWSER_REQUEST:
                  value:
                    error: Called from a browser
                    code: BROWSER_REQUEST
        '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/v1/setup-links/{setupLinkId}:
    get:
      operationId: checkSetupLink
      tags:
      - Setup links
      summary: Check a setup link
      description: Where the link stands. The first check after the person finishes returns an API key for each domain (null where the account already had one) and the server key if requested; later checks do not repeat them.
      security:
      - setupToken: []
      parameters:
      - name: setupLinkId
        in: path
        required: true
        schema:
          type: string
          pattern: ^sl_[0-9a-f]{32}$
          description: The setup link's id.
      responses:
        '200':
          description: The link
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SetupLink'
        '401':
          description: Missing token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                INVALID_TOKEN:
                  value:
                    error: Missing token
                    code: INVALID_TOKEN
        '403':
          description: Called from a browser
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                BROWSER_REQUEST:
                  value:
                    error: Called from a browser
                    code: BROWSER_REQUEST
        '404':
          description: Unknown link, or not its token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                NOT_FOUND:
                  value:
                    error: Unknown link, or not its token
                    code: NOT_FOUND
        '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
components:
  schemas:
    CreatedSetupLink:
      allOf:
      - $ref: '#/components/schemas/SetupLink'
      - type: object
        required:
        - token
        properties:
          token:
            type: string
            pattern: ^tt_setup_[0-9a-f]{64}$
            description: Checks the link. Shown only now.
    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.
    SetupLinkRequest:
      type: object
      required:
      - domains
      additionalProperties: false
      properties:
        domains:
          type: array
          minItems: 1
          maxItems: 5
          items:
            type: string
            examples:
            - example.com
            - localhost
          description: The sites to create API keys for. URLs are reduced to their domain; add localhost for local development.
        email:
          type: string
          format: email
          description: 'The person''s email, if known: it prefills the page.'
        serverKey:
          type: boolean
          description: Also create a server key, so the backend can verify identifications.
    SetupLink:
      type: object
      required:
      - id
      - status
      - setupUrl
      - domains
      - expiresAt
      - next
      properties:
        id:
          type: string
          pattern: ^sl_[0-9a-f]{32}$
          description: The setup link's id.
        status:
          type: string
          enum:
          - pending
          - completed
          - delivered
          - expired
          description: 'delivered: the keys were handed over (in this response, or an earlier one).'
        setupUrl:
          type: string
          format: uri
          description: The page to give the person.
        domains:
          type: array
          items:
            type: string
        expiresAt:
          type:
          - string
          - 'null'
          format: date-time
          description: When the person, then the agent, runs out of time.
        next:
          type: string
          description: What to do next, in words.
        account:
          type: object
          required:
          - email
          - paidUsage
          properties:
            email:
              type: string
              description: Masked (j***@example.com), for the person to check the account is theirs.
            paidUsage:
              type: boolean
              description: Metered usage billing is active.
            billingExempt:
              type: boolean
              description: When true, identification requests are unlimited and free.
          description: 'With the keys: the account they belong to.'
        apiKeys:
          type: array
          description: 'With the keys, once: one per domain. apiKey is null where the account already had a key for it.'
          items:
            type: object
            required:
            - domain
            - apiKey
            properties:
              domain:
                type: string
              apiKey:
                type:
                - string
                - 'null'
                pattern: ^tt_[0-9a-f]{64}$
        serverKey:
          type:
          - string
          - 'null'
          pattern: ^tts_[0-9a-f]{64}$
          description: With the keys, once, if requested and the account was created through the link (an existing account creates its own).
  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