rooms:upsert

Description: Create a room or update a single room by ID or import_id.

Rooms are conversation spaces that allow multiple participants to communicate. When creating a room, you must provide at least one participant.

---

Request Schema

{
  "payload": {
    "id": 123,
    "import_id": "ROOM-001",
    "type": "rooms:upsert",
    "name": "Weekly Coordination Meeting",
    "person_id": 456,
    "topic": {
      "type": "Distribution",
      "id": 789
    },
    "participant_ids": [456, 789, 101],
    "remove_participant_ids": []
  },
  "signature": "payload_ed25519_hex_signature",
  "source_public_key": "your_client_public_key"
}

Request Attributes

• See global request attributes

Field Constraints

Field	Type	Required	Default	Max Length	Constraints
id	Integer	No	null	-	Arkipel ID. When set, updates existing record. When omitted, creates new record.
import_id	String	No	Auto-generated	255	Your external system ID for this room. Unique per account. Auto-generated if not provided.
name	String	Conditional	null	255	Room name/title. Required when creating a new room.
person_id	Integer	No	null	-	ID of the primary person associated with this room
topic	Object	No	null	-	Associated topic object (e.g., Distribution, Person, Organization). See Topic fields
participant_ids	Array	Conditional	[]	-	Array of person IDs to add as participants. Required when creating a new room (at least one).
remove_participant_ids	Array	No	[]	-	Array of person IDs to remove from participants. Only the room creator can remove other participants.

Topic Fields

The topic is an optional associated object (e.g., a Distribution, Person, or Organization that this room is about):

Field	Type	Required	Description
type	String	Yes	Topic class name: “Distribution”, “Person”, “Organization”, etc.
id	Integer	Yes	ID of the topic object

Real Life Examples

Creating a New Room

{
  "type": "rooms:upsert",
  "name": "Spring Festival Planning",
  "participant_ids": [101, 102, 103],
  "topic": {
    "type": "Distribution",
    "id": 456
  }
}

Creating a Room with External ID

{
  "type": "rooms:upsert",
  "import_id": "ROOM-2024-001",
  "name": "Monthly Check-in",
  "participant_ids": [101]
}

Updating a Room Name

{
  "type": "rooms:upsert",
  "id": 123,
  "name": "Updated Room Name"
}

Adding Participants

{
  "type": "rooms:upsert",
  "id": 123,
  "participant_ids": [104, 105]
}

Removing Participants (Creator Only)

{
  "type": "rooms:upsert",
  "id": 123,
  "remove_participant_ids": [105]
}

Updating by Import ID

{
  "type": "rooms:upsert",
  "import_id": "ROOM-2024-001",
  "name": "Quarterly Review",
  "participant_ids": [101, 102, 103, 104]
}

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": {
    "message_id": "6916452112f746b2b4cf48c1",
    "type": "rooms:upsert"
  }
}

Response Attributes

• payload.message_id - String - The MongoDB ID of the created message for tracking
• payload.type - String - The message type: “rooms:upsert”

Error Responses

Missing Required Fields (New Room)

{
  "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:upsert",
    "participant_ids": [101]
  },
  "error": "Missing required field: name must be provided for room creation. Please refer to https://devkit.arkipel.co/specs/mutations/rooms-upsert.html",
  "status": "bad_request"
}

No Participants (New Room)

{
  "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:upsert",
    "name": "Test Room"
  },
  "error": "Missing required field: participant_ids must include at least one person for room creation.",
  "status": "bad_request"
}

Unauthorized Participant Removal

{
  "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:upsert",
    "id": 123,
    "remove_participant_ids": [101, 102]
  },
  "error": "Forbidden: Only the room creator can remove other participants. You can only remove yourself.",
  "status": "forbidden"
}

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": "rooms:upsert",
    "id": 99999
  },
  "error": "Couldn't find Room with 'id'=99999",
  "status": "not_found"
}

---

Usage Notes

• This is a persistent mutation - a message is created and processed asynchronously
• The creator is automatically added as a participant when creating a new room
• Only the room creator can remove other participants; others can only remove themselves
• Participants who are removed can be re-added later
• Room archiving is handled separately (not through this endpoint)
• The import_id field allows you to link Arkipel rooms with your external system
• When updating an existing room, only provided fields are changed; omitted fields keep their current values