Skip to main content

REST API

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​

MethodPathRequired permissionWhat it does
GET/auth/configNone (public)Where to sign in (the sign-in service login URL) and whether email sign-in is on
GET/auth/sessionAny signed-in callerCurrent session
POST/auth/sign-inNone (public)Sign in
POST/auth/sign-outYour own accountSign out (returns the identity provider's logout URL)
POST/auth/sign-upNone (public)Sign up and create the first organization
POST/eventsAny signed-in callerConsole interactions for product analytics (ids and enums only)
GET/me/accessAny signed-in callerWhat the caller may do: tenant permissions and org-level grants
GET/welcomeNone (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/organizationNone (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/selectNone (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-outNone (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​

MethodPathRequired permissionWhat it does
POST/orgsorgs:createCreate org
GET/orgsAny signed-in callerOrg tree
DELETE/orgs/:idorgs:deleteDelete org (must be empty)
PATCH/orgs/:idorgs:updateRename or move org

Members, groups, roles and service accounts​

MethodPathRequired permissionWhat it does
GET/auditaudit:readAudit log
GET/audit/exportaudit:exportAudit log as CSV (same filters as the list)
GET/emailsemails:readThe emails Dwaar sent, newest first: recipient, subject, kind and delivery status, never the body (filter by status and kind)
POST/groupsgroups:create (signed-in person only)Create group
GET/groupsgroups:readList groups
DELETE/groups/:idgroups:delete (signed-in person only)Delete group
PATCH/groups/:idgroups:update, or groups.members:update for its members (signed-in person only)Change a group: name and description, role and organizations, or members
POST/invitesmembers: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/invitesmembers:readList invites
DELETE/invites/:idmembers:invite (signed-in person only)Revoke invite (kept, status revoked) and take back the sign-in it added
POST/invites/:id/resendmembers:invite (signed-in person only)Resend invite: renews it and emails it again; delivery says whether it was emailed
GET/membersmembers:readList members
DELETE/members/:idmembers:remove (signed-in person only)Remove member, with their sign-in to the tenant
PATCH/members/:idmembers:update, or groups.members:update for their groups (signed-in person only)Suspend or reactivate a member, or set their groups
GET/permissionsAny signed-in callerPermission catalogue and API-key presets
POST/rolesroles:create (signed-in person only)Create a custom role (explicit permissions, no wildcards)
GET/rolesroles:readBuilt-in and custom roles
DELETE/roles/:idroles:delete (signed-in person only)Delete a custom role no group uses
PATCH/roles/:idroles:update (signed-in person only)Change a custom role
GET/securityAny signed-in callerSecurity settings; your sessions and sign-ins (everyone's with security:read)
PATCH/securitysecurity:update (signed-in person only)Update security settings
DELETE/security/sessions/:idYour own session, or anyone's with sessions:revokeRevoke a session
POST/service-accountsservice_accounts:create (signed-in person only)Create a service account
GET/service-accountsservice_accounts:readService accounts
DELETE/service-accounts/:idservice_accounts:delete (signed-in person only)Delete a service account and its keys
PATCH/service-accounts/:idservice_accounts:update (signed-in person only)Change a service account
POST/service-accounts/:id/keysservice_accounts:update (signed-in person only)Create a key for a service account (secret shown once)
GET/service-accounts/:id/keysservice_accounts:readA service account's API keys
DELETE/service-accounts/:id/keys/:keyIdservice_accounts:update (signed-in person only)Revoke a service account key

Usage​

MethodPathRequired permissionWhat it does
GET/settings/usagebilling:readUsage today, this UTC month and on each of the last 30 days, with every limit's state (limits warn, never enforce)
PATCH/settings/usage/limitsbilling:update (signed-in person only)Set usage limits (value null removes one); the limits not named stay as they are

Resources and components​

MethodPathRequired permissionWhat it does
GET/componentsresources:readEvery 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/:idresources:readOne 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/countsresources:readComponents in scope per group (the page's tabs)
GET/resourcesresources:readList 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/:idresources:readResource
GET/resources/:id/componentsresources:readComponents 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/:documentIdresources:readDownload 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/inventoryresources:readWhat 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/lineageresources:readLineage around one resource: the links its scans found and the links people mapped
POST/resources/:id/lineageresources.lineage:updateMap 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/:otherIdresources.lineage:updateRemove a link mapped by hand or approved from a suggestion. 409 when a scan found it
POST/resources/:id/refsresources:updateTrack one more branch, tag or image tag (at most 5 beyond the defaults), or turn an excluded one back on
GET/resources/:id/refsresources:readTracked refs (branches, tags, image tags) and the snapshot each resolved to
DELETE/resources/:id/refs/:refIdresources:updateStop tracking a ref: a manual one is removed, a default or rule one is excluded
POST/resources/:id/rescanscans:runScan the resource's tracked refs now: unchanged snapshots get a rematch, new ones a full scan; force runs every scanner
GET/resources/:id/versionsresources:readA cloud workload's versions with the artifact versions each runs, or an artifact's versions with the workload versions running each
GET/resources/:id/sbomresources:readThe 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​

MethodPathRequired permissionWhat it does
GET/productsproducts:readList products with their roll-ups
POST/productsproducts:createCreate a product
GET/products/:idproducts:readOne product
PATCH/products/:idproducts:updateChange a product
DELETE/products/:idproducts:deleteDelete a product; its resources stay and leave it
GET/products/:id/lineageproducts:readThe lineage graph over a product's resources
GET/products/:id/vendorsproducts:readThe 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/productsresources:attachAdd 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/:productIdresources:attachRemove a resource from a product; products:update on the product's organization also allows it

Vendors​

MethodPathRequired permissionWhat it does
GET/resources/:id/vendor-linkresources:readWhich vendor a SaaS app belongs to and why, or for an app with none, the vendors its name suggests
PUT/resources/:id/vendor-linkresources:updateLink 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-linkresources:updateUnlink 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-profileresources:readHow 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-profileresources:attachSet 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-sbomsresources:createUpload 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/vendorsresources:createOnboard 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​

MethodPathRequired permissionWhat it does
GET/vendor-assessmentsresources:readVendor assessments in scope, with where each stands and what it found (filter by vendor, status, tier and template)
POST/vendor-assessmentsresources.vendor:request_documentsStart 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/:idresources:readOne 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/:documentIdresources.vendor:download_documentsDownload a document the vendor uploaded, exactly as uploaded; every download is audited
PATCH/vendor-assessments/:id/documents/:documentIdresources:updateCorrect 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/reviewresources:updateDecide 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/sendresources.vendor:request_documentsIssue 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/templatesresources:readThe 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.

MethodPathRequired permissionWhat it does
GET/vendor-portalNone (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-portalNone (public)Save the vendor's answers, a draft until they submit
POST/vendor-portal/documentsNone (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/:documentIdNone (public)Remove an uploaded document before submitting
POST/vendor-portal/submitNone (public)Submit the answers and documents for review; 422 while a required question is unanswered

Findings and GraphQL​

MethodPathRequired permissionWhat it does
GET/finding-configurationsfindings:readScan 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/:idfindings.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/checksfindings:readScan 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/checksfindings.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/findingsfindings:readList 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/:idfindings:readFinding (the lifecycle row; observations and events are on graphql)
POST/findings/:id/commentsfindings:updateComment 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/recommendationfindings:readHow 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/historyfindings:readA 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/severityfindings:updateSet or clear (null) the tenant's severity override, with a required reason
DELETE/findings/:id/waiverfindings:updateRevoke the active waiver, with a required reason
POST/findings/:id/waiverfindings:updateWaive a finding: accepted risk or false positive, with a reason and an optional expiry (replaces an active waiver)
GET/findings/checksfindings:readThe 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/countsfindings:readCounts by type, effective severity, effective status and currency (sum the cells you need)
GET/findings/decisionsfindings:readFindings › 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/exportfindings:exportThe decisions the filters select as CSV (at most 50,000 rows); the export is audited
GET/findings/exportfindings:exportFindings 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/graphqlfindings:readRead-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​

MethodPathRequired permissionWhat it does
GET/query/samplesAny signed-in callerSuggested questions, each with its query
GET/query/usagequery:runThis UTC month's query units against the monthly limit (limits warn, never enforce)
POST/query/checkquery:runValidate 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/buildquery: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/runquery:runRun 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/historyYour own accountThe caller's own queries, newest first
PATCH/query/history/:idYour own accountStar or archive the caller's own entry
DELETE/query/history/:idYour own accountDelete the caller's own entry; the units it spent stay counted
MethodPathRequired permissionWhat it does
GET/searchAny signed-in callerSearch 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​

MethodPathRequired permissionWhat it does
GET/discovery/jobsdiscovery:readDiscovery queue and history: running first, then queued by position, then newest
POST/discovery/jobsdiscovery:runDiscover one connection now; the job queues scans for new and changed resources
GET/discovery/jobs/:iddiscovery:readOne discovery job
POST/discovery/jobs/:id/canceldiscovery:cancelCancel a queued or running discovery (scans it already queued stay)
GET/discovery/schedulesdiscovery:readUpcoming discovery per connection, soonest first
POST/scanner-requestsAny signed-in callerRequest a scanner for a category
GET/scanner-requestsscanners:readScanner requests
GET/scannersscanners:readScanners by resource and category
PATCH/scanners/:idscanners:updateTurn a category on or off for the tenant's next scans (version and scanner only where the scan plane offers a choice)
GET/scansscans:readQueue and history
DELETE/scans/:idscans:deleteDelete one-time scan results
GET/scans/:idscans:readScan
PATCH/scans/:idscans:updateChange priority, move in queue, keep results
POST/scans/:id/cancelscans:cancelCancel
POST/scans/:id/retryscans:runRetry a failed scan
POST/scans/one-timescans:runScan one resource once (no schedule)

Outposts​

MethodPathRequired permissionWhat it does
GET/outpostsoutposts:readYour outposts, with their status from their heartbeats, their live jobs and the connections bound to them
PATCH/outposts/:idoutposts: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/jobsoutposts:readAn outpost's jobs, newest first: what each runs, its lease and its attempt (filter by status)
POST/outposts/:id/revokeoutposts:delete (signed-in person only)Revoke an outpost: its credential stops working at once, and it cannot come back
GET/outposts/capacity-figuresoutposts:readWhat each kind of scan takes of a host (containers, limits, peak memory) and the arithmetic an outpost admits it by
POST/outposts/capacity-recommendationoutposts: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/ecsoutposts:readThe CloudFormation template and its parameters, to deploy an outpost on AWS ECS
GET/outposts/deploy/hostoutposts:readThe files and commands to deploy an outpost on a Linux host, with Docker or with Compose
POST/outposts/enrollment-tokensoutposts: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-tokensoutposts:readThe enrollment tokens that can still enroll an outpost, soonest to expire first, never the token itself
DELETE/outposts/enrollment-tokens/:idoutposts: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​

MethodPathRequired permissionWhat it does
GET/integrations/connectionsintegrations:readConnections (optionally by provider)
GET/integrations/connections/:idintegrations:readConnection
DELETE/integrations/connections/:idintegrations:delete (signed-in person only)Disconnect
PATCH/integrations/connections/:idintegrations:update (signed-in person only)Save settings
GET/integrations/connections/:id/activityintegrations:readActivity log (for a chat or webhook connection, also each notification delivery, retry and failure)
POST/integrations/connections/:id/scan-oncescans:runAd-hoc scan of one resource from this connection
POST/integrations/connections/:id/syncintegrations:syncRun discovery now
POST/integrations/connections/:id/testintegrations:testTest connection and preview discovery
POST/integrations/connections/:id/test-messageintegrations:testSend 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-credentialsintegrations:update (signed-in person only)Test a credential change without saving it
GET/integrations/connections/:id/vault-accessintegrations:readVault access log: every read Dwaar made of this vault
GET/integrations/providersAny signed-in callerCatalog
GET/integrations/providers/:idAny signed-in callerProvider
POST/integrations/providers/:id/app-installintegrations: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/returnintegrations: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/completeintegrations: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/connectionsintegrations:create (signed-in person only)Add a connection with its discovery settings (credentials tested first; refused when they fail)
GET/integrations/providers/:id/setupAny signed-in callerValues the connect form shows first (AWS external id)
POST/integrations/providers/:id/testintegrations:create (signed-in person only)Test a new connection's credentials without saving, and preview what discovery would list
GET/integrations/routingintegrations:readNotification routing rules of the organizations in scope
POST/integrations/routingintegrations.routing:updateSend one event kind to a Slack, Teams or webhook connection, optionally narrowed by organizations, products and a minimum severity
PATCH/integrations/routing/:idintegrations.routing:updateEdit, enable, disable or reorder (move: up | down) a rule
DELETE/integrations/routing/:idintegrations.routing:updateDelete 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.

MethodPathRequired permissionWhat it does
GET/guard/policiesguard.policies:readPolicies, each with its owner organization, revision, mode, scope, controls, impact and compliance
POST/guard/policiesguard.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/:idguard.policies:readOne policy
PATCH/guard/policies/:idguard.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/:idguard.policies:deleteDelete a policy. 409 default_policy for a default one: archive it instead
GET/guard/controlsguard.policies:readThe controls a policy can use, with their parameters and checkpoints
GET/guard/attributesguard.policies:readScope attributes per resource type
GET/guard/violationsguard.policies:readEvents in scope, open first (filter by policy, resource, product, connection, status, severity, control, type, excepted)
GET/guard/violations/:idguard.policies:readOne event with its evidence
GET/guard/complianceguard.policies:readCompliance 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/exceptionsguard.exceptions:readExceptions in scope
POST/guard/exceptionsguard.exceptions:createRequest 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/:idguard.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​

MethodPathRequired permissionWhat it does
GET/notificationsYour own accountYour notification feed, filtered by what you can read (unread=true for unread only)
PATCH/notifications/:idYour own accountMark one notification read or unread
POST/notifications/read-allYour own accountMark everything read
GET/settings/notificationsYour own accountYour notification preferences, per event kind: in the feed and by email
PUT/settings/notificationsYour own accountChange your notification preferences

Home and installation​

MethodPathRequired permissionWhat it does
GET/overviewAny signed-in callerHome: grades, funnel, findings, coverage, next actions, each under your own read permission
GET/installAny signed-in callerInstallable 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.

MethodPathRequired permissionWhat it does
DELETE/records/:kind/:idThe kind's delete permissionDelete it for good
POST/records/:kind/:id/archiveThe kind's update permissionArchive it: hidden from lists until it is restored
POST/records/:kind/:id/restoreThe kind's update permissionRestore it from the archive

:kind is one of these, and the permission counts on the organization that owns it:

KindArchive and restoreDelete
productproducts:updateproducts:delete
resourceresources:updateresources:delete
scanscans:updatescans:delete
policyguard.policies:updateguard.policies:delete
exceptionguard.exceptions:updateguard.exceptions:update
connectionintegrations:update (signed-in person only)integrations:delete (signed-in person only)
assessment, a vendor assessmentresources:updateresources: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​

MethodPathRequired permissionWhat it does
GET/settings/api-keysYour own accountAPI keys and guard tokens
POST/settings/api-keysYour own account (signed-in person only)Create key (secret shown once)
DELETE/settings/api-keys/:idYour own key, or anyone's with api_keys:revokeRevoke key

Dwaar AI​

MethodPathRequired permissionWhat it does
POST/ai/runsai: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/runsai.settings:readRecent Dwaar AI runs, newest first (Settings › AI › Recent activity)
POST/ai/runs/:id/feedbackai:use (signed-in person only)Helpful or not, on the caller's own run
GET/ai/statusai: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-suggestionsai: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-suggestionsresources:readSuggestions of one place, strongest first (surface, anchorId, status; pending when omitted)
POST/mapping-suggestions/:id/reviewresources.lineage:update, resources:attach or products:create, by the suggestion's kindApprove, 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/aiai.settings:readDwaar AI settings: mode, the four tier bindings, defaults, budget
PATCH/settings/aiai.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/providersai.settings:readProviders 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.