Skip to main content
The Tolmo API is a REST API over HTTPS. Use the published endpoints to integrate Tolmo with your own tools. The CLI also provides local conveniences such as report parsing, artifact downloads, and installation. 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, org context and command-specific 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 how to get an API key.

​
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. An API key is limited to its organization. A user token can access the organizations you belong to. Authorization also applies to SQL and Cypher queries. A resource ID outside your access returns 404.

​
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

Pagination depends on the endpoint: For findings, pass nextCursor as the next request’s cursor until it is null. Check each endpoint’s schema for defaults and 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

Most failures return a JSON body with statusCode, error, and message; some endpoints and provider proxies use different shapes. 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. Use the documented /api/v1 routes for integrations. Other route namespaces are not part of this public reference.