API reference

Public endpoints used by the SDK, parser upload, deploy attribution, and setup diagnostics.

Use the API directly when wiring custom CI, validating ingestion, or debugging project setup.

Authentication

Api Keys (THEME (light)) — API keys are managed from project settings — write keys for CI, public keys for the browser SDK.

X-Trueclara-Project-Key authenticates graph, deploy, and manual revenue write endpoints. Store it in CI or server-side secrets. Manual revenue events also accept Authorization: Bearer $TRUECLARA_PROJECT_KEY for server-side webhook forwarders.

The browser SDK uses NEXT_PUBLIC_TRUECLARA_KEY instead. Do not put the write key in browser code.

Endpoints

Deploys List (THEME (light)) — Deploy uploads via the API show up in the deploys list with commit context attached.

Method and path	Auth	Purpose
`POST /v1/events`	Public project key	Runtime event ingestion. Prefer the SDK.
`POST /v1/static-graphs`	Write key	Upload the full `@trueclara/parser` output.
`POST /v1/deploys`	Write key	Record a deploy, commit metadata, graph, and diff.
`GET /v1/deploys/last?environment=production`	Write key	Resolve the latest known deploy for a project.
`POST /v1/revenue/events`	Write key	Provider-agnostic manual revenue and funnel events.

Runtime events

Use @trueclara/next unless you are validating transport behavior. SDK event forwarding is rate limited by publishable key and by IP.

Static graphs

POST /v1/static-graphs expects parser output with a schema version and routes array. A successful upload replaces the current graph for the project until the next deploy upload supersedes it.

Terminal
curl -X POST https://api.trueclara.com/v1/static-graphs \
  -H "Content-Type: application/json" \
  -H "X-Trueclara-Project-Key: $TRUECLARA_PROJECT_KEY" \
  --data-binary @trueclara-graph.json

Deploys

POST /v1/deploys expects the payload documented in Deploy attribution. A successful response returns the deploy and a dashboard URL.

Last deploy

Use GET /v1/deploys/last when CI needs the previous graph or commit for diffing.

Terminal
curl "https://api.trueclara.com/v1/deploys/last?environment=production" \
  -H "X-Trueclara-Project-Key: $TRUECLARA_PROJECT_KEY"

Omit environment only if production is the intended default.

Manual revenue events

Use POST /v1/revenue/events from server-side billing, checkout, or product activation code when your revenue provider is not one of TrueClara's native billing integrations. The endpoint accepts one event or { "events": [...] } with up to 50 events. Idempotency is scoped to the project.

Terminal
curl -X POST https://api.trueclara.com/v1/revenue/events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TRUECLARA_PROJECT_KEY" \
  --data '{
    "event": "trial_to_paid",
    "occurred_at": "2026-05-29T10:00:00Z",
    "amount": { "value": 1900, "currency": "USD" },
    "user_ref": "workspace_or_customer_ref",
    "idempotency_key": "paddle:event-id:trial_to_paid",
    "attributes": {
      "provider": "paddle",
      "plan": "pro_monthly",
      "environment": "production"
    }
  }'

Supported event names are signup_completed, trial_started, paywall_viewed, trial_to_paid, subscription_renewed, subscription_churned, expansion, and activation. Monetary events require amount.value in minor units and a three-letter currency code. Funnel-only events omit amount.

TrueClara hashes user_ref per project before storage. Provider names in attributes.provider are informational; the endpoint does not branch by provider.