Intents and journeys API¶

Intent endpoint¶

Method	Path	Access	Purpose
`POST`	`/intents/compile`	Authenticated	Assess and persist one citizen message

Request:

{
  "message": "I need to correct the address on my National ID."
}

Important response fields:

{
  "intent_id": "INTENT_ID",
  "original_message": "I need to correct the address on my National ID.",
  "supported": true,
  "selected_workflow_code": "GOVERNMENT_RECORD_INFORMATION_UPDATE",
  "response_mode": "JOURNEY_PROPOSAL",
  "assistant_reply": null,
  "explicit_context": {
    "goal": "CORRECT_PERSONAL_INFORMATION",
    "requested_changes": ["ADDRESS"]
  }
}

The complete response also contains inference, uncertainty, verification, candidates, and routing diagnostics.

Journey endpoints¶

Method	Path	Access	Purpose
`GET`	`/journeys`	Authenticated	List every owned journey
`POST`	`/journeys/from-intent/{intent_id}`	High assurance	Create or return the journey for an intent
`GET`	`/journeys/{journey_id}/roadmap`	Authenticated	Return resolved roadmap state
`GET`	`/journeys/{journey_id}/plan`	Authenticated	Return dynamic milestones, questions, and documents
`POST`	`/journeys/{journey_id}/milestones/{milestone_code}/complete`	Authenticated	Persist answers and advance
`GET`	`/journeys/{journey_id}/current-action`	Authenticated	Return one current valid action
`POST`	`/journeys/{journey_id}/reevaluate`	Authenticated	Update allowed intent context and resolve again
`POST`	`/journeys/{journey_id}/evidence-refresh`	High assurance	Resolve again with current vault evidence
`GET`	`/journeys/{journey_id}/debug-resolution`	Authenticated	Return rule-resolution diagnostics

Plan response¶

{
  "journey_id": "JOURNEY_ID",
  "title": "Update Government Record Information",
  "status": "ACTIVE",
  "progress_percent": 25,
  "current_milestone_code": "CONFIRM_REQUESTED_INFORMATION",
  "milestones": [
    {
      "code": "CONFIRM_REQUESTED_INFORMATION",
      "title": "Tell us what needs to change",
      "position": 2,
      "status": "CURRENT",
      "questions": [],
      "documents": []
    }
  ]
}

Complete milestone¶

Request:

{
  "answers": {
    "record": "National ID",
    "requested_change": "Address"
  }
}

The server rejects out-of-order actions with 409 INVALID_JOURNEY_ACTION.

Ownership¶

Compilation claims the intent for the current citizen. Journey creation verifies intent ownership and claims the journey. Every subsequent journey endpoint checks that link.