ThreatTree API Enterprise
A REST API for pipelines, scripts and internal tools: read and build threat models, generate attack trees, manage risks, registers and the threat library, receive signed webhooks, and fail a release when risk is too high.
- Authentication
- Scopes
- Conventions
- Endpoints
- Build diagrams
- Release gate
- Import and drift
- Webhooks
- Use in CI
- OpenAPI 3.1 file
Base URL: https://api.threattree.com/api/v1. The full description is in openapi.json (OpenAPI 3.1), which you can load into Postman, Insomnia or a code generator.
Authentication
Create a key in Settings → API keys (organization owners and admins, or a role with Manage API keys and webhooks). A key belongs to the organization, not to a person, and doesn't use a seat. Its secret is shown once; ThreatTree only keeps a hash of it.
Send it in the Authorization header. Keys are never accepted in the query string.
curl -H "Authorization: Bearer $THREATTREE_API_KEY" https://api.threattree.com/api/v1/forests
- Each key has scopes, an optional expiry, an optional list of forests it can reach (otherwise every forest of the organization), and an optional IP allowlist on top of the organization's.
- Rotate a key to get a new secret (the old one stops at once), or revoke it. Settings shows when and from where each key was last used.
- Everything a key changes is in the activity log, with "API key: <name>" as the actor.
- The API needs the Enterprise plan. If the organization leaves Enterprise, every call returns
402; keys are kept and work again when it comes back.
Scopes
| Scope | Allows |
|---|---|
forests:read | List forests and read one: its trees with every element, data flow and threat, review state, risk counts, coverage and trends. |
forests:write | Create forests (owned by the key's creator), rename them or change their description, and take backups. |
diagrams:write | Create, rename, link and delete DFDs and attack trees; add, change and delete elements and connections; generate attack trees from a DFD. |
risks:read | Read risk registers, and the release gate. |
risks:write | Update risks, one or up to 100 at a time: likelihood, impact, description, owner, collaborator, status, treatments, framework tags, standard controls, ATT&CK and ATLAS techniques. Open a ticket for a risk. |
registers:read | Read the asset register and the mitigation catalogue. |
registers:write | Create, change and delete assets and mitigations, and link them to elements and risks. |
comments:read | Read discussions: comments, replies and what each is about. |
comments:write | Post comments and replies, and resolve or reopen discussions. |
reviews:read | Read review and approval: state, stages, the pending review and history. |
reviews:write | Submit a model for approval, and cancel a pending review. |
reports:read | Download the forest PDF report and the STIX 2.1 export. |
import:write | Import Terraform, CloudFormation or OpenAPI into a new DFD, or compare it with an existing one. |
portfolio:read | Read the organization-wide risk portfolio. |
audit:read | Read the activity log. |
members:read | Read the organization's members and who can open each forest (names, emails, roles). |
library:read | Read the organization's threat library, its own frameworks, the risk matrix and the standards catalogue. |
library:write | Add, change and delete threats in the threat library, and the organization's own frameworks. |
webhooks:manage | List, add, change, test and delete webhooks, and read their delivery log. |
No key can create other keys, invite or remove people, change sign-in, security or billing settings, approve a threat model, sign off an accepted risk, delete a forest or restore a backup. Those stay with people in the app.
GET /me needs no scope: it returns the key's name, scopes, forests, IP list, expiry and rate limits, which helps when setting up a pipeline.
Conventions
- JSON everywhere. IDs are strings; dates are ISO 8601.
- Errors look like
{"error": {"code": "insufficient_scope", "message": "…"}}. Codes includeunauthenticated,key_revoked,key_expired,plan_required(402),insufficient_scope,ip_not_allowed,not_found,validation_failed,forest_lockedandrate_limited. - Pagination: lists return
dataandnext_cursor. Pass it back as?cursor=; it'snullon the last page.?limit=sets the page size. - Idempotency: send an
Idempotency-Keyheader on a POST. The same key with the same body within 24 hours returns the first response (withIdempotent-Replayed: true) instead of doing the work again. - Rate limits: 600 reads and 60 writes a minute per key. Responses carry
RateLimit-Limit,RateLimit-RemainingandRateLimit-Reset; over the limit you get429withRetry-After. - Encrypted forests are listed with their metadata only (the label you gave them, when they were locked). Their content is never read or changed through the API.
- Versioning: changes within
/v1only add fields and endpoints. Anything deprecated gets aSunsetheader well before it goes.
Endpoints
| Request | Scope | What it does |
|---|---|---|
GET/forests | forests:read | Forests the key can reach. |
POST/forests | forests:write | Create a forest: {"name": "…", "description": "…"}. |
GET/forests/{id} | forests:read | A forest with its trees, review state, open risks by severity and threat coverage. |
PATCH/forests/{id} | forests:write | Rename a forest or change its description. |
GET/search?q= | forests:read | Forests, trees, elements, threats and goals matching q, across the forests the key reaches. |
GET/forests/{id}/risks | risks:read | The risk register, highest first. Filters: severity, status (open, mitigated), needs_review, owner (empty for none). |
GET/forests/{id}/risks/{risk} | risks:read | One risk in full: description, treatment plan, framework tags, standard controls, ATT&CK/ATLAS techniques, tickets, re-review reasons and tracked mitigations. |
PATCH/forests/{id}/risks/{risk} | risks:write | likelihood, impact, description, owner, collaborator, status (open, mitigated), treatments, frameworks, controls, attack_techniques, atlas_techniques. Validated like an edit in the app (risk matrix, known tags and controls, technique IDs). A risk with linked tickets takes its status from them (409). A treatment of type accept on a risk at or above the organization's sign-off threshold asks for sign-off, as in the app. |
PATCH/forests/{id}/risks | risks:write | Up to 100 risk updates: {"updates": [{"id": "…", "owner": "…"}, …]}. Each item is applied on its own; the answer gives each item's status, with 207 if any failed. |
POST/forests/{id}/risks/{risk}/tickets | risks:write | Open a ticket for a scored risk in each connected ticketing tool (Jira, Azure DevOps, ServiceNow, Linear) that doesn't have an open one. High and critical risks get tickets automatically. |
GET/forests/{id}/risks.csv | risks:read | The risk register as CSV. assets.csv and mitigations.csv (registers:read) export the registers. |
GET/forests/{id}/risk-matrix | forests:read | The likelihood and impact scales and severity bands the forest is scored on. |
GET/forests/{id}/gate | risks:read | Pass or fail for a release, with the reasons. Details. |
POST/forests/{id}/import | import:write | Import code into a new DFD, or compare it with an existing one. Details. |
GET/forests/{id}/trees | forests:read | The forest's DFDs and attack trees. |
GET/forests/{id}/trees/{tree} | forests:read | A DFD with its elements, data flows and security attributes, or an attack tree with its goal, gates and threats (and which are in the risk register). |
POST PATCH DELETE/forests/{id}/trees[/{tree}] | diagrams:write | Create a DFD or attack tree (dfd_id links an attack tree to its DFD), rename it, link or unlink it, delete it. |
POST PATCH DELETE/forests/{id}/trees/{tree}/nodes[/{node}] | diagrams:write | Add, change or delete an element: type, label, description, properties, x, y. Details. |
POST PATCH DELETE/forests/{id}/trees/{tree}/connections[/{edge}] | diagrams:write | Add, change or delete a data flow (DFD) or attack path (attack tree): from, to, label. |
GET/forests/{id}/trees/{tree}/suggestions | forests:read | The threats suggested for each element of a DFD: the built-in dictionary, your threat library and rule hits. |
POST/forests/{id}/trees/{tree}/generate | diagrams:write | Generate attack trees from a DFD: every new suggestion, or the selections you pass. |
GET/forests/{id}/trends | forests:read | The forest's daily risk figures over days (30, 90 or 365). |
GET/forests/{id}/assets | registers:read | The asset register, with C/I/A ratings, elements and the threats that reach each asset. |
POST PATCH DELETE/forests/{id}/assets[/{asset}] | registers:write | Create, update or delete an asset. Link it to DFD elements with element_ids. |
GET/forests/{id}/mitigations | registers:read | The mitigation catalogue: owner, status, due date, overdue, and the risks each one treats. |
POST PATCH DELETE/forests/{id}/mitigations[/{mitigation}] | registers:write | Create, update or delete a mitigation. Link it to risks with risk_ids; standard controls in controls. |
GET/forests/{id}/comments | comments:read | Discussions with their replies, filtered by status (open, resolved). |
POST/forests/{id}/comments | comments:write | Start a discussion on a risk, element or connection (risk_id, element_id, connection_id), or reply (parent_id). …/comments/{comment}/resolve and /reopen close and reopen it. |
GET POST/forests/{id}/snapshots | forests:read / forests:write | List backups, or take one with a label. Restoring needs a person's password, so it stays in the app. |
GET/forests/{id}/members | members:read | Who can open the forest, with their role and whether it comes from a group. |
GET/forests/{id}/review | reviews:read | Review and approval: state, stages, the pending review and history. |
POST/forests/{id}/review | reviews:write | Submit for approval: approvers (user IDs or emails) or stages (one list per stage), and a note. DELETE cancels the pending review. |
GET/forests/{id}/report.pdf | reports:read | The forest PDF report, with optional title, classification, version and executive_notes. |
GET/forests/{id}/stix | reports:read | A STIX 2.1 bundle of the forest's attack trees. |
GET/portfolio | portfolio:read | Headline figures and every risk across the forests the key reaches. |
GET/portfolio/trends | portfolio:read | Daily risk figures summed over those forests. |
GET/audit-logs | audit:read | The activity log, newest first. Filters: since, until, action (a prefix, such as risk.), forest_id. |
GET/members | members:read | The organization's members: name, email, role and custom role. |
GET POST PATCH DELETE/threat-library[/{threat}] | library:read / library:write | The organization's own threats, which the generator suggests next to the built-in dictionary. PATCH keeps fields you don't send. |
GET POST PATCH DELETE/frameworks[/{framework}] | library:read / library:write | The organization's own frameworks and their categories. Set archived to retire one; only unused frameworks can be deleted. |
GET/risk-matrix | library:read | The organization's risk matrix. |
GET/standards | library:read | Every framework tag and standard control reference that frameworks and controls accept. |
GET POST PATCH DELETE/webhooks[/{webhook}] | webhooks:manage | Webhooks. …/test sends a test event; …/deliveries is the delivery log. Details. |
GET/me | none | The key itself: name, scopes, forests, limits. |
# Open critical risks without an owner
curl -H "Authorization: Bearer $THREATTREE_API_KEY" \
"https://api.threattree.com/api/v1/forests/123/risks?severity=critical&status=open&owner="
# Assign one and record a treatment
curl -X PATCH -H "Authorization: Bearer $THREATTREE_API_KEY" -H "Content-Type: application/json" \
-d '{"owner": "Payments team", "treatments": [{"type": "mitigate", "text": "Tokenize card numbers"}]}' \
https://api.threattree.com/api/v1/forests/123/risks/9876
More examples
# Score a risk on the forest's matrix and tag it
curl -X PATCH -H "Authorization: Bearer $THREATTREE_API_KEY" -H "Content-Type: application/json" \
-d '{"likelihood": 4, "impact": 5, "attack_techniques": ["T1565.001"]}' \
https://api.threattree.com/api/v1/forests/123/risks/9876
# Track a mitigation for two risks
curl -X POST -H "Authorization: Bearer $THREATTREE_API_KEY" -H "Content-Type: application/json" \
-d '{"title": "Sign ledger entries", "owner": "Payments team", "status": "in_progress", "due_date": "2027-01-31", "risk_ids": ["9876", "9877"]}' \
https://api.threattree.com/api/v1/forests/123/mitigations
# Submit the model for approval from a release pipeline
curl -X POST -H "Authorization: Bearer $THREATTREE_API_KEY" -H "Content-Type: application/json" \
-d '{"approvers": ["ciso@example.com"], "note": "Release 2.4"}' \
https://api.threattree.com/api/v1/forests/123/review
# Archive the board report with the release
curl -H "Authorization: Bearer $THREATTREE_API_KEY" -o threat-model.pdf \
"https://api.threattree.com/api/v1/forests/123/report.pdf?version=2.4&classification=Internal"
Writes go through the same rules as the app: a field the app refuses is refused here with the same message. Approving or requesting changes stays a person's decision in the app; keys can submit and cancel, not approve. Reviews submitted through the API are submitted by the key's creator when they can edit the model, otherwise by its owner, and approvers get the usual emails.
Build diagrams
Diagrams written through the API go through the same code as the editors, so change impact, custom roles and validation all apply: changing an element flags its threats for re-review, as an edit in the app does. IDs returned by one call are used in the next.
TT=https://api.threattree.com/api/v1; H="Authorization: Bearer $THREATTREE_API_KEY"
# A DFD with two elements and a data flow
DFD=$(curl -s -X POST -H "$H" -H "Content-Type: application/json" -d '{"name": "Checkout", "type": "dfd"}' $TT/forests/123/trees | jq -r .data.id)
API=$(curl -s -X POST -H "$H" -H "Content-Type: application/json" -d '{"type": "process", "label": "Checkout API"}' $TT/forests/123/trees/$DFD/nodes | jq -r .data.id)
DB=$(curl -s -X POST -H "$H" -H "Content-Type: application/json" -d '{"type": "data_store", "label": "Orders DB"}' $TT/forests/123/trees/$DFD/nodes | jq -r .data.id)
curl -s -X POST -H "$H" -H "Content-Type: application/json" -d "{\"from\": \"$API\", \"to\": \"$DB\", \"label\": \"Writes orders\"}" $TT/forests/123/trees/$DFD/connections
# Attack trees from every suggested threat
curl -s -X POST -H "$H" $TT/forests/123/trees/$DFD/generate | jq '.data'
Element types are the editors' palette: process, data_store, external_entity, trust_boundary and the technology elements in DFDs; goal, leaf, or_gate and and_gate in attack trees. Security attributes go in properties; a PATCH merges the properties you send into the current ones. Without x and y, a new element is placed to the right of the others; Auto Layout in the editor tidies them.
Release gate
GET /forests/{id}/gate answers one question for a pipeline: can this release go out? It always returns 200; check data.result.
| Parameter | Fails the gate when… |
|---|---|
max_severity (default high) | an open risk is at or above this severity: critical, high, medium or low. |
require_approved=true | the threat model isn't approved (review and approval). |
fail_on_review=true | threats wait for a re-review after a diagram change. |
Add format=sarif to get the same result as SARIF 2.1.0, which GitHub code scanning reads: one result per open risk over the threshold (critical and high as errors, medium as warnings, low as notes) and one per other reason. sarif_path sets the file the results point at (default threattree/forest-<id>.json). The SARIF answer is always 200; runs[0].properties.gateResult says pass or fail. GitHub shows the results in the repository's code scanning alerts and in the pull request's checks (private repositories need GitHub Advanced Security). GitLab doesn't read SARIF; use the JSON gate there.
{
"data": {
"result": "fail",
"reasons": [
{ "code": "open_risks_over_threshold", "message": "1 open risk at or above high.",
"risks": [{ "id": "9876", "title": "Card skimming", "severity": "critical" }] }
],
"counts": { "open": { "low": 0, "medium": 2, "high": 0, "critical": 1 }, "needs_review": 0, "review_state": "approved" }
}
}
Import and drift
POST /forests/{id}/import takes Terraform (HCL or terraform show -json output), CloudFormation (JSON or YAML) or OpenAPI, as {"source": "…"} or a multipart file. It uses the same parser as Import from code in the app.
- Without
compare, it creates a new DFD and returns itstree_id. It never changes an existing diagram. - With
compareset to an existing DFD's ID, it creates nothing and returns the drift: elements in the code but not in the diagram (added), in the diagram but not in the code (removed), andin_sync. Elements are matched by type and name.
jq -Rs '{source: ., compare: "456"}' infra/main.tf | curl -X POST \
-H "Authorization: Bearer $THREATTREE_API_KEY" -H "Content-Type: application/json" \
-d @- https://api.threattree.com/api/v1/forests/123/import
Webhooks
Webhooks send ThreatTree events to your systems as they happen, whether a person or a key caused them. Add them in Settings → Webhooks (owners, admins, or a role with Manage API keys and webhooks) or through /webhooks. Each is an HTTPS URL on a public address with the events it wants.
| Event | When |
|---|---|
risk.high_or_critical | A risk becomes high or critical. |
risk.updated | A risk is updated through the API. |
threats.flagged_for_review | Threats are flagged for re-review after a diagram change. |
review.submitted, review.stage_approved, review.approved, review.changes_requested, review.cancelled | Review and approval. |
comment.created, comment.resolved | Discussions. |
mitigation.created, mitigation.updated | The mitigation catalogue (for example a status change). |
import.completed | A DFD is imported from code. |
forest.created, tree.created, tree.deleted | Forests and diagrams. |
Each delivery is a JSON POST:
{
"id": "evt_4821",
"event": "risk.high_or_critical",
"created_at": "2026-11-17T10:42:00+00:00",
"organization_id": "12",
"forest": { "id": "123", "name": "Payments", "url": "https://threattree.com/app/forest?id=123" },
"actor": { "type": "user", "name": "Dana Lee", "email": "dana@example.com" },
"target": { "type": "Node", "id": "9876", "label": "Card skimming" },
"data": { "score": 20, "severity": "critical" }
}
- Headers:
ThreatTree-Event,ThreatTree-Delivery(the event ID, the same on every retry) andThreatTree-Signature: t=<unix time>,v1=<signature>. - Signature: the hex HMAC-SHA256 of
<t>.<raw body>, keyed with the webhook's signing secret (whsec_…, shown once when you add the webhook or ask for a new one). Reject requests whose signature doesn't match or whosetis more than five minutes old. - Retries: any answer other than 2xx, or no answer within 5 seconds, is retried after 1, 5, 30, 120 and 720 minutes, then marked failed. Redirects aren't followed. Use
ThreatTree-Deliveryto ignore duplicates. - Delivery log: the last 30 days, with status, attempts, the answer code and each payload, in Settings and at
/webhooks/{id}/deliveries. Send test sends apingevent. - Encrypted forests send their events without the forest name or labels.
# Python: check a delivery
import hmac, hashlib, time
def verify(raw_body: bytes, header: str, secret: str) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
if abs(time.time() - int(parts["t"])) > 300:
return False
expected = hmac.new(secret.encode(), parts["t"].encode() + b"." + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts["v1"])
Use in CI
Store the key as a secret in your CI system. These examples check drift and run the release gate on every pull request or pipeline; the job fails when the gate does.
GitHub Actions
name: Threat model
on: [pull_request]
jobs:
threattree:
runs-on: ubuntu-latest
env:
TT: https://api.threattree.com/api/v1
TT_KEY: ${{ secrets.THREATTREE_API_KEY }}
FOREST_ID: "123" # the forest of this service
DFD_ID: "456" # its data flow diagram
steps:
- uses: actions/checkout@v4
- name: Architecture drift (Terraform vs. the diagram)
run: |
jq -Rs '{source: ., compare: $ENV.DFD_ID}' infra/main.tf > body.json
curl -sS --fail-with-body -X POST "$TT/forests/$FOREST_ID/import" \
-H "Authorization: Bearer $TT_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: ${{ github.run_id }}-drift" -d @body.json | jq '.data'
- name: Release gate
run: |
curl -sS --fail-with-body "$TT/forests/$FOREST_ID/gate?max_severity=high&require_approved=true" \
-H "Authorization: Bearer $TT_KEY" > gate.json
jq -r '.data.reasons[].message' gate.json
jq -e '.data.result == "pass"' gate.json
To list the open risks in GitHub code scanning and the pull request's checks, upload the SARIF form of the gate (the job needs security-events: write):
- name: Risks as code scanning results
if: always()
run: |
curl -sS --fail-with-body "$TT/forests/$FOREST_ID/gate?max_severity=high&format=sarif&sarif_path=infra/main.tf" \
-H "Authorization: Bearer $TT_KEY" > threattree.sarif
- uses: github/codeql-action/upload-sarif@v3
if: always()
with:
sarif_file: threattree.sarif
category: threattree
GitLab CI
threat-model-gate:
stage: test
image: alpine:3.20
variables:
TT: "https://api.threattree.com/api/v1"
FOREST_ID: "123"
before_script:
- apk add --no-cache curl jq
script:
# THREATTREE_API_KEY is a masked CI/CD variable
- >
curl -sS --fail-with-body "$TT/forests/$FOREST_ID/gate?max_severity=high"
-H "Authorization: Bearer $THREATTREE_API_KEY" > gate.json
- jq -r '.data.reasons[].message' gate.json
- jq -e '.data.result == "pass"' gate.json
Azure Pipelines
steps:
- script: |
curl -sS --fail-with-body "$TT/forests/$FOREST_ID/gate?max_severity=high" \
-H "Authorization: Bearer $TT_KEY" > gate.json
jq -r '.data.reasons[].message' gate.json
jq -e '.data.result == "pass"' gate.json
displayName: ThreatTree release gate
env:
TT: https://api.threattree.com/api/v1
FOREST_ID: "123"
TT_KEY: $(THREATTREE_API_KEY) # a secret pipeline variable
The API is part of the Enterprise plan. Questions, or a scope you need? Contact us. In the app, see Help → ThreatTree API.