Skip to main content
For AI agents: a documentation index is available at https://docs.coverbase.com/llms.txt — this page is also available in markdown by appending .md to the URL.
A finding (cbtask_...) is an issue raised against a vendor or an assessment. This API exists for GRC sync and external visibility: pull findings into your GRC tool, push status changes back.
Findings are internally modeled as “tasks”, so finding IDs use the cbtask_ prefix. A cbtask_... value is a finding ID.
All endpoints are org-scoped to the API key. See API conventions for shared behavior, including pagination.
MethodPath
GET/v1/findings
POST/v1/findings
GET/v1/findings/{finding_id}
PATCH/v1/findings/{finding_id}
None of these honor Idempotency-Key.

​
List findings

​
method
GET
GET /v1/findings

​
Query parameters

​
vendor_id
string
Filter to findings on a vendor (cbvndr_...).
​
assessment_id
string
Filter to findings on an assessment (cbqsrw_...).
​
limit
integer
Page size. Default 50, range 1–200.
​
offset
integer
Page offset. Default 0.

​
Example request

cURL
curl -X GET "https://sandbox.api.coverbase.app/v1/findings?vendor_id=cbvndr_e448ba62882143f3ba0c140bb2e30162&limit=50&offset=0" \
  -H "Authorization: Bearer ak_live_xxx"

​
Example response

{
  "items": [
    {
      "id": "cbtask_9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d",
      "public_idx": "F-142",
      "vendor_id": "cbvndr_e448ba62882143f3ba0c140bb2e30162",
      "assessment_id": "cbqsrw_2d5e8f1a4b7c0d3e6f9a2b5c8d1e4f7a",
      "finding_status_id": "cbst_open1234567890abcdef1234567890ab",
      "due_date": 1749168000,
      "is_archived": false,
      "created_at": 1746576000,
      "updated_at": 1746576400
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

​
Finding object

​
id
string
Finding ID (cbtask_...).
​
public_idx
string | null
Human-readable index (e.g. F-142), if assigned.
​
vendor_id
string | null
Vendor the finding is on, if any.
​
assessment_id
string | null
Assessment the finding is on, if any.
​
finding_status_id
string | null
Status record ID (cbst_...).
​
due_date
integer | null
Unix timestamp (seconds), if set.
​
is_archived
boolean
true if archived.
​
created_at
integer
Unix timestamp (seconds).
​
updated_at
integer
Unix timestamp (seconds).
The list envelope adds total (full filtered count), limit, and offset — see pagination.

​
Create a finding

​
method
POST
POST /v1/findings
Returns 201 Created. Exactly one of vendor_id or assessment_id must be provided — supplying neither or both is rejected with 422 (“Exactly one of vendor_id or assessment_id must be provided.”).

​
Request body

​
title
string
required
Finding title.
​
body
string
Finding detail / description.
​
vendor_id
string
Vendor the finding is raised against (cbvndr_...). Provide this or assessment_id, not both.
​
assessment_id
string
Assessment the finding is raised against (cbqsrw_...). Provide this or vendor_id, not both.
​
finding_status_id
string
Initial status record ID (cbst_...).
​
due_date
integer
Unix timestamp (seconds).

​
Example request

cURL
curl -X POST "https://sandbox.api.coverbase.app/v1/findings" \
  -H "Authorization: Bearer ak_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Missing SOC 2 Type II report",
    "body": "Vendor has not provided a current SOC 2 Type II.",
    "vendor_id": "cbvndr_e448ba62882143f3ba0c140bb2e30162",
    "due_date": 1749168000
  }'
Returns the finding object.

​
Error responses

StatusBodyWhen
422Standard validation error (msg: “Exactly one of vendor_id or assessment_id must be provided.”)Neither or both of vendor_id/assessment_id supplied, title missing, or body malformed.
400{"detail": {"code": "invalid_finding", "message": "..."}}Business-rule rejection (e.g. a bad reference ID).

​
Retrieve a finding

​
method
GET
GET /v1/findings/{finding_id}
cURL
curl -X GET "https://sandbox.api.coverbase.app/v1/findings/cbtask_9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d" \
  -H "Authorization: Bearer ak_live_xxx"
Returns the finding object.
StatusBodyWhen
404{"detail": {"code": "finding_not_found", "message": "Finding not found."}}Not found / not in the API key’s org.

​
Update / status-sync a finding

​
method
PATCH
PATCH /v1/findings/{finding_id}
Designed for the GRC round-trip: push status and due-date changes (or archive) back into Coverbase. Only included fields change.

​
Request body

​
finding_status_id
string
New status record ID (cbst_...).
​
due_date
integer
New due date (Unix seconds).
​
is_archived
boolean
Archive (true) or restore (false) the finding.

​
Example request

cURL
curl -X PATCH "https://sandbox.api.coverbase.app/v1/findings/cbtask_9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d" \
  -H "Authorization: Bearer ak_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "finding_status_id": "cbst_resolved234567890abcdef1234567890" }'
Returns the refreshed finding object.

​
Error responses

StatusBodyWhen
400{"detail": {"code": "invalid_update", "message": "..."}}Update rejected (e.g. invalid status ID).
404{"detail": {"code": "finding_not_found", "message": "Finding not found."}}Not found / not in the API key’s org.
422Standard validation errorBody failed schema validation.