inbox:query

Description: Retrieve a consolidated inbox view of unread discussions and recent activity.

This endpoint returns a unified view of rooms with unread messages, including recent comments, room metadata, and contextual information about related todos and notes. It’s designed to provide everything needed for an inbox-style interface in a single call.

Request Schema

{
  "payload": {
    "type": "inbox:query",
    "q": {
      "include_content": true,
      "max_comments_per_room": 3,
      "since": "2025-04-14T10:00:00Z",
      "include_read": false
    }
  },
  "signature": "payload_ed25519_hex_signature",
  "source_public_key": "your_client_public_key"
}

Request Attributes

See global request attributes

Attribute	Type	Required	Default	Description
`q.include_content`	Boolean	No	false	When `true`, includes full HTML content of comments. When `false`, only returns content snippets.
`q.max_comments_per_room`	Integer	No	3	Maximum number of comments to return per room
`q.since`	String	No	null	Only include rooms with activity since this ISO 8601 timestamp
`q.include_read`	Boolean	No	false	When `true`, includes rooms with no unread messages but recent activity

Authentication Behavior

This endpoint follows Pattern A: Full Account Access.

All authentication methods see the same data - rooms are filtered by participation (person must be a participant or creator of the room).

Response Schema

{
  "source_public_key": "community_public_key",
  "source_site": {
    "protocol": "https",
    "fqdn": "arkipel.localhost:3000"
  },
  "created_at": "2025-04-15T14:30:00Z",
  "signature": "8b6392d5550605bd6ccddf9c21ebec470de4b44e4b4deb746076e37ab61c5346e07e7c7c7cebb5bbee41cdd92a476bcd3f02373d146ec165b31c31fc31c9ce0d",
  "payload": {
    "type": "inbox:query",
    "q": {
      "include_content": true,
      "max_comments_per_room": 3,
      "since": "2025-04-14T10:00:00Z",
      "include_read": false
    },
    "total_unread_rooms": 5,
    "total_unread_comments": 12,
    "resources": [
      {
        "room": {
          "id": 9415,
          "name": "Discussion about competitor analysis",
          "unread_count": 3,
          "last_comment_at": "2026-04-15T08:27:22Z",
          "last_comment_by": "Rip",
          "topic": {
            "type": "Note",
            "id": 8,
            "name": "Competitor Analysis"
          },
          "participants": [
            { "id": 1, "name": "Benjamin" },
            { "id": 2, "name": "Rip" }
          ]
        },
        "unread_comments": [
          {
            "id": 25432,
            "person": "Rip",
            "content": "Testing the room read functionality",
            "content_snippet": "Testing the room read functionality",
            "created_at": "2026-04-15T08:27:22Z",
            "is_unread": true
          }
        ],
        "topic_context": {
          "todos": [
            {
              "id": 123,
              "title": "Review pricing",
              "status": "completed",
              "assigned_to_me": true,
              "due_on": "2026-04-10"
            }
          ],
          "attached_notes": [
            {
              "id": 8,
              "title": "Competitor Analysis",
              "body_snippet": "Analysis of features and pricing...",
              "source": "taskable"
            }
          ]
        }
      }
    ]
  }
}

Response Attributes

payload.q - Object - Query metadata including the original query parameters
payload.total_unread_rooms - Integer - Total number of rooms with unread messages
payload.total_unread_comments - Integer - Total number of unread comments across all rooms
payload.resources - Array of inbox entries, each containing:

Room Object

Field	Type	Description
`id`	Integer	Unique identifier for the room
`name`	String	Room name/title
`unread_count`	Integer	Number of unread comments in this room
`last_comment_at`	String	ISO 8601 timestamp of the most recent comment
`last_comment_by`	String	Name of the person who posted the last comment
`topic`	Object	Optional associated topic (see Topic fields below)
`participants`	Array	List of room participants with `id` and `name`

Topic Object (within room)

Field	Type	Description
`type`	String	Topic class name (e.g., “Note”, “Distribution”)
`id`	Integer	Topic ID
`name`	String	Topic display name

Unread Comments Array

Each entry in unread_comments contains:

Field	Type	Description
`id`	Integer	Unique identifier for the comment
`person`	String	Display name of the comment author
`content`	String	Full HTML content (only when `include_content: true`)
`content_snippet`	String	Truncated plain text preview of the comment
`created_at`	String	ISO 8601 timestamp when the comment was posted
`is_unread`	Boolean	Always `true` for unread comments in the inbox

Topic Context Object (optional)

Field	Type	Description
`todos`	Array	Related todos for the topic (see Todo fields below)
`attached_notes`	Array	Notes attached to the topic (see Note fields below)

Todo Fields

Field	Type	Description
`id`	Integer	Todo ID
`title`	String	Todo title
`status`	String	Todo status: “pending”, “completed”, or “archived”
`assigned_to_me`	Boolean	Whether the todo is assigned to the authenticated person
`due_on`	String	Due date in YYYY-MM-DD format (optional)

Note Fields

Field	Type	Description
`id`	Integer	Note ID
`title`	String	Note title
`body_snippet`	String	Truncated preview of the note body
`source`	String	How the note is linked: “taskable” (activity) or “subject” (subject)

Error Responses

When an invalid query parameter is provided:

{
  "source_public_key": "community_public_key",
  "source_site": {
    "protocol": "https",
    "fqdn": "arkipel.localhost:3000"
  },
  "created_at": "2025-04-15T14:30:00Z",
  "signature": "...",
  "payload": {
    "type": "inbox:query",
    "q": { "since": "invalid-date" }
  },
  "error": "Invalid date format for 'since' parameter. Use ISO 8601 format (e.g., 2025-04-15T10:00:00Z)",
  "status": "bad_request"
}

Real Life Examples

Get basic inbox (unread only)

{
  "payload": {
    "type": "inbox:query",
    "q": {
      "include_content": false,
      "max_comments_per_room": 3,
      "include_read": false
    }
  },
  "signature": "...",
  "source_public_key": "your_client_public_key"
}

Get inbox with full content

{
  "payload": {
    "type": "inbox:query",
    "q": {
      "include_content": true,
      "max_comments_per_room": 5,
      "include_read": false
    }
  },
  "signature": "...",
  "source_public_key": "your_client_public_key"
}

Get inbox with recent activity (including read rooms)

{
  "payload": {
    "type": "inbox:query",
    "q": {
      "include_content": false,
      "max_comments_per_room": 2,
      "since": "2025-04-14T10:00:00Z",
      "include_read": true
    }
  },
  "signature": "...",
  "source_public_key": "your_client_public_key"
}

Usage Notes

This is an ephemeral query - no message is persisted to the database
Rooms are ordered by last_comment_at DESC (most recently active first)
Only rooms where the authenticated person is a participant or creator are returned
The topic_context is only included when the room has an associated topic (e.g., linked to a Note or Distribution)
When include_read is false (default), only rooms with unread_count > 0 are returned
The since parameter is useful for “refresh” scenarios where you want to check for new activity since your last poll
This endpoint is designed to power inbox/notification-style UIs with a single API call