HTTP API
Status: Accepted · Version: 0.1
Base path: /v1.
Authentication: owner session cookie or bearer token, except POST /v1/sessions and trusted-contact or recipient portal routes, which use their own tokens. A recipient token must be rejected on owner routes and the reverse.
Errors use a JSON body { "error": { "code": "...", "message": "..." } }. Secret rejection uses code secret_rejected and must not echo the submitted value.
Write operations that change the entities in TITIP-010 are audited in the same transaction.
Owner
| Operation | Use |
|---|---|
POST /v1/users |
UC-01 create account |
POST /v1/sessions |
UC-01 sign in (email + OTP at MVP; prototype may stub) |
DELETE /v1/sessions/current |
Revoke session |
GET /v1/me |
Profile and summary counts for the home screen |
Trusted contacts
| Operation | Use |
|---|---|
POST /v1/trusted-contacts |
UC-02 invite |
POST /v1/trusted-contacts/{id}/accept |
Portal accept |
POST /v1/trusted-contacts/{id}/reject |
Portal reject |
POST /v1/trusted-contacts/{id}/verify |
Channel verification |
DELETE /v1/trusted-contacts/{id} |
Owner removes |
Recipients and assets
| Operation | Use |
|---|---|
POST /v1/recipients |
Create a recipient record |
POST /v1/vaults |
Create vault in DRAFT or ACTIVE |
POST /v1/vaults/{id}/assignments |
UC-04 assign one recipient and optional rules |
POST /v1/vaults/{id}/assets |
UC-03 add asset |
POST /v1/vaults/{id}/instructions |
New instruction version. Body is plaintext only on the request; storage is ciphertext |
GET of an instruction returns plaintext only to the owner session or to a recipient token that lists that vault. It never returns plaintext to a trusted-contact token.
Life check
| Operation | Use |
|---|---|
POST /v1/life-check/policies |
UC-05 activate a new immutable version |
GET /v1/life-check/current |
Active version, state, next check date |
POST /v1/life-check/confirm |
Owner confirms from any escalation state |
Simulation and release
| Operation | Use |
|---|---|
POST /v1/simulations |
UC-06 start a simulated cycle |
POST /v1/simulations/{id}/advance |
Advance to a named state or demo day |
GET /v1/release-cases/{id} |
Case with per-vault RELEASABLE or HOLD |
Prototype servers must reject POST /v1/release-cases/{id}/approve with not_available_in_prototype. The route may exist so clients do not invent a different path later. It must not issue tokens.
Admin
| Operation | Use |
|---|---|
POST /v1/admin/release-hold |
Body { "enabled": true, "reason": "..." } |
Reviewer role required. Owner tokens are rejected.
Pagination and ids
List endpoints accept limit (default 20, max 100). Identifiers are prefixed strings. Schemas: ../schemas/.