# Tolmo

> Tolmo builds AI-native cybersecurity for engineering teams. The platform combines automated cloud and SaaS discovery (AWS, GitHub, Datadog, Linear, Cloudflare, ...) with event-driven agents that run threat modeling, finding generation, and remediation against the customer's real infrastructure graph.

- [Tolmo CLI](https://docs.tolmo.com/introduction.md): Use the Tolmo CLI to review findings, query infrastructure, inspect inventory, and manage connected services.
- [Install the Tolmo CLI: Homebrew, Script, and Debian](https://docs.tolmo.com/installation.md): Install the Tolmo CLI via Homebrew, the install script, or a Debian package. Supports macOS and Linux on amd64 and arm64 architectures.
- [Authenticate the Tolmo CLI](https://docs.tolmo.com/authentication.md): Sign in with a browser for interactive use, or use an organization API key for automation.
- [Run SQL and Cypher Queries Against Your Infrastructure](https://docs.tolmo.com/commands/sql-cypher.md): Run SQL queries against your org's relational data and Cypher queries against the infrastructure graph. Both commands support --json for scripting.
- [Inspect discovered applications](https://docs.tolmo.com/commands/apps.md): List applications from your repositories and inspect their HTTP endpoints and linked hostnames.
- [Browse and Clone Repositories Connected to Your Organization](https://docs.tolmo.com/commands/code.md): Use tolmo code to list repositories in your organization and clone them from GitHub or GitLab. Supports multiple input formats and bulk cloning.
- [Review and triage security findings](https://docs.tolmo.com/commands/findings.md): Filter Tolmo and third-party findings, import scanner reports, create drafts, and record status decisions with the Tolmo CLI.
- [Query Connected Services Through Tolmo's Secure Proxy](https://docs.tolmo.com/commands/query.md): Proxy REST, GraphQL, and CLI requests to GitHub, AWS, Linear, Sentry, and Datadog through Tolmo. Credentials are resolved server-side and never exposed.
- [Download Threat Model Artifacts](https://docs.tolmo.com/features/threat-model.md): Retrieve threat model pipeline runs and artifacts using tolmo threat-model. Download the latest run or a specific step from a named pipeline scan.
- [Manage Platform-Owned Datadog Monitors](https://docs.tolmo.com/features/monitors.md): Create, update, and delete Datadog monitors managed by the Tolmo platform. All monitors are tagged managed-by:tolmo and use server-side org credentials.
- [Website Scans and Organization Management](https://docs.tolmo.com/features/website-org.md): List crawled domains and scan history with tolmo website, and switch between organizations with tolmo org. Manage your active context from the terminal.
- [Browse the domain inventory](https://docs.tolmo.com/features/domains.md): List apex domains and hosts with discovery, lifecycle, DNS, and web status filters.
- [Connect and inspect integrations](https://docs.tolmo.com/features/integrations.md): Discover provider requirements, connect integrations, and select existing integrations with the Tolmo CLI.
- [Review secret findings](https://docs.tolmo.com/features/secret-findings.md): Read detected secrets and their triage state through the public REST API.
- [Red Team Agent: Automated Penetration Testing](https://docs.tolmo.com/agents/red-team-agent.md): Red Team Agent tests your authorized domains the way an attacker would. Authorize domains, understand the ten-day run schedule, review validated findings, and copy a fix prompt straight into your editor.
- [Review agent run history](https://docs.tolmo.com/agents/run-history.md): List existing Red and Blue Agent runs and inspect Blue Agent execution details from the CLI.
- [Manage named profiles](https://docs.tolmo.com/configuration/profiles.md): Store separate CLI sessions and API environments, select the active profile, and switch organization context.
- [Configure the CLI with environment variables](https://docs.tolmo.com/configuration/environment-variables.md): Set API credentials, organization context, profiles, and installer options for the Tolmo CLI.
- [Global flags and JSON output](https://docs.tolmo.com/configuration/global-flags.md): Select an organization or profile for one invocation and understand command-specific JSON output.
- [Use Tolmo in CI/CD](https://docs.tolmo.com/guides/ci-cd.md): Install Tolmo, authenticate with an API key, and inspect security findings in GitHub Actions or GitLab CI.
- [Install the Tolmo CLI skill](https://docs.tolmo.com/guides/agent-skill.md): Install and update the Tolmo command reference for compatible coding agents.
- [Query historical findings and graph observations](https://docs.tolmo.com/guides/time-machine.md): Read findings at a past time with SQL and use graph observation timestamps to review infrastructure changes.
- [Use the terminal UI](https://docs.tolmo.com/guides/terminal-ui.md): Browse Tolmo findings, repositories, and threat models with an interactive terminal interface.
- [Tolmo REST API Reference for Security Automation](https://docs.tolmo.com/api-reference/introduction.md): Call the Tolmo API directly over HTTPS to read findings, query your infrastructure graph, manage integrations, and drive security workflows from your own tooling.
- [Authenticate to the Tolmo API with an API key](https://docs.tolmo.com/api-reference/authentication.md): Create an API key in the Tolmo app, send it as a bearer credential, and understand how keys and user tokens expire and are revoked.
- [Tolmo API Error Responses and Status Codes](https://docs.tolmo.com/api-reference/errors.md): Read the Tolmo API error body, understand what each status code means, and handle retries, precondition failures, and permission errors correctly.
- [List findings](https://docs.tolmo.com/api-reference/findings/list-findings.md): List every finding in the organization — Tolmo-authored and third-party scanner rows — from the unified findings read. Filter with origin=tolmo for Tolmo-authored rows only. The lean catalog (source/agent facets, idsOnly) lives at GET /findings/catalog.
- [Create a finding](https://docs.tolmo.com/api-reference/findings/create-a-finding.md): Create a finding. Regular human tokens and purposeless customer automation tokens may create drafts but cannot publish; platform-minted agent-run tokens, verified super-admins, and scoped pentesters may publish. Accepts optional `sourceAgentName` provenance for agent-authored drafts.
- [List finding filter facets](https://docs.tolmo.com/api-reference/findings/list-finding-filter-facets.md): Return the available filter values (status, severity, and related dimensions) with their counts for the current query, for building filter UIs without a second full scan. Applies the same visibility rules as GET /findings/catalog.
- [Get a finding](https://docs.tolmo.com/api-reference/findings/get-a-finding.md): Fetch a single finding by id. Internal triage columns are never serialized on this org-facing surface. Returns 404 rather than 403 for a finding in another organization, and for a draft the caller may not see.
- [List a finding's attachments](https://docs.tolmo.com/api-reference/findings/list-a-findings-attachments.md): List the evidence files attached to a finding. Human tokens only; machine org tokens are rejected.
- [Upload a finding attachment](https://docs.tolmo.com/api-reference/findings/upload-a-finding-attachment.md): Upload one evidence file for a finding as `application/octet-stream`, capped at 250 MiB. File name and content type travel in the `X-Attachment-File-Name` and `X-Attachment-Content-Type` headers, with an optional URI-encoded `X-Attachment-Title`. A `report_exhibit` video must send `X-Attachment-Expl…
- [Delete a finding attachment](https://docs.tolmo.com/api-reference/findings/delete-a-finding-attachment.md): Permanently delete one attachment. Because it is irreversible, the caller must be the attachment's uploader or an effective super-admin.
- [Download a finding attachment](https://docs.tolmo.com/api-reference/findings/download-a-finding-attachment.md): Stream one attachment's bytes back through the authenticated route — attachments are served from a private bucket and never exposed as object URLs. Responses are forced to attachment disposition with `no-store` and `nosniff`.
- [List a finding's sources](https://docs.tolmo.com/api-reference/findings/list-a-findings-sources.md): Return the evidence sources attached to a finding — the scans, resources, and detections that produced or corroborated it.
- [Update a finding's status](https://docs.tolmo.com/api-reference/findings/update-a-findings-status.md): Transition a finding between `open`, `in_review`, `acknowledged`, `closed`, `false_positive`, and `canceled`. The transition is recorded in the finding's status history with its actor, so the change is auditable. On a scanner row (GitHub, Wiz, and the rest) this writes `provider_status` and does not…
- [List a finding's status history](https://docs.tolmo.com/api-reference/findings/list-a-findings-status-history.md): Return the ordered audit trail of status transitions for one finding, including who made each change and when.
- [List Tolmo-authored findings (catalog)](https://docs.tolmo.com/api-reference/findings/list-tolmo-authored-findings-catalog.md): List the organization's Tolmo-authored findings, newest first, with the shared lean paginated contract. Regular callers see published findings only; effective super-admins may additionally read all drafts, and a scoped pentester may list drafts they authored. Scanner-origin rows are excluded. Prefer…
- [List Tolmo catalog filter facets](https://docs.tolmo.com/api-reference/findings/list-tolmo-catalog-filter-facets.md): Return the available filter values (status, severity, and related dimensions) with their counts for the current query, for building filter UIs without a second full scan. Applies the same visibility rules as GET /findings/catalog.
- [Count findings by saved view](https://docs.tolmo.com/api-reference/external-findings/count-findings-by-saved-view.md): Return counts for the saved finding views visible to the caller, with the time the counts were computed.
- [Get a unified finding](https://docs.tolmo.com/api-reference/external-findings/get-a-unified-finding.md): Fetch a Tolmo-authored or third-party finding by its unified finding ID, including its description and assessment history. Returns 404 when the finding is not visible to the caller.
- [Import third-party findings](https://docs.tolmo.com/api-reference/external-findings/import-third-party-findings.md): Import findings under a provider and stable source name. Reusing the same provider, source, and external ID updates the existing record. Returns the imported finding IDs.
- [Run a SQL query](https://docs.tolmo.com/api-reference/sql/run-a-sql-query.md): Execute a read-only SQL query with RLS org isolation
- [Run a Cypher query](https://docs.tolmo.com/api-reference/cypher/run-a-cypher-query.md): Execute an openCypher query (org-scoped, read-only, temporary). Automated and agent callers must send `intent`: one short sentence naming the specific question this query should answer and how the result will guide the next step. It never changes the query or its results; when set, it is attached to…
- [Get a resource subgraph](https://docs.tolmo.com/api-reference/resource-graph/get-a-resource-subgraph.md): Get a subgraph filtered by provider/service/resourceType
- [List domains](https://docs.tolmo.com/api-reference/domains/list-domains.md): List hostnames (Postgres; not Attack Surface). Ordered by apex then FQDN. Optional apexDomain scopes to one apex. Offset pagination via page + limit.
- [List apex domains](https://docs.tolmo.com/api-reference/domains/list-apex-domains.md): List apex domains with an exact organization-wide subdomain total, host counts, and collapsed-row summaries (apex host, probe snapshots, first/last seen) for canonical domain inventory. Ordered by apex ASC. Offset pagination via page + limit.
- [List descendant probe aggregates](https://docs.tolmo.com/api-reference/domains/list-descendant-probe-aggregates.md): Complete probe aggregates for every intermediate parent under one apex (Postgres; not Attack Surface). Same filters as the host list. Not paginated — one row per parent with grouped subdomainProbes (capped) and subdomainCount.
- [Export the domain inventory](https://docs.tolmo.com/api-reference/domains/export-the-domain-inventory.md): Download canonical (primary) domain inventory as CSV or JSON. One row per hostname, same filters as the list (`q`, lifecycle, dns, web, source). Omits Attack Surface / candidates and bookkeeping evidence sources. Ordered by apex then FQDN.
- [Clone a repository](https://docs.tolmo.com/api-reference/code/clone-a-repository.md): Download a bare git repo archive from storage or a live GitHub PR ref
- [Download a repository archive](https://docs.tolmo.com/api-reference/code/download-a-repository-archive.md): Download a bare git repo as a tar archive from S3
- [List code repositories](https://docs.tolmo.com/api-reference/code/list-code-repositories.md): List code repositories with clone availability
- [List scan runs](https://docs.tolmo.com/api-reference/scans/list-scan-runs.md): List scan runs for the org
- [List screenshots](https://docs.tolmo.com/api-reference/screenshots/list-screenshots.md): List URL screenshots captured for the org by the daily Cloudflare browser-rendering pipeline.
- [Get a screenshot](https://docs.tolmo.com/api-reference/screenshots/get-a-screenshot.md): Stream a single screenshot PNG. Bucket is private; this endpoint proxies the GetObject through the backend so org isolation can be enforced.
- [List activity events](https://docs.tolmo.com/api-reference/activity-feed/list-activity-events.md): Cursor-paginated Mission Control activity events. Filters are applied before the page limit; follow nextCursor until null.
- [List integration providers](https://docs.tolmo.com/api-reference/integrations/list-integration-providers.md): List publicly available integration providers and their field specs. A client-supplied `orgId` is accepted for compatibility and ignored: org-restricted specs are never unlocked by a query parameter.
- [List integrations](https://docs.tolmo.com/api-reference/integrations/list-integrations.md): List integrations
- [Connect an integration](https://docs.tolmo.com/api-reference/integrations/connect-an-integration.md): Create/update an integration
- [List connected services](https://docs.tolmo.com/api-reference/connected-services/list-connected-services.md): List connected integrations available for querying via the proxy
- [Run an AWS CLI command](https://docs.tolmo.com/api-reference/connected-services/run-an-aws-cli-command.md): Execute an AWS CLI command server-side using the org's connected AWS integration
- [Proxy a raw AWS request](https://docs.tolmo.com/api-reference/connected-services/proxy-a-raw-aws-request-get.md): Re-sign and forward raw AWS HTTP requests from the CLI local proxy
- [Proxy a raw AWS request](https://docs.tolmo.com/api-reference/connected-services/proxy-a-raw-aws-request-post.md): Re-sign and forward raw AWS HTTP requests from the CLI local proxy
- [Proxy a raw AWS request](https://docs.tolmo.com/api-reference/connected-services/proxy-a-raw-aws-request-put.md): Re-sign and forward raw AWS HTTP requests from the CLI local proxy
- [Proxy a raw AWS request](https://docs.tolmo.com/api-reference/connected-services/proxy-a-raw-aws-request-patch.md): Re-sign and forward raw AWS HTTP requests from the CLI local proxy
- [Proxy a raw AWS request](https://docs.tolmo.com/api-reference/connected-services/proxy-a-raw-aws-request-delete.md): Re-sign and forward raw AWS HTTP requests from the CLI local proxy
- [Proxy a request to a provider](https://docs.tolmo.com/api-reference/connected-services/proxy-a-request-to-a-provider.md): Proxy a read-only request to an external API through a connected integration
- [List Datadog monitors](https://docs.tolmo.com/api-reference/datadog-monitors/list-datadog-monitors.md): List the Datadog monitors Tolmo manages for this organization. Requests are proxied to Datadog with platform-held credentials, so no Datadog API key is needed.
- [Create a Datadog monitor](https://docs.tolmo.com/api-reference/datadog-monitors/create-a-datadog-monitor.md): Create a Datadog monitor through Tolmo's managed Datadog integration.
- [Get a Datadog monitor](https://docs.tolmo.com/api-reference/datadog-monitors/get-a-datadog-monitor.md): Fetch one Tolmo-managed Datadog monitor by its Datadog monitor id.
- [Update a Datadog monitor](https://docs.tolmo.com/api-reference/datadog-monitors/update-a-datadog-monitor.md): Update the definition of an existing Tolmo-managed Datadog monitor.
- [Delete a Datadog monitor](https://docs.tolmo.com/api-reference/datadog-monitors/delete-a-datadog-monitor.md): Delete a Tolmo-managed Datadog monitor. This removes the monitor in Datadog itself.
- [List threat model versions](https://docs.tolmo.com/api-reference/threat-models/list-threat-model-versions.md): List the organization's generated threat models, newest first. Each entry is a summary; fetch a version to get the full document.
- [Get the latest threat model](https://docs.tolmo.com/api-reference/threat-models/get-the-latest-threat-model.md): Fetch the most recent threat model generated for the organization, in full.
- [Get a threat model version](https://docs.tolmo.com/api-reference/threat-models/get-a-threat-model-version.md): Fetch one specific version of the organization's threat model, in full — the stable way to pin a report to a known revision.
- [List secret findings](https://docs.tolmo.com/api-reference/secrets/list-secret-findings.md): List leaked-credential findings detected across the organization's connected source repositories, with their current triage state.
- [Changelog](https://docs.tolmo.com/changelog.md): New features and improvements in Tolmo, newest first.

## OpenAPI Specs

- [openapi](/api-reference/openapi.json)


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