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.