Conspectus
POST
/api/v1/conspectuses
Specification. Intended behavior: create an ETR conspectus for a user resolved by
(system_user_id, system_uuid). Narrative per
ADR 0026. Planned
operationId: createConspectus (OpenAPI when implemented).
Planned operationId: createConspectus
Request path and behavior
Intended: protected route; middleware per ADR 0005.
Flow: resolve client_uuid via existing user lookup; persist conspectus row; compute initial slot and
next_review_at from a schedule policy (implementation TBD).
Idempotency: required Idempotency-Key header. Storage key
endpoint_path = "/api/v1/conspectuses" (constant CONSPECTUS_HTTP_BASE_PATH) plus
SHA-256 hash of canonical JSON body per ADR 0006.
Replay returns stored 201 body.
Success: 201 Created — body matches ConspectusResponse (includes
conspectus_uuid, slot, next_review_at, ETR fields).
Errors
Envelope per ADR 0003.
| HTTP | Code / key | When |
|---|---|---|
400 |
COMMON_400 / IDEMPOTENCY_KEY_REQUIRED |
Missing or empty Idempotency-Key after handler check. |
404 |
USER_404 / USER_NOT_FOUND |
No user for (system_user_id, system_uuid). |
409 |
COMMON_409 |
Same idempotency key reused with different payload hash. |
422 |
Validation | Body fails Pydantic rules (e.g. invalid cue_sheet shape, empty bullets). |
401 / 429 / 413 |
— | Middleware (auth, rate limit, body size). |
Logging
conspectus_created at info after persist; create_conspectus_idempotent_replay on replay.
Standard request_done with path template from metrics.
Single-file deep spec
Conspectus hub — this operation · Field mapping (cue sheet → JSON)
Page history
| Date | Change | Author |
|---|---|---|
| Added Page history section (repository baseline). | Ivan Boyarkin |