API: specs

Status: GA Access: token required API contract: 0.3.0 · capability 2026-09-03.1 View as Markdown Open in Claude Open in ChatGPT

`GET /api/v1/specs`

List Specs

Open as a page →

: list all specs sorted by id descending.

Auth: Authorization: Bearer <token> required

Responses:

Code	Meaning	Body
`200`	Successful Response	`SpecListResponse`
`401`	Missing or invalid authentication credentials	`ErrorResponse`

`GET /api/v1/specs/{spec_id}`

Get Spec

Open as a page →

: detail with frontmatter, body, sections, tests_status.

Auth: Authorization: Bearer <token> required

Parameter	In	Required	Type	Description
`spec_id`	path	yes	`string`

Responses:

Code	Meaning	Body
`200`	Successful Response	`SpecDetailResponse`
`400`	Malformed spec id (expected SPEC-NNN)	—
`401`	Missing or invalid authentication credentials	`ErrorResponse`
`404`	Spec not found	—
`422`	Validation Error	`HTTPValidationError`

`GET /api/v1/specs/{spec_id}/history`

Get Spec History

Open as a page →

: git log per file. Empty if.git not mounted.

Auth: Authorization: Bearer <token> required

Parameter	In	Required	Type	Description
`spec_id`	path	yes	`string`

Responses:

Code	Meaning	Body
`200`	Successful Response	`array of object`
`400`	Malformed spec id (expected SPEC-NNN)	—
`401`	Missing or invalid authentication credentials	`ErrorResponse`
`404`	Spec not found	—
`422`	Validation Error	`HTTPValidationError`

`GET /api/v1/specs/{spec_id}/progress`

Get Spec Progress

Open as a page →

Implementation progress grouped by spec section — each leaf §-anchor with its label and whether a test covers it (SPEC-NNN §X.Y citation).

Auth: Authorization: Bearer <token> required

Parameter	In	Required	Type	Description
`spec_id`	path	yes	`string`

Responses:

Code	Meaning	Body
`200`	Successful Response	`array of ProgressSection`
`400`	Malformed spec id (expected SPEC-NNN)	—
`401`	Missing or invalid authentication credentials	`ErrorResponse`
`404`	Spec not found	—
`422`	Validation Error	`HTTPValidationError`

`PATCH /api/v1/specs/{spec_id}/status`

Patch Spec Status

Open as a page →

: status transition with validation.

Auth: Authorization: Bearer <token> required

Parameter	In	Required	Type	Description
`spec_id`	path	yes	`string`
`Idempotency-Key`	header	no	`string`	Optional.

Request body: application/json — schema StatusPatch

Field	Type	Required	Description
`status`	`string`	yes	One of draft/review/accepted/implemented/obsolete

Responses:

Code	Meaning	Body
`200`	Successful Response	`object`
`401`	Missing or invalid authentication credentials	`ErrorResponse`
`422`	Validation Error	`HTTPValidationError`

`GET /api/v1/specs/{spec_id}/tests`

Get Spec Tests

Open as a page →

Return individual pytest test-cases for this spec from junit.xml.

Auth: Authorization: Bearer <token> required

Parameter	In	Required	Type	Description
`spec_id`	path	yes	`string`

Responses:

Code	Meaning	Body
`200`	Successful Response	`array of SpecTestCase`
`400`	Malformed spec id (expected SPEC-NNN)	—
`401`	Missing or invalid authentication credentials	`ErrorResponse`
`404`	Spec not found	—
`422`	Validation Error	`HTTPValidationError`