{
  "openapi": "3.1.0",
  "info": {
    "title": "Tug API",
    "version": "2026-11-22",
    "summary": "Send behavioural events, serve approved decisions, and handle data subject requests.",
    "description": "Tug's public REST API. JSON in and out; a `text/plain` body holding JSON is accepted too (the browser snippet sends that to skip the CORS preflight).\n\nExamples write the host as `https://TUG_HOST`. Use the host you signed up on; /docs shows every example with it filled in.\n\nEvery error is JSON in the `Error` shape with a `Request-Id`, including unknown paths (`404 not_found`) and methods an endpoint doesn't take (`405 method_not_allowed`, with an `Allow` header). A database outage is `503 service_unavailable` with `Retry-After`.\n\nVersioning: the version is in the path (`/api/v1`). Additive changes ship without notice. Breaking changes get at least 90 days' notice in the changelog (/docs/resources/changelog), and responses from a deprecated endpoint carry `Deprecation` and `Sunset` headers (RFC 8594) until it is removed. `info.version` is the date of the latest change.\n\nChangelog entries: 1. Latest: 2026-11-22.",
    "contact": {
      "name": "Tug support",
      "url": "https://TUG_HOST/docs"
    }
  },
  "servers": [
    {
      "url": "/api/v1",
      "description": "Relative to the host serving this document."
    }
  ],
  "tags": [
    {
      "name": "Ingestion",
      "description": "Events and traits, from browsers or servers."
    },
    {
      "name": "Decisions",
      "description": "Approved messages for a user and surface, and what happened to them."
    },
    {
      "name": "Projects",
      "description": "Workspace projects, for server code."
    },
    {
      "name": "Integrations",
      "description": "Inbound webhooks from other tools."
    },
    {
      "name": "Data subject requests",
      "description": "GDPR and CCPA erasure, export and suppression. Server API key only."
    }
  ],
  "paths": {
    "/events": {
      "post": {
        "operationId": "trackEvents",
        "summary": "Track events",
        "description": "One event, or an array of up to 100 with the same publicKey. A batch is all or nothing: an invalid event is named (`events[3].occurredAt`) and none are stored. Counts 600 events per minute per project. Events for a suppressed (erased) end user are dropped and counted under `suppressed`.",
        "tags": [
          "Ingestion"
        ],
        "security": [
          {
            "publicKey": []
          },
          {
            "publicKey": [],
            "serverKey": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "description": "For a single event without its own idempotencyKey.",
            "schema": {
              "type": "string",
              "maxLength": 128
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/Event"
                  },
                  {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/Event"
                    },
                    "minItems": 1,
                    "maxItems": 100
                  }
                ]
              },
              "examples": {
                "single": {
                  "summary": "One event",
                  "value": {
                    "publicKey": "phk_live_3kV9xQmR2pT8wYc1Ld5NbA",
                    "distinctId": "user_123",
                    "name": "signup_completed",
                    "properties": {
                      "plan": "pro"
                    },
                    "occurredAt": "2026-11-22T16:41:00.000Z",
                    "idempotencyKey": "signup-user_123",
                    "sessionId": "s_8f2a1c",
                    "url": "https://app.example.com/signup"
                  }
                },
                "batch": {
                  "summary": "A batch",
                  "value": [
                    {
                      "publicKey": "phk_live_3kV9xQmR2pT8wYc1Ld5NbA",
                      "distinctId": "user_1",
                      "name": "$pageview"
                    },
                    {
                      "publicKey": "phk_live_3kV9xQmR2pT8wYc1Ld5NbA",
                      "distinctId": "user_2",
                      "name": "$pageview"
                    }
                  ]
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Stored. `accepted` + `duplicates` + `suppressed` equals the events sent.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/X-RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "accepted": {
                      "type": "integer",
                      "description": "Newly stored.",
                      "minimum": 0
                    },
                    "duplicates": {
                      "type": "integer",
                      "description": "Already stored under the same idempotency key.",
                      "minimum": 0
                    },
                    "suppressed": {
                      "type": "integer",
                      "description": "Dropped because the end user was erased.",
                      "minimum": 0
                    }
                  },
                  "required": [
                    "ok",
                    "accepted",
                    "duplicates",
                    "suppressed"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "ok": true,
                  "accepted": 1,
                  "duplicates": 0,
                  "suppressed": 0
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid. Fix it before retrying. Codes: `invalid_json`, `invalid_request`, `missing_public_key`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "invalid_json",
                    "message": "The body is empty or isn't valid JSON.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-invalid_json",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "invalid_json",
              "invalid_request",
              "missing_public_key"
            ]
          },
          "401": {
            "description": "Missing or wrong credentials. Codes: `invalid_public_key`, `invalid_api_key`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "invalid_public_key",
                    "message": "The publicKey is unknown, belongs to an archived project, or was rotated and its grace period ended.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-invalid_public_key",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "invalid_public_key",
              "invalid_api_key"
            ]
          },
          "402": {
            "description": "Billing stops this call. Codes: `trial_expired`, `billing_inactive`, `plan_limit_reached`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "trial_expired",
                    "message": "The workspace's trial has ended. Choose a plan under Settings, Billing.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-trial_expired",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "trial_expired",
              "billing_inactive",
              "plan_limit_reached"
            ]
          },
          "403": {
            "description": "Credentials are valid but not for this. Codes: `origin_not_allowed`, `api_key_project_mismatch`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "origin_not_allowed",
                    "message": "The request's Origin isn't the project's Allowed origin.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-origin_not_allowed",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "origin_not_allowed",
              "api_key_project_mismatch"
            ]
          },
          "413": {
            "description": "Too large. Codes: `payload_too_large`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "payload_too_large",
                    "message": "The body or the batch is over the documented size limit.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-payload_too_large",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "payload_too_large"
            ]
          },
          "429": {
            "description": "Rate limited. Retry after Retry-After seconds. Codes: `rate_limited`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "rate_limited",
                    "message": "Too many requests in this window. Wait for Retry-After seconds, then retry.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-rate_limited",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "rate_limited"
            ]
          },
          "500": {
            "description": "Tug failed. Safe to retry. Codes: `internal_error`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "internal_error",
                    "message": "Something failed on Tug's side. It is safe to retry.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-internal_error",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "internal_error"
            ]
          },
          "503": {
            "description": "Tug's database is unreachable. Retry after Retry-After seconds. Codes: `service_unavailable`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "service_unavailable",
                    "message": "Tug's database couldn't be reached. Retry after a short wait.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-service_unavailable",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "service_unavailable"
            ]
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST \"https://TUG_HOST/api/v1/events\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"publicKey\": \"phk_live_3kV9xQmR2pT8wYc1Ld5NbA\",\n    \"distinctId\": \"user_123\",\n    \"name\": \"signup_completed\",\n    \"properties\": {\n      \"plan\": \"pro\"\n    },\n    \"occurredAt\": \"2026-11-22T16:41:00.000Z\",\n    \"idempotencyKey\": \"signup-user_123\",\n    \"sessionId\": \"s_8f2a1c\",\n    \"url\": \"https://app.example.com/signup\"\n  }'"
          },
          {
            "lang": "JavaScript",
            "label": "Browser SDK",
            "source": "// The current visitor; call identify() after login to use your own id.\ntug.track(\"signup_completed\", { plan: \"pro\" });"
          },
          {
            "lang": "TypeScript",
            "label": "Node",
            "source": "import { TugClient } from \"tug-sdk\";\n\nconst tug = new TugClient({\n  publicKey: \"phk_live_3kV9xQmR2pT8wYc1Ld5NbA\",\n  baseUrl: \"https://TUG_HOST/api/v1\",\n  apiKey: process.env.TUG_API_KEY, // optional server API key\n});\n\nawait tug.track(\"user_123\", \"signup_completed\", { plan: \"pro\" }, {\n  idempotencyKey: \"signup-user_123\",\n  occurredAt: \"2026-11-22T16:41:00.000Z\",\n});"
          }
        ]
      }
    },
    "/identify": {
      "post": {
        "operationId": "identify",
        "summary": "Identify a user",
        "description": "Merge traits onto one end user (new keys added, existing keys replaced). Needs an active plan but doesn't count toward event limits. 300 requests per minute per project.",
        "tags": [
          "Ingestion"
        ],
        "security": [
          {
            "publicKey": []
          },
          {
            "publicKey": [],
            "serverKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "publicKey": {
                    "type": "string",
                    "description": "The project's public key (`phk_live_…`) from its project page.",
                    "maxLength": 200,
                    "examples": [
                      "phk_live_3kV9xQmR2pT8wYc1Ld5NbA"
                    ]
                  },
                  "distinctId": {
                    "type": [
                      "string",
                      "number"
                    ],
                    "description": "Your stable id for the end user. Numbers are converted to strings; surrounding spaces are trimmed. Don't use an email address or other personal data. Up to 256 characters.",
                    "maxLength": 256,
                    "examples": [
                      "user_123"
                    ]
                  },
                  "traits": {
                    "type": "object",
                    "description": "Traits to merge: a JSON object (not an array), up to 32 KB as JSON, 5 levels deep, keys up to 256 characters. No NUL characters or unpaired surrogates anywhere.",
                    "additionalProperties": true
                  }
                },
                "required": [
                  "publicKey",
                  "distinctId"
                ],
                "additionalProperties": false
              },
              "examples": {
                "identify": {
                  "summary": "Set traits",
                  "value": {
                    "publicKey": "phk_live_3kV9xQmR2pT8wYc1Ld5NbA",
                    "distinctId": "user_123",
                    "traits": {
                      "plan": "trial",
                      "company_size": "10"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Merged. `suppressed: true` means the end user was erased and nothing was stored.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/X-RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "suppressed": {
                      "const": true
                    }
                  },
                  "required": [
                    "ok"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "ok": true
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid. Fix it before retrying. Codes: `invalid_json`, `invalid_request`, `missing_public_key`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "invalid_json",
                    "message": "The body is empty or isn't valid JSON.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-invalid_json",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "invalid_json",
              "invalid_request",
              "missing_public_key"
            ]
          },
          "401": {
            "description": "Missing or wrong credentials. Codes: `invalid_public_key`, `invalid_api_key`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "invalid_public_key",
                    "message": "The publicKey is unknown, belongs to an archived project, or was rotated and its grace period ended.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-invalid_public_key",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "invalid_public_key",
              "invalid_api_key"
            ]
          },
          "402": {
            "description": "Billing stops this call. Codes: `trial_expired`, `billing_inactive`, `plan_limit_reached`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "trial_expired",
                    "message": "The workspace's trial has ended. Choose a plan under Settings, Billing.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-trial_expired",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "trial_expired",
              "billing_inactive",
              "plan_limit_reached"
            ]
          },
          "403": {
            "description": "Credentials are valid but not for this. Codes: `origin_not_allowed`, `api_key_project_mismatch`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "origin_not_allowed",
                    "message": "The request's Origin isn't the project's Allowed origin.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-origin_not_allowed",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "origin_not_allowed",
              "api_key_project_mismatch"
            ]
          },
          "413": {
            "description": "Too large. Codes: `payload_too_large`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "payload_too_large",
                    "message": "The body or the batch is over the documented size limit.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-payload_too_large",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "payload_too_large"
            ]
          },
          "429": {
            "description": "Rate limited. Retry after Retry-After seconds. Codes: `rate_limited`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "rate_limited",
                    "message": "Too many requests in this window. Wait for Retry-After seconds, then retry.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-rate_limited",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "rate_limited"
            ]
          },
          "500": {
            "description": "Tug failed. Safe to retry. Codes: `internal_error`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "internal_error",
                    "message": "Something failed on Tug's side. It is safe to retry.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-internal_error",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "internal_error"
            ]
          },
          "503": {
            "description": "Tug's database is unreachable. Retry after Retry-After seconds. Codes: `service_unavailable`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "service_unavailable",
                    "message": "Tug's database couldn't be reached. Retry after a short wait.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-service_unavailable",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "service_unavailable"
            ]
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST \"https://TUG_HOST/api/v1/identify\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"publicKey\": \"phk_live_3kV9xQmR2pT8wYc1Ld5NbA\",\n    \"distinctId\": \"user_123\",\n    \"traits\": {\n      \"plan\": \"trial\"\n    }\n  }'"
          },
          {
            "lang": "JavaScript",
            "label": "Browser SDK",
            "source": "// After login: later calls use this id.\ntug.identify(\"user_123\", { plan: \"trial\" });"
          },
          {
            "lang": "TypeScript",
            "label": "Node",
            "source": "import { TugClient } from \"tug-sdk\";\n\nconst tug = new TugClient({\n  publicKey: \"phk_live_3kV9xQmR2pT8wYc1Ld5NbA\",\n  baseUrl: \"https://TUG_HOST/api/v1\",\n  apiKey: process.env.TUG_API_KEY, // optional server API key\n});\n\nawait tug.identify(\"user_123\", { plan: \"trial\" });"
          }
        ]
      }
    },
    "/decisions/{surface}": {
      "get": {
        "operationId": "getDecision",
        "summary": "Get a decision",
        "description": "The highest-priority approved message for this user and surface, or `{ \"decision\": null }` (nothing approved, the user is in the holdout or was erased, or a cap applies). Safe to repeat: a serve counts toward billing and frequency caps when you report `shown` (POST /feedback), not when you fetch. `holdoutLogIds` lists control-group entries for messages that would have shown here: render nothing, and report `shown` for each when the slot renders, so both arms are counted the same way. A repeat fetch within 30 minutes returns the same `logId`. 1200 requests per minute per project, and 120 per end user.",
        "tags": [
          "Decisions"
        ],
        "security": [
          {
            "publicKey": []
          },
          {
            "publicKey": [],
            "userHash": []
          },
          {
            "publicKey": [],
            "serverKey": []
          }
        ],
        "parameters": [
          {
            "name": "surface",
            "in": "path",
            "required": true,
            "description": "Where the message appears. Any other value is a 400 that lists these.",
            "schema": {
              "type": "string",
              "enum": [
                "banner",
                "dashboard_card",
                "modal",
                "notification",
                "email"
              ]
            },
            "example": "banner"
          },
          {
            "name": "publicKey",
            "in": "query",
            "required": true,
            "description": "The project's public key.",
            "schema": {
              "type": "string",
              "maxLength": 200
            },
            "example": "phk_live_3kV9xQmR2pT8wYc1Ld5NbA"
          },
          {
            "name": "userId",
            "in": "query",
            "required": true,
            "description": "The end user's distinct id, up to 256 characters. \"undefined\" and \"null\" are refused.",
            "schema": {
              "type": "string",
              "maxLength": 256
            },
            "example": "user_123"
          },
          {
            "name": "userHash",
            "in": "query",
            "description": "Identity verification: lowercase hex HMAC-SHA256 of the user id, keyed with the project's identity secret, computed on your server. Required once the project turns on identity verification; ignored on server API key calls.",
            "schema": {
              "type": "string",
              "pattern": "^[0-9a-fA-F]{64}$"
            }
          },
          {
            "name": "shown",
            "in": "query",
            "description": "Server API key calls that render the message straight away can send shown=true to count the serve now, instead of a separate POST /feedback.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A decision, or null.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/X-RateLimit-Reset"
              },
              "X-Tug-Identity": {
                "$ref": "#/components/headers/X-Tug-Identity"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "decision": {
                      "oneOf": [
                        {
                          "$ref": "#/components/schemas/Decision"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "holdoutLogIds": {
                      "type": "array",
                      "items": {
                        "type": "integer",
                        "minimum": 1
                      },
                      "description": "Control-group entries for this slot. Report shown on each when the slot renders."
                    }
                  },
                  "required": [
                    "decision"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "decision": {
                    "id": "8e1f4a2b-6c3d-4e5f-9a0b-1c2d3e4f5a6b",
                    "logId": 42,
                    "surface": "banner",
                    "title": "You're close, one step left",
                    "body": "Most teams that finish setup see their first result the same day.",
                    "ctaLabel": "Finish setup",
                    "ctaUrl": "/onboarding",
                    "priority": 0.8
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid. Fix it before retrying. Codes: `invalid_json`, `invalid_request`, `missing_public_key`, `unknown_surface`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "invalid_json",
                    "message": "The body is empty or isn't valid JSON.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-invalid_json",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "invalid_json",
              "invalid_request",
              "missing_public_key",
              "unknown_surface"
            ]
          },
          "401": {
            "description": "Missing or wrong credentials. Codes: `invalid_public_key`, `invalid_api_key`, `missing_user_hash`, `invalid_user_hash`, `server_key_required`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "invalid_public_key",
                    "message": "The publicKey is unknown, belongs to an archived project, or was rotated and its grace period ended.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-invalid_public_key",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "invalid_public_key",
              "invalid_api_key",
              "missing_user_hash",
              "invalid_user_hash",
              "server_key_required"
            ]
          },
          "402": {
            "description": "Billing stops this call. Codes: `trial_expired`, `billing_inactive`, `plan_limit_reached`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "trial_expired",
                    "message": "The workspace's trial has ended. Choose a plan under Settings, Billing.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-trial_expired",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "trial_expired",
              "billing_inactive",
              "plan_limit_reached"
            ]
          },
          "403": {
            "description": "Credentials are valid but not for this. Codes: `origin_not_allowed`, `api_key_project_mismatch`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "origin_not_allowed",
                    "message": "The request's Origin isn't the project's Allowed origin.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-origin_not_allowed",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "origin_not_allowed",
              "api_key_project_mismatch"
            ]
          },
          "413": {
            "description": "Too large. Codes: `payload_too_large`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "payload_too_large",
                    "message": "The body or the batch is over the documented size limit.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-payload_too_large",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "payload_too_large"
            ]
          },
          "429": {
            "description": "Rate limited. Retry after Retry-After seconds. Codes: `rate_limited`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "rate_limited",
                    "message": "Too many requests in this window. Wait for Retry-After seconds, then retry.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-rate_limited",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "rate_limited"
            ]
          },
          "500": {
            "description": "Tug failed. Safe to retry. Codes: `internal_error`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "internal_error",
                    "message": "Something failed on Tug's side. It is safe to retry.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-internal_error",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "internal_error"
            ]
          },
          "503": {
            "description": "Tug's database is unreachable. Retry after Retry-After seconds. Codes: `service_unavailable`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "service_unavailable",
                    "message": "Tug's database couldn't be reached. Retry after a short wait.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-service_unavailable",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "service_unavailable"
            ]
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl \"https://TUG_HOST/api/v1/decisions/banner?publicKey=phk_live_3kV9xQmR2pT8wYc1Ld5NbA&userId=user_123\""
          },
          {
            "lang": "JavaScript",
            "label": "Browser SDK",
            "source": "const placement = await tug.getPlacement({ surface: \"banner\", userId: \"user_123\" });\nif (placement.decision) renderBanner(placement.decision);\n// When the slot is on screen (counts the message, or the holdout entries):\nplacement.shown();"
          },
          {
            "lang": "TypeScript",
            "label": "Node",
            "source": "import { TugClient } from \"tug-sdk\";\n\nconst tug = new TugClient({\n  publicKey: \"phk_live_3kV9xQmR2pT8wYc1Ld5NbA\",\n  baseUrl: \"https://TUG_HOST/api/v1\",\n  apiKey: process.env.TUG_API_KEY, // optional server API key\n});\n\n// Rendering now, on the server: count the serve in the same call.\nconst decision = await tug.getDecision({ surface: \"banner\", userId: \"user_123\", shown: true });\n\n// Or fetch now and report when the slot renders (counts holdout users too):\nconst placement = await tug.getPlacement({ surface: \"banner\", userId: \"user_123\" });\nawait tug.reportShown(placement);"
          }
        ]
      }
    },
    "/feedback": {
      "post": {
        "operationId": "sendFeedback",
        "summary": "Report what happened to a decision",
        "description": "Record `shown` (it rendered; this is what counts as a serve), `dismissed`, `clicked` or `converted` against a served decision. Send its logId, or its id as recommendationId to use the user's latest serve. Only `shown` is accepted for holdout entries. 300 requests per minute per project, and 60 per end user.",
        "tags": [
          "Decisions"
        ],
        "security": [
          {
            "publicKey": []
          },
          {
            "publicKey": [],
            "userHash": []
          },
          {
            "publicKey": [],
            "serverKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "publicKey": {
                    "type": "string",
                    "description": "The project's public key (`phk_live_…`) from its project page.",
                    "maxLength": 200,
                    "examples": [
                      "phk_live_3kV9xQmR2pT8wYc1Ld5NbA"
                    ]
                  },
                  "distinctId": {
                    "type": [
                      "string",
                      "number"
                    ],
                    "description": "Your stable id for the end user. Numbers are converted to strings; surrounding spaces are trimmed. Don't use an email address or other personal data. Up to 256 characters.",
                    "maxLength": 256,
                    "examples": [
                      "user_123"
                    ]
                  },
                  "userId": {
                    "type": [
                      "string",
                      "number"
                    ],
                    "description": "Old name for distinctId.",
                    "maxLength": 256,
                    "examples": [
                      "user_123"
                    ],
                    "deprecated": true
                  },
                  "action": {
                    "type": "string",
                    "enum": [
                      "shown",
                      "dismissed",
                      "clicked",
                      "converted"
                    ]
                  },
                  "logId": {
                    "type": [
                      "integer",
                      "string"
                    ],
                    "description": "The decision's logId (a numeric string is accepted).",
                    "minimum": 1,
                    "pattern": "^[0-9]+$"
                  },
                  "recommendationId": {
                    "type": "string",
                    "description": "The decision's id; uses the user's latest serve of it.",
                    "format": "uuid"
                  },
                  "userHash": {
                    "type": "string",
                    "description": "Identity verification: lowercase hex HMAC-SHA256 of the user id, keyed with the project's identity secret, computed on your server. Required once the project turns on identity verification; ignored on server API key calls.",
                    "pattern": "^[0-9a-fA-F]{64}$",
                    "examples": [
                      "6f1ed002ab5595859014ebf0951522d9a6c5b2c4f1e3a0b7d8c9e0f1a2b3c4d5"
                    ]
                  }
                },
                "required": [
                  "publicKey",
                  "action"
                ],
                "additionalProperties": false,
                "allOf": [
                  {
                    "anyOf": [
                      {
                        "required": [
                          "distinctId"
                        ]
                      },
                      {
                        "required": [
                          "userId"
                        ]
                      }
                    ]
                  },
                  {
                    "anyOf": [
                      {
                        "required": [
                          "logId"
                        ]
                      },
                      {
                        "required": [
                          "recommendationId"
                        ]
                      }
                    ]
                  }
                ]
              },
              "examples": {
                "clicked": {
                  "summary": "By logId",
                  "value": {
                    "publicKey": "phk_live_3kV9xQmR2pT8wYc1Ld5NbA",
                    "distinctId": "user_123",
                    "logId": 42,
                    "action": "clicked"
                  }
                },
                "byRecommendation": {
                  "summary": "By recommendation id",
                  "value": {
                    "publicKey": "phk_live_3kV9xQmR2pT8wYc1Ld5NbA",
                    "distinctId": "user_123",
                    "recommendationId": "8e1f4a2b-6c3d-4e5f-9a0b-1c2d3e4f5a6b",
                    "action": "dismissed"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Recorded. `recorded: false` means it was accepted but not stored (the end user was erased, or `shown` was already recorded).",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/X-RateLimit-Reset"
              },
              "X-Tug-Identity": {
                "$ref": "#/components/headers/X-Tug-Identity"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "recorded": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "ok"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "ok": true
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid. Fix it before retrying. Codes: `invalid_json`, `invalid_request`, `missing_public_key`, `holdout_feedback`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "invalid_json",
                    "message": "The body is empty or isn't valid JSON.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-invalid_json",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "invalid_json",
              "invalid_request",
              "missing_public_key",
              "holdout_feedback"
            ]
          },
          "401": {
            "description": "Missing or wrong credentials. Codes: `invalid_public_key`, `invalid_api_key`, `missing_user_hash`, `invalid_user_hash`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "invalid_public_key",
                    "message": "The publicKey is unknown, belongs to an archived project, or was rotated and its grace period ended.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-invalid_public_key",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "invalid_public_key",
              "invalid_api_key",
              "missing_user_hash",
              "invalid_user_hash"
            ]
          },
          "403": {
            "description": "Credentials are valid but not for this. Codes: `origin_not_allowed`, `api_key_project_mismatch`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "origin_not_allowed",
                    "message": "The request's Origin isn't the project's Allowed origin.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-origin_not_allowed",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "origin_not_allowed",
              "api_key_project_mismatch"
            ]
          },
          "404": {
            "description": "Not found. Codes: `decision_not_found`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "decision_not_found",
                    "message": "No served decision matches this logId (or recommendationId) for this user.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-decision_not_found",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "decision_not_found"
            ]
          },
          "413": {
            "description": "Too large. Codes: `payload_too_large`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "payload_too_large",
                    "message": "The body or the batch is over the documented size limit.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-payload_too_large",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "payload_too_large"
            ]
          },
          "429": {
            "description": "Rate limited. Retry after Retry-After seconds. Codes: `rate_limited`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "rate_limited",
                    "message": "Too many requests in this window. Wait for Retry-After seconds, then retry.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-rate_limited",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "rate_limited"
            ]
          },
          "500": {
            "description": "Tug failed. Safe to retry. Codes: `internal_error`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "internal_error",
                    "message": "Something failed on Tug's side. It is safe to retry.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-internal_error",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "internal_error"
            ]
          },
          "503": {
            "description": "Tug's database is unreachable. Retry after Retry-After seconds. Codes: `service_unavailable`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "service_unavailable",
                    "message": "Tug's database couldn't be reached. Retry after a short wait.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-service_unavailable",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "service_unavailable"
            ]
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST \"https://TUG_HOST/api/v1/feedback\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"publicKey\": \"phk_live_3kV9xQmR2pT8wYc1Ld5NbA\",\n    \"distinctId\": \"user_123\",\n    \"logId\": 42,\n    \"action\": \"clicked\"\n  }'"
          },
          {
            "lang": "JavaScript",
            "label": "Browser SDK",
            "source": "tug.feedback({ logId: decision.logId, action: \"clicked\" }); // or \"dismissed\""
          },
          {
            "lang": "TypeScript",
            "label": "Node",
            "source": "import { TugClient } from \"tug-sdk\";\n\nconst tug = new TugClient({\n  publicKey: \"phk_live_3kV9xQmR2pT8wYc1Ld5NbA\",\n  baseUrl: \"https://TUG_HOST/api/v1\",\n  apiKey: process.env.TUG_API_KEY, // optional server API key\n});\n\nconst decision = await tug.getDecision(\"banner\", \"user_123\");\nif (decision) {\n  await tug.feedback({ distinctId: \"user_123\", logId: decision.logId, action: \"clicked\" });\n}"
          }
        ]
      }
    },
    "/projects": {
      "get": {
        "operationId": "listProjects",
        "summary": "List projects",
        "description": "The API key's workspace projects with their public keys and environment labels, oldest first. Archived projects are left out.",
        "tags": [
          "Projects"
        ],
        "security": [
          {
            "serverKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Projects.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "projects": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Project"
                      }
                    }
                  },
                  "required": [
                    "projects"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "projects": [
                    {
                      "id": "5b0c7f9e-2d41-4c8a-9a6e-3f1d2b7c8e90",
                      "name": "Shipcart",
                      "slug": "shipcart",
                      "publicKey": "phk_live_3kV9xQmR2pT8wYc1Ld5NbA",
                      "allowedOrigin": "https://app.shipcart.example",
                      "environment": "production",
                      "createdAt": "2026-11-01T09:00:00.000Z"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong credentials. Codes: `server_key_required`, `invalid_api_key`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "server_key_required",
                    "message": "This endpoint or option needs a server API key (`Authorization: Bearer tug_…`).",
                    "docs": "https://TUG_HOST/docs/api/errors#error-server_key_required",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "server_key_required",
              "invalid_api_key"
            ]
          },
          "500": {
            "description": "Tug failed. Safe to retry. Codes: `internal_error`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "internal_error",
                    "message": "Something failed on Tug's side. It is safe to retry.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-internal_error",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "internal_error"
            ]
          },
          "503": {
            "description": "Tug's database is unreachable. Retry after Retry-After seconds. Codes: `service_unavailable`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "service_unavailable",
                    "message": "Tug's database couldn't be reached. Retry after a short wait.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-service_unavailable",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "service_unavailable"
            ]
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl \"https://TUG_HOST/api/v1/projects\" \\\n  -H \"Authorization: Bearer $TUG_API_KEY\""
          },
          {
            "lang": "TypeScript",
            "label": "Node",
            "source": "// No SDK method; any HTTP client works.\nconst res = await fetch(`https://TUG_HOST/api/v1/projects`, {\n  method: \"GET\",\n  headers: { Authorization: `Bearer ${process.env.TUG_API_KEY}` },\n});\nconst body = await res.json();\nif (!res.ok) throw new Error(`${body.error.code}: ${body.error.message} (${body.error.requestId})`);"
          }
        ]
      }
    },
    "/webhooks/posthog": {
      "post": {
        "operationId": "posthogWebhook",
        "summary": "Receive PostHog events",
        "description": "Target for a PostHog webhook destination. Server to server: no CORS or Allowed origin. Field limits match POST /events, but long values are cut rather than refused so a delivery is never rejected for length. Events for erased end users are dropped and counted under `suppressed`.",
        "tags": [
          "Integrations"
        ],
        "security": [
          {
            "publicKey": [],
            "webhookSecret": []
          }
        ],
        "parameters": [
          {
            "name": "publicKey",
            "in": "query",
            "required": true,
            "description": "The project's public key (part of the webhook URL Tug shows you).",
            "schema": {
              "type": "string"
            },
            "example": "phk_live_3kV9xQmR2pT8wYc1Ld5NbA"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/PostHogWrappedEvent"
                  },
                  {
                    "$ref": "#/components/schemas/PostHogFlatEvent"
                  },
                  {
                    "type": "array",
                    "items": {
                      "oneOf": [
                        {
                          "$ref": "#/components/schemas/PostHogWrappedEvent"
                        },
                        {
                          "$ref": "#/components/schemas/PostHogFlatEvent"
                        }
                      ]
                    },
                    "minItems": 1,
                    "maxItems": 100
                  }
                ]
              },
              "examples": {
                "template": {
                  "summary": "The destination body Tug recommends (before PostHog fills it in)",
                  "value": {
                    "event": {
                      "uuid": "{event.uuid}",
                      "event": "{event.event}",
                      "distinct_id": "{event.distinct_id}",
                      "timestamp": "{event.timestamp}",
                      "properties": "{event.properties}"
                    }
                  }
                },
                "wrapped": {
                  "summary": "Wrapped, as delivered",
                  "value": {
                    "event": {
                      "uuid": "01936f0e-5a7b-7c3d-9e1f-2a3b4c5d6e7f",
                      "event": "$pageview",
                      "distinct_id": "user_abc",
                      "timestamp": "2026-11-22T12:00:00.000Z",
                      "properties": {
                        "$current_url": "https://app.example.com/home",
                        "plan": "trial"
                      }
                    }
                  }
                },
                "flat": {
                  "summary": "Flat",
                  "value": {
                    "uuid": "01936f0e-5a7b-7c3d-9e1f-2a3b4c5d6e80",
                    "distinct_id": "user_abc",
                    "event": "signup_completed",
                    "timestamp": "2026-11-22T12:00:00.000Z",
                    "properties": {
                      "plan": "pro"
                    }
                  }
                },
                "batch": {
                  "summary": "A batch of either shape",
                  "value": [
                    {
                      "uuid": "01936f0e-5a7b-7c3d-9e1f-2a3b4c5d6e81",
                      "distinct_id": "user_1",
                      "event": "trial_started",
                      "timestamp": "2026-11-22T12:00:00.000Z",
                      "properties": {}
                    },
                    {
                      "event": {
                        "uuid": "01936f0e-5a7b-7c3d-9e1f-2a3b4c5d6e82",
                        "event": "$pageview",
                        "distinct_id": "user_2",
                        "timestamp": "2026-11-22T12:00:01.000Z",
                        "properties": {}
                      }
                    }
                  ]
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Stored (duplicates by uuid are stored once).",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "accepted": {
                      "type": "integer",
                      "description": "Events received and stored or already stored.",
                      "minimum": 0
                    },
                    "suppressed": {
                      "type": "integer",
                      "description": "Dropped because the end user was erased.",
                      "minimum": 0
                    }
                  },
                  "required": [
                    "ok",
                    "accepted",
                    "suppressed"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "ok": true,
                  "accepted": 1,
                  "suppressed": 0
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid. Fix it before retrying. Codes: `invalid_json`, `invalid_request`, `missing_public_key`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "invalid_json",
                    "message": "The body is empty or isn't valid JSON.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-invalid_json",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "invalid_json",
              "invalid_request",
              "missing_public_key"
            ]
          },
          "401": {
            "description": "Missing or wrong credentials. Codes: `invalid_public_key`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "invalid_public_key",
                    "message": "The publicKey is unknown, belongs to an archived project, or was rotated and its grace period ended.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-invalid_public_key",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "invalid_public_key"
            ]
          },
          "402": {
            "description": "Billing stops this call. Codes: `trial_expired`, `billing_inactive`, `plan_limit_reached`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "trial_expired",
                    "message": "The workspace's trial has ended. Choose a plan under Settings, Billing.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-trial_expired",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "trial_expired",
              "billing_inactive",
              "plan_limit_reached"
            ]
          },
          "403": {
            "description": "Credentials are valid but not for this. Codes: `webhook_not_enabled`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "webhook_not_enabled",
                    "message": "PostHog forwarding isn't turned on for this project.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-webhook_not_enabled",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "webhook_not_enabled"
            ]
          },
          "413": {
            "description": "Too large. Codes: `payload_too_large`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "payload_too_large",
                    "message": "The body or the batch is over the documented size limit.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-payload_too_large",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "payload_too_large"
            ]
          },
          "500": {
            "description": "Tug failed. Safe to retry. Codes: `internal_error`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "internal_error",
                    "message": "Something failed on Tug's side. It is safe to retry.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-internal_error",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "internal_error"
            ]
          },
          "503": {
            "description": "Tug's database is unreachable. Retry after Retry-After seconds. Codes: `service_unavailable`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "service_unavailable",
                    "message": "Tug's database couldn't be reached. Retry after a short wait.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-service_unavailable",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "service_unavailable"
            ]
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST \"https://TUG_HOST/api/v1/webhooks/posthog?publicKey=phk_live_3kV9xQmR2pT8wYc1Ld5NbA\" \\\n  -H \"X-Tug-Webhook-Secret: fwh_q8Zr3mN6vB1xK4cT7yW0pL2s\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"event\": {\n      \"uuid\": \"01936f0e-5a7b-7c3d-9e1f-2a3b4c5d6e7f\",\n      \"event\": \"signup_completed\",\n      \"distinct_id\": \"user_abc\",\n      \"timestamp\": \"2026-11-22T12:00:00.000Z\",\n      \"properties\": {\n        \"plan\": \"pro\"\n      }\n    }\n  }'"
          }
        ]
      }
    },
    "/users/{distinctId}": {
      "delete": {
        "operationId": "deleteUser",
        "summary": "Erase an end user",
        "description": "Deletes the end user's events, identity and traits, cohort memberships and decision log rows in this project, then keeps their ID (as a SHA-256 hash) on the suppression list so later data for it is dropped and counted. Deletes run in bounded batches. `200` with a completed receipt; `202` with `status: \"in_progress\"` when a very large user needs more time: send the same request again to continue (it resumes the same receipt), or leave it and the daily job finishes it. Idempotent. 120 data subject requests per minute per project.",
        "tags": [
          "Data subject requests"
        ],
        "security": [
          {
            "serverKey": []
          }
        ],
        "parameters": [
          {
            "name": "distinctId",
            "in": "path",
            "required": true,
            "description": "The end user's distinct id, percent-encoded (encodeURIComponent).",
            "schema": {
              "type": "string",
              "maxLength": 256
            },
            "example": "user_123"
          },
          {
            "name": "project",
            "in": "query",
            "required": true,
            "description": "Project id (a UUID; GET /projects lists them). Must belong to the API key's workspace.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "example": "5b0c7f9e-2d41-4c8a-9a6e-3f1d2b7c8e90"
          }
        ],
        "responses": {
          "200": {
            "description": "Erased.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/X-RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeletionReceipt"
                },
                "example": {
                  "object": "deletion_receipt",
                  "id": "0d9c8b7a-6f5e-4d3c-8b2a-19f8e7d6c5b4",
                  "projectId": "5b0c7f9e-2d41-4c8a-9a6e-3f1d2b7c8e90",
                  "distinctId": "user_123",
                  "status": "completed",
                  "deleted": {
                    "events": 1842,
                    "identities": 1,
                    "cohortMemberships": 3,
                    "decisions": 12
                  },
                  "suppressed": true,
                  "requestedAt": "2026-11-22T18:02:11.000Z",
                  "completedAt": "2026-11-22T18:02:12.000Z"
                }
              }
            }
          },
          "202": {
            "description": "Partly erased; send the request again to continue.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/X-RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeletionReceipt"
                },
                "example": {
                  "object": "deletion_receipt",
                  "id": "0d9c8b7a-6f5e-4d3c-8b2a-19f8e7d6c5b4",
                  "projectId": "5b0c7f9e-2d41-4c8a-9a6e-3f1d2b7c8e90",
                  "distinctId": "user_123",
                  "status": "in_progress",
                  "deleted": {
                    "events": 250000,
                    "identities": 0,
                    "cohortMemberships": 0,
                    "decisions": 0
                  },
                  "suppressed": true,
                  "requestedAt": "2026-11-22T18:02:11.000Z",
                  "completedAt": null
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid. Fix it before retrying. Codes: `invalid_request`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "invalid_request",
                    "message": "A field is missing or invalid. The message names the field.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-invalid_request",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "invalid_request"
            ]
          },
          "401": {
            "description": "Missing or wrong credentials. Codes: `server_key_required`, `invalid_api_key`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "server_key_required",
                    "message": "This endpoint or option needs a server API key (`Authorization: Bearer tug_…`).",
                    "docs": "https://TUG_HOST/docs/api/errors#error-server_key_required",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "server_key_required",
              "invalid_api_key"
            ]
          },
          "404": {
            "description": "Not found. Codes: `project_not_found`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "project_not_found",
                    "message": "The `project` query parameter isn't a project in the API key's workspace (or it is archived). Copy the id from GET /projects.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-project_not_found",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "project_not_found"
            ]
          },
          "429": {
            "description": "Rate limited. Retry after Retry-After seconds. Codes: `rate_limited`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "rate_limited",
                    "message": "Too many requests in this window. Wait for Retry-After seconds, then retry.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-rate_limited",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "rate_limited"
            ]
          },
          "500": {
            "description": "Tug failed. Safe to retry. Codes: `internal_error`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "internal_error",
                    "message": "Something failed on Tug's side. It is safe to retry.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-internal_error",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "internal_error"
            ]
          },
          "503": {
            "description": "Tug's database is unreachable. Retry after Retry-After seconds. Codes: `service_unavailable`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "service_unavailable",
                    "message": "Tug's database couldn't be reached. Retry after a short wait.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-service_unavailable",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "service_unavailable"
            ]
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X DELETE \"https://TUG_HOST/api/v1/users/user_123?project=5b0c7f9e-2d41-4c8a-9a6e-3f1d2b7c8e90\" \\\n  -H \"Authorization: Bearer $TUG_API_KEY\""
          },
          {
            "lang": "TypeScript",
            "label": "Node",
            "source": "// Server only: needs a server API key.\nconst res = await fetch(`https://TUG_HOST/api/v1/users/${encodeURIComponent(userId)}?project=5b0c7f9e-2d41-4c8a-9a6e-3f1d2b7c8e90`, {\n  method: \"DELETE\",\n  headers: { Authorization: `Bearer ${process.env.TUG_API_KEY}` },\n});\nconst body = await res.json();\nif (!res.ok) throw new Error(`${body.error.code}: ${body.error.message} (${body.error.requestId})`);\n// 202 means more to delete: send the same request again."
          }
        ]
      }
    },
    "/users/{distinctId}/export": {
      "get": {
        "operationId": "exportUser",
        "summary": "Export an end user's data",
        "description": "Everything Tug stores about the end user in this project: identity and traits, cohort memberships, decision log rows and events. Events are paged oldest first (`limit`, default 1000, at most 10,000); follow `nextCursor` while `hasMore` is true. Other sections come whole on every page.",
        "tags": [
          "Data subject requests"
        ],
        "security": [
          {
            "serverKey": []
          }
        ],
        "parameters": [
          {
            "name": "distinctId",
            "in": "path",
            "required": true,
            "description": "The end user's distinct id, percent-encoded (encodeURIComponent).",
            "schema": {
              "type": "string",
              "maxLength": 256
            },
            "example": "user_123"
          },
          {
            "name": "project",
            "in": "query",
            "required": true,
            "description": "Project id (a UUID; GET /projects lists them). Must belong to the API key's workspace.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "example": "5b0c7f9e-2d41-4c8a-9a6e-3f1d2b7c8e90"
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Events per page, 1 to 10000. Default 1000.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 10000,
              "default": 1000
            },
            "example": 1000
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "nextCursor from the previous page.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The end user's data.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/X-RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserExport"
                },
                "example": {
                  "object": "user_export",
                  "projectId": "5b0c7f9e-2d41-4c8a-9a6e-3f1d2b7c8e90",
                  "distinctId": "user_123",
                  "exportedAt": "2026-11-22T18:00:00.000Z",
                  "suppressed": false,
                  "identity": {
                    "traits": {
                      "plan": "trial"
                    },
                    "firstSeenAt": "2026-11-01T09:12:00.000Z",
                    "lastSeenAt": "2026-11-22T16:41:00.000Z"
                  },
                  "cohorts": [
                    {
                      "cohortId": "3c2b1a09-8f7e-4d6c-9b5a-4e3d2c1b0a9f",
                      "name": "Stalled in setup",
                      "addedAt": "2026-11-20T07:00:00.000Z"
                    }
                  ],
                  "decisions": [
                    {
                      "logId": 42,
                      "recommendationId": "8e1f4a2b-6c3d-4e5f-9a0b-1c2d3e4f5a6b",
                      "surface": "banner",
                      "servedAt": "2026-11-21T10:00:00.000Z",
                      "shownAt": "2026-11-21T10:00:01.000Z",
                      "clickedAt": null,
                      "dismissedAt": null,
                      "convertedAt": null,
                      "isHoldout": false
                    }
                  ],
                  "events": [
                    {
                      "id": 90812,
                      "name": "signup_completed",
                      "properties": {
                        "plan": "pro"
                      },
                      "occurredAt": "2026-11-22T16:41:00.000Z",
                      "ingestedAt": "2026-11-22T16:41:01.000Z",
                      "sessionId": "s_8f2a1c",
                      "url": "https://app.example.com/signup"
                    }
                  ],
                  "hasMore": false,
                  "nextCursor": null
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid. Fix it before retrying. Codes: `invalid_request`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "invalid_request",
                    "message": "A field is missing or invalid. The message names the field.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-invalid_request",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "invalid_request"
            ]
          },
          "401": {
            "description": "Missing or wrong credentials. Codes: `server_key_required`, `invalid_api_key`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "server_key_required",
                    "message": "This endpoint or option needs a server API key (`Authorization: Bearer tug_…`).",
                    "docs": "https://TUG_HOST/docs/api/errors#error-server_key_required",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "server_key_required",
              "invalid_api_key"
            ]
          },
          "404": {
            "description": "Not found. Codes: `project_not_found`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "project_not_found",
                    "message": "The `project` query parameter isn't a project in the API key's workspace (or it is archived). Copy the id from GET /projects.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-project_not_found",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "project_not_found"
            ]
          },
          "429": {
            "description": "Rate limited. Retry after Retry-After seconds. Codes: `rate_limited`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "rate_limited",
                    "message": "Too many requests in this window. Wait for Retry-After seconds, then retry.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-rate_limited",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "rate_limited"
            ]
          },
          "500": {
            "description": "Tug failed. Safe to retry. Codes: `internal_error`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "internal_error",
                    "message": "Something failed on Tug's side. It is safe to retry.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-internal_error",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "internal_error"
            ]
          },
          "503": {
            "description": "Tug's database is unreachable. Retry after Retry-After seconds. Codes: `service_unavailable`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "service_unavailable",
                    "message": "Tug's database couldn't be reached. Retry after a short wait.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-service_unavailable",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "service_unavailable"
            ]
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl \"https://TUG_HOST/api/v1/users/user_123/export?project=5b0c7f9e-2d41-4c8a-9a6e-3f1d2b7c8e90\" \\\n  -H \"Authorization: Bearer $TUG_API_KEY\""
          },
          {
            "lang": "TypeScript",
            "label": "Node",
            "source": "// Server only: needs a server API key. Collects every page of events.\nconst base = `https://TUG_HOST/api/v1/users/${encodeURIComponent(userId)}/export?project=5b0c7f9e-2d41-4c8a-9a6e-3f1d2b7c8e90`;\nconst headers = { Authorization: `Bearer ${process.env.TUG_API_KEY}` };\nlet page = await (await fetch(base, { headers })).json();\nconst events = [...page.events];\nwhile (page.hasMore) {\n  page = await (await fetch(`${base}&cursor=${page.nextCursor}`, { headers })).json();\n  events.push(...page.events);\n}"
          }
        ]
      }
    },
    "/suppressions/{distinctId}": {
      "delete": {
        "operationId": "deleteSuppression",
        "summary": "Lift a suppression",
        "description": "Removes the ID from the suppression list an erasure added, so data for it is accepted again (for example, the person signed up again and agreed). Idempotent: `removed` is false when it wasn't suppressed.",
        "tags": [
          "Data subject requests"
        ],
        "security": [
          {
            "serverKey": []
          }
        ],
        "parameters": [
          {
            "name": "distinctId",
            "in": "path",
            "required": true,
            "description": "The end user's distinct id, percent-encoded (encodeURIComponent).",
            "schema": {
              "type": "string",
              "maxLength": 256
            },
            "example": "user_123"
          },
          {
            "name": "project",
            "in": "query",
            "required": true,
            "description": "Project id (a UUID; GET /projects lists them). Must belong to the API key's workspace.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "example": "5b0c7f9e-2d41-4c8a-9a6e-3f1d2b7c8e90"
          }
        ],
        "responses": {
          "200": {
            "description": "Done.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/X-RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "const": "suppression"
                    },
                    "projectId": {
                      "type": "string",
                      "description": "Project id.",
                      "format": "uuid"
                    },
                    "distinctId": {
                      "type": "string",
                      "description": "The ID."
                    },
                    "removed": {
                      "type": "boolean",
                      "description": "False when the ID wasn't suppressed."
                    }
                  },
                  "required": [
                    "object",
                    "projectId",
                    "distinctId",
                    "removed"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "object": "suppression",
                  "projectId": "5b0c7f9e-2d41-4c8a-9a6e-3f1d2b7c8e90",
                  "distinctId": "user_123",
                  "removed": true
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid. Fix it before retrying. Codes: `invalid_request`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "invalid_request",
                    "message": "A field is missing or invalid. The message names the field.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-invalid_request",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "invalid_request"
            ]
          },
          "401": {
            "description": "Missing or wrong credentials. Codes: `server_key_required`, `invalid_api_key`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "server_key_required",
                    "message": "This endpoint or option needs a server API key (`Authorization: Bearer tug_…`).",
                    "docs": "https://TUG_HOST/docs/api/errors#error-server_key_required",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "server_key_required",
              "invalid_api_key"
            ]
          },
          "404": {
            "description": "Not found. Codes: `project_not_found`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "project_not_found",
                    "message": "The `project` query parameter isn't a project in the API key's workspace (or it is archived). Copy the id from GET /projects.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-project_not_found",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "project_not_found"
            ]
          },
          "429": {
            "description": "Rate limited. Retry after Retry-After seconds. Codes: `rate_limited`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "rate_limited",
                    "message": "Too many requests in this window. Wait for Retry-After seconds, then retry.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-rate_limited",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "rate_limited"
            ]
          },
          "500": {
            "description": "Tug failed. Safe to retry. Codes: `internal_error`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "internal_error",
                    "message": "Something failed on Tug's side. It is safe to retry.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-internal_error",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "internal_error"
            ]
          },
          "503": {
            "description": "Tug's database is unreachable. Retry after Retry-After seconds. Codes: `service_unavailable`.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "service_unavailable",
                    "message": "Tug's database couldn't be reached. Retry after a short wait.",
                    "docs": "https://TUG_HOST/docs/api/errors#error-service_unavailable",
                    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
                  }
                }
              }
            },
            "x-tug-error-codes": [
              "service_unavailable"
            ]
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X DELETE \"https://TUG_HOST/api/v1/suppressions/user_123?project=5b0c7f9e-2d41-4c8a-9a6e-3f1d2b7c8e90\" \\\n  -H \"Authorization: Bearer $TUG_API_KEY\""
          },
          {
            "lang": "TypeScript",
            "label": "Node",
            "source": "// Server only: needs a server API key.\nconst res = await fetch(`https://TUG_HOST/api/v1/suppressions/${encodeURIComponent(userId)}?project=5b0c7f9e-2d41-4c8a-9a6e-3f1d2b7c8e90`, {\n  method: \"DELETE\",\n  headers: { Authorization: `Bearer ${process.env.TUG_API_KEY}` },\n});\nconst body = await res.json();\nif (!res.ok) throw new Error(`${body.error.code}: ${body.error.message} (${body.error.requestId})`);"
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "Event": {
        "type": "object",
        "properties": {
          "publicKey": {
            "type": "string",
            "description": "The project's public key (`phk_live_…`) from its project page.",
            "maxLength": 200,
            "examples": [
              "phk_live_3kV9xQmR2pT8wYc1Ld5NbA"
            ]
          },
          "distinctId": {
            "type": [
              "string",
              "number"
            ],
            "description": "Your stable id for the end user. Numbers are converted to strings; surrounding spaces are trimmed. Don't use an email address or other personal data. Up to 256 characters.",
            "maxLength": 256,
            "examples": [
              "user_123"
            ]
          },
          "name": {
            "type": "string",
            "description": "Event name, up to 200 characters. Trimmed; blank is refused.",
            "maxLength": 200,
            "minLength": 1
          },
          "properties": {
            "type": "object",
            "description": "Event properties: a JSON object (not an array), up to 32 KB as JSON, 5 levels deep, keys up to 256 characters. No NUL characters or unpaired surrogates anywhere.",
            "additionalProperties": true
          },
          "occurredAt": {
            "type": "string",
            "description": "When the event happened, ISO 8601 (stored as UTC). Defaults to when Tug receives it. Must be in 2000 or later and at most an hour ahead of Tug's clock. Use it to backfill.",
            "format": "date-time"
          },
          "idempotencyKey": {
            "type": "string",
            "description": "Up to 128 characters. The same key again for the project is stored once and counted under duplicates. Both SDKs set one on every event.",
            "maxLength": 128
          },
          "sessionId": {
            "type": "string",
            "description": "Up to 128 characters.",
            "maxLength": 128
          },
          "url": {
            "type": "string",
            "description": "Page URL. Longer than 2048 characters is cut to that length, not refused."
          }
        },
        "required": [
          "publicKey",
          "distinctId",
          "name"
        ],
        "additionalProperties": false
      },
      "Decision": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "The recommendation's id. Send it as recommendationId to POST /feedback if you lost logId.",
            "format": "uuid"
          },
          "logId": {
            "type": [
              "integer",
              "null"
            ],
            "description": "This serve's decision log id. Send it to POST /feedback.",
            "minimum": 1
          },
          "surface": {
            "type": "string",
            "enum": [
              "banner",
              "dashboard_card",
              "modal",
              "notification",
              "email"
            ]
          },
          "title": {
            "type": "string",
            "description": "Approved headline."
          },
          "body": {
            "type": "string",
            "description": "Approved body copy."
          },
          "ctaLabel": {
            "type": [
              "string",
              "null"
            ],
            "description": "Button label."
          },
          "ctaUrl": {
            "type": [
              "string",
              "null"
            ],
            "description": "Button link: an absolute http(s) URL or a path starting with /."
          },
          "priority": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "description": "0 to 1. When several messages match, the highest is served."
          }
        },
        "required": [
          "id",
          "logId",
          "surface",
          "title",
          "body",
          "ctaLabel",
          "ctaUrl",
          "priority"
        ],
        "additionalProperties": false
      },
      "Project": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Project id.",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "description": "Name."
          },
          "slug": {
            "type": "string",
            "description": "URL slug."
          },
          "publicKey": {
            "type": "string",
            "description": "Browser-safe key."
          },
          "allowedOrigin": {
            "type": [
              "string",
              "null"
            ],
            "description": "Browser calls are accepted only from this origin; null means any."
          },
          "environment": {
            "type": "string",
            "enum": [
              "production",
              "staging",
              "development"
            ],
            "description": "Label for which environment the project's keys belong to. Use one project per environment."
          },
          "createdAt": {
            "type": "string",
            "description": "Created.",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "name",
          "slug",
          "publicKey",
          "allowedOrigin",
          "environment",
          "createdAt"
        ],
        "additionalProperties": false
      },
      "PostHogWrappedEvent": {
        "type": "object",
        "properties": {
          "event": {
            "type": "object",
            "properties": {
              "uuid": {
                "type": "string",
                "description": "PostHog's event id. Stored as the idempotency key (`ph:<uuid>`), so retries are stored once. Send it."
              },
              "event": {
                "type": "string",
                "description": "Event name. Longer than 200 characters is cut."
              },
              "distinct_id": {
                "type": "string",
                "description": "PostHog distinct id. Longer than 256 characters is cut."
              },
              "timestamp": {
                "type": "string",
                "description": "When it happened, ISO 8601. Defaults to when Tug receives it.",
                "format": "date-time"
              },
              "properties": {
                "type": [
                  "object",
                  "string"
                ],
                "description": "Properties, or a JSON string of them. `$`-prefixed keys are dropped except $current_url, which becomes url (cut to 2048 characters). Nested objects and arrays are dropped. Tug adds source: \"posthog\"."
              }
            },
            "required": [
              "event",
              "distinct_id"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "event"
        ],
        "additionalProperties": true,
        "description": "PostHog's destination shape. Other top-level keys (person, …) are ignored."
      },
      "PostHogFlatEvent": {
        "type": "object",
        "properties": {
          "uuid": {
            "type": "string",
            "description": "PostHog's event id. Stored as the idempotency key (`ph:<uuid>`), so retries are stored once. Send it."
          },
          "event": {
            "type": "string",
            "description": "Event name. Longer than 200 characters is cut."
          },
          "distinct_id": {
            "type": "string",
            "description": "PostHog distinct id. Longer than 256 characters is cut."
          },
          "timestamp": {
            "type": "string",
            "description": "When it happened, ISO 8601. Defaults to when Tug receives it.",
            "format": "date-time"
          },
          "properties": {
            "type": [
              "object",
              "string"
            ],
            "description": "Properties, or a JSON string of them. `$`-prefixed keys are dropped except $current_url, which becomes url (cut to 2048 characters). Nested objects and arrays are dropped. Tug adds source: \"posthog\"."
          }
        },
        "required": [
          "event",
          "distinct_id"
        ],
        "additionalProperties": false,
        "description": "One event at the top level."
      },
      "DeletionReceipt": {
        "type": "object",
        "properties": {
          "object": {
            "const": "deletion_receipt"
          },
          "id": {
            "type": "string",
            "description": "Receipt id. Re-sending the request while it is in progress continues this receipt.",
            "format": "uuid"
          },
          "projectId": {
            "type": "string",
            "description": "Project the end user was erased from.",
            "format": "uuid"
          },
          "distinctId": {
            "type": "string",
            "description": "The erased end user's id, as you sent it. Tug keeps only a SHA-256 hash of it."
          },
          "status": {
            "type": "string",
            "enum": [
              "completed",
              "in_progress"
            ]
          },
          "deleted": {
            "type": "object",
            "properties": {
              "events": {
                "type": "integer",
                "description": "Events deleted.",
                "minimum": 0
              },
              "identities": {
                "type": "integer",
                "description": "Identity rows deleted (traits live on the identity).",
                "minimum": 0
              },
              "cohortMemberships": {
                "type": "integer",
                "description": "Cohort memberships deleted.",
                "minimum": 0
              },
              "decisions": {
                "type": "integer",
                "description": "Decision log rows deleted.",
                "minimum": 0
              }
            },
            "required": [
              "events",
              "identities",
              "cohortMemberships",
              "decisions"
            ],
            "additionalProperties": false
          },
          "suppressed": {
            "type": "boolean",
            "description": "True once the ID is on the suppression list."
          },
          "requestedAt": {
            "type": "string",
            "description": "When the request was first received.",
            "format": "date-time"
          },
          "completedAt": {
            "type": [
              "string",
              "null"
            ],
            "description": "When deletion finished.",
            "format": "date-time"
          }
        },
        "required": [
          "object",
          "id",
          "projectId",
          "distinctId",
          "status",
          "deleted",
          "suppressed",
          "requestedAt",
          "completedAt"
        ],
        "additionalProperties": false
      },
      "UserExport": {
        "type": "object",
        "properties": {
          "object": {
            "const": "user_export"
          },
          "projectId": {
            "type": "string",
            "description": "Project id.",
            "format": "uuid"
          },
          "distinctId": {
            "type": "string",
            "description": "The end user's id."
          },
          "exportedAt": {
            "type": "string",
            "description": "When this page was produced.",
            "format": "date-time"
          },
          "suppressed": {
            "type": "boolean",
            "description": "True when the ID is on the suppression list (it was erased)."
          },
          "identity": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "traits": {
                "type": "object",
                "description": "Merged traits from identify().",
                "additionalProperties": true
              },
              "firstSeenAt": {
                "type": "string",
                "description": "First event or identify.",
                "format": "date-time"
              },
              "lastSeenAt": {
                "type": "string",
                "description": "Latest event or identify.",
                "format": "date-time"
              }
            },
            "required": [
              "traits",
              "firstSeenAt",
              "lastSeenAt"
            ],
            "additionalProperties": false
          },
          "cohorts": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "cohortId": {
                  "type": "string",
                  "description": "Cohort id.",
                  "format": "uuid"
                },
                "name": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Cohort name."
                },
                "addedAt": {
                  "type": "string",
                  "description": "When the user joined it.",
                  "format": "date-time"
                }
              },
              "required": [
                "cohortId",
                "name",
                "addedAt"
              ],
              "additionalProperties": false
            }
          },
          "decisions": {
            "type": "array",
            "description": "Decision log rows, oldest first (up to 10,000).",
            "items": {
              "type": "object",
              "properties": {
                "logId": {
                  "type": "integer",
                  "description": "Decision log id.",
                  "minimum": 1
                },
                "recommendationId": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Recommendation served.",
                  "format": "uuid"
                },
                "surface": {
                  "type": "string",
                  "enum": [
                    "banner",
                    "dashboard_card",
                    "modal",
                    "notification",
                    "email"
                  ]
                },
                "servedAt": {
                  "type": "string",
                  "description": "Fetched.",
                  "format": "date-time"
                },
                "shownAt": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Reported shown.",
                  "format": "date-time"
                },
                "clickedAt": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Reported clicked.",
                  "format": "date-time"
                },
                "dismissedAt": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Reported dismissed.",
                  "format": "date-time"
                },
                "convertedAt": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Converted.",
                  "format": "date-time"
                },
                "isHoldout": {
                  "type": "boolean",
                  "description": "In the control group (nothing was shown)."
                }
              },
              "required": [
                "logId",
                "recommendationId",
                "surface",
                "servedAt",
                "shownAt",
                "clickedAt",
                "dismissedAt",
                "convertedAt",
                "isHoldout"
              ],
              "additionalProperties": false
            }
          },
          "events": {
            "type": "array",
            "description": "This page of events, oldest first.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer",
                  "description": "Event id.",
                  "minimum": 1
                },
                "name": {
                  "type": "string",
                  "description": "Event name."
                },
                "properties": {
                  "type": "object",
                  "description": "Event properties as stored.",
                  "additionalProperties": true
                },
                "occurredAt": {
                  "type": "string",
                  "description": "When it happened.",
                  "format": "date-time"
                },
                "ingestedAt": {
                  "type": "string",
                  "description": "When Tug received it.",
                  "format": "date-time"
                },
                "sessionId": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Session id."
                },
                "url": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Page URL."
                }
              },
              "required": [
                "id",
                "name",
                "properties",
                "occurredAt",
                "ingestedAt",
                "sessionId",
                "url"
              ],
              "additionalProperties": false
            }
          },
          "hasMore": {
            "type": "boolean",
            "description": "More events exist; fetch nextCursor."
          },
          "nextCursor": {
            "type": [
              "string",
              "null"
            ],
            "description": "Pass as cursor for the next page of events."
          }
        },
        "required": [
          "object",
          "projectId",
          "distinctId",
          "exportedAt",
          "suppressed",
          "identity",
          "cohorts",
          "decisions",
          "events",
          "hasMore",
          "nextCursor"
        ],
        "additionalProperties": false
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "invalid_request",
                  "invalid_json",
                  "missing_public_key",
                  "unknown_surface",
                  "holdout_feedback",
                  "invalid_public_key",
                  "invalid_api_key",
                  "server_key_required",
                  "missing_user_hash",
                  "invalid_user_hash",
                  "trial_expired",
                  "billing_inactive",
                  "plan_limit_reached",
                  "feature_not_in_plan",
                  "origin_not_allowed",
                  "api_key_project_mismatch",
                  "webhook_not_enabled",
                  "not_found",
                  "decision_not_found",
                  "project_not_found",
                  "method_not_allowed",
                  "payload_too_large",
                  "rate_limited",
                  "internal_error",
                  "service_unavailable"
                ],
                "description": "Stable; branch on this."
              },
              "message": {
                "type": "string",
                "description": "What happened and what to do, for people. May change."
              },
              "docs": {
                "type": "string",
                "description": "Link to this code in the catalogue.",
                "format": "uri"
              },
              "requestId": {
                "type": "string",
                "description": "Also in the Request-Id header. Quote it to support.",
                "pattern": "^req_"
              }
            },
            "required": [
              "code",
              "message",
              "docs",
              "requestId"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false,
        "description": "Every non-2xx response has this body."
      }
    },
    "securitySchemes": {
      "publicKey": {
        "type": "apiKey",
        "in": "query",
        "name": "publicKey",
        "description": "The project's browser-safe key (`phk_live_…`). GET endpoints take it in the query; POST endpoints in the JSON body as `publicKey`. Browser calls are checked against the project's Allowed origin (a request without an Origin header, such as curl, is not)."
      },
      "serverKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "tug_…",
        "description": "Server API key from Settings, API keys. New keys start with `tug_`; keys made before the rename (`folio_`) keep working. Never ship it to a browser. Required for /projects and data subject requests; optional on the others, where it marks the call as server to server (no Allowed origin check, no userHash needed) and must belong to the publicKey's workspace."
      },
      "userHash": {
        "type": "apiKey",
        "in": "query",
        "name": "userHash",
        "description": "Identity verification for decisions and feedback: lowercase hex HMAC-SHA256(identity secret, userId), computed on your server. Query parameter on GET /decisions, body field on POST /feedback. The X-Folio-Identity response header says whether it checked out."
      },
      "webhookSecret": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Tug-Webhook-Secret",
        "description": "The project's PostHog forwarding secret (`fwh_…`), from Connect PostHog on the project page. The old header name, X-Folio-Webhook-Secret, is still accepted."
      }
    },
    "headers": {
      "Request-Id": {
        "description": "Unique id for this request, on every response (also X-Request-Id, and requestId in error bodies). Quote it to support.",
        "schema": {
          "type": "string",
          "pattern": "^req_"
        }
      },
      "X-Request-Id": {
        "description": "The same value as Request-Id, for tools that look for this name.",
        "schema": {
          "type": "string",
          "pattern": "^req_"
        }
      },
      "X-RateLimit-Limit": {
        "description": "The tightest limit that applied, for the current one-minute window: requests, or events for POST /events. GET /decisions and POST /feedback also have per-user limits, and whichever has fewer left is reported. Sent on every response once the project is known, errors included.",
        "schema": {
          "type": "integer"
        }
      },
      "X-RateLimit-Remaining": {
        "description": "Left in the current window. Absent when the limiter couldn't count the request.",
        "schema": {
          "type": "integer"
        }
      },
      "X-RateLimit-Reset": {
        "description": "Seconds until the window resets.",
        "schema": {
          "type": "integer"
        }
      },
      "Retry-After": {
        "description": "Seconds to wait before retrying (429 and 503).",
        "schema": {
          "type": "integer"
        }
      },
      "X-Tug-Identity": {
        "description": "Identity verification result: verified, unverified (no userHash sent), invalid, or server_key.",
        "schema": {
          "type": "string",
          "enum": [
            "verified",
            "unverified",
            "invalid",
            "server_key"
          ]
        }
      }
    }
  }
}
