Documents and agent API¶

Government document endpoints¶

All vault endpoints require high assurance.

Method	Path	Purpose
`GET`	`/documents/catalog`	Supported document types, MIME types, and upload limit
`POST`	`/documents`	Upload one owner-scoped private copy
`GET`	`/documents`	List safe summaries for the current citizen
`POST`	`/documents/{document_id}/signed-url`	Create short-lived owner-scoped access

Upload¶

curl -X POST \
  -H "Authorization: Bearer $EAKTO_SESSION" \
  -F "document_code=MARRIAGE_CERTIFICATE" \
  -F "file=@synthetic-marriage-certificate.pdf;type=application/pdf" \
  http://localhost:8000/api/v1/documents

Use only synthetic files in development.

Journey agent endpoints¶

Method	Path	Purpose
`POST`	`/journeys/{journey_id}/agent/continue`	Run one bounded current-action assistance operation
`GET`	`/journeys/{journey_id}/agent/status`	Read the latest safe agent state
`GET`	`/journeys/{journey_id}/agent/debug`	Development/test-only safe diagnostics
`POST`	`/journeys/{journey_id}/guidance/translate`	Translate current guidance
`POST`	`/journeys/{journey_id}/guidance/speech`	Generate written speech-style guidance
`POST`	`/journeys/{journey_id}/documents/consent`	Record journey-scoped extraction consent
`POST`	`/journeys/{journey_id}/documents/extract`	Extract and normalize an allowed file

Translation request¶

{
  "target_lang": "fil"
}

The backend builds the source guidance from the current action. The caller cannot provide a provider prompt.

Document extraction¶

The extraction request is multipart:

file — PDF, JPEG, or PNG;
consent_id — active consent belonging to the journey.

Normalized evidence remains unverified until citizen confirmation.

Current authorization gap

The journey-agent router does not currently attach the same authentication and resource-ownership dependencies used by the main journey router. Treat these routes as local prototype endpoints only. Do not expose them publicly until authentication, ownership, high-assurance checks where appropriate, and abuse controls are added and tested.