The API for host applications
A host application is another of your applications, say Prospec360’s own admin screens, that shows watchdep’s findings to its people. It reads through a workspace API token and, if the token allows it, records decisions on behalf of the people it names. A signed webhook tells it when a finding’s state changes, so it can refresh. (To connect an AI agent as yourself instead, see Agents.)
Host application or agent
| A host application | An agent | |
|---|---|---|
| Who | Another of the workspace’s applications, showing findings to its own people | Claude Code, Claude Desktop or any MCP client a person connects |
| Credential | A workspace API token (wda_...) an owner or admin creates |
OAuth: the person signs in and ticks scopes |
| Acts as | The person it names on each decision, on the host’s word | The person who connected it, with their role |
| In the log | “Jane Smith, via Prospec360” | “D. Kim, through Claude Code” |
| Reads | Its own workspace only | The workspace it was connected to only |
| Never | Reaches settings, members, tokens, connections, fix settings or alerts | The same, and never opens pull requests |
API tokens
Owners and admins create tokens in Settings, API tokens. A token has a name (use the host application’s name: it appears in the log) and a choice of whether it may write decisions. Every token can read.
- The token starts
wda_and is shown once, right after it is created. Only its digest is kept, with its first ten characters so you can tell tokens apart. The page shows when each was last used. - Revoking a token is immediate and permanent.
- A token reads only its own workspace. Anything else, including another workspace’s finding by id, answers “not found”.
Send it on every request:
curl -H "Authorization: Bearer wda_..." https://watchdep.example.com/api/v1/workspace/applications
Project tokens (wdp_...), the ones watchdep scan uses, do not work here.
Endpoints
Every endpoint is under /api/v1/workspace and answers JSON. Times are ISO 8601 in UTC. The examples below are trimmed.
GET applications
Every application with its open confirmed findings counted by level, and its open early warnings.
curl -H "Authorization: Bearer $WATCHDEP_API_TOKEN" \
https://watchdep.example.com/api/v1/workspace/applications
{
"applications": [
{
"slug": "prospec360",
"name": "Prospec360",
"open_findings": { "severe": 1, "high": 2, "medium": 4, "low": 0 },
"early_warnings": 0
}
]
}
GET applications/<slug>
The same, with its parts: each part’s production branch, its production rule (the head of the production branch, or the last deployed commit), how it is connected, and its last inventory: how it was taken (cli or github), when, the commit and branch, the package count, whether it is complete, and what was not read.
curl -H "Authorization: Bearer $WATCHDEP_API_TOKEN" \
https://watchdep.example.com/api/v1/workspace/applications/prospec360
{
"slug": "prospec360",
"name": "Prospec360",
"open_findings": { "severe": 1, "high": 2, "medium": 4, "low": 0 },
"early_warnings": 0,
"parts": [
{
"slug": "api",
"name": "api",
"production_branch": "main",
"production_rule": "head of main",
"connected_through": "the CLI",
"last_inventory": {
"taken_by": "cli",
"taken_at": "2026-11-12T09:14:02Z",
"commit": "3f2c1a9e0b7d...",
"branch": "main",
"packages": 212,
"complete": true,
"not_read": []
}
},
{
"slug": "client",
"name": "client",
"production_branch": "main",
"production_rule": "last deployed commit a41f9c2",
"connected_through": "GitHub (prospec360/client) and the CLI",
"last_inventory": {
"taken_by": "github",
"complete": false,
"not_read": [
{ "what": "package-lock.json", "why": "could not read it: unexpected end of JSON input", "incomplete": true }
]
}
}
]
}
last_inventory is null for a part that has sent none: that part has not been looked at, which is not the same as clean.
GET findings
Open findings, loudest first, 100 a page.
| Parameter | What |
|---|---|
page |
The page, from 1 |
application |
An application’s slug |
state |
States, comma separated: new, acknowledged, fix_pr_open, fix_merged, fixed, accepted, not_affected, withdrawn. Without it, open findings only (the first four). |
level |
Levels, comma separated: severe, high, medium, low |
lane |
confirmed or early_warning |
curl -H "Authorization: Bearer $WATCHDEP_API_TOKEN" \
"https://watchdep.example.com/api/v1/workspace/findings?application=prospec360&level=severe,high"
{
"page": 1,
"per_page": 100,
"total": 3,
"findings": [
{
"id": 12,
"primary_id": "CVE-2022-30123",
"ids": ["CVE-2022-30123", "GHSA-wq4h-7r42-5hrr"],
"application": "Prospec360",
"summary": "Shell escape in Rack",
"level": "severe",
"labels": ["provisional"],
"reason": "critical (CVSS 10.0) with no EPSS score yet; provisional",
"lane": "confirmed",
"kind": "vulnerability",
"state": "new",
"scope": "production",
"malicious": false,
"exploited_now_since": null,
"epss": null,
"cvss": 10.0,
"first_seen_at": "2026-11-10T13:40:00Z",
"accepted_until": null
}
]
}
exploited_now_since is the date the finding was listed in CISA KEV, when it is. epss is a probability from 0 to 1, or null when there is no score yet. kind is vulnerability or end_of_life. What levels, labels and lanes mean is in Levels and lanes.
GET findings/<id>
The same, with every place (part, package, version, file or image, scope, relation, dependency paths, the fix and whether it is a new major version), the latest code check per part (verdict, reason, and evidence as file paths and line numbers, never code), pull requests, and the full log.
curl -H "Authorization: Bearer $WATCHDEP_API_TOKEN" \
https://watchdep.example.com/api/v1/workspace/findings/12
{
"id": 12,
"primary_id": "CVE-2022-30123",
"level": "severe",
"state": "acknowledged",
"places": [
{
"part": "api",
"present": true,
"kind": "package",
"ecosystem": "RubyGems",
"name": "rack",
"version": "2.2.3",
"file": "Gemfile.lock",
"scope": "production",
"relation": "transitive",
"paths": [["sidekiq", "rack"]],
"more_paths": 0,
"paths_recorded": true,
"fix": "2.2.3.1",
"fix_is_major": false
}
],
"code_checks": [
{
"part": "api",
"verdict": "used",
"reason": "Rack::Request is built from every request in the middleware",
"evidence": [{ "path": "app/middleware/tenant.rb", "line": 14, "note": "Rack::Request.new(env)" }],
"at": "2026-11-11T08:02:10Z"
}
],
"pull_requests": [],
"log": [
{ "at": "2026-11-10T13:40:00Z", "action": "new", "who": "CLI (token api-ci)", "from_state": null, "to_state": "new", "from_level": null, "to_level": "severe", "reason": "..." },
{ "at": "2026-11-11T10:05:31Z", "action": "acknowledge", "who": "Jane Smith, via Prospec360", "from_state": "new", "to_state": "acknowledged", "from_level": null, "to_level": null, "reason": "Acknowledged: looking at it this sprint" }
]
}
A place with present: false is gone: that part’s production inventory no longer has the package at an affected version. A code check verdict (used, not_used or unclear) is a draft; it never closes a finding. See The code check.
GET sources
Each source’s health: when it last synced well, when it last tried, whether it is stalled (no good sync in 24 hours) or has never synced, and its last error. A host can show these beside the findings, so nobody reads “no findings” as clean while a source is down.
curl -H "Authorization: Bearer $WATCHDEP_API_TOKEN" \
https://watchdep.example.com/api/v1/workspace/sources
{
"sources": [
{ "name": "OSV", "last_success_at": "2026-11-12T13:07:12Z", "last_attempt_at": "2026-11-12T13:07:12Z", "stalled": false, "never_synced": false, "last_error": null },
{ "name": "EPSS", "last_success_at": "2026-11-10T15:10:40Z", "last_attempt_at": "2026-11-12T15:10:03Z", "stalled": true, "never_synced": false, "last_error": "the download answered 503" }
]
}
POST findings/<id>/decisions
Records a decision on behalf of a person the host names. The token needs “write decisions”.
| Field | What |
|---|---|
kind |
acknowledge, not_affected or accept |
reason |
Required for not_affected and accept |
until |
For accept: the date (YYYY-MM-DD) the acceptance ends, after today and at most a year away |
person |
Who decided: name and email, both required |
curl -X POST -H "Authorization: Bearer $WATCHDEP_API_TOKEN" -H "Content-Type: application/json" \
https://watchdep.example.com/api/v1/workspace/findings/12/decisions \
-d '{
"kind": "accept",
"reason": "The upload endpoint is behind the VPN until the upgrade ships",
"until": "2026-12-15",
"person": { "name": "Jane Smith", "email": "jane@example.com" }
}'
It answers 201 Created with the finding as in GET findings, now in its new state.
Decisions on behalf of a person
The host vouches for its own people, and watchdep takes it at its word:
- The decision is recorded as the named person, via the token’s name: “Jane Smith, via Prospec360”. The log never claims watchdep checked who they are.
- When the email matches a member of the workspace, the decision is linked to that member, and their role’s rules apply: a viewer named by a host cannot decide (403).
- A person with no watchdep account may decide through the host.
- A decision without the person’s name and email is refused (422), so leaving the email out cannot get round a member’s role.
- Every other rule of decisions holds: a reason for not affected and for accepting, the year limit on accepting, and the states each decision can be made from. A decision covers only the places present when it was made. See Decisions.
Errors
Errors answer JSON with one field, error, in plain words:
{ "error": "this token cannot write decisions" }
| Status | When |
|---|---|
| 401 | No token, or a token that is unknown or revoked |
| 403 | A token without “write decisions” posted a decision, or the named member’s role cannot decide |
| 404 | The application or finding does not exist in the token’s workspace |
| 422 | The decision is invalid: no person, an unknown kind, a missing reason, a date out of range, or a state the decision cannot be made from (for example, acknowledging a finding that is already accepted) |
State change webhooks
The workspace’s webhook (Settings, Webhook) posts new and escalated findings by level, as described in Alerts. Tick “Also every state change” and it also posts one finding.state_changed event for every change of a finding’s state, whatever its level, and whoever made it: a person, a host, an agent or the CLI. That covers acknowledged, accepted, not affected, fix pull request open, fix merged, fixed and reopened by expiry. A finding’s first appearance is not a state change; it is finding.new, sent by level as before. The option is off by default.
{
"event": "finding.state_changed",
"workspace": "Prospec360 team",
"sent_at": "2026-11-12T13:41:02Z",
"text": "CVE-2022-30123 in Prospec360: New to acknowledged (Jane Smith, via Prospec360). https://watchdep.example.com/findings/12",
"finding": {
"id": 12,
"url": "https://watchdep.example.com/findings/12",
"primary_id": "CVE-2022-30123",
"level": "severe",
"state": "acknowledged",
"application": "Prospec360",
"places": [{ "part": "api", "ecosystem": "RubyGems", "name": "rack", "version": "2.2.3", "file": "Gemfile.lock", "paths": [["sidekiq", "rack"]], "fix": "2.2.3.1" }]
},
"change": { "from": "new", "to": "acknowledged", "who": "Jane Smith, via Prospec360", "reason": "Acknowledged: looking at it this sprint" },
"fix": "2.2.3.1"
}
A post that errors or answers anything but 2xx is retried, five attempts in all. The webhook’s last delivery, status and error are shown in Settings, Webhook.
Verifying the signature
Every post carries these headers:
| Header | What |
|---|---|
X-Watchdep-Event |
The event, for example finding.state_changed |
X-Watchdep-Timestamp |
When it was sent, in Unix seconds |
X-Watchdep-Signature |
sha256= followed by the hex HMAC-SHA256 of <timestamp>.<body>, keyed with the webhook’s secret |
The secret (whsec_...) is shown once, when the webhook is added or when someone asks for a new one. To verify a post: take the timestamp header and the raw body exactly as received, join them with a full stop, compute HMAC-SHA256 with the secret, prefix sha256=, and compare with the signature header in constant time. Reject a mismatch, and reject an old timestamp (for example, older than five minutes) so a captured post cannot be replayed.
In Node.js:
import crypto from "node:crypto";
function verify(rawBody, timestamp, signature, secret) {
const expected = "sha256=" + crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) < 300;
return fresh && expected.length === signature.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}
From a shell, to check one saved post:
printf '%s.%s' "$TIMESTAMP" "$(cat body.json)" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET"
Compare the hex it prints with the signature header after sha256=.