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.

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

ScopeAllows
forests:readList forests and read one: its trees with every element, data flow and threat, review state, risk counts, coverage and trends.
forests:writeCreate forests (owned by the key's creator), rename them or change their description, and take backups.
diagrams:writeCreate, rename, link and delete DFDs and attack trees; add, change and delete elements and connections; generate attack trees from a DFD.
risks:readRead risk registers, and the release gate.
risks:writeUpdate 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:readRead the asset register and the mitigation catalogue.
registers:writeCreate, change and delete assets and mitigations, and link them to elements and risks.
comments:readRead discussions: comments, replies and what each is about.
comments:writePost comments and replies, and resolve or reopen discussions.
reviews:readRead review and approval: state, stages, the pending review and history.
reviews:writeSubmit a model for approval, and cancel a pending review.
reports:readDownload the forest PDF report and the STIX 2.1 export.
import:writeImport Terraform, CloudFormation or OpenAPI into a new DFD, or compare it with an existing one.
portfolio:readRead the organization-wide risk portfolio.
audit:readRead the activity log.
members:readRead the organization's members and who can open each forest (names, emails, roles).
library:readRead the organization's threat library, its own frameworks, the risk matrix and the standards catalogue.
library:writeAdd, change and delete threats in the threat library, and the organization's own frameworks.
webhooks:manageList, 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 include unauthenticated, key_revoked, key_expired, plan_required (402), insufficient_scope, ip_not_allowed, not_found, validation_failed, forest_locked and rate_limited.
  • Pagination: lists return data and next_cursor. Pass it back as ?cursor=; it's null on the last page. ?limit= sets the page size.
  • Idempotency: send an Idempotency-Key header on a POST. The same key with the same body within 24 hours returns the first response (with Idempotent-Replayed: true) instead of doing the work again.
  • Rate limits: 600 reads and 60 writes a minute per key. Responses carry RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset; over the limit you get 429 with Retry-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 /v1 only add fields and endpoints. Anything deprecated gets a Sunset header well before it goes.

Endpoints

RequestScopeWhat it does
GET/forestsforests:readForests the key can reach.
POST/forestsforests:writeCreate a forest: {"name": "…", "description": "…"}.
GET/forests/{id}forests:readA forest with its trees, review state, open risks by severity and threat coverage.
PATCH/forests/{id}forests:writeRename a forest or change its description.
GET/search?q=forests:readForests, trees, elements, threats and goals matching q, across the forests the key reaches.
GET/forests/{id}/risksrisks:readThe risk register, highest first. Filters: severity, status (open, mitigated), needs_review, owner (empty for none).
GET/forests/{id}/risks/{risk}risks:readOne 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:writelikelihood, 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}/risksrisks:writeUp 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}/ticketsrisks:writeOpen 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.csvrisks:readThe risk register as CSV. assets.csv and mitigations.csv (registers:read) export the registers.
GET/forests/{id}/risk-matrixforests:readThe likelihood and impact scales and severity bands the forest is scored on.
GET/forests/{id}/gaterisks:readPass or fail for a release, with the reasons. Details.
POST/forests/{id}/importimport:writeImport code into a new DFD, or compare it with an existing one. Details.
GET/forests/{id}/treesforests:readThe forest's DFDs and attack trees.
GET/forests/{id}/trees/{tree}forests:readA 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:writeCreate 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:writeAdd, change or delete an element: type, label, description, properties, x, y. Details.
POST PATCH DELETE/forests/{id}/trees/{tree}/connections[/{edge}]diagrams:writeAdd, change or delete a data flow (DFD) or attack path (attack tree): from, to, label.
GET/forests/{id}/trees/{tree}/suggestionsforests:readThe threats suggested for each element of a DFD: the built-in dictionary, your threat library and rule hits.
POST/forests/{id}/trees/{tree}/generatediagrams:writeGenerate attack trees from a DFD: every new suggestion, or the selections you pass.
GET/forests/{id}/trendsforests:readThe forest's daily risk figures over days (30, 90 or 365).
GET/forests/{id}/assetsregisters:readThe asset register, with C/I/A ratings, elements and the threats that reach each asset.
POST PATCH DELETE/forests/{id}/assets[/{asset}]registers:writeCreate, update or delete an asset. Link it to DFD elements with element_ids.
GET/forests/{id}/mitigationsregisters:readThe mitigation catalogue: owner, status, due date, overdue, and the risks each one treats.
POST PATCH DELETE/forests/{id}/mitigations[/{mitigation}]registers:writeCreate, update or delete a mitigation. Link it to risks with risk_ids; standard controls in controls.
GET/forests/{id}/commentscomments:readDiscussions with their replies, filtered by status (open, resolved).
POST/forests/{id}/commentscomments:writeStart 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}/snapshotsforests:read / forests:writeList backups, or take one with a label. Restoring needs a person's password, so it stays in the app.
GET/forests/{id}/membersmembers:readWho can open the forest, with their role and whether it comes from a group.
GET/forests/{id}/reviewreviews:readReview and approval: state, stages, the pending review and history.
POST/forests/{id}/reviewreviews:writeSubmit 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.pdfreports:readThe forest PDF report, with optional title, classification, version and executive_notes.
GET/forests/{id}/stixreports:readA STIX 2.1 bundle of the forest's attack trees.
GET/portfolioportfolio:readHeadline figures and every risk across the forests the key reaches.
GET/portfolio/trendsportfolio:readDaily risk figures summed over those forests.
GET/audit-logsaudit:readThe activity log, newest first. Filters: since, until, action (a prefix, such as risk.), forest_id.
GET/membersmembers:readThe organization's members: name, email, role and custom role.
GET POST PATCH DELETE/threat-library[/{threat}]library:read / library:writeThe 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:writeThe organization's own frameworks and their categories. Set archived to retire one; only unused frameworks can be deleted.
GET/risk-matrixlibrary:readThe organization's risk matrix.
GET/standardslibrary:readEvery framework tag and standard control reference that frameworks and controls accept.
GET POST PATCH DELETE/webhooks[/{webhook}]webhooks:manageWebhooks. …/test sends a test event; …/deliveries is the delivery log. Details.
GET/menoneThe 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.

ParameterFails the gate when…
max_severity (default high)an open risk is at or above this severity: critical, high, medium or low.
require_approved=truethe threat model isn't approved (review and approval).
fail_on_review=truethreats 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 its tree_id. It never changes an existing diagram.
  • With compare set 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), and in_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.

EventWhen
risk.high_or_criticalA risk becomes high or critical.
risk.updatedA risk is updated through the API.
threats.flagged_for_reviewThreats are flagged for re-review after a diagram change.
review.submitted, review.stage_approved, review.approved, review.changes_requested, review.cancelledReview and approval.
comment.created, comment.resolvedDiscussions.
mitigation.created, mitigation.updatedThe mitigation catalogue (for example a status change).
import.completedA DFD is imported from code.
forest.created, tree.created, tree.deletedForests 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) and ThreatTree-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 whose t is 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-Delivery to 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 a ping event.
  • 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.