Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.coverbase.com/llms.txt

Use this file to discover all available pages before exploring further.

The Assessments API lets external systems start and manage assessments without going through the dashboard. The most common use case is a GRC tool or scheduled job kicking off a reassessment of a known vendor.

​
Start an assessment

​
method
POST
POST /v1/assessments
Creates a new assessment for a vendor, optionally covering specific services and invoking a named workflow to orchestrate downstream actions.

​
Request body

​
vendor_id
string
required
The Coverbase vendor ID (cbvndr_...) the assessment runs against.
​
control_set_ids
array
required
Array of control set IDs (cbcset_...) to evaluate the vendor against. Assessments can evaluate against one or more policy control sets.
​
risk_type
string
required
Assessment risk type. Values come from the RiskType enum and include security-oriented types. Verify available values for your org through the dashboard.
​
name
string
Assessment name. Required unless assessment_name_format is provided.
​
assessment_name_format
string
If provided (even as an empty string), auto-generates the assessment name using the built-in format. Use this OR name, not both.
​
service_ids
array
Optional array of service IDs (cbsvc_...) the assessment covers. An assessment can cover multiple services.
​
trigger_workflow
string
Optional name of a workflow to invoke. If omitted, any workflow bound to assessment.created runs by default. If specified, that named workflow runs instead.
​
assignee_id
string
Optional user ID to assign the assessment to. Defaults to the vendor’s risk owner.
​
supporting_document_ids
array
Optional array of document IDs (cbdoc_...) to attach as evidence.
​
doc_collection_mode
string
How evidence is collected. Values come from the DocCollectionMode enum.
​
products
array
Optional array of product name strings associated with this assessment.

​
Headers

​
Authorization
string
required
Bearer <api-key>
​
Idempotency-Key
string
Optional. If the same key is sent twice within 24 hours, the second call returns the original response without starting a new assessment. Recommended for retries on network failure.

​
Example request

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

​
Example response

{
  "id": "cbasmt_2d5e8f1a4b7c0d3e6f9a2b5c8d1e4f7a",
  "vendor_id": "cbvndr_e448ba62882143f3ba0c140bb2e30162",
  "name": "Acme Q2 2026 Reassessment",
  "service_ids": ["cbsvc_3c2b1a098f7e6d5c4b3a2918374655ab"],
  "control_set_ids": ["cbcset_9f4a1c0d7b2e4e9f8c1d2b3a4e5f6071"],
  "risk_type": "security",
  "status": "started",
  "assignee_id": "cbusr_a1b2c3d4...",
  "workflow_run_id": "cbwfr_a8f2c19e3d4b5e6f7a8b9c0d1e2f3a4b",
  "initiated_at": 1746576000,
  "created_at": 1746576000
}

​
Response fields

​
id
string
The new assessment ID.
​
vendor_id
string
The vendor the assessment runs against.
​
name
string
The assessment name, either provided directly or auto-generated from assessment_name_format.
​
service_ids
array
The services the assessment covers, if any were specified.
​
control_set_ids
array
The control sets being evaluated.
​
risk_type
string
The risk type passed in the request.
​
status
string
Current status. The assessment status system uses org-customizable labels (via CbStatus), so initial values vary by org configuration.
​
assignee_id
string or null
The assigned user, if any.
​
workflow_run_id
string
The workflow run that this assessment triggered, when applicable. Use this to correlate downstream webhooks.
​
initiated_at
integer or null
Unix timestamp when the assessment was initiated. May differ from created_at if the assessment is created in a pending state before initiation.
​
created_at
integer
Unix timestamp when the assessment was created.

​
Retrieve an assessment

​
method
GET
GET /v1/assessments/{assessment_id}
Fetches a single assessment by ID, including its current status and score.

​
Example request

cURL
curl -X GET "https://api.coverbase.app/v1/assessments/cbasmt_2d5e8f1a4b7c0d3e6f9a2b5c8d1e4f7a" \
  -H "Authorization: Bearer <api-key>"

​
Example response

{
  "id": "cbasmt_2d5e8f1a4b7c0d3e6f9a2b5c8d1e4f7a",
  "vendor_id": "cbvndr_e448ba62882143f3ba0c140bb2e30162",
  "name": "Acme Q2 2026 Reassessment",
  "control_set_ids": ["cbcset_9f4a1c0d7b2e4e9f8c1d2b3a4e5f6071"],
  "risk_type": "security",
  "status": "completed",
  "score_percent": 0.82,
  "findings_count": 3,
  "assignee_id": "cbusr_a1b2c3d4...",
  "initiated_at": 1746576000,
  "created_at": 1746576000
}

​
Response fields

​
score_percent
float
Score as a decimal between 0 and 1 representing the assessment outcome.
​
findings_count
integer
Derived count of evaluations flagged as findings within this assessment. This is a computed value, not a stored field.
​
initiated_at
integer or null
Unix timestamp when the assessment was initiated.

​
Error responses

StatusCodeWhen
400missing_required_fieldOne of vendor_id, control_set_ids, or risk_type was omitted.
400invalid_control_set_idsOne or more IDs in control_set_ids do not exist or are not accessible to the API key.
404vendor_not_foundThe provided vendor_id does not exist or is not accessible to the API key.
404workflow_not_foundThe provided trigger_workflow name is not configured for this org.
409idempotency_conflictAn assessment already exists for this idempotency key. The original response is returned in the body.