Huddle

Huddle is where an organization talks: everyone in its huddle, its Cypress Manager and Cedar; channels for a topic (#titles), open or private; threads under any message; direct messages between two people (or a person and their Cypress Manager); a person's own room with Cedar; and the deal lanes of a sale. People see the same rooms in Cypress (Huddle, on a computer) and in Grove (on a phone). The Inbox holds what needs a person: a direct message, a mention, a new offer, a match for a buy plan, a closing step, a task handed to them, what Cedar needs.

Your app reads and posts as the person or agent its token acts for, and sees exactly what they would see on the screen: the rooms they are in, the open channels they may join, never someone else's room with Cedar or a private channel they were not added to.

Since 1.9.0.

Who may call

• An app acting for a person (Connect Cypress) reads and posts as that person.
• An agent's token reads, posts, replies and reacts as the agent, in the rooms the agent is in. Joining, opening channels and adding people are a person's.
• A CM token reads the organization named in Cypress-Organization; with view=mine, every room the Cypress Manager is in, in every organization. A Cypress Manager may join any customer organization's huddle or open channel (the room reads "Ana from Cypress joined"); a private channel only when someone in it adds them.
• An API key never reaches conversations (403 PEOPLE_ONLY): a message is always someone's, never the organization's.

Every write takes ?dryRun=true (it checks the caller, the scope and the body, and posts nothing) and an Idempotency-Key.

List the rooms

curl "$BASE/api/v1/huddle/rooms" -H "authorization: Bearer $TOKEN"

{
  "view": "org",
  "org": { "id": "org_coastal", "name": "Coastal Rent A Car" },
  "rooms": [
    { "id": "rm_1", "kind": "ORG_HUDDLE", "title": "Coastal Rent A Car huddle", "member": true, "unread": 2,
      "last": { "preview": "Sam: Pickup at 9", "at": "2026-10-28T14:02:11.000Z" } },
    { "id": "rm_7", "kind": "TEAM", "title": "#titles", "isPrivate": false, "member": true, "unread": 0, "last": null }
  ],
  "joinable": [
    { "id": "rm_9", "kind": "TEAM", "title": "#weekly-list", "member": false, "memberCount": 4 }
  ],
  "inboxUnread": 3
}

kind is ORG_HUDDLE, TEAM (a channel), DIRECT (a direct message, its title the other person's name), AGENT (the person's room with Cedar) or DEAL_LANE. The organization's huddle is made the first time anyone opens Huddle, with its active members, its Cypress Manager and Cedar.

Read a room

curl "$BASE/api/v1/huddle/rooms/rm_1/messages?limit=50" -H "authorization: Bearer $TOKEN"

Up to 100 messages, oldest first. before (a time, ISO 8601) pages back; thread (a message id) reads that message's replies. Each message carries its author (kind is PERSON, STAFF for Cypress or AGENT), body, mentions, attachments (each with a url that opens for a member of the room), reactions, replyCount, and, when Grove posted a card (an offer, a closing, a task), the card and cardSummary: the card in words, with an href when it names a Cypress page. A pinned message has pinned (when, and byId, who pinned it); otherwise pinned is null.

Pins

Anyone in a room pins a message or a card to it, and anyone unpins it: several per room, 50 at most. A pin says so in the room ("Dana pinned a message"); an unpin is quiet. Pins show above the conversation in Cypress and Grove, oldest first, and Cedar reads them as the room's standing facts. A room about one thing (a car, Reports) has its own card as its first pin, until someone unpins it.

curl -X POST "$BASE/api/v1/huddle/messages/msg_1/pin" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "pinned": true }'

curl "$BASE/api/v1/huddle/rooms/rm_1/pins" -H "Authorization: Bearer $TOKEN"

A line the room wrote (someone joined) and a deleted message cannot be pinned (409); someone outside the room gets 404.

Post

curl -X POST "$BASE/api/v1/huddle/rooms/rm_1/messages" \
  -H "authorization: Bearer $TOKEN" -H "content-type: application/json" \
  -H "Idempotency-Key: 6f1c…" \
  -d '{ "body": "@Sam the title for the Tahoe came in" }'

parentId posts in a message's thread. Up to 4,000 characters. A mention is @ and the first name, or the whole name without spaces when two people share a first name (an ambiguous first name mentions nobody). Mentioning someone puts it in their Inbox; @Cedar gets Cedar's answer in the room; mentioning the organization's Cypress Manager adds them to the room. Post in a room you are in: join an open one first.

Direct messages

curl -X POST "$BASE/api/v1/huddle/direct" \
  -H "authorization: Bearer $TOKEN" -H "content-type: application/json" \
  -d '{ "personId": "usr_sam" }'

{ "roomId": "rm_31", "created": true }

One private room per pair: the same roomId every time (created is false after the first). With one of the organization's people or its Cypress Manager, never an agent. Every message in it reaches the other person's Inbox (kind DIRECT) and, unless they turned it off in Grove, their phone's lock screen. Post in it with post_huddle_message.

Errors