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.
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:
X-Api-Key: vo_xxxxxxxx_your_keyAuthorization: Bearer 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/mcponly. The REST API accepts company API keys.
Endpoints
| Method | Path | What it does |
|---|---|---|
| GET | /members | Active people in the company |
| GET | /meetings | Upcoming calendar meetings (next 14 days) |
| GET | /channels | Company chat channels |
| GET | /channels/{channelId}/messages | Recent messages in a channel |
| POST | /channels/{channelId}/messages | Post 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
curl https://collabiro.com/api/public/v1/members \
-H "X-Api-Key: $COLLABIRO_API_KEY"using System.Net.Http.Json;
using var http = new HttpClient { BaseAddress = new Uri("https://collabiro.com/api/public/v1/") };
http.DefaultRequestHeaders.Add("X-Api-Key", Environment.GetEnvironmentVariable("COLLABIRO_API_KEY"));
var members = await http.GetFromJsonAsync<List<Member>>("members");
public sealed record Member(Guid UserId, string DisplayName, string Email, string Role, bool Deactivated);const res = await fetch("https://collabiro.com/api/public/v1/members", {
headers: { "X-Api-Key": process.env.COLLABIRO_API_KEY }
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const data = await res.json();Example response
[
{
"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
| Field | Type | Description |
|---|---|---|
userId | uuid | The person's id |
displayName | string | Name shown in the office |
email | string | Sign-in email |
role | string | Owner, Admin or Member |
deactivated | boolean | Always false here, because only active people are listed |
avatarVersion | integer | null | Not 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
curl https://collabiro.com/api/public/v1/meetings \
-H "X-Api-Key: $COLLABIRO_API_KEY"using System.Net.Http.Json;
using var http = new HttpClient { BaseAddress = new Uri("https://collabiro.com/api/public/v1/") };
http.DefaultRequestHeaders.Add("X-Api-Key", Environment.GetEnvironmentVariable("COLLABIRO_API_KEY"));
var meetings = await http.GetFromJsonAsync<List<Meeting>>("meetings");
public sealed record Attendee(Guid UserId, string DisplayName, string Email, string Rsvp);
public sealed record Meeting(Guid Id, string Title, DateTime StartsAtUtc, DateTime EndsAtUtc,
Guid SpaceId, string SpaceName, string? ZoomJoinUrl, string OrganizerName, List<Attendee> Attendees);const res = await fetch("https://collabiro.com/api/public/v1/meetings", {
headers: { "X-Api-Key": process.env.COLLABIRO_API_KEY }
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const data = await res.json();Example response
[
{
"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)
| Field | Type | Description |
|---|---|---|
id | uuid | Meeting id |
title | string | Meeting title |
startsAtUtc / endsAtUtc | date-time | Start and end of this occurrence, in UTC |
spaceId / spaceName | uuid / string | The office room the meeting is in |
zoomJoinUrl | string | null | External join link, if one was added |
organizerUserId / organizerName | uuid / string | Who organised it |
attendees | array | userId, displayName, email and rsvp (for example Pending or Accepted) |
recurrence | string | none for one-off meetings, otherwise the repeat rule |
seriesId / occurrenceStartsAtUtc | uuid / date-time | Identify one occurrence of a recurring series |
timeZoneId | string | IANA time zone the meeting was created in |
notes | string | null | Meeting 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
curl https://collabiro.com/api/public/v1/channels \
-H "X-Api-Key: $COLLABIRO_API_KEY"using System.Net.Http.Json;
using var http = new HttpClient { BaseAddress = new Uri("https://collabiro.com/api/public/v1/") };
http.DefaultRequestHeaders.Add("X-Api-Key", Environment.GetEnvironmentVariable("COLLABIRO_API_KEY"));
var channels = await http.GetFromJsonAsync<List<Channel>>("channels");
var general = channels!.First(c => c.Name == "general");
public sealed record Channel(Guid Id, string Name, DateTime CreatedAtUtc, bool Archived);const res = await fetch("https://collabiro.com/api/public/v1/channels", {
headers: { "X-Api-Key": process.env.COLLABIRO_API_KEY }
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const data = await res.json();Example response
[
{ "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
| Field | Type | Description |
|---|---|---|
id | uuid | Channel id |
name | string | Channel name, without the # |
createdAtUtc | date-time | When it was created |
archived | boolean | Archived 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
| Name | In | Type | Description |
|---|---|---|---|
channelId | path | uuid | Channel id from List channels |
take | query | integer | How many messages to return. Default 20, clamped to 1 to 50. |
Example request
curl https://collabiro.com/api/public/v1/channels/6f1d2c3b-8a4e-4f7a-9b2c-1d3e5f7a9b0c/messages?take=20 \
-H "X-Api-Key: $COLLABIRO_API_KEY"using System.Net.Http.Json;
using var http = new HttpClient { BaseAddress = new Uri("https://collabiro.com/api/public/v1/") };
http.DefaultRequestHeaders.Add("X-Api-Key", Environment.GetEnvironmentVariable("COLLABIRO_API_KEY"));
var page = await http.GetFromJsonAsync<HistoryPage>("channels/6f1d2c3b-8a4e-4f7a-9b2c-1d3e5f7a9b0c/messages?take=20");
public sealed record Message(Guid Id, Guid UserId, string UserName, string Content, DateTime SentAtUtc, int ReplyCount);
public sealed record HistoryPage(List<Message> Messages, bool HasMore);const res = await fetch("https://collabiro.com/api/public/v1/channels/6f1d2c3b-8a4e-4f7a-9b2c-1d3e5f7a9b0c/messages?take=20", {
headers: { "X-Api-Key": process.env.COLLABIRO_API_KEY }
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const data = await res.json();Example response
{
"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
| Field | Type | Description |
|---|---|---|
messages | array | Message objects, oldest first |
hasMore | boolean | Always false on this endpoint. Use take to ask for up to 50. |
id / userId / userName | uuid / uuid / string | Message id and author |
content | string | Message text. Mentions keep their text form. |
sentAtUtc | date-time | When it was sent |
attachment | object | null | fileName, contentType, sizeBytes, isImage, isAudio |
reactions | array | Emoji, count and who reacted |
replyCount | integer | Number of thread replies |
editedAtUtc / deletedAtUtc | date-time | null | Set when the message was edited or deleted |
sequence | integer | Increasing 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
| Name | In | Type | Description |
|---|---|---|---|
channelId | path | uuid | Channel to post in |
content | body | string | Message text, 1 to 8,000 characters. Required. |
Example request
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."}'using System.Net.Http.Json;
using var http = new HttpClient { BaseAddress = new Uri("https://collabiro.com/api/public/v1/") };
http.DefaultRequestHeaders.Add("X-Api-Key", Environment.GetEnvironmentVariable("COLLABIRO_API_KEY"));
var channelId = Guid.Parse("6f1d2c3b-8a4e-4f7a-9b2c-1d3e5f7a9b0c");
using var response = await http.PostAsJsonAsync(
$"channels/{channelId}/messages",
new { content = "Deploy finished: version 1.4 is live." });
response.EnsureSuccessStatusCode();
var message = await response.Content.ReadFromJsonAsync<ChatMessage>();
public sealed record ChatMessage(Guid Id, Guid UserId, string UserName, string Content, DateTime SentAtUtc, Guid? GroupId);const res = await fetch("https://collabiro.com/api/public/v1/channels/6f1d2c3b-8a4e-4f7a-9b2c-1d3e5f7a9b0c/messages", {
method: "POST",
headers: {
"X-Api-Key": process.env.COLLABIRO_API_KEY,
"Content-Type": "application/json"
},
body: JSON.stringify({ content: "Deploy finished: version 1.4 is live." })
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const message = await res.json();Example response
{
"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.
| Status | When | Example body |
|---|---|---|
400 | Empty message or longer than 8,000 characters, or the channel is archived | Message is invalid. · This channel is archived. |
401 | Missing, malformed, unknown, revoked or rotated-away key | Invalid or missing API key. |
403 | The key does not have the public scope, or the company is suspended | {"error":"This API key does not include the public scope."} |
404 | The channel does not exist, is not a channel, or belongs to another company | Conversation not found. |
Good practice
- Cache the channel list and look channels up by name, instead of calling
/channelsbefore every post. - Retry
5xxerrors with a short backoff. Do not retry4xxerrors 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.