Obligations API

An obligation (cboblg_...) is a compliance obligation tracked against the org. Obligations created through this API are of type CUEC (complementary user-entity controls). This API exists for GRC sync and external visibility. All endpoints are org-scoped to the API key. See API conventions for shared behavior, including pagination.

Method	Path
`GET`	`/v1/obligations`
`POST`	`/v1/obligations`
`GET`	`/v1/obligations/{obligation_id}`
`PATCH`	`/v1/obligations/{obligation_id}`

None of these honor Idempotency-Key.

Status values

The status field accepts exactly:

Value	Meaning
`satisfied`	The obligation is met.
`not_satisfied`	The obligation is not met (default on create).

Any other value returns 400 invalid_status listing the accepted values.

List obligations

GET

GET /v1/obligations

Query parameters

string

Filter to obligations associated with a vendor (cbvndr_...).

string

Filter by status — satisfied or not_satisfied.

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/obligations?obligation_status=not_satisfied&limit=50" \
  -H "Authorization: Bearer ak_live_xxx"

Example response

{
  "items": [
    {
      "id": "cboblg_4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c",
      "statement": "Customer must enforce MFA on all admin accounts.",
      "status": "not_satisfied",
      "obligation_type": "cuec",
      "compliance_type": null,
      "vendor_document_id": "cbvdoc_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
      "assignee_id": "cbuser_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
      "assignee_group_id": null,
      "due_date": 1749168000,
      "is_archived": false,
      "created_at": 1746576000,
      "updated_at": 1746576400
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Obligation object

string

Obligation ID (cboblg_...).

string

The obligation statement.

string

satisfied or not_satisfied.

string

Always cuec for obligations created via this API.

string | null

How compliance is established (manual, internal_control, or similar_obligation), if set.

string | null

Source vendor document (cbvdoc_...), if linked.

string | null

Assigned user (cbuser_...).

string | null

Assigned group, if assigned to a group instead of a user.

integer | null

Unix timestamp (seconds), if set.

boolean

true if archived.

integer

Unix timestamp (seconds).

integer

Unix timestamp (seconds).

The list envelope adds total, limit, offset — see pagination.

Create an obligation

POST

POST /v1/obligations

Returns 201 Created. obligation_type is always set to cuec.

Request body

string

required

The obligation statement.

string

satisfied or not_satisfied. Defaults to not_satisfied.

string

Link to a source vendor document (cbvdoc_...).

string

Assign to a user (cbuser_...).

string

Assign to a group instead of a user.

integer

Unix timestamp (seconds).

Example request

cURL

curl -X POST "https://sandbox.api.coverbase.app/v1/obligations" \
  -H "Authorization: Bearer ak_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "statement": "Customer must enforce MFA on all admin accounts.",
    "status": "not_satisfied",
    "due_date": 1749168000
  }'

Returns the obligation object.

Error responses

Status	Body	When
400	`{"detail": {"code": "invalid_status", "message": "Invalid status '...'. Expected one of: satisfied, not_satisfied."}}`	`status` not one of the accepted values.
400	`{"detail": {"code": "invalid_obligation", "message": "..."}}`	Other business-rule rejection.
422	Standard validation error	`statement` missing or body malformed.

Retrieve an obligation

GET

GET /v1/obligations/{obligation_id}

cURL

curl -X GET "https://sandbox.api.coverbase.app/v1/obligations/cboblg_4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c" \
  -H "Authorization: Bearer ak_live_xxx"

Returns the obligation object.

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

Update / status-sync an obligation

PATCH

PATCH /v1/obligations/{obligation_id}

Push status, assignment, due-date, or statement changes (or archive) back into Coverbase. Only included fields change.

Request body

string

Updated statement.

string

satisfied or not_satisfied.

string

Reassign to a user (cbuser_...).

string

Reassign to a group.

integer

New due date (Unix seconds).

boolean

Archive (true) or restore (false).

Example request

cURL

curl -X PATCH "https://sandbox.api.coverbase.app/v1/obligations/cboblg_4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c" \
  -H "Authorization: Bearer ak_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "status": "satisfied" }'

Returns the refreshed obligation object.

Error responses

Status	Body	When
400	`{"detail": {"code": "invalid_status", "message": "Invalid status '...'. Expected one of: satisfied, not_satisfied."}}`	`status` not accepted.
400	`{"detail": {"code": "invalid_update", "message": "..."}}`	Update otherwise rejected.
404	`{"detail": {"code": "obligation_not_found", "message": "Obligation 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

Status values

List obligations

Query parameters

Example request

Example response

Obligation object

Create an obligation

Request body

Example request

Error responses

Retrieve an obligation

Update / status-sync an obligation

Request body

Example request

Error responses

​Status values

​List obligations

​Query parameters

​Example request

​Example response

​Obligation object

​Create an obligation

​Request body

​Example request

​Error responses

​Retrieve an obligation

​Update / status-sync an obligation

​Request body

​Example request

​Error responses

Status values

List obligations

Query parameters

Example request

Example response

Obligation object

Create an obligation

Request body

Example request

Error responses

Retrieve an obligation

Update / status-sync an obligation

Request body

Example request

Error responses