Sources API

Tracking sources are the control plane for Tiny installs. A source owns the public key, allowed origins, install snippets, and debug history for a tracked app.

Authentication

All source-management endpoints use bearer-token authentication and are scoped to a workspace through organizationId.

curl "https://your-tiny-api/api/tracking-sources?organizationId=org_123" \
  -H "Authorization: Bearer {access_token}"

Endpoints

Name
GET /api/tracking-sources
Description
List sources for a workspace. Requires organizationId as a query parameter.
Name
POST /api/tracking-sources
Description
Create a source with organizationId, name, optional slug, allowedOrigins, and optional frameworkHint.
Name
PATCH /api/tracking-sources/:sourceId
Description
Update source fields such as name, slug, allowedOrigins, frameworkHint, or isActive.
Name
POST /api/tracking-sources/:sourceId/regenerate-key
Description
Rotate the source public key.
Name
GET /api/tracking-sources/:sourceId/install
Description
Fetch the generated browser snippet, Next.js example, React example, and debug URL for the source.
Name
GET /api/tracking-sources/:sourceId/debug
Description
Fetch source debug data, recent ingest attempts, event outcomes, and source limits.

Create and update sources

Create a source:

curl https://your-tiny-api/api/tracking-sources \
  -X POST \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "org_123",
    "name": "Marketing site",
    "slug": "marketing-site",
    "allowedOrigins": [
      "https://www.example.com",
      "http://localhost:3000"
    ],
    "frameworkHint": "nextjs"
  }'

Update a source:

curl https://your-tiny-api/api/tracking-sources/src_123 \
  -X PATCH \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "org_123",
    "allowedOrigins": [
      "https://www.example.com",
      "https://staging.example.com",
      "http://localhost:3000"
    ],
    "isActive": true
  }'

Install payload

The install endpoint returns the source-specific install assets used by the Tiny app.

{
  "publicKey": "pk_...",
  "apiBaseUrl": "https://your-tiny-api",
  "ingestVersion": 2,
  "browserSnippet": "<script>...</script>",
  "nextjsExample": "import Script from \"next/script\"; ...",
  "reactExample": "import { initTinyAnalytics } from \"@tiny/analytics\"; ...",
  "debugUrl": "https://your-app/analytics/setup/debug?sourceId=src_123"
}

Use this payload instead of hand-writing install snippets. It keeps the public key, API base URL, and debug route aligned.

Debug endpoint

The debug endpoint backs Analytics > Setup > Debug.

Expect it to include:

source metadata
ingest limits such as max batch size and payload bytes
recent bootstrap and event attempts
raw and normalized payload snapshots
per-event results for accepted, duplicate, and rejected outcomes

When an install is failing, start here before you inspect browser code manually.