REST API reference

The Collabiro Public API v1 gives your scripts and services company-scoped access to people, upcoming meetings and channel chat over HTTPS.

Base URLhttps://collabiro.com/api/public/v1
Formatapplication/json, camelCase, UTC times (ISO 8601)
AuthCompany API key in X-Api-Key

Authentication

Every request needs a company API key. A company owner or admin creates one in the admin portal under API keys. Give it a name (up to 80 characters), copy the secret, and store it somewhere safe. The secret is shown once and saved only as a SHA-256 hash, so Collabiro cannot show it again. Keys look like vo_xxxxxxxx_…: the first part is a public prefix used to find the key, the rest is the secret.

Send the key in either header:

HTTP
X-Api-Key: vo_xxxxxxxx_your_key
  • The key acts as the person who created it, in that person's company. Messages it posts show as “Name · API”.
  • New keys carry the scopes public,mcp, so the same key also works for the MCP server.
  • Revoke a key from the same page. A revoked or rotated key is rejected straight away with 401.
  • Personal access tokens (vo_pat_…) and OAuth tokens are for /mcp only. The REST API accepts company API keys.
Important. Keep API keys on a server. Do not ship them in a browser app, a mobile app or a public repository: anyone with the key can read your company's channels and post as its owner.

Endpoints

MethodPathWhat it does
GET/membersActive people in the company
GET/meetingsUpcoming calendar meetings (next 14 days)
GET/channelsCompany chat channels
GET/channels/{channelId}/messagesRecent messages in a channel
POST/channels/{channelId}/messagesPost a message to a channel

List members

GET/api/public/v1/members

Returns the active (not deactivated) people in the key's company, sorted by display name.

Example request

Shell
curl https://collabiro.com/api/public/v1/members \
  -H "X-Api-Key: $COLLABIRO_API_KEY"

Example response

200 OK
[
  {
    "userId": "2b7c9e10-4d1a-4c55-9a51-0f3e6b7d8a21",
    "displayName": "Sara Ahmed",
    "email": "sara@example.com",
    "role": "Owner",
    "deactivated": false,
    "avatarVersion": null
  },
  {
    "userId": "8d4f2a66-1b3c-47e9-b0d2-5c6a7e8f9012",
    "displayName": "Omar Khan",
    "email": "omar@example.com",
    "role": "Member",
    "deactivated": false,
    "avatarVersion": null
  }
]

Member object

FieldTypeDescription
userIduuidThe person's id
displayNamestringName shown in the office
emailstringSign-in email
rolestringOwner, Admin or Member
deactivatedbooleanAlways false here, because only active people are listed
avatarVersioninteger | nullNot set by this endpoint

List upcoming meetings

GET/api/public/v1/meetings

Returns calendar meetings from now until 14 days ahead, up to 50. Recurring meetings are expanded into one item per occurrence, and cancelled occurrences are left out.

Example request

Shell
curl https://collabiro.com/api/public/v1/meetings \
  -H "X-Api-Key: $COLLABIRO_API_KEY"

Example response

200 OK
[
  {
    "id": "c1a2b3d4-e5f6-4789-a0b1-c2d3e4f5a6b7",
    "title": "Design review",
    "startsAtUtc": "2026-11-21T08:00:00Z",
    "endsAtUtc": "2026-11-21T08:30:00Z",
    "spaceId": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
    "spaceName": "Meeting Room A",
    "zoomJoinUrl": null,
    "organizerUserId": "2b7c9e10-4d1a-4c55-9a51-0f3e6b7d8a21",
    "organizerName": "Sara Ahmed",
    "canManage": false,
    "attendees": [
      { "userId": "8d4f2a66-1b3c-47e9-b0d2-5c6a7e8f9012", "displayName": "Omar Khan", "email": "omar@example.com", "rsvp": "Accepted" }
    ],
    "notes": null,
    "recurrence": "weekly",
    "recurrenceUntilUtc": null,
    "timeZoneId": "Asia/Riyadh",
    "seriesId": "c1a2b3d4-e5f6-4789-a0b1-c2d3e4f5a6b7",
    "occurrenceStartsAtUtc": "2026-11-21T08:00:00Z",
    "isException": false,
    "myRsvp": null,
    "roomConflict": null,
    "sourceMessageId": null,
    "recurrenceDays": null,
    "recurrenceCount": null,
    "reminderMinutes": null
  }
]

Meeting object (main fields)

FieldTypeDescription
iduuidMeeting id
titlestringMeeting title
startsAtUtc / endsAtUtcdate-timeStart and end of this occurrence, in UTC
spaceId / spaceNameuuid / stringThe office room the meeting is in
zoomJoinUrlstring | nullExternal join link, if one was added
organizerUserId / organizerNameuuid / stringWho organised it
attendeesarrayuserId, displayName, email and rsvp (for example Pending or Accepted)
recurrencestringnone for one-off meetings, otherwise the repeat rule
seriesId / occurrenceStartsAtUtcuuid / date-timeIdentify one occurrence of a recurring series
timeZoneIdstringIANA time zone the meeting was created in
notesstring | nullMeeting notes text, if any

List channels

GET/api/public/v1/channels

Returns the company's chat channels, sorted by name. Direct messages and private groups are never included. Use the id with the message endpoints below.

Example request

Shell
curl https://collabiro.com/api/public/v1/channels \
  -H "X-Api-Key: $COLLABIRO_API_KEY"

Example response

200 OK
[
  { "id": "6f1d2c3b-8a4e-4f7a-9b2c-1d3e5f7a9b0c", "name": "general", "createdAtUtc": "2026-11-01T09:00:00Z", "archived": false },
  { "id": "0a9b8c7d-6e5f-4a3b-9c2d-1e0f9a8b7c6d", "name": "design", "createdAtUtc": "2026-11-03T12:30:00Z", "archived": false }
]

Channel object

FieldTypeDescription
iduuidChannel id
namestringChannel name, without the #
createdAtUtcdate-timeWhen it was created
archivedbooleanArchived channels can be read but not posted to

Read recent channel messages

GET/api/public/v1/channels/{channelId}/messages

Returns the most recent top-level messages in a channel, oldest first. Thread replies are not included (see replyCount), and disappearing messages that have expired are left out.

Parameters

NameInTypeDescription
channelIdpathuuidChannel id from List channels
takequeryintegerHow many messages to return. Default 20, clamped to 1 to 50.

Example request

Shell
curl https://collabiro.com/api/public/v1/channels/6f1d2c3b-8a4e-4f7a-9b2c-1d3e5f7a9b0c/messages?take=20 \
  -H "X-Api-Key: $COLLABIRO_API_KEY"

Example response

200 OK
{
  "messages": [
    {
      "id": "7f8e9d0c-1b2a-4394-8576-a1b2c3d4e5f6",
      "userId": "8d4f2a66-1b3c-47e9-b0d2-5c6a7e8f9012",
      "userName": "Omar Khan",
      "content": "New icons are ready for review",
      "sentAtUtc": "2026-11-20T10:15:00Z",
      "spaceId": null,
      "groupId": "6f1d2c3b-8a4e-4f7a-9b2c-1d3e5f7a9b0c",
      "attachment": null,
      "reactions": [ { "emoji": "👍", "count": 1, "users": [ { "userId": "2b7c9e10-4d1a-4c55-9a51-0f3e6b7d8a21", "userName": "Sara Ahmed" } ] } ],
      "parentMessageId": null,
      "replyCount": 2,
      "mentions": [],
      "editedAtUtc": null,
      "deletedAtUtc": null,
      "sequence": 1042,
      "expiresAtUtc": null
    }
  ],
  "hasMore": false
}

Message fields

FieldTypeDescription
messagesarrayMessage objects, oldest first
hasMorebooleanAlways false on this endpoint. Use take to ask for up to 50.
id / userId / userNameuuid / uuid / stringMessage id and author
contentstringMessage text. Mentions keep their text form.
sentAtUtcdate-timeWhen it was sent
attachmentobject | nullfileName, contentType, sizeBytes, isImage, isAudio
reactionsarrayEmoji, count and who reacted
replyCountintegerNumber of thread replies
editedAtUtc / deletedAtUtcdate-time | nullSet when the message was edited or deleted
sequenceintegerIncreasing order number within the conversation

Post a channel message

POST/api/public/v1/channels/{channelId}/messages

Posts a new top-level message to a channel as the key's owner. Everyone in the channel sees it immediately, mentions notify as usual, and a chat.message webhook fires. The author name gets a “ · API” suffix so people can tell it came from an integration.

Parameters

NameInTypeDescription
channelIdpathuuidChannel to post in
contentbodystringMessage text, 1 to 8,000 characters. Required.

Example request

Shell
curl -X POST https://collabiro.com/api/public/v1/channels/6f1d2c3b-8a4e-4f7a-9b2c-1d3e5f7a9b0c/messages \
  -H "X-Api-Key: $COLLABIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"Deploy finished: version 1.4 is live."}'

Example response

200 OK
{
  "id": "9a8b7c6d-5e4f-4321-9abc-def012345678",
  "userId": "2b7c9e10-4d1a-4c55-9a51-0f3e6b7d8a21",
  "userName": "Sara Ahmed · API",
  "content": "Deploy finished: version 1.4 is live.",
  "sentAtUtc": "2026-11-20T16:02:11Z",
  "spaceId": null,
  "groupId": "6f1d2c3b-8a4e-4f7a-9b2c-1d3e5f7a9b0c",
  "attachment": null,
  "reactions": [],
  "parentMessageId": null,
  "replyCount": 0,
  "mentions": [],
  "editedAtUtc": null,
  "deletedAtUtc": null,
  "sequence": 1043,
  "expiresAtUtc": null
}

Errors

Errors use standard HTTP status codes. The body is a short text message, or JSON with an error field.

StatusWhenExample body
400Empty message or longer than 8,000 characters, or the channel is archivedMessage is invalid. · This channel is archived.
401Missing, malformed, unknown, revoked or rotated-away keyInvalid or missing API key.
403The key does not have the public scope, or the company is suspended{"error":"This API key does not include the public scope."}
404The channel does not exist, is not a channel, or belongs to another companyConversation not found.

Good practice

  • Cache the channel list and look channels up by name, instead of calling /channels before every post.
  • Retry 5xx errors with a short backoff. Do not retry 4xx errors without changing the request.
  • Create one key per integration with a clear name, so you can revoke one without breaking the others. The portal shows when each key was last used.
  • For real-time updates, use webhooks instead of polling for new messages.

OpenAPI

The API is described by an OpenAPI document named Collabiro Public API (/swagger/public/swagger.json). It is served by development builds of the API. If you run Collabiro from source, start the API and open Swagger UI to try each endpoint with your key.

Questions

Is there a rate limit on the REST API?

The per-minute limit (60 requests a minute by default, set per company) applies to the MCP endpoint. Keep REST polling modest and prefer webhooks for real-time updates.

Can the API read direct messages?

No. The Public API only lists company channels and reads channel messages. Direct messages and private groups are never returned.

Can I delete or edit messages with the API?

No. The Public API is read-only apart from posting new channel messages.

Which time zone are times in?

All times are UTC in ISO 8601 format, for example 2026-11-21T08:00:00Z. Meetings also include the IANA time zone they were created in.

Last updated 20 November 2026. Something missing or wrong? Tell us.