API documentation

Tracelight ships a JSON REST API for everything you can do in the dashboard — open cases, add subjects, run OSINT enrichments, pull cited reports. The same RLS that gates your dashboard scopes every API call to your workspace.

Base URL: https://trytracelight.com/api/v1

Authentication

Every request must include an Authorization: Bearer tl_… header. Generate tokens in Dashboard → API tokens. Scopes:

read — GET endpoints
write — POST/PATCH (implies read)
admin — everything (implies write)

Token strings are shown only once at creation. Store them like database credentials.

Rate limits

POST /api/v1/subjects/{sid}/enrich is gated per-workspace by an hourly cap matched to your plan. When exceeded the API returns 429 with a Retry-After: 3600 header.

Plan	Enrichments / hour
Free	5
Starter	60
Pro	240
Agency	1,000

Errors

All errors are returned as { "error": "<message>" } with an appropriate HTTP status:

400 — invalid input (Zod schema failure)
401 — missing or revoked token
403 — token lacks the required scope
404 — entity not found in this workspace
429 — rate-limit exceeded (check Retry-After)
5xx — server error; retry with exponential backoff

Cases

GET/api/v1/casesscope: read

List all cases in the authenticated workspace.

curl https://trytracelight.com/api/v1/cases \
  -H "Authorization: Bearer tl_..."

POST/api/v1/casesscope: write

Open a new case. Counts against your monthly case quota.

Body

`title`required	string	Display title for the case.
`description`	string	Free-text description.
`client_reference`	string	Your internal ID for this matter.
`priority`	low \| normal \| high \| urgent	Defaults to normal.
`tags`	string[]	Arbitrary tags.

curl https://trytracelight.com/api/v1/cases \
  -X POST \
  -H "Authorization: Bearer tl_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "ACME M&A diligence",
    "priority": "high",
    "client_reference": "ACME-2026-0142"
  }'

Subjects

GET/api/v1/subjectsscope: read

List subjects in the workspace. Filter with ?case_id=.

Query parameters

case_id uuid Optional. Filter to a single case.

curl "https://trytracelight.com/api/v1/subjects?case_id=<uuid>" \
  -H "Authorization: Bearer tl_..."

POST/api/v1/subjectsscope: write

Add a subject to a case.

Body

`case_id`required	uuid	Case the subject belongs to.
`full_name`	string	Display name.
`emails`	string[]
`phones`	string[]
`usernames`	string[]
`ip_addresses`	string[]
`domains`	string[]
`consent_obtained`	boolean	Required for FCRA-regulated decisions.

curl https://trytracelight.com/api/v1/subjects \
  -X POST \
  -H "Authorization: Bearer tl_..." \
  -H "Content-Type: application/json" \
  -d '{
    "case_id": "<case-uuid>",
    "full_name": "Jane Doe",
    "emails": ["jane@example.com"],
    "usernames": ["jdoe99"]
  }'

GET/api/v1/subjects/{sid}scope: read

Fetch a single subject with all identifiers + risk score.

curl https://trytracelight.com/api/v1/subjects/<sid> \
  -H "Authorization: Bearer tl_..."

POST/api/v1/subjects/{sid}/enrichscope: write

Kick off the 32-worker OSINT enrichment for this subject. Synchronous — returns once every worker has reported. Plan-tier hourly rate limit applies (429 with Retry-After if exceeded).

curl https://trytracelight.com/api/v1/subjects/<sid>/enrich \
  -X POST \
  -H "Authorization: Bearer tl_..."

Reports

GET/api/v1/reports/{rid}scope: read

Fetch a generated report — narrative, citations, and a signed PDF URL valid for 1 hour.

curl https://trytracelight.com/api/v1/reports/<rid> \
  -H "Authorization: Bearer tl_..."

Webhooks & events

Subscribe a URL to Tracelight events from Dashboard → Integrations. Signed payloads include X-Tracelight-Signature: sha256=<hex> for HMAC verification.

Event	Fired when
`case.created`	A case is opened.
`case.completed`	A case status flips to closed or archived.
`subject.added`	A subject is added to a case.
`enrichment.completed`	An OSINT enrichment run finishes.
`alert.fired`	A monitor produces a new alert.
`report.generated`	An investigator generates a subject report.
`monitor.match`	A monitor finds a new match (paired with alert.fired).

Full event payload schemas are documented at /zapier.

Ready to integrate?

Generate a token and you can hit the API in 60 seconds.

Get a token