API reference
All endpoints are served under /api; on the hosted service that is https://app.tracemason.com/api. Errors are JSON: { "error": "<code>", "message": "<human readable>" }.
Two kinds of authentication:
- Session cookie — for people using the dashboard. Obtained through
/api/auth/* (provided by better-auth).
- Ingestion key —
Authorization: Bearer tm_ing_…, for collectors and SDKs. Can only write events and read its own configuration.
Organization endpoints take the organization slug in the path. If you are not a member, the response is 404 — the same as for an organization that does not exist. If your role lacks the permission, it is 403 and names the permission required.
Ingestion (ingestion key)
| Method |
Path |
|
| POST |
/ingest/events |
Send up to 500 events. See Event schema. |
| GET |
/ingest/config |
Collection level and enabled policies for this key's organization. |
| POST |
/otlp/v1/logs |
OTLP/HTTP JSON logs. See OpenTelemetry. |
| POST |
/otlp/v1/metrics, /otlp/v1/traces |
Acknowledged, not stored. |
Collector authorization
| Method |
Path |
Auth |
|
| POST |
/cli/device |
none |
Start: returns device_code, user_code, verification_url. |
| POST |
/cli/device/token |
none |
Poll with device_code. {status:"pending"} until approved; then the ingestion key, once. |
| GET |
/cli/device/:userCode |
session |
What is being approved. |
| POST |
/orgs/:org/cli/approve |
credentials.create |
{ user_code, approve } |
Account
| Method |
Path |
|
| GET |
/config |
Public switches (GitHub login enabled, demo account). |
| GET |
/me |
Current user and organizations. |
| POST |
/orgs |
Create an organization { name }. |
| GET |
/invitations/:token |
Preview an invitation. |
| POST |
/invitations/:token/accept |
Accept; the signed-in email must match. |
Organization — /orgs/:org/…
| Method |
Path |
Permission |
| GET / PATCH / DELETE |
`` |
org.read / org.update / org.delete |
| GET |
/members, /invitations |
members.read |
| PATCH / DELETE |
/members/:id |
members.manage |
| POST / DELETE |
/invitations, /invitations/:id |
members.manage |
| GET |
/audit |
audit.read |
| GET |
/credentials, /collectors |
credentials.read |
| POST |
/credentials |
credentials.create |
| DELETE |
/credentials/:id |
credentials.revoke |
Activity (activity.read)
| Method |
Path |
|
| GET |
/overview?range=1h|24h|7d|30d |
Metrics, each with its definition, plus chart series. |
| GET |
/sessions?status&agent&repository&q&findings&before&limit |
Session list. |
| GET |
/sessions/:id |
The trace. :id may be the internal id or the source's session id. |
| GET |
/sessions/:id/export |
Trace as a JSON download (data.export). |
| GET |
/events?limit&type&before |
Recent events. |
| GET |
/stream?cursor |
Server-Sent Events. |
| GET |
/agents, /agents/:id |
|
| GET |
/repositories, /repositories/:id |
|
| PATCH |
/repositories/:id |
{ sensitive?, tracked? } (repositories.manage) |
| GET |
/environments |
|
| PATCH |
/environments/:id |
{ kind?, verified? } (policies.manage) |
| GET |
/topology?range |
Nodes and edges, each edge with its evidence. |
Security
| Method |
Path |
Permission |
| GET |
/findings?status&severity&policy&session, /findings/:id |
findings.read |
| PATCH |
/findings/:id { status?, assigneeId? } |
findings.triage |
| GET |
/policies |
policies.read |
| PATCH / POST / DELETE |
/policies/:id, /policies |
policies.manage |
| GET |
/alerts?status, /alert-channels |
findings.read |
| PATCH |
/alerts/:id { status } |
findings.triage |
| POST / DELETE |
/alert-channels, /alert-channels/:id |
alerts.manage |
| GET |
/investigations, /investigations/:id |
investigations.read |
| POST / PATCH |
/investigations, /investigations/:id, /investigations/:id/items |
investigations.write |
Integrations, data and billing
| Method |
Path |
Permission |
| GET |
/integrations |
integrations.read |
| POST |
/integrations/github/install, /integrations/github/local-harness |
integrations.manage |
| DELETE |
/integrations/:id |
integrations.manage |
| GET |
/retention |
org.read |
| POST |
/retention/run |
org.update |
| GET |
/export |
data.export |
| GET |
/billing |
billing.read |
| POST |
/billing/checkout, /billing/portal, /billing/dev-override |
billing.manage |
Webhooks received
| Path |
Verified by |
POST /webhooks/github |
X-Hub-Signature-256 (HMAC-SHA256 of the raw body) |
POST /webhooks/stripe |
Stripe-Signature, when Stripe is configured |
Rate limits
Ingestion: 1,200 requests per minute per key (INGEST_RATE_LIMIT). Authentication and collector authorization: per-IP limits. Exceeding a limit returns 429 with retry_after_seconds.
OpenAPI
A machine-readable OpenAPI document is not generated yet. This page is the reference.