{"openapi":"3.1.0","info":{"title":"ThreatTree API","version":"1.2.0","description":"The ThreatTree REST API for Enterprise organizations: read threat models and risk registers, update risks, import architecture from code, build and change diagrams, generate attack trees, manage the threat library and frameworks, receive signed webhooks, and gate releases on risk (JSON or SARIF).\n\n**Authentication:** an organization API key (Settings \u2192 API keys) in `Authorization: Bearer tt_\u2026`. Keys are never accepted in the query string.\n\n**Conventions:** JSON; IDs are strings; dates are ISO 8601; errors are `{\"error\": {\"code\", \"message\"}}`; lists return `data` and `next_cursor` (null on the last page); POSTs accept an `Idempotency-Key` header. Changes within v1 are additive only; anything deprecated gets a `Sunset` header first.\n\n**Rate limits:** 600 reads and 60 writes a minute per key, with `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` headers, and `429` with `Retry-After` when exceeded.\n\n**Encrypted forests** are listed with their metadata only; their content is never read through the API."},"servers":[{"url":"https:\/\/api.threattree.com\/api\/v1"}],"security":[{"apiKey":[]}],"paths":{"\/forests":{"get":{"summary":"List forests","operationId":"listForests","security":[{"apiKey":["forests:read"]}],"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size.","schema":{"type":"integer","minimum":1}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` of the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Forests the key can reach.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ForestList"}}}},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}},"post":{"summary":"Create a forest","operationId":"createForest","security":[{"apiKey":["forests:write"]}],"parameters":[{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string"}}}}}},"responses":{"201":{"description":"Created. Owned by the key's creator.","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/Forest"}}}}}},"422":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/forests\/{id}":{"get":{"summary":"Get a forest","operationId":"getForest","security":[{"apiKey":["forests:read"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Forest ID","schema":{"type":"string"}}],"responses":{"200":{"description":"The forest with its trees, risk counts and coverage.","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/ForestDetail"}}}}}},"404":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}},"patch":{"summary":"Rename a forest or change its description","operationId":"updateForest","security":[{"apiKey":["forests:write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Forest ID","schema":{"type":"string"}}],"description":"Deleting a forest needs a person's password, so it is not in the API.","requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"}}}}}},"responses":{"200":{"description":"The forest.","content":{"application\/json":{"schema":{"type":"object"}}}},"404":{"$ref":"#\/components\/responses\/Error"},"422":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/forests\/{id}\/risks":{"get":{"summary":"List the risk register","operationId":"listRisks","security":[{"apiKey":["risks:read"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Forest ID","schema":{"type":"string"}},{"name":"severity","in":"query","required":false,"description":"Only this severity.","schema":{"type":"string","enum":["critical","high","medium","low"]}},{"name":"status","in":"query","required":false,"description":"Only open or mitigated risks.","schema":{"type":"string","enum":["open","mitigated"]}},{"name":"needs_review","in":"query","required":false,"description":"Only risks flagged (or not) for re-review after a diagram change.","schema":{"type":"boolean"}},{"name":"owner","in":"query","required":false,"description":"Only this owner; empty for risks with no owner.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size.","schema":{"type":"integer","minimum":1}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` of the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Risks, highest first.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/RiskList"}}}},"404":{"$ref":"#\/components\/responses\/Error"},"422":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}},"patch":{"summary":"Update up to 100 risks","operationId":"updateRisks","security":[{"apiKey":["risks:write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Forest ID","schema":{"type":"string"}}],"description":"Each item has an `id` and the fields of PATCH \/forests\/{id}\/risks\/{risk}. Items are applied one by one; the answer lists each item's status, with 207 if any failed.","requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["updates"],"properties":{"updates":{"type":"array","maxItems":100,"items":{"type":"object","required":["id"],"properties":{"id":{"type":"string"}}}}}}}}},"responses":{"200":{"description":"All applied.","content":{"application\/json":{"schema":{"type":"object"}}}},"207":{"description":"Some failed; see each item.","content":{"application\/json":{"schema":{"type":"object"}}}},"422":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/forests\/{id}\/risks\/{risk}":{"get":{"summary":"Get one risk in full","operationId":"getRisk","security":[{"apiKey":["risks:read"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Forest ID","schema":{"type":"string"}},{"name":"risk","in":"path","required":true,"description":"Risk ID","schema":{"type":"string"}}],"responses":{"200":{"description":"The risk with its description, treatment plan, framework tags, controls, techniques, tickets, re-review reasons and tracked mitigations.","content":{"application\/json":{"schema":{"type":"object"}}}},"404":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}},"patch":{"summary":"Update a risk","operationId":"updateRisk","security":[{"apiKey":["risks:write"]}],"description":"Validated like an edit in the app: likelihood and impact on the forest's risk matrix, known framework tags and standard controls, valid technique IDs. A risk with linked tickets takes its status from them (409). Other fields are refused (field_not_writable).","parameters":[{"name":"id","in":"path","required":true,"description":"Forest ID","schema":{"type":"string"}},{"name":"risk","in":"path","required":true,"description":"Risk ID (its attack-tree node)","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"owner":{"type":["string","null"]},"collaborator":{"type":["string","null"]},"status":{"type":"string","enum":["open","mitigated"]},"likelihood":{"type":["integer","null"]},"impact":{"type":["integer","null"]},"description":{"type":["string","null"]},"frameworks":{"type":"array","items":{"type":"object","properties":{"fw":{"type":"string"},"cat":{"type":"string"}}}},"controls":{"type":"object","description":"Standard => list of control references, for example {\"ISO 27001:2022\": [\"A.8.24 Use of cryptography\"]}."},"attack_techniques":{"type":"array","items":{"type":"string","pattern":"^T\\d{4}(\\.\\d{3})?$"}},"atlas_techniques":{"type":"array","items":{"type":"string","pattern":"^AML\\.T\\d{4}(\\.\\d{3})?$"}},"treatments":{"type":"array","items":{"type":"object","required":["type","text"],"properties":{"type":{"type":"string","enum":["mitigate","avoid","transfer","accept"]},"text":{"type":"string"}}}}}}}}},"responses":{"200":{"description":"The updated risk.","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/Risk"}}}}}},"404":{"$ref":"#\/components\/responses\/Error"},"409":{"$ref":"#\/components\/responses\/Error"},"422":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/forests\/{id}\/gate":{"get":{"summary":"Release gate","operationId":"gate","security":[{"apiKey":["risks:read"]}],"description":"Pass or fail for a release, with the reasons. Always 200: check `data.result`.","parameters":[{"name":"id","in":"path","required":true,"description":"Forest ID","schema":{"type":"string"}},{"name":"max_severity","in":"query","required":false,"description":"Fail on open risks at or above this.","schema":{"type":"string","enum":["critical","high","medium","low"]}},{"name":"require_approved","in":"query","required":false,"description":"Fail unless the model is approved.","schema":{"type":"boolean"}},{"name":"fail_on_review","in":"query","required":false,"description":"Fail while threats need re-review.","schema":{"type":"boolean"}},{"name":"format","in":"query","required":false,"description":"`json` (default) or `sarif` (SARIF 2.1.0 for GitHub code scanning).","schema":{"type":"string","enum":["json","sarif"]}},{"name":"sarif_path","in":"query","required":false,"description":"File the SARIF results point at (default threattree\/forest-<id>.json).","schema":{"type":"string"}}],"responses":{"200":{"description":"The verdict.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Gate"}}}},"404":{"$ref":"#\/components\/responses\/Error"},"422":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/forests\/{id}\/import":{"post":{"summary":"Import architecture from code","operationId":"import","security":[{"apiKey":["import:write"]}],"description":"Terraform (HCL or plan JSON), CloudFormation (JSON or YAML) or OpenAPI. Creates a new DFD; with `compare` (an existing DFD's ID) creates nothing and returns the drift between the code and that diagram.","parameters":[{"name":"id","in":"path","required":true,"description":"Forest ID","schema":{"type":"string"}},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["source"],"properties":{"source":{"type":"string","description":"The file's text."},"name":{"type":"string"},"compare":{"type":"string"}}}},"multipart\/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"},"name":{"type":"string"},"compare":{"type":"string"}}}}}},"responses":{"201":{"description":"The new DFD.","content":{"application\/json":{"schema":{"type":"object"}}}},"200":{"description":"With compare: the drift.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Drift"}}}},"404":{"$ref":"#\/components\/responses\/Error"},"409":{"$ref":"#\/components\/responses\/Error"},"422":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/portfolio":{"get":{"summary":"Organization risk portfolio","operationId":"portfolio","security":[{"apiKey":["portfolio:read"]}],"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size.","schema":{"type":"integer","minimum":1}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` of the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Headline figures and every risk the key can reach.","content":{"application\/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/audit-logs":{"get":{"summary":"Activity log","operationId":"auditLogs","security":[{"apiKey":["audit:read"]}],"parameters":[{"name":"since","in":"query","required":false,"description":"From this date and time.","schema":{"type":"string","format":"date-time"}},{"name":"until","in":"query","required":false,"description":"Before this date and time.","schema":{"type":"string","format":"date-time"}},{"name":"action","in":"query","required":false,"description":"Actions starting with this, for example `risk.` or `tree.imported`.","schema":{"type":"string"}},{"name":"forest_id","in":"query","required":false,"description":"One forest.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size.","schema":{"type":"integer","minimum":1}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` of the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Newest first.","content":{"application\/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/forests\/{id}\/trees":{"get":{"summary":"List a forest's trees","operationId":"listTrees","security":[{"apiKey":["forests:read"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Forest ID","schema":{"type":"string"}}],"responses":{"200":{"description":"DFDs and attack trees, with element and connection counts.","content":{"application\/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}},"post":{"summary":"Create a DFD or attack tree","operationId":"createTree","security":[{"apiKey":["diagrams:write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Forest ID","schema":{"type":"string"}},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["name","type"],"properties":{"name":{"type":"string"},"type":{"type":"string","enum":["dfd","attack_tree"]},"dfd_id":{"type":"string","description":"For an attack tree: the DFD it belongs to."}}}}}},"responses":{"201":{"description":"The tree.","content":{"application\/json":{"schema":{"type":"object"}}}},"422":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/forests\/{id}\/trees\/{tree}":{"get":{"summary":"Get a tree with its elements and connections","operationId":"getTree","security":[{"apiKey":["forests:read"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Forest ID","schema":{"type":"string"}},{"name":"tree","in":"path","required":true,"description":"Tree ID","schema":{"type":"string"}}],"responses":{"200":{"description":"A DFD (elements, data flows, security attributes) or an attack tree (goal, gates, threats, and whether each is in the risk register).","content":{"application\/json":{"schema":{"type":"object"}}}},"404":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}},"patch":{"summary":"Rename a tree, or link or unlink an attack tree's DFD","operationId":"updateTree","security":[{"apiKey":["diagrams:write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Forest ID","schema":{"type":"string"}},{"name":"tree","in":"path","required":true,"description":"Tree ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"dfd_id":{"type":["string","null"]}}}}}},"responses":{"200":{"description":"The tree.","content":{"application\/json":{"schema":{"type":"object"}}}},"404":{"$ref":"#\/components\/responses\/Error"},"422":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}},"delete":{"summary":"Delete a tree","operationId":"deleteTree","security":[{"apiKey":["diagrams:write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Forest ID","schema":{"type":"string"}},{"name":"tree","in":"path","required":true,"description":"Tree ID","schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted."},"404":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/forests\/{id}\/trends":{"get":{"summary":"Risk trends of one forest","operationId":"forestTrends","security":[{"apiKey":["forests:read"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Forest ID","schema":{"type":"string"}},{"name":"days","in":"query","required":false,"description":"30, 90 (default) or 365.","schema":{"type":"integer","enum":[30,90,365]}}],"responses":{"200":{"description":"One point per recorded day.","content":{"application\/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/portfolio\/trends":{"get":{"summary":"Risk trends across the forests the key reaches","operationId":"portfolioTrends","security":[{"apiKey":["portfolio:read"]}],"parameters":[{"name":"days","in":"query","required":false,"description":"30, 90 (default) or 365.","schema":{"type":"integer","enum":[30,90,365]}}],"responses":{"200":{"description":"One point per recorded day, summed over the forests.","content":{"application\/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/forests\/{id}\/assets":{"get":{"summary":"List the asset register","operationId":"listAssets","security":[{"apiKey":["registers:read"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Forest ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Assets with their C\/I\/A ratings, elements and the threats that reach them; `meta` has the allowed types and classifications.","content":{"application\/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}},"post":{"summary":"Create an asset","operationId":"createAsset","security":[{"apiKey":["registers:write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Forest ID","schema":{"type":"string"}},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/AssetInput"}}}},"responses":{"201":{"description":"The asset.","content":{"application\/json":{"schema":{"type":"object"}}}},"422":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/forests\/{id}\/assets\/{asset}":{"patch":{"summary":"Update an asset","operationId":"updateAsset","security":[{"apiKey":["registers:write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Forest ID","schema":{"type":"string"}},{"name":"asset","in":"path","required":true,"description":"Asset ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/AssetInput"}}}},"responses":{"200":{"description":"The asset.","content":{"application\/json":{"schema":{"type":"object"}}}},"404":{"$ref":"#\/components\/responses\/Error"},"422":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}},"delete":{"summary":"Delete an asset","operationId":"deleteAsset","security":[{"apiKey":["registers:write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Forest ID","schema":{"type":"string"}},{"name":"asset","in":"path","required":true,"description":"Asset ID","schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted."},"404":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/forests\/{id}\/mitigations":{"get":{"summary":"List the mitigation catalogue","operationId":"listMitigations","security":[{"apiKey":["registers:read"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Forest ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Mitigations with owner, status, due date and the risks they treat; `meta` has the statuses and counts.","content":{"application\/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}},"post":{"summary":"Create a mitigation","operationId":"createMitigation","security":[{"apiKey":["registers:write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Forest ID","schema":{"type":"string"}},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/MitigationInput"}}}},"responses":{"201":{"description":"The mitigation.","content":{"application\/json":{"schema":{"type":"object"}}}},"422":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/forests\/{id}\/mitigations\/{mitigation}":{"patch":{"summary":"Update a mitigation","operationId":"updateMitigation","security":[{"apiKey":["registers:write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Forest ID","schema":{"type":"string"}},{"name":"mitigation","in":"path","required":true,"description":"Mitigation ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/MitigationInput"}}}},"responses":{"200":{"description":"The mitigation.","content":{"application\/json":{"schema":{"type":"object"}}}},"404":{"$ref":"#\/components\/responses\/Error"},"422":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}},"delete":{"summary":"Delete a mitigation","operationId":"deleteMitigation","security":[{"apiKey":["registers:write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Forest ID","schema":{"type":"string"}},{"name":"mitigation","in":"path","required":true,"description":"Mitigation ID","schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted."},"404":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/forests\/{id}\/comments":{"get":{"summary":"List discussions","operationId":"listComments","security":[{"apiKey":["comments:read"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Forest ID","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"open, resolved or all (default).","schema":{"type":"string","enum":["open","resolved","all"]}}],"responses":{"200":{"description":"Threads with their replies and what each is about.","content":{"application\/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}},"post":{"summary":"Post a comment or reply","operationId":"createComment","security":[{"apiKey":["comments:write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Forest ID","schema":{"type":"string"}},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"description":"Posted as the key's creator when they can still edit the forest, otherwise as its owner. Give one of risk_id, element_id or connection_id to anchor a new discussion, or parent_id to reply.","requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["body"],"properties":{"body":{"type":"string"},"risk_id":{"type":"string"},"element_id":{"type":"string"},"connection_id":{"type":"string"},"parent_id":{"type":"string"}}}}}},"responses":{"201":{"description":"The comment.","content":{"application\/json":{"schema":{"type":"object"}}}},"422":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/forests\/{id}\/review":{"get":{"summary":"Review and approval state","operationId":"getReview","security":[{"apiKey":["reviews:read"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Forest ID","schema":{"type":"string"}}],"responses":{"200":{"description":"State, stages, the pending review and history.","content":{"application\/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}},"post":{"summary":"Submit for approval","operationId":"submitReview","security":[{"apiKey":["reviews:write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Forest ID","schema":{"type":"string"}},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"description":"Submitted by the key's creator when they can edit the model, else by its owner. Approvers get the usual emails; someone who can't open the model yet is invited as a read-only viewer.","requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"approvers":{"type":"array","items":{"type":"string"},"description":"User IDs or email addresses (without organization stages)."},"stages":{"type":"array","items":{"type":"array","items":{"type":"string"}},"description":"One list of approvers per organization stage, in order."},"note":{"type":"string"}}}}}},"responses":{"201":{"description":"The review.","content":{"application\/json":{"schema":{"type":"object"}}}},"422":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}},"delete":{"summary":"Cancel the pending review","operationId":"cancelReview","security":[{"apiKey":["reviews:write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Forest ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Cancelled.","content":{"application\/json":{"schema":{"type":"object"}}}},"422":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/forests\/{id}\/report.pdf":{"get":{"summary":"Forest PDF report","operationId":"report","security":[{"apiKey":["reports:read"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Forest ID","schema":{"type":"string"}},{"name":"title","in":"query","required":false,"description":"Cover title.","schema":{"type":"string"}},{"name":"classification","in":"query","required":false,"description":"Confidential, Internal or Public.","schema":{"type":"string"}},{"name":"version","in":"query","required":false,"description":"Version label.","schema":{"type":"string"}},{"name":"executive_notes","in":"query","required":false,"description":"Executive summary notes.","schema":{"type":"string"}}],"responses":{"200":{"description":"The PDF.","content":{"application\/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/forests\/{id}\/stix":{"get":{"summary":"STIX 2.1 export","operationId":"stix","security":[{"apiKey":["reports:read"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Forest ID","schema":{"type":"string"}}],"responses":{"200":{"description":"A STIX 2.1 bundle of the forest's attack trees.","content":{"application\/json":{"schema":{"type":"object"}}}},"422":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/me":{"get":{"summary":"The key itself","operationId":"me","description":"Needs no scope.","responses":{"200":{"description":"Name, prefix, organization, scopes, forest restriction, IP list, expiry and rate limits.","content":{"application\/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/search":{"get":{"summary":"Search","operationId":"search","security":[{"apiKey":["forests:read"]}],"parameters":[{"name":"q","in":"query","required":false,"description":"2 to 100 characters.","schema":{"type":"string"}}],"responses":{"200":{"description":"Matching forests, trees, elements, threats and goals in the forests the key reaches (not encrypted ones).","content":{"application\/json":{"schema":{"type":"object"}}}},"422":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/forests\/{id}\/risks.csv":{"get":{"summary":"Risk register as CSV","operationId":"risksCsv","security":[{"apiKey":["risks:read"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Forest ID","schema":{"type":"string"}}],"responses":{"200":{"description":"One row per risk.","content":{"text\/csv":{"schema":{"type":"string"}}}},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/forests\/{id}\/assets.csv":{"get":{"summary":"Asset register as CSV","operationId":"assetsCsv","security":[{"apiKey":["registers:read"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Forest ID","schema":{"type":"string"}}],"responses":{"200":{"description":"One row per asset.","content":{"text\/csv":{"schema":{"type":"string"}}}},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/forests\/{id}\/mitigations.csv":{"get":{"summary":"Mitigations as CSV","operationId":"mitigationsCsv","security":[{"apiKey":["registers:read"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Forest ID","schema":{"type":"string"}}],"responses":{"200":{"description":"One row per mitigation.","content":{"text\/csv":{"schema":{"type":"string"}}}},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/forests\/{id}\/risks\/{risk}\/tickets":{"post":{"summary":"Open a ticket for a risk","operationId":"createTicket","security":[{"apiKey":["risks:write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Forest ID","schema":{"type":"string"}},{"name":"risk","in":"path","required":true,"description":"Risk ID","schema":{"type":"string"}}],"description":"In each connected ticketing tool (Jira, Azure DevOps, ServiceNow, Linear) without an open ticket for this risk. The risk must be scored. High and critical risks get tickets automatically.","responses":{"201":{"description":"Ticket links; `meta.created` and any provider errors.","content":{"application\/json":{"schema":{"type":"object"}}}},"200":{"description":"Nothing new: every tool already has an open ticket.","content":{"application\/json":{"schema":{"type":"object"}}}},"409":{"$ref":"#\/components\/responses\/Error"},"422":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/forests\/{id}\/risk-matrix":{"get":{"summary":"The risk matrix a forest is scored on","operationId":"forestRiskMatrix","security":[{"apiKey":["forests:read"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Forest ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Likelihood and impact scales and severity bands.","content":{"application\/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/forests\/{id}\/snapshots":{"get":{"summary":"List backups","operationId":"listSnapshots","security":[{"apiKey":["forests:read"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Forest ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Manual, safety and approval backups, newest first.","content":{"application\/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}},"post":{"summary":"Back up a forest","operationId":"createSnapshot","security":[{"apiKey":["forests:write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Forest ID","schema":{"type":"string"}},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"description":"Restoring a backup needs a person's password, so it stays in the app.","requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"release_version":{"type":"string"}}}}}},"responses":{"201":{"description":"The backup.","content":{"application\/json":{"schema":{"type":"object"}}}},"422":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"}}}},"\/forests\/{id}\/comments\/{comment}\/resolve":{"post":{"summary":"Resolve a discussion","operationId":"resolveComment","security":[{"apiKey":["comments:write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Forest ID","schema":{"type":"string"}},{"name":"comment","in":"path","required":true,"description":"Discussion ID","schema":{"type":"string"}}],"responses":{"200":{"description":"The discussion.","content":{"application\/json":{"schema":{"type":"object"}}}},"404":{"$ref":"#\/components\/responses\/Error"},"422":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/forests\/{id}\/comments\/{comment}\/reopen":{"post":{"summary":"Reopen a discussion","operationId":"reopenComment","security":[{"apiKey":["comments:write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Forest ID","schema":{"type":"string"}},{"name":"comment","in":"path","required":true,"description":"Discussion ID","schema":{"type":"string"}}],"responses":{"200":{"description":"The discussion.","content":{"application\/json":{"schema":{"type":"object"}}}},"404":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/forests\/{id}\/members":{"get":{"summary":"Who can open a forest","operationId":"forestMembers","security":[{"apiKey":["members:read"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Forest ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Name, email, role, and whether access is direct or through groups.","content":{"application\/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/members":{"get":{"summary":"The organization's members","operationId":"members","security":[{"apiKey":["members:read"]}],"responses":{"200":{"description":"Name, email, organization role and custom role.","content":{"application\/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/forests\/{id}\/trees\/{tree}\/nodes":{"post":{"summary":"Add an element","operationId":"createNode","security":[{"apiKey":["diagrams:write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Forest ID","schema":{"type":"string"}},{"name":"tree","in":"path","required":true,"description":"Tree ID","schema":{"type":"string"}},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"description":"A DFD element (process, data_store, external_entity, trust_boundary or any palette type) or an attack-tree node (goal, leaf, or_gate, and_gate). Without x and y it is placed to the right of the others.","requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["type","label"],"properties":{"type":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"},"properties":{"type":"object"},"x":{"type":"number"},"y":{"type":"number"}}}}}},"responses":{"201":{"description":"The element.","content":{"application\/json":{"schema":{"type":"object"}}}},"422":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/forests\/{id}\/trees\/{tree}\/nodes\/{node}":{"patch":{"summary":"Change an element","operationId":"updateNode","security":[{"apiKey":["diagrams:write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Forest ID","schema":{"type":"string"}},{"name":"tree","in":"path","required":true,"description":"Tree ID","schema":{"type":"string"}},{"name":"node","in":"path","required":true,"description":"Element ID","schema":{"type":"string"}}],"description":"Properties you send are merged into the current ones.","requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"},"properties":{"type":"object"},"x":{"type":"number"},"y":{"type":"number"}}}}}},"responses":{"200":{"description":"The element.","content":{"application\/json":{"schema":{"type":"object"}}}},"404":{"$ref":"#\/components\/responses\/Error"},"422":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}},"delete":{"summary":"Delete an element and its connections","operationId":"deleteNode","security":[{"apiKey":["diagrams:write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Forest ID","schema":{"type":"string"}},{"name":"tree","in":"path","required":true,"description":"Tree ID","schema":{"type":"string"}},{"name":"node","in":"path","required":true,"description":"Element ID","schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted."},"404":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/forests\/{id}\/trees\/{tree}\/connections":{"post":{"summary":"Add a data flow or attack path","operationId":"createConnection","security":[{"apiKey":["diagrams:write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Forest ID","schema":{"type":"string"}},{"name":"tree","in":"path","required":true,"description":"Tree ID","schema":{"type":"string"}},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["from","to"],"properties":{"from":{"type":"string"},"to":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"properties":{"type":"object"}}}}}},"responses":{"201":{"description":"The connection.","content":{"application\/json":{"schema":{"type":"object"}}}},"422":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/forests\/{id}\/trees\/{tree}\/connections\/{edge}":{"patch":{"summary":"Change a connection","operationId":"updateConnection","security":[{"apiKey":["diagrams:write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Forest ID","schema":{"type":"string"}},{"name":"tree","in":"path","required":true,"description":"Tree ID","schema":{"type":"string"}},{"name":"edge","in":"path","required":true,"description":"Connection ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"type":{"type":"string"},"properties":{"type":"object"}}}}}},"responses":{"200":{"description":"The connection.","content":{"application\/json":{"schema":{"type":"object"}}}},"404":{"$ref":"#\/components\/responses\/Error"},"422":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}},"delete":{"summary":"Delete a connection","operationId":"deleteConnection","security":[{"apiKey":["diagrams:write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Forest ID","schema":{"type":"string"}},{"name":"tree","in":"path","required":true,"description":"Tree ID","schema":{"type":"string"}},{"name":"edge","in":"path","required":true,"description":"Connection ID","schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted."},"404":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/forests\/{id}\/trees\/{tree}\/suggestions":{"get":{"summary":"Threats suggested for a DFD","operationId":"suggestions","security":[{"apiKey":["forests:read"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Forest ID","schema":{"type":"string"}},{"name":"tree","in":"path","required":true,"description":"Tree ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Per element: dictionary, threat-library and rule threats, and whether each is already in an attack tree.","content":{"application\/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/forests\/{id}\/trees\/{tree}\/generate":{"post":{"summary":"Generate attack trees from a DFD","operationId":"generate","security":[{"apiKey":["diagrams:write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Forest ID","schema":{"type":"string"}},{"name":"tree","in":"path","required":true,"description":"Tree ID","schema":{"type":"string"}},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"description":"Without `selections`, every suggestion not yet in an attack tree is used.","requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"mode":{"type":"string","enum":["per_goal","single"]},"selections":{"type":"array","items":{"type":"object","properties":{"node_id":{"type":"string"},"threat_ids":{"type":"array","items":{"type":"string"}}}}}}}}}},"responses":{"201":{"description":"The generated attack trees.","content":{"application\/json":{"schema":{"type":"object"}}}},"422":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/threat-library":{"get":{"summary":"The organization's threat library","operationId":"listLibrary","security":[{"apiKey":["library:read"]}],"responses":{"200":{"description":"Threats; `meta` has element types and STRIDE categories.","content":{"application\/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}},"post":{"summary":"Add a threat to the library","operationId":"createLibraryThreat","security":[{"apiKey":["library:write"]}],"parameters":[{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["element_type","title","description"],"properties":{"element_type":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"stride_category":{"type":"string"},"mitre_techniques":{"type":"array"},"frameworks":{"type":"array"},"std_controls":{"type":"object"}}}}}},"responses":{"201":{"description":"The threat.","content":{"application\/json":{"schema":{"type":"object"}}}},"422":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/threat-library\/{threat}":{"patch":{"summary":"Change a library threat","operationId":"updateLibraryThreat","security":[{"apiKey":["library:write"]}],"parameters":[{"name":"threat","in":"path","required":true,"description":"Threat ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"stride_category":{"type":"string"}}}}}},"responses":{"200":{"description":"The threat.","content":{"application\/json":{"schema":{"type":"object"}}}},"404":{"$ref":"#\/components\/responses\/Error"},"422":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}},"delete":{"summary":"Delete a library threat","operationId":"deleteLibraryThreat","security":[{"apiKey":["library:write"]}],"parameters":[{"name":"threat","in":"path","required":true,"description":"Threat ID","schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted."},"404":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/frameworks":{"get":{"summary":"The organization's own frameworks","operationId":"listFrameworks","security":[{"apiKey":["library:read"]}],"parameters":[{"name":"include_archived","in":"query","required":false,"description":"Include archived frameworks.","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Frameworks with their categories and usage.","content":{"application\/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}},"post":{"summary":"Create a framework","operationId":"createFramework","security":[{"apiKey":["library:write"]}],"parameters":[{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["name","color","categories"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"color":{"type":"string"},"categories":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"}}}}}}}}},"responses":{"201":{"description":"The framework.","content":{"application\/json":{"schema":{"type":"object"}}}},"422":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/frameworks\/{framework}":{"patch":{"summary":"Change or archive a framework","operationId":"updateFramework","security":[{"apiKey":["library:write"]}],"parameters":[{"name":"framework","in":"path","required":true,"description":"Framework ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"color":{"type":"string"},"archived":{"type":"boolean"},"categories":{"type":"array"}}}}}},"responses":{"200":{"description":"The framework.","content":{"application\/json":{"schema":{"type":"object"}}}},"404":{"$ref":"#\/components\/responses\/Error"},"422":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}},"delete":{"summary":"Delete an unused framework","operationId":"deleteFramework","security":[{"apiKey":["library:write"]}],"parameters":[{"name":"framework","in":"path","required":true,"description":"Framework ID","schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted."},"404":{"$ref":"#\/components\/responses\/Error"},"422":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/risk-matrix":{"get":{"summary":"The organization's risk matrix","operationId":"riskMatrix","security":[{"apiKey":["library:read"]}],"responses":{"200":{"description":"Scales and severity bands.","content":{"application\/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/standards":{"get":{"summary":"Framework tags and standard controls","operationId":"standards","security":[{"apiKey":["library:read"]}],"responses":{"200":{"description":"What `frameworks` and `controls` accept.","content":{"application\/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/webhooks":{"get":{"summary":"List webhooks","operationId":"listWebhooks","security":[{"apiKey":["webhooks:manage"]}],"responses":{"200":{"description":"Endpoints; `meta.events` lists every event.","content":{"application\/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}},"post":{"summary":"Add a webhook","operationId":"createWebhook","security":[{"apiKey":["webhooks:manage"]}],"parameters":[{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"description":{"type":"string"},"active":{"type":"boolean"}}}}}},"responses":{"201":{"description":"The webhook with its signing `secret`, shown once.","content":{"application\/json":{"schema":{"type":"object"}}}},"422":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/webhooks\/{webhook}":{"patch":{"summary":"Change a webhook or rotate its secret","operationId":"updateWebhook","security":[{"apiKey":["webhooks:manage"]}],"parameters":[{"name":"webhook","in":"path","required":true,"description":"Webhook ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"events":{"type":"array"},"description":{"type":"string"},"active":{"type":"boolean"},"rotate_secret":{"type":"boolean"}}}}}},"responses":{"200":{"description":"The webhook (with `secret` when rotated).","content":{"application\/json":{"schema":{"type":"object"}}}},"404":{"$ref":"#\/components\/responses\/Error"},"422":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}},"delete":{"summary":"Delete a webhook","operationId":"deleteWebhook","security":[{"apiKey":["webhooks:manage"]}],"parameters":[{"name":"webhook","in":"path","required":true,"description":"Webhook ID","schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted."},"404":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/webhooks\/{webhook}\/test":{"post":{"summary":"Send a test event","operationId":"testWebhook","security":[{"apiKey":["webhooks:manage"]}],"parameters":[{"name":"webhook","in":"path","required":true,"description":"Webhook ID","schema":{"type":"string"}}],"responses":{"200":{"description":"How the delivery went.","content":{"application\/json":{"schema":{"type":"object"}}}},"404":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/webhooks\/{webhook}\/deliveries":{"get":{"summary":"Delivery log","operationId":"webhookDeliveries","security":[{"apiKey":["webhooks:manage"]}],"parameters":[{"name":"webhook","in":"path","required":true,"description":"Webhook ID","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"pending, delivered or failed.","schema":{"type":"string","enum":["pending","delivered","failed"]}},{"name":"limit","in":"query","required":false,"description":"Up to 100.","schema":{"type":"integer"}}],"responses":{"200":{"description":"The last 30 days, newest first, with each payload.","content":{"application\/json":{"schema":{"type":"object"}}}},"404":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"An organization API key (tt_\u2026). Scopes: forests:read, forests:write, risks:read, risks:write, registers:read, registers:write, comments:read, comments:write, members:read, reviews:read, reviews:write, reports:read, diagrams:write, webhooks:manage, library:read, library:write, import:write, portfolio:read, audit:read."}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"Repeat a POST safely: the same key and body within 24 hours replay the first response.","schema":{"type":"string","maxLength":255}}},"responses":{"Error":{"description":"An error.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"Forest":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"encrypted":{"type":"boolean"},"lock_label":{"type":["string","null"]},"review_state":{"type":["string","null"]},"approval_required":{"type":"boolean"},"updated_at":{"type":"string","format":"date-time"}}},"ForestList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/Forest"}},"next_cursor":{"type":["string","null"]}}},"ForestDetail":{"allOf":[{"$ref":"#\/components\/schemas\/Forest"},{"type":"object","properties":{"trees":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["dfd","attack_tree"]},"dfd_id":{"type":["string","null"]}}}},"risks":{"type":"object"},"coverage":{"type":"object"}}}]},"Risk":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"forest_id":{"type":"string"},"tree_id":{"type":"string"},"severity":{"type":["string","null"],"enum":["critical","high","medium","low",null]},"score":{"type":["integer","null"]},"status":{"type":"string","enum":["open","mitigated"]},"owner":{"type":["string","null"]},"treatments":{"type":"array","items":{"type":"string"}},"tickets":{"type":"integer"},"needs_review":{"type":"boolean"}}},"RiskList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/Risk"}},"total":{"type":"integer"},"next_cursor":{"type":["string","null"]}}},"Gate":{"type":"object","properties":{"data":{"type":"object","properties":{"result":{"type":"string","enum":["pass","fail"]},"reasons":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["open_risks_over_threshold","not_approved","needs_review"]},"message":{"type":"string"}}}},"counts":{"type":"object"}}}}},"AssetInput":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string","enum":["data","service","infrastructure","other"]},"description":{"type":"string"},"owner":{"type":"string"},"confidentiality":{"type":"integer"},"integrity":{"type":"integer"},"availability":{"type":"integer"},"classification":{"type":"string"},"element_ids":{"type":"array","items":{"type":"string"},"description":"DFD element IDs the asset sits on."}}},"MitigationInput":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"owner":{"type":"string"},"status":{"type":"string","enum":["planned","in_progress","implemented","verified","wont_do"]},"due_date":{"type":"string","format":"date"},"controls":{"type":"object"},"risk_ids":{"type":"array","items":{"type":"string"},"description":"Risks (attack-tree threats) it treats."}}},"Drift":{"type":"object","properties":{"data":{"type":"object","properties":{"in_sync":{"type":"boolean"},"added":{"type":"array"},"removed":{"type":"array"},"unchanged":{"type":"integer"}}}}}}}}