room:query

Description: Retrieve a single room by ID.

This endpoint returns detailed information about a specific room, including all participant details. The authenticated person must be a participant in the room or the room creator.

---

Request Schema

{
  "payload": {
    "type": "room:query",
    "id": 123
  },
  "signature": "payload_ed25519_hex_signature",
  "source_public_key": "your_client_public_key"
}

Request Attributes

• See global request attributes

Attribute	Type	Required	Description
id	Integer	Yes	The unique identifier of the room to retrieve

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": "room:query",
    "resource": {
      "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": [
        {
          "id": 1,
          "name": "John Doe"
        },
        {
          "id": 2,
          "name": "Jane Smith"
        },
        {
          "id": 3,
          "name": "Bob Johnson"
        }
      ],
      "topic": {
        "type": "Distribution",
        "id": 456,
        "name": "Weekly Vegetable Distribution - March 18"
      }
    }
  }
}

Response Attributes

• payload.resource - Object - The room object:
  • 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 - Array - List of room participants
    • id - Integer - Person ID
    • name - String - Person display name
  • 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

Room Not Found

{
  "source_public_key": "community_public_key",
  "source_site": {
    "protocol": "https",
    "fqdn": "arkipel.localhost:3000"
  },
  "created_at": "2025-03-18T10:30:00Z",
  "signature": "...",
  "payload": {
    "type": "room:query",
    "id": 123
  },
  "error": "Room not found with id: 123",
  "status": "not_found"
}

Not a Participant (Forbidden)

{
  "source_public_key": "community_public_key",
  "source_site": {
    "protocol": "https",
    "fqdn": "arkipel.localhost:3000"
  },
  "created_at": "2025-03-18T10:30:00Z",
  "signature": "...",
  "payload": {
    "type": "room:query",
    "id": 123
  },
  "error": "Forbidden: You are not a participant in this room",
  "status": "forbidden"
}

Missing ID

{
  "source_public_key": "community_public_key",
  "source_site": {
    "protocol": "https",
    "fqdn": "arkipel.localhost:3000"
  },
  "created_at": "2025-03-18T10:30:00Z",
  "signature": "...",
  "payload": {
    "type": "room:query"
  },
  "error": "Missing required field: id",
  "status": "bad_request"
}

Real Life Example

Get a specific room with full participant details

{
  "payload": {
    "type": "room:query",
    "id": 123
  },
  "signature": "...",
  "source_public_key": "your_client_public_key"
}

---

Usage Notes

• This is an ephemeral query - no message is persisted to the database
• Unlike rooms:query, this endpoint returns full participant details (not just count)
• You must be a participant in the room or the room creator to access it
• Authentication can be via token, whitelist, or membership