Skip to main content

Compliance Frameworks

List compliance frameworks, make workspace documents frameworks, turn a framework ON or OFF, and remove one. Only ON frameworks count in compliance evaluations.

A framework row describes the reading of one framework document: its status, whether it is ON (active), the items extracted from it, and the state of its rule generation. GET /v1/compliance/frameworks lists the frameworks of the workspace whose document still exists, newest first, without the extracted items. It is the route to poll after adopting a document, because both the reading (status) and the rule derivation (rules_status) are visible on each row.

status is one of pending, processing, waiting, completed and error. waiting means the reading waits for the workspace's own agent because the decider is external. rules_status is one of none, generating, waiting, ready and error, with rules_error carrying the reason of a failure. Two counts are easy to confuse: rule_count is the number of items extracted from the framework (its captured fields), while generated_rule_count is the number of rules currently stored, after people edited or deleted generated ones.

Turning a framework ON puts its rules in force. Only a framework whose reading is completed can be turned ON, and turning it OFF always works. OFF hides a framework's rules from evaluations and from discrepancy counts without deleting anything, so a framework can be turned ON again later with its rules intact.

GET/v1/compliance/frameworks

Framework fields

document_idstring (uuid)The framework document.
statusstringThe reading: pending, processing, waiting, completed or error.
activebooleanWhether the framework's rules are in force (ON). Frameworks start OFF.
framework_namestring | nullThe framework's name as read from the document.
rule_countintegerItems extracted from the framework (its captured fields), not the stored rules.
generated_rule_countintegerRules currently stored for the framework.
rules_statusstringRule generation: none, generating, waiting, ready or error.
rules_errorstring | nullWhy rule generation failed.
decided_by / rules_decided_bystring | nullThe external agent's label when it read the requirements or derived the rules.
summarystring | nullOne or two sentences describing the document. Present on this list; null on the views returned after a change.
errorstring | nullWhy the reading failed.
extracted_at / updated_atstring (date-time)When the reading finished (null until then) and when the row last changed.

Response: 200 Frameworks (excerpt)

{
  "data": [
    {
      "document_id": "9d0c4f6e-3b1a-4c53-8f0e-2a7b6c1d5e40",
      "status": "completed",
      "active": true,
      "framework_name": "Supplier Code of Conduct",
      "rule_count": 34,
      "error": null,
      "extracted_at": "2026-10-19T14:02:11.000Z",
      "updated_at": "2026-10-19T14:03:40.000Z",
      "rules_status": "ready",
      "rules_error": null,
      "rules_decided_by": null,
      "decided_by": null,
      "generated_rule_count": 28,
      "summary": "Obligations for suppliers on safety, security incidents and subcontracting."
    }
  ]
}
POST/v1/compliance/frameworks/from-documents

Body fields

document_ids*string[] (uuid)1 to 50 workspace documents. Duplicates are removed; the response keeps the order given.

The response is { "data": [...] } with one framework view per document. With the external decider, each reading waits as a task for the workspace's agent instead of calling the platform's model (see External Decider and Tasks). A document id that is not found in the workspace returns 404.

POST/v1/compliance/frameworks/{documentId}/active

Path and body

documentId*string (uuid)Path parameter: the framework document.
active*booleantrue puts the rules in force, false takes them out.

cURL: Turn a framework OFF

curl -X POST "https://api.talonic.com/v1/compliance/frameworks/9d0c4f6e-3b1a-4c53-8f0e-2a7b6c1d5e40/active" \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"active": false}'

Turning ON a framework whose reading is not completed is refused with 422, and an unknown framework returns 404. The summary field is null on the view returned after a change; read the list to see it.

DELETE/v1/compliance/frameworks/{documentId}

Path parameters

documentId*string (uuid)The framework document.
Removing a framework keeps its history readable: evaluations already made keep the rules they copied, including the rule text and framework name. Use ON/OFF, not removal, to pause a framework without losing its rules.

Frequently asked questions

Why can I not turn my framework ON?+
Only a framework whose reading is completed can be turned ON; the route refuses the request with 422 otherwise. Poll GET /v1/compliance/frameworks until status is completed, which also means the rules derivation has started or finished.
What is the difference between rule_count and generated_rule_count?+
rule_count is the number of items extracted from the framework document, its captured fields. generated_rule_count is the number of rules currently stored for the framework, which are the rules people edit and evaluations use. The two differ because rules are derived from the text and then edited or deleted.
Does turning a framework OFF delete anything?+
No. OFF hides the framework's rules from evaluations and from discrepancy counts and lists, and turning it ON again restores them. Only removing the framework deletes its row and rules, and even then the document stays in the workspace.
What happens when I adopt a document that is already a framework?+
It is read again. The request is a way to refresh a framework's reading after the document changed; the returned row starts in processing or waiting.

Related

Compliance Overview
Rules and Rule Sets
Document Evaluations
External Decider and Tasks