Push Notification Dispatcher - API Contract

GET /api/v1/notifications/api/v1/notifications

List dispatched notifications with delivery status

Public

Response Example

{
  "data": [
    {
      "id": "notif_d1e2f3",
      "user_id": "usr_4bc8d2",
      "title": "Time to log your run!",
      "body": "You haven't recorded an activity in 3 days. Keep your training on track.",
      "scenario_id": "missed_activity_3day",
      "prompt_id": "ph_9c1d4e",
      "device_tokens_targeted": 2,
      "delivered_count": 2,
      "failed_count": 0,
      "sent_at": "2026-03-26T08:00:00Z",
      "status": "sent"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 312
  }
}

GET /api/v1/notifications/api/v1/notifications/:id

Fetch a single notification dispatch record

Public

Response Example

{
  "id": "notif_d1e2f3",
  "user_id": "usr_4bc8d2",
  "title": "Time to log your run!",
  "body": "You haven't recorded an activity in 3 days. Keep your training on track.",
  "data": {
    "deep_link": "eirapp://wizard/activity?scenario=missed_activity_3day&activity_id=act_7e2f9a&chapter_id=ch_boston_001",
    "prompt_id": "ph_9c1d4e",
    "scenario_id": "missed_activity_3day"
  },
  "scenario_id": "missed_activity_3day",
  "prompt_id": "ph_9c1d4e",
  "device_tokens": [
    "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]"
  ],
  "delivered_count": 1,
  "failed_count": 0,
  "sent_at": "2026-03-26T08:00:00Z",
  "status": "sent"
}

POST /api/v1/notifications/api/v1/notifications

Dispatch a push notification to a single user (maps to sendNotification)

Public

Request Example

{
  "user_id": "usr_4bc8d2",
  "title": "Time to log your run!",
  "body": "You haven't recorded an activity in 3 days. Keep your training on track.",
  "data": {
    "deep_link": "eirapp://wizard/activity?scenario=missed_activity_3day&activity_id=act_7e2f9a&chapter_id=ch_boston_001",
    "prompt_id": "ph_9c1d4e",
    "scenario_id": "missed_activity_3day"
  },
  "prompt_id": "ph_9c1d4e",
  "scenario_id": "missed_activity_3day"
}

Response Example

{
  "id": "notif_d1e2f3",
  "user_id": "usr_4bc8d2",
  "title": "Time to log your run!",
  "body": "You haven't recorded an activity in 3 days. Keep your training on track.",
  "device_tokens_targeted": 1,
  "delivered_count": 1,
  "failed_count": 0,
  "sent_at": "2026-03-26T08:00:00Z",
  "status": "sent"
}

PUT /api/v1/notifications/api/v1/notifications/:id

Update a notification record (e.g. mark retried, add resolution note)

Public

Request Example

{
  "status": "retried",
  "retry_note": "Re-sent after token refresh."
}

Response Example

{
  "id": "notif_d1e2f3",
  "status": "retried",
  "retry_note": "Re-sent after token refresh.",
  "updated_at": "2026-03-26T08:05:00Z"
}

DELETE /api/v1/notifications/api/v1/notifications/:id

Delete a notification dispatch record

Public

Response Example

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

POST /api/v1/notifications/api/v1/notifications/batch

Dispatch push notifications to multiple users in one call (maps to sendBatchNotifications)

Public

Request Example

{
  "targets": [
    {
      "user_id": "usr_4bc8d2",
      "title": "Time to log your run!",
      "body": "You haven't recorded an activity in 3 days.",
      "data": {
        "prompt_id": "ph_9c1d4e",
        "scenario_id": "missed_activity_3day",
        "deep_link": "eirapp://wizard/activity?scenario=missed_activity_3day&activity_id=act_7e2f9a&chapter_id=ch_boston_001"
      }
    },
    {
      "user_id": "usr_9ea3c7",
      "title": "Your weekly mileage is below target",
      "body": "You're at 60% of your training plan for this week. A short run today keeps you on track.",
      "data": {
        "prompt_id": "ph_2a7f8b",
        "scenario_id": "low_mileage_week",
        "deep_link": "eirapp://wizard/activity?scenario=low_mileage_week&activity_id=act_1b5c8f&chapter_id=ch_boston_001"
      }
    }
  ]
}

Response Example

{
  "batch_id": "batch_f9a1b2",
  "total": 2,
  "succeeded": 2,
  "failed": 0,
  "results": [
    {
      "user_id": "usr_4bc8d2",
      "notification_id": "notif_d1e2f3",
      "status": "sent"
    },
    {
      "user_id": "usr_9ea3c7",
      "notification_id": "notif_e4f5g6",
      "status": "sent"
    }
  ],
  "sent_at": "2026-03-26T08:00:05Z"
}

GET /api/v1/notifications/api/v1/notifications/device-tokens

Look up registered device tokens for a user (maps to lookupDeviceTokens)

Public

Response Example

{
  "user_id": "usr_4bc8d2",
  "tokens": [
    {
      "token": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]",
      "platform": "ios",
      "registered_at": "2026-01-10T14:00:00Z",
      "last_used_at": "2026-03-25T18:00:00Z"
    }
  ]
}

DELETE /api/v1/notifications/api/v1/notifications/device-tokens/:token

Invalidate and remove a device token (maps to handleTokenInvalidation)

Public

Response Example

{
  "invalidated": true,
  "token": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]",
  "invalidated_at": "2026-03-26T08:01:00Z"
}

Additional Metadata

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