Notification Model - API Contract

GET /api/v1/notification-models/api/v1/notification-models

List all notification model definitions (types and their schema)

Public

Response Example

{
  "data": [
    {
      "id": "model_peer_mention",
      "type": "peer_mention",
      "label": "Peer Mention",
      "schema_version": "1.0",
      "required_fields": [
        "user_id",
        "entity_id",
        "entity_type",
        "title",
        "body"
      ],
      "supports_deep_link": true,
      "created_at": "2026-01-10T00:00:00Z"
    },
    {
      "id": "model_task_assigned",
      "type": "task_assigned",
      "label": "Task Assigned",
      "schema_version": "1.0",
      "required_fields": [
        "user_id",
        "entity_id",
        "entity_type",
        "title",
        "body"
      ],
      "supports_deep_link": true,
      "created_at": "2026-01-10T00:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 8
  }
}

GET /api/v1/notification-models/api/v1/notification-models/:id

Get schema and metadata for a specific notification model type

Public

Response Example

{
  "id": "model_peer_mention",
  "type": "peer_mention",
  "label": "Peer Mention",
  "schema_version": "1.0",
  "required_fields": [
    "user_id",
    "entity_id",
    "entity_type",
    "title",
    "body"
  ],
  "optional_fields": [
    "deep_link",
    "image_url"
  ],
  "supports_deep_link": true,
  "sample": {
    "user_id": "user_xyz789",
    "type": "peer_mention",
    "title": "Alex mentioned you",
    "body": "Great work!",
    "entity_id": "checkin_def456",
    "entity_type": "check_in"
  },
  "created_at": "2026-01-10T00:00:00Z"
}

POST /api/v1/notification-models/api/v1/notification-models

Register a new notification model type

Public

Request Example

{
  "type": "badge_earned",
  "label": "Badge Earned",
  "schema_version": "1.0",
  "required_fields": [
    "user_id",
    "entity_id",
    "entity_type",
    "title",
    "body"
  ],
  "optional_fields": [
    "deep_link",
    "badge_image_url"
  ],
  "supports_deep_link": true
}

Response Example

{
  "id": "model_badge_earned",
  "type": "badge_earned",
  "label": "Badge Earned",
  "schema_version": "1.0",
  "required_fields": [
    "user_id",
    "entity_id",
    "entity_type",
    "title",
    "body"
  ],
  "optional_fields": [
    "deep_link",
    "badge_image_url"
  ],
  "supports_deep_link": true,
  "created_at": "2026-03-26T10:05:00Z"
}

PUT /api/v1/notification-models/api/v1/notification-models/:id

Update an existing notification model definition

Public

Request Example

{
  "schema_version": "1.1",
  "optional_fields": [
    "deep_link",
    "badge_image_url",
    "xp_awarded"
  ]
}

Response Example

{
  "id": "model_badge_earned",
  "type": "badge_earned",
  "label": "Badge Earned",
  "schema_version": "1.1",
  "required_fields": [
    "user_id",
    "entity_id",
    "entity_type",
    "title",
    "body"
  ],
  "optional_fields": [
    "deep_link",
    "badge_image_url",
    "xp_awarded"
  ],
  "supports_deep_link": true,
  "updated_at": "2026-03-26T11:00:00Z"
}

DELETE /api/v1/notification-models/api/v1/notification-models/:id

Remove a notification model type definition

Public

Response Example

{
  "success": true,
  "deleted_id": "model_badge_earned"
}

Additional Metadata

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