> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tolmo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tolmo REST API Reference for Security Automation

> Call the Tolmo API directly over HTTPS to read findings, query your infrastructure graph, manage integrations, and drive security workflows from your own tooling.

The Tolmo API is a REST API over HTTPS. Use the published endpoints to integrate Tolmo with your own tools. The [CLI](https://docs.tolmo.com/introduction.md) 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.

> [!TIP]
>
> 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:

```text theme={null}
https://api.tolmo.com
```

Every endpoint lives under the `/api/v1` prefix. Requests must use HTTPS.

## Authentication

Every endpoint requires a bearer token:

```bash theme={null}
curl https://api.tolmo.com/api/v1/orgs/acme/findings \
  -H "Authorization: Bearer $TOLMO_API_TOKEN"
```

See [Authentication](https://docs.tolmo.com/api-reference/authentication.md) for how to get an [API key](https://app.tolmo.com/settings/api-keys).

## Organization scoping

Most endpoints are scoped to a single organization, identified by its slug in the path:

```text theme={null}
/api/v1/orgs/{orgSlug}/findings
```

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`:

```bash theme={null}
curl -G https://api.tolmo.com/api/v1/orgs/acme/findings \
  -H "Authorization: Bearer $TOLMO_API_TOKEN" \
  -d status=open \
  -d severity=critical
```

## What you can do

> [card] Findings
>
> List, filter, create, and triage security findings, with their full status history and evidence attachments.

> [card] Query your graph
>
> Run read-only SQL and openCypher against your organization's infrastructure graph.

> [card] Inventory
>
> Read the canonical domain inventory, code repositories, scan runs, and the resource graph.

> [card] Integrations
>
> Connect and inspect providers, and proxy read-only calls to them using Tolmo-held credentials.

## Pagination

Pagination depends on the endpoint:

| Endpoint | Parameters | Response |
| - | - | - |
| Unified findings | `limit`, `cursor` | `items` and `nextCursor` |
| Domains and apex domains | `page`, `limit` | `items`, `total`, and `totalPages` |
| Threat model versions | `limit`, `offset` | Array of version summaries |
| Secret findings | `limit`, `offset` | Array of detections |

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](https://docs.tolmo.com/api-reference/errors.md) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.