Assessments API

The Assessments API lets external systems start an assessment for an existing vendor and retrieve its state. The most common use case is a GRC tool or scheduled job kicking off a reassessment of a known vendor. All endpoints are org-scoped to the API key. See API conventions for authentication, IDs, timestamps, idempotency, and the error envelope.

Create an assessment

POST

POST /v1/assessments

Creates a new assessment for a vendor. Returns 201 Created.

Request body

string

required

The vendor ID (cbvndr_...) the assessment runs against.

string[]

required

Control set IDs (cbctst_...) to evaluate the vendor against. May be an empty array, but the field itself is required.

string

Assessment name. Optional.

string

Optional template used to auto-generate the assessment name.

string[]

Optional service IDs (cbsvc_...) the assessment covers.

string

Optional user ID (cbuser_...) to assign the assessment to.

string

Optional name of a workflow to invoke alongside the assessment. If the named workflow does not exist for the org, the request fails with 404 workflow_not_found.

string[]

Optional document IDs (cbvdoc_...) to attach as supporting evidence. Upload documents first with the Documents API to obtain these IDs.

Headers

string

required

Bearer ak_...

string

Optional. If the same key is sent again within 24 hours for this endpoint, the original response is returned and no new assessment is created. See Idempotency.

Example request

curl -X POST "https://api.coverbase.app/v1/assessments" \
  -H "Authorization: Bearer ak_live_xxx" \
  -H "Idempotency-Key: grc-reassess-2026-q2-acme" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_id": "cbvndr_e448ba62882143f3ba0c140bb2e30162",
    "control_set_ids": ["cbctst_9f4a1c0d7b2e4e9f8c1d2b3a4e5f6071"],
    "name": "Acme Q2 2026 Reassessment",
    "service_ids": ["cbsvc_3c2b1a098f7e6d5c4b3a2918374655ab"],
    "trigger_workflow": "annual-reassessment-flow"
  }'

import os
import requests

API_KEY = os.environ["COVERBASE_API_KEY"]
BASE_URL = "https://api.coverbase.app"

payload = {
    "vendor_id": "cbvndr_e448ba62882143f3ba0c140bb2e30162",
    "control_set_ids": ["cbctst_9f4a1c0d7b2e4e9f8c1d2b3a4e5f6071"],
    "name": "Acme Q2 2026 Reassessment",
    "service_ids": ["cbsvc_3c2b1a098f7e6d5c4b3a2918374655ab"],
    "trigger_workflow": "annual-reassessment-flow",
}

resp = requests.post(
    f"{BASE_URL}/v1/assessments",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Idempotency-Key": "grc-reassess-2026-q2-acme",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

Example response

201 Created:

{
  "id": "cbqsrw_2d5e8f1a4b7c0d3e6f9a2b5c8d1e4f7a",
  "vendor_id": "cbvndr_e448ba62882143f3ba0c140bb2e30162",
  "name": "Acme Q2 2026 Reassessment",
  "status": "created",
  "control_set_ids": ["cbctst_9f4a1c0d7b2e4e9f8c1d2b3a4e5f6071"],
  "service_ids": ["cbsvc_3c2b1a098f7e6d5c4b3a2918374655ab"],
  "assignee_id": "cbuser_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "score_percent": null,
  "findings_count": 0,
  "initiated_at": null,
  "created_at": 1746576000,
  "updated_at": 1746576000,
  "workflow_run_id": "cbwr_a8f2c19e3d4b5e6f7a8b9c0d1e2f3a4b"
}

Response fields

string

The new assessment ID (cbqsrw_...).

string

The vendor the assessment runs against.

string

The assessment name.

string

Assessment status. One of: created, collecting_documents, indexing_supporting_documents, analyzing_questionnaire, review_evals, complete, failed, canceled. Newly created assessments are typically created.

string[]

The control sets being evaluated.

string[]

The services the assessment covers.

string | null

The assigned user (cbuser_...), if any.

number | null

Score as a decimal (typically 0–1), or null until scored.

integer | null

Number of findings on the assessment. 0 on creation.

integer | null

Unix timestamp (seconds) when the assessment was initiated, or null.

integer

Unix timestamp (seconds) when the assessment was created.

integer

Unix timestamp (seconds) of the last update.

string | null

The workflow run created when trigger_workflow was supplied, otherwise null.

Error responses

Status	Body	When
400	`{"detail": {"error": "..."}}`	The assessment could not be created (e.g. an invalid `vendor_id`, `control_set_ids`, `service_ids`, or `assignee_id`). `error` contains the reason.
404	`{"detail": {"code": "workflow_not_found", "message": "Workflow '...' not found."}}`	`trigger_workflow` was supplied but no workflow with that name exists for the org.
422	Standard validation error	The request body failed schema validation (e.g. `vendor_id` or `control_set_ids` missing). See API conventions.

Re-sending a request with a previously used Idempotency-Key returns the original 201 response body. It does not return a conflict error.

Retrieve an assessment

GET

GET /v1/assessments/{assessment_id}

Fetches a single assessment by ID.

Path parameters

string

required

The assessment ID (cbqsrw_...).

Example request

cURL

curl -X GET "https://api.coverbase.app/v1/assessments/cbqsrw_2d5e8f1a4b7c0d3e6f9a2b5c8d1e4f7a" \
  -H "Authorization: Bearer ak_live_xxx"

Example response

{
  "id": "cbqsrw_2d5e8f1a4b7c0d3e6f9a2b5c8d1e4f7a",
  "vendor_id": "cbvndr_e448ba62882143f3ba0c140bb2e30162",
  "name": "Acme Q2 2026 Reassessment",
  "status": "complete",
  "control_set_ids": ["cbctst_9f4a1c0d7b2e4e9f8c1d2b3a4e5f6071"],
  "service_ids": ["cbsvc_3c2b1a098f7e6d5c4b3a2918374655ab"],
  "assignee_id": "cbuser_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "score_percent": 0.82,
  "findings_count": 3,
  "initiated_at": 1746576000,
  "created_at": 1746576000,
  "updated_at": 1746579600
}

The shape matches the create response, minus workflow_run_id. findings_count is a computed count of findings on the assessment.

Error responses

Status	Body	When
404	`{"detail": {"code": "assessment_not_found", "message": "Assessment not found."}}`	The `assessment_id` does not exist or is not in the API key’s org.

Cancel (archive) an assessment

DELETE

DELETE /v1/assessments/{assessment_id}

Cancels an in-flight assessment or archives a completed one. Mirrors the in-product “Archive” action on the assessment page. The operation is a soft delete: the assessment row plus its evals and findings are marked is_archived=true, the assessment’s portal (if any) is closed, and any in-flight workflow runs targeting the assessment are canceled in the workflow engine on a best-effort basis. The underlying rows are retained for audit; GET /v1/assessments/{assessment_id} will continue to return them.

Path parameters

string

required

The assessment ID (cbqsrw_...).

Example request

cURL

curl -X DELETE "https://api.coverbase.app/v1/assessments/cbqsrw_2d5e8f1a4b7c0d3e6f9a2b5c8d1e4f7a" \
  -H "Authorization: Bearer ak_live_xxx"

Example response

200 OK:

{
  "id": "cbqsrw_2d5e8f1a4b7c0d3e6f9a2b5c8d1e4f7a",
  "status": "canceled",
  "is_archived": true,
  "archived_at": 1746580000
}

Response fields

string

The archived assessment ID.

string

Assessment status at the time of archival. The workflow engine receives a best-effort cancel signal immediately after archive; transient runs may still surface a brief canceled lifecycle event.

boolean

Always true after a successful archive.

integer

Unix timestamp (seconds) when the archive took effect.

Error responses

Status	Body	When
404	`{"detail": {"code": "assessment_not_found", "message": "Assessment not found."}}`	The `assessment_id` does not exist or is not in the API key’s org.

Archive is idempotent: archiving an already-archived assessment returns 200 with the same envelope. To restore an archived assessment, use the Coverbase dashboard.

Getting started

Products

Control Set library

Trust & security

API Reference

Data Import & Export

Integration Workflows

AI, Agents, MCP

Create an assessment

Request body

Headers

Example request

Example response

Response fields

Error responses

Retrieve an assessment

Path parameters

Example request

Example response

Error responses

Cancel (archive) an assessment

Path parameters

Example request

Example response

Response fields

Error responses

​Create an assessment

​Request body

​Headers

​Example request

​Example response

​Response fields

​Error responses

​Retrieve an assessment

​Path parameters

​Example request

​Example response

​Error responses

​Cancel (archive) an assessment

​Path parameters

​Example request

​Example response

​Response fields

​Error responses

Create an assessment

Request body

Headers

Example request

Example response

Response fields

Error responses

Retrieve an assessment

Path parameters

Example request

Example response

Error responses

Cancel (archive) an assessment

Path parameters

Example request

Example response

Response fields

Error responses