Units
Create, read, update, delete, and verify reasoning units.
Units are the core building blocks of Ctrl AI — typed, composable reasoning elements that domain experts create and verify.
List Units
GET /api/v1/unitsQuery Parameters
| Parameter | Type | Description |
|---|---|---|
status | string | Filter by status: candidate, in_review, verified, partial_verified |
unitType | string | Filter by type: program, framework, pattern, argument, protocol |
domainId | string | Filter by domain |
jurisdiction | string | Filter by jurisdiction |
limit | number | Items per page (default: 20, max: 200) |
offset | number | Pagination offset |
Example
curl https://app.ctrlai.com/api/v1/units?status=verified&unitType=program \
-H "Authorization: Bearer ctrlai_pk_..."Get Unit
GET /api/v1/units/{id}Create Unit
POST /api/v1/unitsRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Unit name |
unitType | string | Yes | program, framework, pattern, argument, protocol |
domainId | string | Yes | Domain ID |
description | string | No | Brief description |
given | string | No | Prerequisites (GIVEN clause) |
when | string | No | Trigger conditions (WHEN clause) |
then | string | No | What the unit produces (THEN clause) |
inputSchema | object | No | Typed input variables |
outputSchema | object | No | Typed output variables |
jurisdiction | string | No | Jurisdiction scope |
Update Unit
PATCH /api/v1/units/{id}Requires author or admin role. All fields from Create are accepted (partial update).
Delete Unit
DELETE /api/v1/units/{id}Requires admin role.
Verify Unit
Submit a verification review on a unit:
POST /api/v1/units/{id}/verifyRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
action | string | Yes | approve, request_changes |
elementReviews | array | No | Per-element reviews |
comment | string | No | Overall review comment |
Element Review Actions
For Programs (per-step):
approve— step is correctcorrect_values— fix a computation or thresholdadd_branch— add a missing conditional pathadd_exception— add an override
For Structured Units (per-element):
approve_element— element is correctsuggest_edit— propose alternative textreweight_element— change factor weightadd_element/remove_element— structural changes
Assign Reviewers
POST /api/v1/units/{id}/assign| Field | Type | Required | Description |
|---|---|---|---|
reviewerIds | string[] | Yes | User IDs to assign as reviewers |
Requires admin role.
Unit Edges
Manage composition edges between units:
GET /api/v1/units/{id}/edges
POST /api/v1/units/{id}/edgesAI-Assisted Edit
POST /api/v1/units/{id}/ai-edit| Field | Type | Required | Description |
|---|---|---|---|
instruction | string | Yes | Natural language edit instruction |
Generate from Coverage Gaps
Auto-generate candidate units for the most-requested missing outputs:
POST /api/v1/units/generate-from-gapsGet by Slugs
POST /api/v1/units/by-slugs| Field | Type | Required | Description |
|---|---|---|---|
slugs | string[] | Yes | Array of unit slugs |