Skip to main content
The Tolmo API is a REST API over HTTPS. Everything the Tolmo CLI does, it does by calling this API — so anything you can do at the command line, you can do from your own code. Use it when you want to pull findings into an internal dashboard, gate a deploy on your organization’s security posture, sync the infrastructure graph into a warehouse, or drive Tolmo from a language the CLI doesn’t cover.
If you just want results in a terminal or a pipeline, reach for the CLI first — it handles authentication, token refresh, org context, and pagination for you. Drop to the API when you are building a service.

​
Base URL

All requests go to:
Every endpoint lives under the /api/v1 prefix. Requests must use HTTPS.

​
Authentication

Every endpoint requires a bearer token:
See Authentication for the two token types and how to get one.

​
Organization scoping

Most endpoints are scoped to a single organization, identified by its slug in the path:
Find your slug with tolmo org list, or read it from your organization settings in the Tolmo app. Scoping is enforced at the data layer, not just in the route — a token can only ever read data belonging to organizations it has access to. Requesting a resource in an organization you cannot see returns 404, not 403, so the API never confirms that an unseen resource exists.

​
Your first request

List your organization’s open critical findings — substitute your own slug for acme:

​
What you can do

Findings

List, filter, create, and triage security findings, with their full status history and evidence attachments.

Query your graph

Run read-only SQL and openCypher against your organization’s infrastructure graph.

Inventory

Read the canonical domain inventory, code repositories, scan runs, and the resource graph.

Integrations

Connect and inspect providers, and proxy read-only calls to them using Tolmo-held credentials.

​
Pagination

List endpoints are paginated. Most accept page and pageSize; some also accept a limit. These are validated, not clamped — limit on findings accepts 1–100, and a value outside that range is rejected with 400 rather than silently reduced. Check the parameters on each endpoint for its exact bounds.

​
Content types

Send Content-Type: application/json on requests with a body. Two endpoints deviate deliberately: finding attachment uploads take application/octet-stream with metadata in headers, and attachment and screenshot downloads return binary streams.

​
Errors

Failures return a JSON body with a statusCode, error, and message. See Errors for the full shape and the status codes each endpoint uses.

​
Stability

This reference is generated from the server’s own route definitions, so it reflects exactly what the API accepts and returns. /api/v1 is the only supported API namespace. The unversioned /api/* alias was removed on 2026-07-17. Endpoints not listed in this reference — including anything under /internal — are internal surfaces that change without notice; don’t build against them.