watchdep
Sign inSource
Docs / Reference / 05

The API for host applications

Section
Reference
Page
05 of 16
Reading time
9 min

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=.