Your CI job needs to fail a build on open critical findings, or your own tooling needs the resource list. You should not be scraping a web page for that. The console is built on the same API you get here, so anything in this table works from a script.
Base path
Every route below sits under /api/v1 on your console host.
https://<your-console-host>/api/v1
Authentication
Send an API key as a bearer token.
# Read the findings your key can see.
curl -H "Authorization: Bearer $DWAAR_API_KEY" \
"https://<your-console-host>/api/v1/findings"
Keys look like dwc_<id>_<secret>. Create one under Settings › API, or for a service account under Settings › Members. See Service accounts and API keys.
The browser uses a session cookie instead. Anything else gets a 401. The /welcome routes are one exception: they serve the welcome screen of a first sign-in, before any session exists, and only answer the browser that signed in, for 15 minutes. The vendor portal routes are the other: they answer a vendor's browser, which holds the token of an assessment's private link.
Routes marked signed-in person only refuse every API key. Some need a person by nature: creating an API key or a service account key, anything that runs Dwaar AI, and the three steps of installing the GitHub App. A key cannot mint another key. That is deliberate. The rest need a permission that no key may carry, whatever its owner holds.
What a key can see
A route's permission is necessary, not sufficient. A key acts for its owner, so it never does more than the owner can do at the moment of the call, and it is also limited to the organizations you scoped it to.
When something exists but sits outside what you can see, expect not_found. Do not read that as proof it does not exist.
Errors
Errors share one shape.
{
"error": "forbidden",
"message": "A sentence you can show to a person",
"requestId": "the id to quote when you report a problem"
}
Branch on error, which is a stable code. Show message, which is written for people and can change. Troubleshooting lists the codes you are most likely to meet.
Pagination and filters
List routes differ, so read the response you get back rather than assuming one pattern. For filtered reads across findings, resources and components, GraphQL is the better tool: every list there is a cursor connection.
Routes
This table is the live API surface. A route that is not listed here is not available to you, even if a screen in the console suggests a related action.
Sign-in and session
| Method | Path | Required permission | What it does |
|---|
| GET | /auth/config | None (public) | Where to sign in (the sign-in service login URL) and whether email sign-in is on |
| GET | /auth/session | Any signed-in caller | Current session |
| POST | /auth/sign-in | None (public) | Sign in |
| POST | /auth/sign-out | Your own account | Sign out (returns the identity provider's logout URL) |
| POST | /auth/sign-up | None (public) | Sign up and create the first organization |
| POST | /events | Any signed-in caller | Console interactions for product analytics (ids and enums only) |
| GET | /me/access | Any signed-in caller | What the caller may do: tenant permissions and org-level grants |
| GET | /welcome | None (public) | The pending sign-in of a person with no tenant here, or several: who signed in and what they can do next (generic, other_domain, choose, no_access or create), decided again on every read |
| POST | /welcome/organization | None (public) | Create the organization of the email's domain (name, confirmAdmin: true) as a new tenant, with the signed-in person as its administrator; returns the /auth/finalize path to open. 409 domain_claimed, 422 domain_not_allowed, 502 upstream. Ends the pending sign-in |
| POST | /welcome/select | None (public) | Sign in to one of the pending sign-in's organizations (orgCode); returns the /auth/finalize path to open. Ends the pending sign-in |
| POST | /welcome/sign-out | None (public) | Drop the pending sign-in, if there is one, and return the identity provider's logout URL. It works after the pending sign-in has expired, so a person can always switch accounts |
Organizations
| Method | Path | Required permission | What it does |
|---|
| POST | /orgs | orgs:create | Create org |
| GET | /orgs | Any signed-in caller | Org tree |
| DELETE | /orgs/:id | orgs:delete | Delete org (must be empty) |
| PATCH | /orgs/:id | orgs:update | Rename or move org |
Members, groups, roles and service accounts
| Method | Path | Required permission | What it does |
|---|
| GET | /audit | audit:read | Audit log |
| GET | /audit/export | audit:export | Audit log as CSV (same filters as the list) |
| GET | /emails | emails:read | The emails Dwaar sent, newest first: recipient, subject, kind and delivery status, never the body (filter by status and kind) |
| POST | /groups | groups:create (signed-in person only) | Create group |
| GET | /groups | groups:read | List groups |
| DELETE | /groups/:id | groups:delete (signed-in person only) | Delete group |
| PATCH | /groups/:id | groups:update, or groups.members:update for its members (signed-in person only) | Change a group: name and description, role and organizations, or members |
| POST | /invites | members:invite (signed-in person only) | Invite by email (email, orgIds, roleId): one role on the organizations picked, through a group per organization. The email must be at the tenant's domain: 422 invite_domain_mismatch, 409 tenant_without_domain. delivery is email, or manual when no email went out |
| GET | /invites | members:read | List invites |
| DELETE | /invites/:id | members:invite (signed-in person only) | Revoke invite (kept, status revoked) and take back the sign-in it added |
| POST | /invites/:id/resend | members:invite (signed-in person only) | Resend invite: renews it and emails it again; delivery says whether it was emailed |
| GET | /members | members:read | List members |
| DELETE | /members/:id | members:remove (signed-in person only) | Remove member, with their sign-in to the tenant |
| PATCH | /members/:id | members:update, or groups.members:update for their groups (signed-in person only) | Suspend or reactivate a member, or set their groups |
| GET | /permissions | Any signed-in caller | Permission catalogue and API-key presets |
| POST | /roles | roles:create (signed-in person only) | Create a custom role (explicit permissions, no wildcards) |
| GET | /roles | roles:read | Built-in and custom roles |
| DELETE | /roles/:id | roles:delete (signed-in person only) | Delete a custom role no group uses |
| PATCH | /roles/:id | roles:update (signed-in person only) | Change a custom role |
| GET | /security | Any signed-in caller | Security settings; your sessions and sign-ins (everyone's with security:read) |
| PATCH | /security | security:update (signed-in person only) | Update security settings |
| DELETE | /security/sessions/:id | Your own session, or anyone's with sessions:revoke | Revoke a session |
| POST | /service-accounts | service_accounts:create (signed-in person only) | Create a service account |
| GET | /service-accounts | service_accounts:read | Service accounts |
| DELETE | /service-accounts/:id | service_accounts:delete (signed-in person only) | Delete a service account and its keys |
| PATCH | /service-accounts/:id | service_accounts:update (signed-in person only) | Change a service account |
| POST | /service-accounts/:id/keys | service_accounts:update (signed-in person only) | Create a key for a service account (secret shown once) |
| GET | /service-accounts/:id/keys | service_accounts:read | A service account's API keys |
| DELETE | /service-accounts/:id/keys/:keyId | service_accounts:update (signed-in person only) | Revoke a service account key |
Usage
| Method | Path | Required permission | What it does |
|---|
| GET | /settings/usage | billing:read | Usage today, this UTC month and on each of the last 30 days, with every limit's state (limits warn, never enforce) |
| PATCH | /settings/usage/limits | billing:update (signed-in person only) | Set usage limits (value null removes one); the limits not named stay as they are |
Resources and components
| Method | Path | Required permission | What it does |
|---|
| GET | /components | resources:read | Every component the current versions of the resources in scope use, one row per versionless component with its versions, licenses, resources and open findings (sort name, kind, resources, versions, findings) |
| GET | /components/:id | resources:read | One component across the resources in scope: versions in use, the resources and refs using it, open findings, links (404 when no resource in scope uses it) |
| GET | /components/counts | resources:read | Components in scope per group (the page's tabs) |
| GET | /resources | resources:read | List resources (filter by type, kind, connection, state, tested, severity, newest run status, product, tracked, lineage; sort name, type, kind, provider, createdAt, lastScanAt, findings) |
| GET | /resources/:id | resources:read | Resource |
| GET | /resources/:id/components | resources:read | Components of the resource's current snapshots, or of one run's snapshot (run): packages, crypto assets, AI components, packages receiving personal data (sort name, kind, version, findings) |
| GET | /resources/:id/documents/:documentId | resources:read | Download one of the resource's scan documents (SBOM, CBOM, AI-BOM, privacy data map, attestations) by its sha256, streamed from the results bucket |
| GET | /resources/:id/inventory | resources:read | What the scans found inside the resource: component counts per group, licenses, the newest run's documents, attestations and privacy data map; with run, all of it from that run (its snapshot and documents) |
| GET | /resources/:id/lineage | resources:read | Lineage around one resource: the links its scans found and the links people mapped |
| POST | /resources/:id/lineage | resources.lineage:update | Map a link by hand to the resource it is built from, runs, or ships to. 409 across organizations or when the other already feeds this one |
| DELETE | /resources/:id/lineage/:otherId | resources.lineage:update | Remove a link mapped by hand or approved from a suggestion. 409 when a scan found it |
| POST | /resources/:id/refs | resources:update | Track one more branch, tag or image tag (at most 5 beyond the defaults), or turn an excluded one back on |
| GET | /resources/:id/refs | resources:read | Tracked refs (branches, tags, image tags) and the snapshot each resolved to |
| DELETE | /resources/:id/refs/:refId | resources:update | Stop tracking a ref: a manual one is removed, a default or rule one is excluded |
| POST | /resources/:id/rescan | scans:run | Scan the resource's tracked refs now: unchanged snapshots get a rematch, new ones a full scan; force runs every scanner |
| GET | /resources/:id/versions | resources:read | A cloud workload's versions with the artifact versions each runs, or an artifact's versions with the workload versions running each |
| GET | /resources/:id/sbom | resources:read | The SBOM of the newest run with results (one platform of an image: platform, else the first); url is resourceDocument's path. Scans write CycloneDX: spdx is 404 until they write SPDX |
Products
| Method | Path | Required permission | What it does |
|---|
| GET | /products | products:read | List products with their roll-ups |
| POST | /products | products:create | Create a product |
| GET | /products/:id | products:read | One product |
| PATCH | /products/:id | products:update | Change a product |
| DELETE | /products/:id | products:delete | Delete a product; its resources stay and leave it |
| GET | /products/:id/lineage | products:read | The lineage graph over a product's resources |
| GET | /products/:id/vendors | products:read | The vendors a product depends on: how it uses each (service, software or both), what is known of their code, their SBOM's age and their open findings |
| POST | /resources/:id/products | resources:attach | Add a resource to a product; also needs products:update on the product's organization. 409 when the resource is not of that organization or one below it |
| DELETE | /resources/:id/products/:productId | resources:attach | Remove a resource from a product; products:update on the product's organization also allows it |
Vendors
| Method | Path | Required permission | What it does |
|---|
| GET | /resources/:id/vendor-link | resources:read | Which vendor a SaaS app belongs to and why, or for an app with none, the vendors its name suggests |
| PUT | /resources/:id/vendor-link | resources:update | Link a SaaS app to a vendor (vendorId or domain), which also needs resources:update on the vendor's organization; later discoveries keep the link, even over the app's own domain |
| DELETE | /resources/:id/vendor-link | resources:update | Unlink a SaaS app from its vendor: it stays its own vendor, even when its domain names one, until someone links it again |
| GET | /resources/:id/vendor-profile | resources:read | How a vendor is used: by each product as a service, software or both, the packages it supplies and where scans found them, and its SBOMs with their age |
| PUT | /resources/:id/vendor-profile | resources:attach | Set how each product uses the vendor and the packages it supplies; also needs products:update on the organization of every product added or removed |
| POST | /resources/vendor-sboms | resources:create | Upload an SBOM for a vendor (vendorId; multipart, at most 32 MiB), validated against its format before it is kept (422 invalid_document) and then read by a scan run |
| POST | /resources/vendors | resources:create | Onboard a vendor by its domain, with its category, tier, products and security contact; 409 vendor_exists when it is onboarded already (taking over a vendor that discovery found also needs resources:update, and adding products resources:attach and products:update) |
Vendor assessments
| Method | Path | Required permission | What it does |
|---|
| GET | /vendor-assessments | resources:read | Vendor assessments in scope, with where each stands and what it found (filter by vendor, status, tier and template) |
| POST | /vendor-assessments | resources.vendor:request_documents | Start an assessment of a vendor (vendorId) from a questionnaire and send it unless send is false; a sent one's response carries the private link's token once, and delivery is email, or link when you pass the link on yourself |
| GET | /vendor-assessments/:id | resources:read | One assessment: its questions, the vendor's answers and documents, and once submitted, the findings Dwaar proposes (never the link's token) |
| GET | /vendor-assessments/:id/documents/:documentId | resources.vendor:download_documents | Download a document the vendor uploaded, exactly as uploaded; every download is audited |
| PATCH | /vendor-assessments/:id/documents/:documentId | resources:update | Correct a document's validity dates, or mark it unreadable or readable again, until the assessment is completed; a submitted assessment's proposals are rebuilt |
| POST | /vendor-assessments/:id/review | resources:update | Decide a submitted assessment: complete files the proposals in accept as findings on the vendor, and return sends it back to the vendor with a note |
| POST | /vendor-assessments/:id/send | resources.vendor:request_documents | Issue a new private link, which stops the old one: a draft is sent, and a past due assessment reopens for 14 more days; the response carries the token once, with delivery as above |
| GET | /vendor-assessments/templates | resources:read | The questionnaires an assessment can use, with the tiers and categories each suits and the documents it asks for |
Vendor portal
The vendor answers an assessment on the vendor portal page, which calls these routes with the token of the assessment's private link in Authorization: VendorPortal <token>. They take no session and no API key. A missing, unknown, replaced or expired link, or an archived assessment, gets not_found.
| Method | Path | Required permission | What it does |
|---|
| GET | /vendor-portal | None (public) | The vendor's view of the assessment: who asks, the questions, the answers so far and the documents, never a score or a proposal |
| PUT | /vendor-portal | None (public) | Save the vendor's answers, a draft until they submit |
| POST | /vendor-portal/documents | None (public) | Upload a document (multipart, at most 32 MiB), optionally as evidence for one question; an SBOM, AI-BOM or VEX is validated against its format first (422 invalid_document) |
| DELETE | /vendor-portal/documents/:documentId | None (public) | Remove an uploaded document before submitting |
| POST | /vendor-portal/submit | None (public) | Submit the answers and documents for review; 422 while a required question is unanswered |
Findings and GraphQL
| Method | Path | Required permission | What it does |
|---|
| GET | /finding-configurations | findings:read | Scan Center › Finding Configurations: the categories of findings the data pipeline ignores, with the tenant's choice and how many current findings each ignores now (in the org scope) |
| PATCH | /finding-configurations/:id | findings.settings:update (signed-in person only) | Turn a category on or off for the tenant; each resource's findings follow when it is next scanned |
| GET | /finding-configurations/checks | findings:read | Scan Center › Configurations › Ignore Checks: the tenant's check settings (ignored, severity) and every Dwaar default ignored check, with how many current findings each has and ignores now (in the org scope); the tenant's rows newest first, then the defaults in code order |
| POST | /finding-configurations/checks | findings.settings:update (signed-in person only) | Change checks for the tenant: ignore or stop ignoring them (turning a Dwaar default off or back on) and set or clear their severity; applies at once to the current findings (an event each) and to every later ingest |
| GET | /findings | findings:read | List findings: a cursor page of lifecycle rows (order severity / first_seen / last_seen, first ≤ 200, after = endCursor; filter by resource, connection, resource type, lifecycle, …). The console reads them over graphql |
| GET | /findings/:id | findings:read | Finding (the lifecycle row; observations and events are on graphql) |
| POST | /findings/:id/comments | findings:update | Comment on a finding (body, at most 4,000 characters); comments are never edited or deleted, and the audit log keeps only the length |
| GET | /findings/:id/recommendation | findings:read | How to fix the finding: { findingId, summary, steps[], prompt }. prompt is text for a coding agent with the finding's facts, the steps and its id; it never holds the scanner's free text or evidence, and its values are cleaned of control characters and clipped to 300 characters |
| GET | /findings/:id/history | findings:read | A finding's events newest first, each with who made it, through what (console, mcp, api, pipeline), the API key and the reason; comments included |
| PUT | /findings/:id/severity | findings:update | Set or clear (null) the tenant's severity override, with a required reason |
| DELETE | /findings/:id/waiver | findings:update | Revoke the active waiver, with a required reason |
| POST | /findings/:id/waiver | findings:update | Waive a finding: accepted risk or false positive, with a reason and an optional expiry (replaces an active waiver) |
| GET | /findings/checks | findings:read | The checks (rule ids) behind the current findings in scope, with their open and ignored counts, the tenant's severity and whether Dwaar ignores them by default: the options of the Findings page's Check filter and of Scan Center › Configurations › Ignore Checks |
| GET | /findings/counts | findings:read | Counts by type, effective severity, effective status and currency (sum the cells you need) |
| GET | /findings/decisions | findings:read | Findings › Decisions: waivers, revoked waivers, severity changes, ignores and comments in the org scope, newest first, with totals per kind and per way in; filter by kind, via, actor, resource, resource type, finding, since, until and search text |
| GET | /findings/decisions/export | findings:export | The decisions the filters select as CSV (at most 50,000 rows); the export is audited |
| GET | /findings/export | findings:export | Findings the filters select as CSV (same filters as the list, worst first, at most 50,000 rows); the export is audited before the first row |
| POST | /graphql | findings:read | Read-only GraphQL (findings, resources, components, vulnerabilities). Depth ≤ 6, complexity budget, first ≤ 200, APQ supported. An API key's call is charged in query units |
Query
| Method | Path | Required permission | What it does |
|---|
| GET | /query/samples | Any signed-in caller | Suggested questions, each with its query |
| GET | /query/usage | query:run | This UTC month's query units against the monthly limit (limits warn, never enforce) |
| POST | /query/check | query:run | Validate and price a query; reads nothing and charges nothing. A query that cannot run is an answer (valid false, with the message, line and column), not an error |
| POST | /query/build | query:run and ai:use (signed-in person only) | Turn a question into a validated query, a clarifying question or the reason there is none. Charges no query units; the model's calls are AI usage. Takes the same ai_ errors as a Dwaar AI run |
| POST | /query/run | query:run | Run one query under the caller's access and organizations; returns the rows and the units quoted and charged. size and after page a query with one top level list. 400 invalid_query, 413 query_result_too_large, 429 query_busy, 504 query_timeout |
| GET | /query/history | Your own account | The caller's own queries, newest first |
| PATCH | /query/history/:id | Your own account | Star or archive the caller's own entry |
| DELETE | /query/history/:id | Your own account | Delete the caller's own entry; the units it spent stay counted |
Search
| Method | Path | Required permission | What it does |
|---|
| GET | /search | Any signed-in caller | Search for a term (q) among what you may read in the org scope: up to 8 resources, 5 connections and, for 3 letters or more, 8 findings |
Scans, scanners and discovery
| Method | Path | Required permission | What it does |
|---|
| GET | /discovery/jobs | discovery:read | Discovery queue and history: running first, then queued by position, then newest |
| POST | /discovery/jobs | discovery:run | Discover one connection now; the job queues scans for new and changed resources |
| GET | /discovery/jobs/:id | discovery:read | One discovery job |
| POST | /discovery/jobs/:id/cancel | discovery:cancel | Cancel a queued or running discovery (scans it already queued stay) |
| GET | /discovery/schedules | discovery:read | Upcoming discovery per connection, soonest first |
| POST | /scanner-requests | Any signed-in caller | Request a scanner for a category |
| GET | /scanner-requests | scanners:read | Scanner requests |
| GET | /scanners | scanners:read | Scanners by resource and category |
| PATCH | /scanners/:id | scanners:update | Turn a category on or off for the tenant's next scans (version and scanner only where the scan plane offers a choice) |
| GET | /scans | scans:read | Queue and history |
| DELETE | /scans/:id | scans:delete | Delete one-time scan results |
| GET | /scans/:id | scans:read | Scan |
| PATCH | /scans/:id | scans:update | Change priority, move in queue, keep results |
| POST | /scans/:id/cancel | scans:cancel | Cancel |
| POST | /scans/:id/retry | scans:run | Retry a failed scan |
| POST | /scans/one-time | scans:run | Scan one resource once (no schedule) |
Outposts
| Method | Path | Required permission | What it does |
|---|
| GET | /outposts | outposts:read | Your outposts, with their status from their heartbeats, their live jobs and the connections bound to them |
| PATCH | /outposts/:id | outposts:update (signed-in person only) | Change an outpost's Scan concurrency (maxJobs) and Memory overcommit (memoryOvercommit); it applies them at its next heartbeat, unless they are set on its host |
| GET | /outposts/:id/jobs | outposts:read | An outpost's jobs, newest first: what each runs, its lease and its attempt (filter by status) |
| POST | /outposts/:id/revoke | outposts:delete (signed-in person only) | Revoke an outpost: its credential stops working at once, and it cannot come back |
| GET | /outposts/capacity-figures | outposts:read | What each kind of scan takes of a host (containers, limits, peak memory) and the arithmetic an outpost admits it by |
| POST | /outposts/capacity-recommendation | outposts:create and ai:use (signed-in person only) | Ask Dwaar AI for an outpost's Scan concurrency and Memory overcommit from the host and workload you describe; changes nothing, and takes the same ai_ errors as a Dwaar AI run |
| GET | /outposts/deploy/ecs | outposts:read | The CloudFormation template and its parameters, to deploy an outpost on AWS ECS |
| GET | /outposts/deploy/host | outposts:read | The files and commands to deploy an outpost on a Linux host, with Docker or with Compose |
| POST | /outposts/enrollment-tokens | outposts:create (signed-in person only) | Create a one-time enrollment token with the name, deployment and starting capacity of the outpost it enrolls; shown once, valid for an hour |
| GET | /outposts/enrollment-tokens | outposts:read | The enrollment tokens that can still enroll an outpost, soonest to expire first, never the token itself |
| DELETE | /outposts/enrollment-tokens/:id | outposts:create (signed-in person only) | Cancel an enrollment token that can still enroll; 409 when it was used, cancelled or has expired |
The outpost itself calls your console on its own API under /api/outpost/v1, which takes only an outpost's credential, never a session or an API key, so it is not for scripts: see How an outpost works.
Integrations
| Method | Path | Required permission | What it does |
|---|
| GET | /integrations/connections | integrations:read | Connections (optionally by provider) |
| GET | /integrations/connections/:id | integrations:read | Connection |
| DELETE | /integrations/connections/:id | integrations:delete (signed-in person only) | Disconnect |
| PATCH | /integrations/connections/:id | integrations:update (signed-in person only) | Save settings |
| GET | /integrations/connections/:id/activity | integrations:read | Activity log (for a chat or webhook connection, also each notification delivery, retry and failure) |
| POST | /integrations/connections/:id/scan-once | scans:run | Ad-hoc scan of one resource from this connection |
| POST | /integrations/connections/:id/sync | integrations:sync | Run discovery now |
| POST | /integrations/connections/:id/test | integrations:test | Test connection and preview discovery |
| POST | /integrations/connections/:id/test-message | integrations:test | Send a sample notification through a Slack, Teams or webhook connection now. 502 delivery_failed with the receiver's host and status when it refuses |
| POST | /integrations/connections/:id/test-credentials | integrations:update (signed-in person only) | Test a credential change without saving it |
| GET | /integrations/connections/:id/vault-access | integrations:read | Vault access log: every read Dwaar made of this vault |
| GET | /integrations/providers | Any signed-in caller | Catalog |
| GET | /integrations/providers/:id | Any signed-in caller | Provider |
| POST | /integrations/providers/:id/app-install | integrations:create (signed-in person only) | Start the browser flow that installs Dwaar's GitHub App (step 1 of 3): keeps the name and the permissions ticked, and returns GitHub's install URL |
| POST | /integrations/app-installs/return | integrations:create (signed-in person only) | Step 2, when GitHub sends the browser back from the install: stores the installation and returns GitHub's authorize URL, or pending when an owner of the GitHub account must approve the install first |
| POST | /integrations/app-installs/complete | integrations:create (signed-in person only) | Step 3, when GitHub sends the browser back from authorizing: verifies that the installation is yours and that you are an owner of its GitHub account, then creates the connection and queues its first discovery |
| POST | /integrations/providers/:id/connections | integrations:create (signed-in person only) | Add a connection with its discovery settings (credentials tested first; refused when they fail) |
| GET | /integrations/providers/:id/setup | Any signed-in caller | Values the connect form shows first (AWS external id) |
| POST | /integrations/providers/:id/test | integrations:create (signed-in person only) | Test a new connection's credentials without saving, and preview what discovery would list |
| GET | /integrations/routing | integrations:read | Notification routing rules of the organizations in scope |
| POST | /integrations/routing | integrations.routing:update | Send one event kind to a Slack, Teams or webhook connection, optionally narrowed by organizations, products and a minimum severity |
| PATCH | /integrations/routing/:id | integrations.routing:update | Edit, enable, disable or reorder (move: up | down) a rule |
| DELETE | /integrations/routing/:id | integrations.routing:update | Delete a rule |
Guard Center
Assurance policies, their events and exceptions. The API calls an event a violation, so its paths and fields say violations. See Assurance policies.
| Method | Path | Required permission | What it does |
|---|
| GET | /guard/policies | guard.policies:read | Policies, each with its owner organization, revision, mode, scope, controls, impact and compliance |
| POST | /guard/policies | guard.policies:create (guard.policies:enforce to create in enforce) | Create an assurance policy in an organization (orgId). 422 runtime_policies_unavailable for a runtime policy |
| GET | /guard/policies/:id | guard.policies:read | One policy |
| PATCH | /guard/policies/:id | guard.policies:update (guard.policies:enforce for every way into enforce) | Edit mode, scope or controls; a change of the policy's rules is a new revision |
| DELETE | /guard/policies/:id | guard.policies:delete | Delete a policy. 409 default_policy for a default one: archive it instead |
| GET | /guard/controls | guard.policies:read | The controls a policy can use, with their parameters and checkpoints |
| GET | /guard/attributes | guard.policies:read | Scope attributes per resource type |
| GET | /guard/violations | guard.policies:read | Events in scope, open first (filter by policy, resource, product, connection, status, severity, control, type, excepted) |
| GET | /guard/violations/:id | guard.policies:read | One event with its evidence |
| GET | /guard/compliance | guard.policies:read | Compliance of the organizations in scope, a product or a resource: policies a resource is non-compliant with, compliant, non-compliant and not evaluated resources (passing, failing, unknown), recent events (recent: opened or reopened in the last 24 hours), open events by severity and overdue events |
| GET | /guard/exceptions | guard.exceptions:read | Exceptions in scope |
| POST | /guard/exceptions | guard.exceptions:create | Request an exception for an event (violationId), or for a policy (and optionally one control) on a resource or product, ending within 365 days. It waits for approval |
| PATCH | /guard/exceptions/:id | guard.exceptions:update (guard.exceptions:approve to approve, reject or revoke) | Approve (status: active), reject, revoke, extend or change the reason. 409 self_approval for your own request |
Notifications
| Method | Path | Required permission | What it does |
|---|
| GET | /notifications | Your own account | Your notification feed, filtered by what you can read (unread=true for unread only) |
| PATCH | /notifications/:id | Your own account | Mark one notification read or unread |
| POST | /notifications/read-all | Your own account | Mark everything read |
| GET | /settings/notifications | Your own account | Your notification preferences, per event kind: in the feed and by email |
| PUT | /settings/notifications | Your own account | Change your notification preferences |
Home and installation
| Method | Path | Required permission | What it does |
|---|
| GET | /overview | Any signed-in caller | Home: grades, funnel, findings, coverage, next actions, each under your own read permission |
| GET | /install | Any signed-in caller | Installable components and snippets |
Archive, restore and delete
Products, resources, scans, policies, exceptions, connections and vendor assessments are archived, restored and deleted through these three routes.
| Method | Path | Required permission | What it does |
|---|
| DELETE | /records/:kind/:id | The kind's delete permission | Delete it for good |
| POST | /records/:kind/:id/archive | The kind's update permission | Archive it: hidden from lists until it is restored |
| POST | /records/:kind/:id/restore | The kind's update permission | Restore it from the archive |
:kind is one of these, and the permission counts on the organization that owns it:
| Kind | Archive and restore | Delete |
|---|
product | products:update | products:delete |
resource | resources:update | resources:delete |
scan | scans:update | scans:delete |
policy | guard.policies:update | guard.policies:delete |
exception | guard.exceptions:update | guard.exceptions:update |
connection | integrations:update (signed-in person only) | integrations:delete (signed-in person only) |
assessment, a vendor assessment | resources:update | resources:delete |
Some deletes are refused with a 409: a scan that is not a finished one-time scan; a default policy; a resource with findings, with a scan running or that a connection still lists; and a connection that other connections read their credentials from. Its message says what to do instead, usually archive. Archiving an assessment also revokes its private link, and restoring one gets a 409 while its vendor has another open assessment.
API keys
| Method | Path | Required permission | What it does |
|---|
| GET | /settings/api-keys | Your own account | API keys and guard tokens |
| POST | /settings/api-keys | Your own account (signed-in person only) | Create key (secret shown once) |
| DELETE | /settings/api-keys/:id | Your own key, or anyone's with api_keys:revoke | Revoke key |
Dwaar AI
| Method | Path | Required permission | What it does |
|---|
| POST | /ai/runs | ai:use (signed-in person only) | Summarise, explain or answer a question (mode ask, with the thread's last turns as history) about what the caller can see: the findings list, a finding, a resource or the workspace; streams meta, delta… and done (or error) as text/event-stream. Before the first frame the JSON envelope carries ai_disabled, ai_not_configured, ai_tier_unavailable, ai_budget_reached, ai_scope_empty (409), ai_context_too_large (413), ai_rate_limited (429) or ai_upstream_failed (502); 400 validation when the mode, surface and scope keys do not match (contracts §2b); 404 when the finding or resource is not visible. A run the caller abandons ends with errorCode client_closed |
| GET | /ai/runs | ai.settings:read | Recent Dwaar AI runs, newest first (Settings › AI › Recent activity) |
| POST | /ai/runs/:id/feedback | ai:use (signed-in person only) | Helpful or not, on the caller's own run |
| GET | /ai/status | ai:use (signed-in person only) | What a member needs to show the Dwaar AI pane: on or off, configured, default tier, budget state; never a credential or a model id in managed mode |
| POST | /mapping-suggestions | ai:use (signed-in person only) | Ask for lineage links, resources to add to a product and new products, from a product, a resource, the workspace or untracked resources; replaces that place's pending suggestions. 409 ai_scope_empty when there is too little to map |
| GET | /mapping-suggestions | resources:read | Suggestions of one place, strongest first (surface, anchorId, status; pending when omitted) |
| POST | /mapping-suggestions/:id/review | resources.lineage:update, resources:attach or products:create, by the suggestion's kind | Approve, reject or restore a suggestion. Approving applies it under the caller's own permissions. 409 when it was already decided or a resource it names was archived |
| GET | /settings/ai | ai.settings:read | Dwaar AI settings: mode, the four tier bindings, defaults, budget |
| PATCH | /settings/ai | ai.settings:update (signed-in person only) | Change Dwaar AI settings; the fields not named stay as they are (a byok tier needs a tested credential) |
| GET | /settings/ai/providers | ai.settings:read | Providers a tenant may bring a key for: auth fields and curated models |
Try this next
Create a key with the Read only (MCP) preset and call GET /findings/counts. If that works, you have everything you need to wire a dashboard or a CI gate. Then read GraphQL to ask for exactly the fields you want.