Integrating via the REST API.

The REST API

It's a versioned REST API under /api/v1. Requests and responses are JSON in snake_case. Every query is scoped to your organisation automatically, derived from the token you present and never from anything in the request body, so an endpoint can only ever address your own tenant.

The important design call is that the API is not a thin passthrough. POST /api/v1/observations/preflight starts the same duplicate-review and create pipeline the manual wizard uses. You review every candidate it returns, then finalize the attempt. The API applies the same public review rules as the in-app flow, and the result enters the same human-visible register and audit trail. Direct POST /observations is deliberately refused with 428.

Bearer tokens, scoped to a role

Every request carries a bearer token over HTTPS: no cookies, no session, no consent screen to redirect through. An administrator creates the token in the UI, and the caller sends it on each request:

Authorization: Bearer sgt_live_<keyId>_<secret>

A couple of things worth knowing about that token:

• It's shown once, and we never store it. The secret is 256 bits of randomness, shown to you exactly once at creation. We only ever keep a one-way hash of it, so we can check a token but never reproduce it. Lose it and you create a new one; there's no recovery.
• The prefix makes a leak obvious. Every token starts with sgt_live_, so one committed to a repo or pasted into a log is easy to spot and revoke.

Tokens are role-scoped. General-purpose tokens carry exactly one role and are authorized as a user of that role would be; the token-only SIEM role is limited to audit export:

• auditor. Read-only. Can hit the GET endpoints, nothing else.
• contributor / member. Can create and update observations.
• siem. Token-only audit export. It can verify with GET /me and poll /audit-events, but cannot read or write observations or be assigned to a human.
• administrator is not assignable. An administrator-level bearer credential could manage billing, members, and other tokens, and delete the org. That's too much authority for a long-lived key, so tokens top out at member.

Pick the lowest role that does the job. A scanner that only files findings wants a contributor token; a dashboard that only reads wants an auditor token.

It's a paid feature, capped at ten tokens

API access is gated to the Pay-per-use and Pro plans. That gate is checked in two places: when you manage tokens, and again on every /api/v1 request. If an org drops to Free after a token was created, that token stops working and returns a 403 PLAN_REQUIRED, even though the token itself is still valid. The plan is the licence to use the API, not the token.

An organisation can have up to ten active tokens at once, regardless of Pro bundle count. Tokens are created, listed, and revoked by an administrator under Account → API Tokens. Each one defaults to 90 days; you can choose 30 days, 90 days, 1 year, or never (the UI warns you on never). The tab shows each token's last-used time so you can spot a stale one and rotate it.

What you can call

All routes live under https://app.securitytrackr.com/api/v1. The API supports observation search and reading, duplicate-safe creation, field updates, treatment, reassessment, comments, relations and evidence. Use the OpenAPI document for the current endpoint list, request fields and response schemas.

Observation lists return lightweight summaries and default to open findings. Fetch an observation by ID for its full content. Evidence uploads use multipart form data rather than JSON and downloads depend on the file's scan status.

A Contributor token can create and update findings, but cannot write comments or upload evidence. Those operations require a Member token. Auditor tokens are read-only; audit export requires the separate SIEM token role. See roles and permissions before choosing a token.

Prepare, review, finalise, then retrieve

First call GET /me to verify the credential. Prepare one proposal with a stable Idempotency-Key. Review every candidate returned and submit a disposition for each. An empty disposition list is valid only when there are no candidates.

# Prepare one finding. Keep the same key when retrying this proposal.
curl -s -X POST https://app.securitytrackr.com/api/v1/observations/preflight \
  -H "Authorization: Bearer $SECURITYTRACKR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: scan-42-tls-lb-prod-01" \
  -d '{"user_observation":"TLS 1.0 enabled on lb-prod-01."}'

# Review the returned candidates. This example assumes there were none.
# Use the attempt_id and review_revision returned by preflight.
curl -s -X POST https://app.securitytrackr.com/api/v1/observations/ingest-attempts/$ATTEMPT_ID/finalize \
  -H "Authorization: Bearer $SECURITYTRACKR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"review_revision":1,"candidate_dispositions":[]}'

# If finalisation returns 202, poll the job URL in its Location header.
curl -s "https://app.securitytrackr.com$JOB_PATH" \
  -H "Authorization: Bearer $SECURITYTRACKR_API_TOKEN"

# After completion, retrieve the attempt for its outcome and observation ID.
curl -s https://app.securitytrackr.com/api/v1/observations/ingest-attempts/$ATTEMPT_ID \
  -H "Authorization: Bearer $SECURITYTRACKR_API_TOKEN"

A 202 Accepted response means work was queued, not that a finding has been created. Poll with the same credential until the job finishes, then read the attempt. Handle failed or cancelled jobs and any renewed review requirement before treating the operation as complete.

With enrichment enabled, the server drafts the finding and assesses its risk. Use enrich: false when you want to supply your own content and likelihood/impact values. Duplicate review still applies. Reassessment and recommendation deployment can also return jobs; use their documented completion flow.

On an interrupted request, recover the existing attempt instead of starting a new proposal. Honour RateLimit-* and Retry-After headers. Errors carry a stable code so callers can distinguish validation, permission and retryable failures.

The OpenAPI spec, served straight from the app

You don't have to take any of the above on faith. The full contract is published as an OpenAPI 3.1 document, served unauthenticated:

GET https://app.securitytrackr.com/api/v1/openapi.json

It contains only the static API shape, no tenant data and no secrets, which is why it's safe to serve without a token. It's the artifact to hand an integrator: import it into Swagger UI, editor.swagger.io, or Postman to explore the endpoints, or feed it to an LLM as a set of tool definitions. It's kept in lockstep with the routes by a test that fails our build if the documented enums or endpoint set ever drift from what actually ships, so it can't silently go stale.

Add the operating guide

The downloadable skills explain when and how an agent should use the API. See wiring an agent with skills for installation and safe credential setup.