Skip to content
Retidal Docs

Introduction

The Retidal marketing-attribution and engagement platform API.

Retidal (engineering codename Trackly) is a multi-tenant marketing platform: short-link attribution, event collection, decisioning, coupons, and email — reachable from two public HTTP surfaces.

Prerequisites

Section titled “Prerequisites”
  • A Retidal project and a project API key — see Quickstart to create one in under five minutes.
  • Nothing else: this page is background, not a procedure.

The two APIs

Section titled “The two APIs”
Ingestion & Decisioning API

The integration surface your application calls at runtime: send events, associate identities, request incentive decisions, upsert profiles, redeem coupons, and back-fill history. Authenticated with a scoped API key. Base URL https://api.retidal.com.

Management API

The console/back-office surface for configuring projects: analytics, the event catalog, email (providers, templates, triggers, campaigns), automations, custom domains, users, and more. Authenticated with a session cookie today; a growing subset accepts scoped API keys. Base URL https://retidal.com.

Core concepts

Section titled “Core concepts”
  • Project — the tenant boundary. Every data row is isolated by projectId; every management path is scoped to /api/projects/{projectId}/....
  • API key — a project credential. A legacy key carries the implicit ingest:write scope only. A scoped key carries an explicit set of capability scopes (see Authentication).
  • Event — a named user action (page_view, user_paid, …) with arbitrary properties, attributed to a visitorId and optionally a userId.
  • Short link — a tracked URL (GET /s/{code}) that always 302-redirects and seeds attribution. Retidal never uses a permanent redirect — a cached permanent redirect would lose tracking on every subsequent click.

Conventions

Section titled “Conventions”
  • Request and response bodies are JSON unless noted.
  • Timestamps are UTC, but the string format is not uniform — check the field description before parsing. Request payloads use ISO-8601 (2026-07-24T10:00:00Z); many console/database fields (createdAt, updatedAt) do not; daily analytics buckets use YYYY-MM-DD; monthly aggregates such as revenue-by-month use YYYY-MM.
  • Monetary amounts are stored in minor units (cents) — for example amount: 9900 means ¥99.00. A few analytics aggregates (such as monthly revenue) are pre-divided into major units for display; the field description says which.
  • Batch requests to POST /api/v1/t are capped at 100 events; the internal backfill endpoint accepts up to 1000.
  • Short codes and API keys are nanoid base62.

What this unlocks

Section titled “What this unlocks”

Understanding the two-API split and the core vocabulary above unlocks everything else in these docs: sending events and identifying visitors (Send data), authenticating requests correctly (Authentication), and reading responses without guessing (Errors & status codes).

Verify it worked

Section titled “Verify it worked”

Confirm you can tell the two APIs apart by hitting the Ingestion API’s base URL directly:

bash
curl -s -o /dev/null -w "%{http_code}\n" -X POST https://api.retidal.com/api/v1/t
# expect: 401 — no X-API-Key header, but a 401 confirms you reached the
# Ingestion API's auth check (the Management API would return not-found on this path)

If it doesn’t work

Section titled “If it doesn’t work”

If nothing above matches what you’re seeing, work through the health checklist.