Quickstart

Get a project API key, send an event, and confirm it was accepted.

Prerequisites

• A Retidal project. Create one in the console at https://retidal.com.
• A project API key. Ingestion has no scope gate — any valid project key works, legacy or scoped — see Authentication.

1. Get your API key

   In the console, open your project’s API Keys settings and copy an existing key, or issue a new one. The raw key is shown once at creation time — store it somewhere you can retrieve it, such as an environment variable.

   bash

   export RETIDAL_API_KEY="tk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

2. Send an event

   POST to https://api.retidal.com/api/v1/t with your key in the X-API-Key header. Add ?sync=1 so the response proves the event reached storage — drop it once you move to production traffic.

   bash

   curl -X POST "https://api.retidal.com/api/v1/t?sync=1" \
     -H "X-API-Key: $RETIDAL_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "eventName": "page_view",
       "visitorId": "vid_abc123"
     }'

3. Confirm it was accepted

   With ?sync=1, POST /api/v1/t returns 200 with processed: true on success — proof the event reached D1 and Analytics Engine, not just that it was queued:

   json

   {
     "accepted": 1,
     "failed": 0,
     "queued": 0,
     "processed": true
   }

   Drop ?sync=1 for production traffic: POST /api/v1/t’s default response is 202 with processed: false — the event was validated and dispatched to background processing, but persistence is not yet proven. Reserve ?sync=1 for integration checks and health checks.

4. Send a purchase event with attribution

   Real events carry more than a name. properties.amount is in minor units (cents), and clickIds captures ad-platform attribution:

   bash

   curl -X POST https://api.retidal.com/api/v1/t \
     -H "X-API-Key: $RETIDAL_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "eventName": "user_paid",
       "visitorId": "vid_abc123",
       "userId": "uid_456",
       "sessionId": "sess_789",
       "properties": { "amount": 9900, "currency": "CNY" },
       "clickIds": { "gclid": "xyz" }
     }'

What this unlocks

Sending your first event unlocks attaching richer identity and properties (Send data), reading the full response contract so you can tell a queued event from a persisted one (Errors & status codes), and wiring ad-platform and cross-device attribution via short links (Attribution).

Verify it worked

Re-run the sync request from step 2 (or step 4) and confirm the response is literally "processed": true:

bash

curl -s "https://api.retidal.com/api/v1/t?sync=1" \
  -H "X-API-Key: $RETIDAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"eventName": "page_view", "visitorId": "vid_abc123"}' | jq .processed
# expect: true

If it doesn’t work

If the request is rejected, times out, or processed never becomes true, work through Events not arriving.

Next steps

Send data

Full event fields, identity association, and Click ID capture.

Authentication

Capability scopes and how to issue and rotate keys.

Errors & status codes

The full ingestion response contract, including validation modes.

Attribution

Short links, cross-device stitching, and ad-platform callbacks.