Prompt History Repository - API Contract

GET /api/v1/prompt-history/api/v1/prompt-history

List prompt history records, filterable by user_id and/or scenario_id

Public

Response Example

{
  "data": [
    {
      "id": "ph_9c1d4e",
      "user_id": "usr_4bc8d2",
      "scenario_id": "missed_activity_3day",
      "activity_id": "act_7e2f9a",
      "rule_id": "rule_8f3a2c",
      "prompt_template_id": "tmpl_re_engage_01",
      "chapter_id": "ch_boston_001",
      "sent_at": "2026-03-22T08:00:00Z",
      "acted_upon_at": null,
      "status": "sent"
    },
    {
      "id": "ph_2a7f8b",
      "user_id": "usr_4bc8d2",
      "scenario_id": "low_mileage_week",
      "activity_id": "act_3d9c1f",
      "rule_id": "rule_3b9e7d",
      "prompt_template_id": "tmpl_mileage_nudge_01",
      "chapter_id": "ch_boston_001",
      "sent_at": "2026-03-18T09:30:00Z",
      "acted_upon_at": "2026-03-18T11:45:00Z",
      "status": "acted_upon"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 87
  }
}

GET /api/v1/prompt-history/api/v1/prompt-history/:id

Fetch a single prompt history record by ID

Public

Response Example

{
  "id": "ph_9c1d4e",
  "user_id": "usr_4bc8d2",
  "scenario_id": "missed_activity_3day",
  "activity_id": "act_7e2f9a",
  "rule_id": "rule_8f3a2c",
  "prompt_template_id": "tmpl_re_engage_01",
  "chapter_id": "ch_boston_001",
  "sent_at": "2026-03-22T08:00:00Z",
  "acted_upon_at": null,
  "status": "sent"
}

POST /api/v1/prompt-history/api/v1/prompt-history

Record a sent scenario prompt (called by the scheduler after dispatch)

Public

Request Example

{
  "user_id": "usr_4bc8d2",
  "scenario_id": "missed_activity_3day",
  "activity_id": "act_7e2f9a",
  "rule_id": "rule_8f3a2c",
  "prompt_template_id": "tmpl_re_engage_01",
  "chapter_id": "ch_boston_001",
  "sent_at": "2026-03-26T08:00:00Z"
}

Response Example

{
  "id": "ph_9c1d4e",
  "user_id": "usr_4bc8d2",
  "scenario_id": "missed_activity_3day",
  "activity_id": "act_7e2f9a",
  "rule_id": "rule_8f3a2c",
  "prompt_template_id": "tmpl_re_engage_01",
  "chapter_id": "ch_boston_001",
  "sent_at": "2026-03-26T08:00:00Z",
  "acted_upon_at": null,
  "status": "sent"
}

PUT /api/v1/prompt-history/api/v1/prompt-history/:id

Update a prompt history record (e.g. mark acted upon, update status)

Public

Request Example

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

Response Example

{
  "id": "ph_9c1d4e",
  "user_id": "usr_4bc8d2",
  "scenario_id": "missed_activity_3day",
  "activity_id": "act_7e2f9a",
  "rule_id": "rule_8f3a2c",
  "prompt_template_id": "tmpl_re_engage_01",
  "chapter_id": "ch_boston_001",
  "sent_at": "2026-03-26T08:00:00Z",
  "acted_upon_at": "2026-03-26T10:05:00Z",
  "status": "acted_upon"
}

DELETE /api/v1/prompt-history/api/v1/prompt-history/:id

Delete a prompt history record

Public

Response Example

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

GET /api/v1/prompt-history/api/v1/prompt-history/check

Check whether a specific prompt has already been sent to a user (deduplication check — maps to hasPromptBeenSent)

Public

Response Example

{
  "already_sent": true,
  "prompt_id": "ph_9c1d4e",
  "sent_at": "2026-03-22T08:00:00Z"
}

GET /api/v1/prompt-history/api/v1/prompt-history/active

Get all unacted-upon prompts currently active for a user

Public

Response Example

{
  "data": [
    {
      "id": "ph_9c1d4e",
      "user_id": "usr_4bc8d2",
      "scenario_id": "missed_activity_3day",
      "activity_id": "act_7e2f9a",
      "prompt_template_id": "tmpl_re_engage_01",
      "sent_at": "2026-03-26T08:00:00Z",
      "status": "sent"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1
  }
}

Additional Metadata

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