Findings API

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.

Method	Path
`GET`	`/v1/findings`
`POST`	`/v1/findings`
`GET`	`/v1/findings/{finding_id}`
`PATCH`	`/v1/findings/{finding_id}`

None of these honor Idempotency-Key.

List findings

GET

GET /v1/findings

Query parameters

string

Filter to findings on a vendor (cbvndr_...).

string

Filter to findings on an assessment (cbqsrw_...).

integer

Page size. Default 50, range 1–200.

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

string

Finding ID (cbtask_...).

string | null

Human-readable index (e.g. F-142), if assigned.

string | null

Vendor the finding is on, if any.

string | null

Assessment the finding is on, if any.

string | null

Status record ID (cbst_...).

integer | null

Unix timestamp (seconds), if set.

boolean

true if archived.

integer

Unix timestamp (seconds).

integer

Unix timestamp (seconds).

The list envelope adds total (full filtered count), limit, and offset — see pagination.

Create a finding

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

string

required

Finding title.

string

Finding detail / description.

string

Vendor the finding is raised against (cbvndr_...). Provide this or assessment_id, not both.

string

Assessment the finding is raised against (cbqsrw_...). Provide this or vendor_id, not both.

string

Initial status record ID (cbst_...).

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

Status	Body	When
422	Standard 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

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.

Status	Body	When
404	`{"detail": {"code": "finding_not_found", "message": "Finding not found."}}`	Not found / not in the API key’s org.

Update / status-sync a finding

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

string

New status record ID (cbst_...).

integer

New due date (Unix seconds).

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

Status	Body	When
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.
422	Standard validation error	Body failed schema validation.

Getting started

Products

Control Set library

Trust & security

API Reference

Data Import & Export

Integration Workflows

AI, Agents, MCP

List findings

Query parameters

Example request

Example response

Finding object

Create a finding

Request body

Example request

Error responses

Retrieve a finding

Update / status-sync a finding

Request body

Example request

Error responses

​List findings

​Query parameters

​Example request

​Example response

​Finding object

​Create a finding

​Request body

​Example request

​Error responses

​Retrieve a finding

​Update / status-sync a finding

​Request body

​Example request

​Error responses

List findings

Query parameters

Example request

Example response

Finding object

Create a finding

Request body

Example request

Error responses

Retrieve a finding

Update / status-sync a finding

Request body

Example request

Error responses