Inbox

The Inbox is a CQRS read model that provides a state-machine projection of actionable items for the authenticated user. Each item tracks a status (unread, read, actioned, archived) and represents something that requires the user's attention, such as an assigned task, a mention, or a pending approval.

The Inbox is a read-side projection built by background workers (projector:run). Status transitions are persisted immediately when you update them via the API, but new items may take a moment to appear after the originating event.

The inbox item model

Every inbox item represents an actionable event directed at the authenticated user.

Properties

  • Name
    id
    Type
    string
    Description

    Unique identifier for the inbox item (UUID).

  • Name
    event_id
    Type
    string
    Description

    The ID of the source domain event that produced this item.

  • Name
    event_type
    Type
    string
    Description

    The type of event, such as task.assigned, entity.mentioned, approval.requested, or comment.added.

  • Name
    family_code
    Type
    string
    Description

    The entity family this item belongs to, such as task, deal, contact, or approval.

  • Name
    entity_id
    Type
    string
    Description

    The UUID of the entity that this inbox item relates to.

  • Name
    status
    Type
    string
    Description

    Current status of the inbox item. One of unread, read, actioned, or archived.

  • Name
    actor_id
    Type
    string
    Description

    The UUID of the user who triggered the event. For example, the user who assigned the task or posted the comment.

  • Name
    summary
    Type
    string
    Description

    A human-readable summary of the item, such as "Alice assigned you a task: Prepare Q3 report".

  • Name
    occurred_at
    Type
    string
    Description

    ISO 8601 timestamp of when the event originally occurred.

GET/core/api/v1/inbox

List inbox items

Retrieve a paginated list of inbox items for the authenticated user. Results are returned in reverse chronological order by default. Supports cursor-based pagination and filtering by status, family, and custom sorting.

Query parameters

  • Name
    status
    Type
    string
    Description

    Filter items by status. One of unread, read, actioned, or archived.

  • Name
    family
    Type
    string
    Description

    Filter items by entity family code, such as task, deal, contact, or approval.

  • Name
    sort
    Type
    string
    Description

    Field to sort by. Defaults to occurred_at.

  • Name
    direction
    Type
    string
    Description

    Sort direction. One of asc or desc. Defaults to desc.

  • Name
    cursor
    Type
    string
    Description

    Cursor for pagination. Pass the next_cursor value from a previous response to fetch the next page.

  • Name
    limit
    Type
    integer
    Description

    Maximum number of items to return per page. Defaults to 50, maximum 100.

Request

GET
/core/api/v1/inbox
curl -G https://your-sphere.example.com/core/api/v1/inbox \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -d status=unread \
  -d family=task \
  -d sort=occurred_at \
  -d direction=desc \
  -d limit=50

Response

{
  "data": [
    {
      "id": "f1e2d3c4-b5a6-9807-fedc-ba9876543210",
      "event_id": "evt_1a2b3c4d-5e6f-7a8b-9c0d-e1f2a3b4c5d6",
      "event_type": "task.assigned",
      "family_code": "task",
      "entity_id": "t7a8b9c0-d1e2-f3a4-b5c6-d7e8f9a0b1c2",
      "status": "unread",
      "actor_id": "u3c4d5e6-f7a8-b9c0-d1e2-f3a4b5c6d7e8",
      "summary": "Alice assigned you a task: Prepare Q3 report",
      "occurred_at": "2025-06-15T16:45:00Z"
    },
    {
      "id": "e2d3c4b5-a697-0876-edcb-a98765432100",
      "event_id": "evt_2b3c4d5e-6f7a-8b9c-0d1e-f2a3b4c5d6e7",
      "event_type": "comment.added",
      "family_code": "deal",
      "entity_id": "d8b9c0d1-e2f3-a4b5-c6d7-e8f9a0b1c2d3",
      "status": "unread",
      "actor_id": "u4d5e6f7-a8b9-c0d1-e2f3-a4b5c6d7e8f9",
      "summary": "Bob commented on deal: Enterprise License Agreement",
      "occurred_at": "2025-06-15T15:30:00Z"
    }
  ],
  "meta": {
    "next_cursor": "eyJpZCI6ImUyZDNjNGI1LWE2OTctMDg3Ni...",
    "has_more": true
  }
}
GET/core/api/v1/inbox/{id}

Get inbox item

Retrieve a single inbox item by its ID. Returns the full item including its current status.

Path parameters

  • Name
    id
    Type
    string
    Description

    The UUID of the inbox item to retrieve.

Request

GET
/core/api/v1/inbox/{id}
curl https://your-sphere.example.com/core/api/v1/inbox/f1e2d3c4-b5a6-9807-fedc-ba9876543210 \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Response

{
  "data": {
    "id": "f1e2d3c4-b5a6-9807-fedc-ba9876543210",
    "event_id": "evt_1a2b3c4d-5e6f-7a8b-9c0d-e1f2a3b4c5d6",
    "event_type": "task.assigned",
    "family_code": "task",
    "entity_id": "t7a8b9c0-d1e2-f3a4-b5c6-d7e8f9a0b1c2",
    "status": "unread",
    "actor_id": "u3c4d5e6-f7a8-b9c0-d1e2-f3a4b5c6d7e8",
    "summary": "Alice assigned you a task: Prepare Q3 report",
    "occurred_at": "2025-06-15T16:45:00Z"
  }
}
PATCH/core/api/v1/inbox/{id}

Update inbox item status

Update the status of an inbox item. This is a state-machine transition -- valid transitions are: unread to read, read to actioned, and any status to archived. Invalid transitions return a 422 error.

Path parameters

  • Name
    id
    Type
    string
    Description

    The UUID of the inbox item to update.

Required attributes

  • Name
    status
    Type
    string
    Description

    The new status to set. One of read, actioned, or archived.

Request

PATCH
/core/api/v1/inbox/{id}
curl -X PATCH https://your-sphere.example.com/core/api/v1/inbox/f1e2d3c4-b5a6-9807-fedc-ba9876543210 \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"status": "read"}'

Response

{
  "data": {
    "id": "f1e2d3c4-b5a6-9807-fedc-ba9876543210",
    "event_id": "evt_1a2b3c4d-5e6f-7a8b-9c0d-e1f2a3b4c5d6",
    "event_type": "task.assigned",
    "family_code": "task",
    "entity_id": "t7a8b9c0-d1e2-f3a4-b5c6-d7e8f9a0b1c2",
    "status": "read",
    "actor_id": "u3c4d5e6-f7a8-b9c0-d1e2-f3a4b5c6d7e8",
    "summary": "Alice assigned you a task: Prepare Q3 report",
    "occurred_at": "2025-06-15T16:45:00Z"
  }
}
POST/core/api/v1/inbox/mark-all-read

Mark all as read

Mark all unread inbox items as read for the authenticated user. This is a bulk operation that affects all items with the unread status. Returns the number of items that were updated.

This endpoint accepts no request body.

Request

POST
/core/api/v1/inbox/mark-all-read
curl -X POST https://your-sphere.example.com/core/api/v1/inbox/mark-all-read \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Response

{
  "data": {
    "updated_count": 12
  },
  "message": "All unread items have been marked as read."
}
GET/core/api/v1/inbox/counts

Get inbox counts

Retrieve the number of inbox items grouped by status for the authenticated user. Useful for rendering badge counts in navigation menus and notification indicators.

Request

GET
/core/api/v1/inbox/counts
curl https://your-sphere.example.com/core/api/v1/inbox/counts \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Response

{
  "data": {
    "unread": 12,
    "read": 45,
    "actioned": 30,
    "archived": 100
  }
}

Was this page helpful?