> ## 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. Everything the [Tolmo CLI](/introduction) 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.

<Tip>
  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.
</Tip>

## Base URL

All requests go to:

```
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](/api-reference/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:

```
/api/v1/orgs/{orgSlug}/findings
```

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

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

<CardGroup cols={2}>
  <Card title="Findings" icon="shield-exclamation">
    List, filter, create, and triage security findings, with their full status history and evidence attachments.
  </Card>

  <Card title="Query your graph" icon="magnifying-glass">
    Run read-only SQL and openCypher against your organization's infrastructure graph.
  </Card>

  <Card title="Inventory" icon="server">
    Read the canonical domain inventory, code repositories, scan runs, and the resource graph.
  </Card>

  <Card title="Integrations" icon="plug">
    Connect and inspect providers, and proxy read-only calls to them using Tolmo-held credentials.
  </Card>
</CardGroup>

## 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](/api-reference/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.