rooms:query

Description: Retrieve a list of rooms for the authenticated account.

Rooms are conversation spaces that allow participants to communicate via comments. This endpoint returns rooms that the authenticated person has access to (either as a participant or as the creator).

---

Request Schema

{
  "payload": {
    "type": "rooms:query",
    "q": {
      "per_page": 25,
      "page": 1,
      "name_cont": "project",
      "unread": true,
      "archived": false
    }
  },
  "signature": "payload_ed25519_hex_signature",
  "source_public_key": "your_client_public_key"
}

Request Attributes

• See global request attributes
• See search request attributes, and:

Attribute	Type	Required	Description
q.name_cont	String	No	Records containing a given string in the room name
q.unread	Boolean	No	When true, returns only rooms with unread comments for the authenticated person
q.archived	Boolean	No	When true, returns only archived rooms. When false, returns only active rooms. If omitted, returns both.
q.topic_type_eq	String	No	Filter by topic type (e.g., “Distribution”, “Person”, “Organization”)
q.topic_id_eq	Integer	No	Filter by topic ID
q.created_at_gteq	String	No	Filter rooms created on or after this date (ISO 8601 format)
q.updated_at_gteq	String	No	Filter rooms updated on or after this date (ISO 8601 format)

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-03-18T10:30:00Z",
  "signature": "8b6392d5550605bd6ccddf9c21ebec470de4b44e4b4deb746076e37ab61c5346e07e7c7c7cebb5bbee41cdd92a476bcd3f02373d146ec165b31c31fc31c9ce0d",
  "payload": {
    "type": "rooms:query",
    "q": {
      "per_page": 25,
      "page": 1,
      "total": 10,
      "unread": true,
      "archived": false
    },
    "resources": [
      {
        "id": 123,
        "name": "Project Alpha Discussion",
        "archived": false,
        "archived_at": null,
        "created_at": "2025-03-15T10:00:00Z",
        "updated_at": "2025-03-18T09:30:00Z",
        "last_comment_at": "2025-03-18T09:30:00Z",
        "last_comment_by": "John Doe",
        "unread_count": 3,
        "participants_count": 5,
        "topic": {
          "type": "Distribution",
          "id": 456,
          "name": "Weekly Vegetable Distribution - March 18"
        }
      }
    ]
  }
}

Response Attributes

• payload.q - Object - Query metadata including pagination info
  • per_page - Integer - Items per page
  • page - Integer - Current page number
  • total - Integer - Total number of matching rooms
• payload.resources - Array of room objects:
  • id - Integer - Unique identifier for the room
  • name - String - Room name/title
  • archived - Boolean - Whether the room has been archived
  • archived_at - ISO 8601 timestamp - When the room was archived (null if not archived)
  • created_at - ISO 8601 timestamp - Creation time
  • updated_at - ISO 8601 timestamp - Last update time
  • last_comment_at - ISO 8601 timestamp - When the last comment was posted
  • last_comment_by - String - Name of the person who posted the last comment
  • unread_count - Integer - Number of unread comments for the authenticated person
  • participants_count - Integer - Number of participants in the room
  • topic - Object - Optional associated topic (e.g., Distribution, Person, Organization)
    • type - String - Topic class name
    • id - Integer - Topic ID
    • name - String - Topic display name

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-03-18T10:30:00Z",
  "signature": "...",
  "payload": {
    "type": "rooms:query",
    "q": { "invalid_param": "value" }
  },
  "error": "Error message",
  "status": "bad_request"
}

Real Life Example

Get all active rooms with unread messages

{
  "payload": {
    "type": "rooms:query",
    "q": {
      "per_page": 10,
      "page": 1,
      "unread": true,
      "archived": false
    }
  },
  "signature": "...",
  "source_public_key": "your_client_public_key"
}

Search rooms by name

{
  "payload": {
    "type": "rooms:query",
    "q": {
      "per_page": 20,
      "page": 1,
      "name_cont": "weekly meeting"
    }
  },
  "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 updated_at DESC (most recently active first) by default
• Soft-deleted rooms are automatically excluded from results
• Only rooms where the authenticated person is a participant or the creator are returned
• Authentication can be via token, whitelist, or membership
• The unread_count is calculated based on the authenticated person’s notifications