---
title: Introduction
description: 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

- A Retidal project and a project API key — see [Quickstart](/docs/quickstart) to create one in under five minutes.
- Nothing else: this page is background, not a procedure.

## The two APIs

<CardGroup cols={2}>
  <Card title="Ingestion & Decisioning API" href="/docs/api/ingestion">
    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`.
  </Card>
  <Card title="Management API" href="/docs/api/management">
    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`.
  </Card>
</CardGroup>

## 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](/docs/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

- 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

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

## 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

If nothing above matches what you're seeing, work through the [health checklist](/docs/troubleshooting/health-checklist).