Workspace API reference

These are the endpoints of your workspace that accept API keys. Everything else in the workspace serves the browser. There is no public API yet for querying telemetry or for managing organizations and workspaces.

Conventions

Detection content

These endpoints take a CI key. They back the tracix-detections CLI; see Monitors, dashboards and detections as code for the repository format.

Validate, plan or apply

POST /api/security/detections takes the files of a detection repository at one commit, or a reference the workspace fetches itself, and validates, plans or applies them.

validate and plan need security.read; apply needs security.manage. Request bodies are limited to 10 MB: for a larger repository, send archiveRef.

curl -fsS -X POST "$TRACIX_URL/api/security/detections" \
-H "X-API-Key: $TRACIX_API_KEY" \
-H "Content-Type: application/json" \
-d @request.json

{
  "action": "plan",
  "revision": "4f2c9e1",
  "files": {
    "tracix-detections.yaml": "package: acme-soc\nprune: true\n",
    "lists/service-accounts.yaml": "name: service-accounts\nitems:\n  - svc_backup\n"
  }
}

Responses

valid is false when a file doesn't compile or a fixture fails. source says where the files came from: {"kind": "files"}, or the code host, repository and commit for archiveRef.

Errors

Follow a background apply

GET /api/security/detections?job=<jobId> returns the progress of an apply that runs in the background. It needs security.read.

The response is {"job": {...}} with jobId, package, revision, planHash, status (running, succeeded, failed or interrupted), total, done, counts, results, startedAt, updatedAt and, once finished, finishedAt. A job that failed or was interrupted also has an error, and a failed one the failedResource it stopped at. It answers 400 without a valid job ID and 404 for an unknown one.

Download the CLI

GET /api/security/detections/cli returns the tracix-detections CLI that matches this workspace, as tracix-detections.mjs. It needs security.read. The X-Tracix-Cli-Sha256 response header carries the file's SHA-256, so a pipeline can check it before running it.

curl -fsS -H "X-API-Key: $TRACIX_API_KEY" -D cli.headers \
"$TRACIX_URL/api/security/detections/cli" -o tracix-detections.mjs

Export detection content

GET /api/security/detections/export returns detection content as repository files. It needs security.read, and a key sees every rule and list.

A package export returns package, revision, files ({"path": "content"}), resources (each with exact: true when compiling the file reproduces what the workspace runs), summary and notes. Fixtures aren't stored in the workspace, so they aren't exported. It answers 404 when nothing is published under the package; a source=ui export answers 404 when no rules match and 422 when none of them can be exported.

External alerts

These endpoints take an API key of the ingest type, with any write: permission. Alerts they receive open and resolve alert episodes alongside your own monitors'.

Receive Alertmanager alerts

POST /api/ingest/alertmanager takes the payload Prometheus Alertmanager sends to a webhook receiver. Send the API key in the X-API-Key header.

The response is {"ok": true, "opened", "reasserted", "resolved", "ignored"}.

Send alert events

POST /api/ingest/events takes events from your own scripts, relays and third-party systems.

Events missing a required field are dropped. Long values are cut to fit: 256 characters for dedupeKey and entity, 300 for title and 1,000 for reason.

curl -fsS -X POST "$TRACIX_URL/api/ingest/events" \
-H "X-API-Key: $TRACIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"events": [{"dedupeKey": "backup-nightly", "status": "firing", "entity": "db-01", "source": "backup", "severity": "warning", "reason": "Nightly backup did not finish"}]}'

{ "ok": true, "received": 1, "dropped": 0, "opened": 1, "reasserted": 0, "resolved": 0, "ignored": 0 }

It answers 400 when the body has no events array or no valid event.

Next steps