Changelog

​

2026-06-08 — Documents API

Upload vendor evidence documents over the REST API and through the MCP server, link them to vendors, services, and assessments, and download them.

​

New features

• Documents API. POST /v1/documents uploads a file (multipart/form-data) and attaches it to a vendor, optionally linking it to services (service_ids) and assessments (assessment_ids) in the same call. List with filters (GET /v1/documents?vendor_id=&service_id=&assessment_id=), fetch metadata (GET /v1/documents/{document_id}), get a short-lived presigned download URL (GET /v1/documents/{document_id}/download), re-link or rename (PATCH /v1/documents/{document_id}), and archive (DELETE /v1/documents/{document_id}). Smart limits apply: 100 MiB per file, an allowed file-type list, and 1–200 page sizes. See the Documents API reference.
• MCP document tools. The MCP server adds mutate(document, create|update|archive) (upload from a URL, re-link, archive) and query_vendors(document_download) (presigned download URL), alongside the existing query_vendors(documents|document_summary) reads.

​

Updates

• Assessment supporting documents. supporting_document_ids on POST /v1/assessments now links documents uploaded via the Documents API.

---

​

2026-06-04 — Vendor fact sheet API

Read and regenerate a vendor’s AI-generated fact sheet (company intelligence) over the REST API.

​

New features

• Vendor fact sheet API. GET /v1/vendors/{vendor_id}/fact-sheet returns the vendor’s fact sheet — company profile, products, public perception, financials, people, compliance/legal, and security posture — along with a generation status. POST /v1/vendors/{vendor_id}/fact-sheet/refresh queues a (re)generation and returns 202 Accepted; poll the read endpoint until status is "completed". See the Vendors API reference.

---

​

2026-06-04 — List and resolve users by email

The Users API can now look up a user by email and returns the existing user on a duplicate create — so external systems (e.g. ServiceNow) can build an email → user ID mapping for relationship-owner / watcher / risk-analyst assignments.

​

New features

• List users / look up by email. GET /v1/users lists the org’s users (paginated via limit/offset, optional include_archived), or resolves a single user with ?email= (case-insensitive exact match; returns the user even if archived). See the Users API reference.

​

Updates

• POST /v1/users is now create-or-get. When a user with the supplied email already exists in the org, the endpoint returns 200 OK with that user (so you can resolve its cbuser_... ID) instead of 409 user_exists. A 409 is now only returned when the email belongs to a user in a different org (emails are globally unique).
• Assigning people by email. The vendor & service relationship_owner_ids, watcher_ids, and risk_analyst_ids fields still take user IDs — the Users API is the supported path to resolve those IDs from emails.

---

​

2026-06-02 — Bill of Materials

Upload, version, and search machine-readable bills of materials (SBOM, AIBOM, HBOM, SaaSBOM) for vendors and services — over the REST API and through the MCP server.

​

New features

• Bill of Materials API. Upload a BOM as a document linked to a vendor or its services (POST /v1/bill_of_materials), and Coverbase parses CycloneDX and SPDX JSON in the background into a searchable list of components. Read the current applied BOM for a vendor or service (GET /v1/bill_of_materials/latest), page the full upload history (GET /v1/bill_of_materials), retrieve one BOM with its components, search components within a BOM or across all of a vendor’s BOMs, and archive a BOM. Only the latest non-archived BOM is “applied”; older ones stay viewable as history. See the Bill of Materials API reference.

​

Updates

• MCP & AI assistants. The query_vendors tool gained two read-only kinds — bill_of_materials (the latest applied BOM and its components) and bill_of_materials_history (every uploaded BOM for a vendor, newest first). See the example prompts.
• Conventions. The ID-prefix table now lists cbbom_ (bill of materials) and cbbomc_ (component). See IDs.

---

​

2026-05-29 — Radar & reassessments come to the API

Programmatic access to continuous monitoring: create radar events, triage alerts, and drive reassessments end-to-end — plus webhooks for all three.

​

New features

• Radar API. Create radar events (POST /v1/radar/events), list and retrieve events, and list, retrieve, dismiss, and undismiss radar alerts. Dismissing with suppress_similar teaches the detector to suppress similar alerts going forward. See the Radar API reference.
• Reassessments API. Create a reassessment from a radar event with its vendors, curate the vendor set (add vendors, opt vendors in/out), set the assessment plan, then confirm, dismiss, or run it. Running creates one assessment per included vendor from the linked plan — and never opens a case. See the Reassessments API reference.
• Radar & reassessment webhooks. Subscribe to RadarEvent.*, RadarDetectorResult.* (radar alerts), and Reassessment.* events. *.Updated events carry per-field field_diffs; soft-archives surface as *.Deleted. See the event catalog.

​

Updates

• MCP & AI assistants. The Coverbase MCP server can now read reassessments (query_radar kind reassessments) and create radar events, dismiss alerts, and create/update reassessments (mutate). The in-product Interrogate assistant can propose the same radar/reassessment actions on a vendor.

---

​

2026-05-22 — This week at Coverbase

A big week for the public API: self-serve key management, deeper workflow visibility, automatic webhook delivery, and tighter network controls.

​

New features

• Self-serve API key management. Admins can now list, create, rotate, and revoke their org’s ak_* keys without filing a support ticket. Rotation is atomic, so you’ll never have two valid keys live at the same time. See the API Keys reference.
• Scoped admin API keys. Admins can mint long-lived ak_* keys carrying the keys:manage and/or audit:read scopes, so key management and audit-log reads can run headlessly — without a short-lived dashboard JWT. The admin-JWT path is unchanged and still works. Granting scopes stays an admin-only action (a scoped key cannot grant scopes to itself or any other key), and a key missing the required scope gets 403 insufficient_scope. See API key scopes.
• List workflow runs. Page through workflow run history with filters for workflow name, status, and time range — no need to know a run ID up front. See List workflow runs.
• Archive an assessment via API. DELETE /v1/assessments/{id} mirrors the in-product Archive action: it soft-deletes the assessment along with its evals and findings, closes the portal if open, and cancels any in-flight workflow runs. See Cancel (archive) an assessment.
• Public API audit log. Every authenticated /v1/* call is now recorded and visible to admins under Settings → Audit log (Integrations group), or via GET /v1/system_audit_log. Request and response bodies are never persisted. See Public API audit log.
• Org-level API IP allowlist. Restrict all public API traffic to a set of CIDRs. Requests from outside the allowlist are rejected with 403 ip_not_allowed. See API IP allowlist.
• Workflow send_webhook action. Workflow automations can now deliver their triggering event to subscribed webhooks, with optional event-type override and an optional subset of recipient webhooks. See Workflow engine → Actions.

​

Updates

• Per-stage workflow outcomes. GET /v1/workflows/runs/{id} now returns the outcome of every executed step — status (success, failed, skipped), an optional message, the artifacts consumed and produced, and a per-step timestamp. Existing fields are unchanged. completed_at also now populates on canceled runs.
• Automatic webhook delivery is live. Subscribed webhooks now receive a fan-out delivery whenever a matching domain event occurs — not just from the manual test endpoint. All webhooks for a single source event share an event_id so receivers can dedupe. See Webhooks.
• Webhook delivery history. Inspect every delivery attempt — event fan-out, manual test, or workflow-triggered — via the new GET /v1/webhooks/{id}/deliveries endpoint, and review aggregate stats (last_delivery_status, delivery_success_rate, delivery_count) on the webhook itself. See Webhook delivery history.

​

Breaking changes

• Webhook event types are now strictly validated. Creating or updating a webhook with an event type outside the event catalog now returns 422 invalid_event_types. Casing matters — use Vendor.Created, not vendor.created. Review your registered subscriptions before your next deploy.
• Webhook URLs are SSRF-restricted. Webhook url must be a public HTTPS endpoint. Non-HTTPS URLs, URLs with credentials or non-standard ports, and URLs resolving to private, loopback, link-local, or metadata addresses are rejected with 400 invalid_url. The same check runs at delivery time (DNS-rebinding safe).

​

Fixes

• API keys revoke is idempotent. Re-revoking an already-revoked key returns success without writing a duplicate audit row. Audit entries are only written on actual state transitions.

---

​

2026-05-21 — Self-serve API keys, workflow run listing, assessment archive, audit log

Additive features answering common customer questions on day-2 operations of the public API.

​

Additive

• Self-serve ak_* API key management. New API Keys API lets an org admin list, create, rotate, and revoke their organization’s public-API keys without contacting Coverbase support. Rotation is atomic: a new key is minted, then the old one is revoked; if the revoke fails the new key is rolled back so there’s never a window with two simultaneously-valid keys. At launch these endpoints were JWT-only (ak_* keys could not manage other keys); they now also accept an ak_* key carrying the keys:manage scope — see the scoped admin API keys entry above.
• GET /v1/workflows/runs — list workflow runs. Page through workflow run history without already knowing the run ID. Filterable by workflow_name, status (repeatable), and a created-at time range. Returns a step_count per run for at-a-glance progress. See Workflows API → List workflow runs.
• Per-stage workflow outcomes. GET /v1/workflows/runs/{id} now surfaces the action outcome of every executed step: status (success / failed / skipped), an optional message (carries the failure reason on failure), the consumed and produced artifacts (with role of trigger or result), and the step’s created_at. The previous response (component id, name, action_type, updated_at) is unchanged so this is additive. completed_at now also populates on canceled.
• DELETE /v1/assessments/{id} — cancel / archive an assessment. Mirrors the in-product Archive action: soft-deletes the assessment plus its evals and findings, closes the portal if open, and best-effort cancels any in-flight workflow runs targeting the assessment. Idempotent at the row level. See Assessments API → Cancel (archive) an assessment.
• Public-API audit log. Every authenticated /v1/* request now writes a CbActivity row (type=external_api_call, target_type=external_api_request) with the method, path, route template, status code, duration, query parameter names, ak_* key id+name, client IP, and a request correlation ID. Visible to admins in Settings → Audit log under the Integrations group, and via GET /v1/system_audit_log. Request and response bodies are never persisted. See API conventions → Public API audit log.

​

2026-05-16 — Webhook event-type validation, SSRF restrictions, delivery history, and API IP allowlist

Reconciled against the claude/webhook-ui-workflow source branch. Two breaking changes and two additive features.

​

Breaking

• Webhook events is now strictly validated. POST /v1/webhooks and PATCH /v1/webhooks/{id} reject any event type outside the supported event catalog with 422 invalid_event_types. Previously the field was a free-form list of strings. Integrations that registered non-canonical values (e.g. lowercase vendor.created) must switch to the exact catalog casing (e.g. Vendor.Created) or their create/update calls will now fail.
• Webhook URLs are SSRF-restricted. A webhook url must be a public HTTPS endpoint. URLs that are non-HTTPS, carry credentials, use a non-standard port, or resolve to a private / loopback / link-local / metadata address (e.g. 169.254.169.254) are rejected at create/update with 400 invalid_url. The same check is re-applied with DNS resolution at delivery time (DNS-rebinding safe); a delivery blocked this way is recorded with status error.

​

Additive

• Automatic event delivery is live. Subscribed webhooks now receive a fan-out delivery whenever a matching domain event occurs (previously only the manual test endpoint dispatched a delivery). All webhooks for one source event share a single event_id so receivers can dedupe the fan-out. The prior “automatic event delivery is not yet wired up” caveat has been removed.
• Webhook delivery history. New GET /v1/webhooks/{id}/deliveries endpoint (paginated, newest first) and a new Webhook delivery history page. Every attempt — event fan-out, manual test, or workflow-triggered — is recorded. The webhook object now also returns last_delivery_status, delivery_success_rate, and delivery_count.
• Org-level API IP allowlist. An org can restrict all /v1/* public API requests to a set of CIDRs via api_ip_allowlist on the org object (POST /v1/org/{id}). Requests from outside the allowlist get 403 ip_not_allowed; the control fails closed. See API conventions → API IP allowlist.
• Workflow send_webhook action. Workflow automations can deliver their triggering event to subscribed webhooks, with an optional event-type override and an optional webhook_ids subset. See Workflow engine → Actions.

​

2026-05-16 — Reconciled against the deployed source branch

Corrected the reference against the branch actually deployed to the sandbox. Changes vs. the prior pass:

• Vendor primary_contact. Create, update, and read now document the primary_contact object (email required + validated, plus name/title/phone_number). On read it is derived from stored contact personnel / security contact email.
• Vendor services. The vendor object now includes a services array (nested service objects).
• Service updates. Added PATCH /v1/vendors/{vendor_id}/services/{service_id} (name / description / tag_ids → service_not_found 404, invalid_service 400). Service create now accepts tag_ids; the service object includes a tags string array.
• User email is validated. POST /v1/users rejects a non-email email with 422; 409 user_exists is also returned on a create race / global uniqueness conflict.
• Findings: exactly one target. POST /v1/findings now requires exactly one of vendor_id/assessment_id — supplying neither or both fails with 422 (“Exactly one of vendor_id or assessment_id must be provided.”).

​

2026-05-16 — Full sandbox surface documented

Added complete reference coverage for the endpoints available on the sandbox API that were previously undocumented:

• Users API — POST /v1/users (provision, idempotent), GET /v1/users/{id}, PATCH /v1/users/{id} (role change / deprovision via is_archived). Documented org role values, 409 user_exists, and the invited/active/inactive membership states.
• Vendor & service creation — POST /v1/vendors (idempotent) and POST /v1/vendors/{id}/services (not idempotent). Added the vendor tier field and external_id create input.
• Findings API — GET/POST /v1/findings, GET/PATCH /v1/findings/{id}. Documented the vendor/assessment filter, limit/offset pagination, the cbtask_ ID prefix, and the “one of vendor_id/assessment_id required” rule.
• Obligations API — GET/POST /v1/obligations, GET/PATCH /v1/obligations/{id}. Documented the satisfied/not_satisfied status enum, CUEC type, and pagination.
• Workflows — the get-run response now documents steps[]; added 409 workflow_disabled and 502 workflow_dispatch_failed; clarified that running a workflow genuinely dispatches the engine (Workflow.RunRequested).
• Added the sandbox base URL (https://sandbox.api.coverbase.app) and a pagination section to API conventions; expanded the ID-prefix table (cbtask_, cboblg_, cbsvc_, cbvdoc_) and the idempotency support matrix.

​

2026-05-16 — Documentation reconciled with the API

The API reference was rebuilt to exactly match the implemented public API. Highlights:

• Resource surface corrected. Fixed schemas for the vendors, assessments, workflows, and webhooks endpoints. (The Users, vendor/service creation, Findings, and Obligations endpoints were documented in the following entry once the deployed sandbox surface was confirmed.)
• Vendor schema fixed. status is a label string (not an object); tags is a string array (not objects). Added status_id. Removed fields that the API does not return (raw_irq_score, next_assessment_date, last_assessment_outcome).
• Assessment schema fixed. Removed the non-existent risk_type, doc_collection_mode, and products request fields. control_set_ids is required. Status values corrected to the real enum. Idempotency replays return the original 201 body (no 409 idempotency_conflict).
• Workflow schema fixed. Run status values are started/completed/canceled/failed. The get-run response returns only run metadata — no checkpoints_reached or output. Removed the non-existent 429 rate_limited / 400 invalid_input errors and the non-existent POST /v1/workflows/runs alternative.
• Webhook signing documented from source. Signature header is Coverbase-Signature (lowercase hex HMAC-SHA256 of the raw body, keyed by the registered secret). Deliveries also send X-Coverbase-Event-Id and X-Coverbase-Event-Type. Envelope is exactly {event_id, event_type, occurred_at, data}. Retries are bounded at 5 attempts with a 10s per-attempt timeout (no documented multi-hour backoff window).
• Event catalog corrected to the emission-backed SupportedEventType values with exact casing (e.g. Vendor.Created, not vendor.created). Removed invented events (evaluation.flagged, evidence.requested, etc.).
• Added a shared API conventions page (auth, IDs, timestamps, idempotency, error envelope).

​

Open questions

• Automatic event delivery. No code path fans domain events out to subscribed webhook endpoints. Resolved 2026-05-16: automatic fan-out is now implemented — see the latest changelog entry above and the Webhooks guide.
• supporting_document_ids ID prefix. The assessment create field accepts document IDs; the precise prefix is intentionally left unspecified pending confirmation.