Scenario Deep Link Handler - API Contract

GET /api/v1/scenario-deep-links/api/v1/scenario-deep-links

List generated deep links (useful for audit and QA)

Public

Response Example

{
  "data": [
    {
      "id": "dl_7a1b2c",
      "prompt_id": "ph_9c1d4e",
      "user_id": "usr_4bc8d2",
      "scenario_id": "missed_activity_3day",
      "route_uri": "eirapp://wizard/activity?scenario=missed_activity_3day&activity_id=act_7e2f9a&chapter_id=ch_boston_001",
      "wizard_route": "/activity-wizard",
      "created_at": "2026-03-26T08:00:00Z",
      "acted_upon_at": null
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 43
  }
}

GET /api/v1/scenario-deep-links/api/v1/scenario-deep-links/:id

Fetch a single deep link record

Public

Response Example

{
  "id": "dl_7a1b2c",
  "prompt_id": "ph_9c1d4e",
  "user_id": "usr_4bc8d2",
  "scenario_id": "missed_activity_3day",
  "activity_id": "act_7e2f9a",
  "chapter_id": "ch_boston_001",
  "route_uri": "eirapp://wizard/activity?scenario=missed_activity_3day&activity_id=act_7e2f9a&chapter_id=ch_boston_001",
  "wizard_route": "/activity-wizard",
  "wizard_args": {
    "scenario_id": "missed_activity_3day",
    "activity_id": "act_7e2f9a",
    "chapter_id": "ch_boston_001",
    "prefill_date": "2026-03-24"
  },
  "created_at": "2026-03-26T08:00:00Z",
  "acted_upon_at": null
}

POST /api/v1/scenario-deep-links/api/v1/scenario-deep-links

Generate a deep link for a scenario prompt (maps to buildWizardRouteArgs + getRouteUri)

Public

Request Example

{
  "prompt_id": "ph_9c1d4e",
  "user_id": "usr_4bc8d2",
  "scenario_id": "missed_activity_3day",
  "activity_id": "act_7e2f9a",
  "chapter_id": "ch_boston_001"
}

Response Example

{
  "id": "dl_7a1b2c",
  "prompt_id": "ph_9c1d4e",
  "user_id": "usr_4bc8d2",
  "scenario_id": "missed_activity_3day",
  "activity_id": "act_7e2f9a",
  "chapter_id": "ch_boston_001",
  "route_uri": "eirapp://wizard/activity?scenario=missed_activity_3day&activity_id=act_7e2f9a&chapter_id=ch_boston_001",
  "wizard_route": "/activity-wizard",
  "wizard_args": {
    "scenario_id": "missed_activity_3day",
    "activity_id": "act_7e2f9a",
    "chapter_id": "ch_boston_001",
    "prefill_date": "2026-03-24"
  },
  "created_at": "2026-03-26T09:00:00Z",
  "acted_upon_at": null
}

PUT /api/v1/scenario-deep-links/api/v1/scenario-deep-links/:id

Update deep link record metadata

Public

Request Example

{
  "acted_upon_at": "2026-03-26T10:05:00Z"
}

Response Example

{
  "id": "dl_7a1b2c",
  "prompt_id": "ph_9c1d4e",
  "acted_upon_at": "2026-03-26T10:05:00Z",
  "updated_at": "2026-03-26T10:05:00Z"
}

DELETE /api/v1/scenario-deep-links/api/v1/scenario-deep-links/:id

Delete a deep link record

Public

Response Example

{
  "deleted": true,
  "id": "dl_7a1b2c"
}

PATCH /api/v1/scenario-deep-links/api/v1/scenario-deep-links/:prompt_id/acted-upon

Mark a prompt as acted upon after the user navigates via deep link (maps to markPromptActedUpon)

Public

Request Example

{
  "acted_upon_at": "2026-03-26T10:05:00Z"
}

Response Example

{
  "prompt_id": "ph_9c1d4e",
  "acted_upon_at": "2026-03-26T10:05:00Z",
  "status": "acted_upon"
}

GET /api/v1/scenario-deep-links/api/v1/scenario-deep-links/route

Resolve the wizard route URI for a prompt without persisting a deep link record (maps to getRouteUri)

Public

Response Example

{
  "prompt_id": "ph_9c1d4e",
  "route_uri": "eirapp://wizard/activity?scenario=missed_activity_3day&activity_id=act_7e2f9a&chapter_id=ch_boston_001",
  "wizard_route": "/activity-wizard",
  "expires_at": "2026-03-27T08:00:00Z"
}

Additional Metadata

{
  "contract_summary": {
    "total_contracts": 410,
    "total_endpoints": 2416,
    "api_styles_used": [
      "rest"
    ]
  },
  "generated_at": "2026-03-26T06:55:53.316Z"
}