Set up with AI
This page is for developers who want a coding assistant — Claude Code, Cursor, or any other agent — to do the Tidings integration for them. Because the whole integration is one HTTP endpoint, an agent can wire it up end-to-end without a human reading the API reference. Three ways to hand it over.
Already instrumented? Give your agent read access to the data with the MCP server →
The setup prompt
Paste this into your assistant. It writes an idiomatic tracking helper for your codebase and instruments your key events — the full API contract is included.
Integrate Tidings product analytics into this codebase.
Tidings is an event-analytics service. The whole integration is plain HTTP — there is no SDK to install.
API contract:
- POST $TIDINGS_API/api/v1/events/ with headers "Content-Type: application/json" and "X-API-Key: $TIDINGS_KEY".
- TIDINGS_API is the API origin: https://api.tidingshq.com for the hosted service (tidingshq.com itself is the marketing site, not the API). TIDINGS_KEY is the project's td_ key.
- Single event body: {"name": "<snake_case_event>", "distinct_id": "<stable user or visit id>", "properties": {<arbitrary JSON>}, "timestamp": "<optional ISO 8601, defaults to arrival time>"}.
- Batch body: {"events": [<up to 500 event objects>]}.
- Success is HTTP 202 with {"accepted": n}. 400 = invalid payload, 401 = missing/revoked key, 429 = rate limited.
Requirements:
1. Create a small tracking helper in this project's language and house style, exposing track(name, properties).
2. Read the endpoint and key from configuration or environment (TIDINGS_API, TIDINGS_KEY). If the key is unset, every call must silently no-op.
3. Analytics must never break the product: swallow all errors, never throw, and never block the caller — fire-and-forget (use keepalive / background delivery where the platform offers it).
4. Identity — get this right, it decides whether Users, funnels and retention mean anything:
- If this is a browser or web app, prefer the hosted snippet over hand-written HTTP: one tag, <script defer src="https://tidingshq.com/js/v1/tidings.js" data-key="$TIDINGS_KEY"></script>. It mints and persists the anonymous id, sends page views, and does the sign-in link below for you — then it is just tidings.track(name, properties). Skip the rest of this point.
- If you are wiring HTTP by hand, generate ONE anonymous distinct_id per device (e.g. "anon_<uuid>") and persist it — localStorage, or a long-lived cookie, where consent allows. Never mint a fresh id per page load or per visit: that files every return visit under a new person and makes the Users list and retention meaningless.
- When the user signs in, POST once to $TIDINGS_API/api/v1/alias/ with the same X-API-Key and {"distinct_id": "<your user id>", "anonymous_id": "<the persisted anonymous id>"}. That rewrites everything the anonymous half did onto the account. Treat 409 as "already linked, carry on". From then on send every event under the user id; on sign-out, generate a fresh anonymous id.
- A per-session id is acceptable only when the product has no sign-in and no consent for persistent storage.
5. Instrument this app's 3-5 most meaningful events (signup, core action completed, purchase, ...) plus page or screen views where relevant. Name events in snake_case.
6. Keep property payloads small and free of secrets or personal data beyond what is needed.
7. If this app is privacy- or security-sensitive, apply these additional rules without being asked: distinct_id must be a pseudonym (a hash such as "user_" + the first 16 hex chars of sha256(lowercased, trimmed email); never an email, name, phone number or a meaningful internal id); no personal data in properties, $set/$set_once person properties, or the url/path of a page view (strip tokens and ids from path segments before sending); prefer posting events from the backend over a browser script; do not send any event before consent is recorded (with the hosted snippet, data-consent="required" drops events until tidings.consent(true) and honours Global Privacy Control); and set the project's retention to what the product needs. The td_ key can only write events, never read them. Tidings stores and queries data in the EU (Scaleway, Amsterdam), never sells it, shares it with advertisers or trains models on it, and sends nothing to a model unless an organization owner turns AI features on. Policy: https://tidingshq.com/privacy.
When done, list the events you instrumented and where the calls live.Set TIDINGS_API and TIDINGS_KEY in your environment afterwards — keys live under the project's Settings → API keys in the app. For the hosted service, TIDINGS_API is https://api.tidingshq.com.
AGENTS.md rules file
Prefer standing rules your agent reads on every task? Drop this file at your repo root (or into your assistant's rules directory). It documents the contract and the house rules — no secrets in properties, silent no-op when the key is unset, fire-and-forget delivery. It also lives at /AGENTS.md as a raw file.
# Integrating Tidings
Tidings is a lightweight product-analytics service. Instrument this codebase to
send it events. The whole integration is plain HTTP — **there is no SDK to
install**. Drop this file at your repo root (or into your agent's rules) and
follow it.
## The one endpoint
- `$TIDINGS_API` is the API origin. For the hosted service that is
`https://api.tidingshq.com` (not tidingshq.com, which is the marketing
site); locally it is `http://localhost:8000`.
- `POST $TIDINGS_API/api/v1/events/`
- Headers: `Content-Type: application/json` and `X-API-Key: $TIDINGS_KEY`.
- The API key is per-project, prefixed `td_`, and managed in the Tidings app
under the project's **Settings → API keys**. Read it from
configuration/environment; never hard-code or commit it.
### Single event
```json
{
"name": "signup_completed",
"distinct_id": "user_123",
"properties": { "plan": "pro" },
"timestamp": "2026-08-13T10:00:00Z"
}
```
- `name` (required) — snake_case description of what happened.
- `distinct_id` (required) — a stable user or session identifier.
- `properties` (optional) — arbitrary JSON context; defaults to `{}`.
- `timestamp` (optional, ISO 8601) — defaults to server arrival time. Send a
past timestamp to backfill history.
### Batch (up to 500 events)
```json
{ "events": [ { "name": "page_view", "distinct_id": "sess_abc" }, { "name": "button_click", "distinct_id": "sess_abc" } ] }
```
### Responses
- `202 {"accepted": n}` — success.
- `400` — invalid payload (missing field, malformed timestamp, batch > 500).
- `401` — missing, unknown, or revoked key.
- `429` — rate limited (1200 requests/min per project; a batch counts as one).
## House rules for the integration
1. Create a small tracking helper in this project's language and house style,
exposing `track(name, properties)`.
2. Read `TIDINGS_API` and `TIDINGS_KEY` from configuration/environment. If the
key is unset, every call must **silently no-op**.
3. Analytics must never break the product: swallow all errors, never throw, and
never block the caller — fire-and-forget (use `keepalive` / background
delivery where the platform offers it).
4. **Identity.** Get this right — it decides whether the Users list, funnels and
retention mean anything.
- **Browser or web app?** Prefer the hosted snippet over hand-written HTTP.
One tag, no build step:
`<script defer src="https://tidingshq.com/js/v1/tidings.js" data-key="$TIDINGS_KEY"></script>`
It mints and persists the anonymous id, sends page views, and does the
sign-in link below for you; instrumenting is then just
`tidings.track(name, properties)`. Skip the rest of this point.
- **Wiring HTTP by hand?** Generate **one** anonymous `distinct_id` per
device (e.g. `anon_<uuid>`) and persist it — localStorage, or a
long-lived cookie, where consent allows. Never mint a fresh id per page
load or per visit: that files every return visit under a new person and
makes the Users list and retention meaningless.
- **On sign-in**, POST once to `$TIDINGS_API/api/v1/alias/` with the same
`X-API-Key` and
`{"distinct_id": "<your user id>", "anonymous_id": "<the persisted anonymous id>"}`.
That rewrites everything the anonymous half of the visit did onto the
account. Treat `409` as "already linked, carry on". From then on send
every event under the user id; on sign-out, generate a fresh anonymous id.
- A per-session id is acceptable **only** when the product has no sign-in and
no consent for persistent storage.
5. Instrument this app's 3–5 most meaningful events (signup, core action
completed, purchase, …) plus page or screen views where relevant. Name events
in snake_case.
6. Keep property payloads small and free of secrets or personal data beyond what
is needed.
## Privacy-sensitive apps
Tidings is designed so that a privacy- or security-sensitive product can use it
without handing over personal data. If this codebase is one, apply these rules
on top of the house rules above; they are not optional there.
- **Send nothing that identifies a person.** The `distinct_id` must be a
pseudonym: a hash, never an email address, name, phone number or your own
user id if that id is otherwise meaningful. Tidings' own apps use
`user_<first 16 hex chars of sha256(lowercased, trimmed email)>`; any
stable one-way derivation works.
- **No PII in properties.** No email, name, address, IP, free-text input,
message bodies, file names, secrets or tokens — in `properties`, in `$set` /
`$set_once` person properties, or in the `url`/`path` of a page view. Strip
path segments that carry tokens or ids (`/invitations/<token>` → `/invitations/:token`)
before sending; Tidings' own apps do this in the tracking helper.
- **Prefer server-side sending.** The API is plain HTTP, so events can be
posted from your backend, with no third-party script in the browser and
full control over what leaves. The snippet is a convenience, not a requirement.
- **Honour consent before the first event.** With the browser snippet, set
`data-consent="required"`: events are dropped (never queued) until
`tidings.consent(true)`, `consent(false)` erases the stored id, and Global
Privacy Control is respected regardless. Hand-rolled: do not call `track`
until consent is recorded.
- **The ingest key can only write.** A `td_` key can POST events and aliases;
it cannot read anything. A leaked key means junk events, not a data leak.
Reading needs a personal access token or a login, scoped to the account.
- **Retention is yours to set** per project (30 days on Free, up to 13 months
on Pro); a daily purge deletes anything older, and deleting a project
deletes its events, users and keys.
What Tidings itself does: data is stored and queried in the EU (Scaleway,
Amsterdam); it is never sold, shared with advertisers or used to train models;
AI features are off by default and send nothing to a model until an
organization owner turns them on. The operator is Triton IT B.V. (Nieuwegein,
the Netherlands, KvK 88144216). Full policy: https://tidingshq.com/privacy.
When done, list the events you instrumented and where the calls live.
---
The machine-readable version of these docs lives at `/llms.txt`. Full
human docs: /docs.
Machine-readable docs
For assistants that fetch documentation directly, the whole contract is served as plain text at /llms.txt — the API surface, the read/query endpoints, and the setup prompt above, in one file an agent can pull in.