HTTP API
ReferenceAPI overview
Base URL, versioning, authentication, action groups and the conventions every call to the Volobox public HTTP API follows.
This page covers what every call to the Volobox public HTTP API has in common: where it lives, how it is versioned, how a caller authenticates, which action groups exist, and the conventions for ids, enums, dates, paging and errors. The endpoints themselves are listed by group in the pages linked from Action groups.
Base URL and versioning
The API lives on your workspace's own address. Every public route starts with /api/v1/:
https://volobox.example.com/api/v1/The OpenAPI document of version 1 and an interactive reference are on the same address:
| What | Path |
|---|---|
| OpenAPI document | /swagger/v1/swagger.json |
| Interactive reference | /swagger |
Both need a sign-in. The interactive reference sends a browser to the sign-in page first, and a script that reads the OpenAPI document sends Authorization: Bearer with any of the bearers below; without one it answers 401. In the interactive reference, Authorize takes a pasted bearer, so Try it out calls the API as that caller. The same document is offered as swagger.json on the API tab of API & MCP in Volobox's settings.
Volobox avoids changing a public contract in place. A breaking change ships as a new action under the next version:
| Change | How it ships |
|---|---|
| A new optional parameter or a new response field | In place, in v1. |
| Removing or retyping a parameter or field, changing a verb, a route or a meaning | A new action under the next version (/api/v2/...). The v1 action keeps answering. |
Write clients that ignore response fields they do not know.
Note
Only routes under /api/v1/ are the public API. Volobox's own app calls other routes for itself (settings, summaries, coding sessions, agents, workflows and more). They are not in the OpenAPI document, change with the app, and are not a contract.
Authentication
Every call sends one bearer in the Authorization header:
GET /api/v1/app-user/my-profile HTTP/1.1
Host: volobox.example.com
Authorization: Bearer vbpt_...A bearer comes through one of three doors:
| Bearer | Looks like | Who creates it | Acts as | Lasts |
|---|---|---|---|---|
| Personal access token | vbpt_... | A person, under Personal Settings > API & MCP > Personal tokens | That person, within the token's action groups | Until the expiry chosen at creation, or until revoked |
| Integration app client secret | vbox_... | An administrator, under Organization Settings > API & MCP | The app itself, not a person | Until the secret is rotated or the app is revoked |
| OAuth access token | Issued by /connect/token | An integration app, through a person's sign-in or the client credentials grant | The person who signed in, or the app | One hour |
Personal access tokens
- A person chooses the token's name, its action groups (from the groups they can use themselves) and when it expires: 30, 90, 180 or 365 days (90 by default), or No expiration.
- The token is shown once, when it is created. The list keeps its name, its last four characters, its groups, its expiry and when it was last used.
- A token's groups are fixed when it is made. To reach another group, create another token.
- Revoke ends a token at once.
- A token is bound to its owner's account security. A password change or reset, a lockout, and turning two-factor authentication on or off all end every personal token of that account.
- A personal token needs no refresh and no sign-in: send it as it is.
Warning
A personal token acts as the person who made it. A token with No expiration works until it is revoked, so keep it on a machine or server you control and revoke it when you stop using it.
OAuth tokens
Integration apps that an administrator registers get tokens from the authorization server on the same address:
| Endpoint | Path |
|---|---|
| Authorization | /connect/authorize |
| Token | /connect/token |
| Rule | Detail |
|---|---|
| Scope | Every token request asks for Volobox. A token issued without it is refused with 401 on every call. |
| Refresh | Add offline_access to the scope of an authorization code request to get a refresh token. |
| PKCE | The authorization code flow requires PKCE with code_challenge_method=S256. |
| Public clients | A public client has no secret: its client id and PKCE are enough. A confidential client also sends its client_secret when it trades the code. |
| Client credentials | grant_type=client_credentials with scope=Volobox gives a token that acts as the app. The app's secret also works directly as a bearer. |
| Access token lifetime | One hour. Use the refresh token, or request another client credentials token, when it expires. |
| Sign-in lifetime | With the standard settings, a person's sign-in through an app ends when it goes unused for about 14 days; the person signs in again. Each use of a refresh token answers a new one: store it in place of the old. |
The whole flow, with the consent page a person sees, is in Build an OAuth integration.
What a bearer reaches
Every bearer reaches only public actions, and only in its own action groups. The caller's own access in Volobox still applies: a token never opens a project, chat or file that the person behind it cannot open.
| Caller | Reaches |
|---|---|
| Personal access token | The groups chosen for the token. |
| A person signed in through an app | The app's groups, less any group the person unticked on the consent page. |
| An app's own secret, or a client credentials token | Audit log only, and never an action about a signed-in person. |
An operation whose description says it acts on the signed-in person's own account (a profile, a setting, a "my ..." list) needs a bearer that stands for a person. An app's own secret is refused there.
Action groups
Every public action belongs to one group. The group is what a token or an app is granted, what the MCP server's volobox_get_connection tool reports, and how the endpoint reference is split.
| Group id | Name | What it covers | With a client secret | Reference |
|---|---|---|---|---|
agenda | Agenda | The signed-in person's agenda, and agenda requests | No | Agenda API |
audit | Audit log | Exporting the organization audit log | Yes | Audit log API |
calendar | Calendar and time off | Time off, bookings, the working calendar's holidays and schedules | No | Calendar API |
conversations | Conversations | Chats, messages, reactions, stars, polls and reminders | No | Conversations API |
docs | Docs | Docs spaces and pages | No | Docs API |
files | Files, inbox, and alerts | Files and shared drives, Inbox items and notifications, alerts | No | Files API |
meetings | Meetings and groups | Meetings, scheduled calls, groups and their members | No | Meetings API |
people | People | The directory, the signed-in person's own profile and status, expertise tags | No | People API |
projects | Projects and tasks | Projects, tasks and requests | No | Projects API |
support | Support | Support tickets and their links to tasks and requests | No | Support API |
workspace | Workspace | Announcements, workspace search and references | No | Workspace API |
Audit log also needs the audit log permission: through a person's sign-in it works only for a person who may view the audit log, and an app's secret works only when an administrator selected Audit log for the app.
Conventions
Operation ids
Every operation has a stable id of dot-separated parts that starts with its group. Most have the form {group}.{resource}.{method}, such as projects.projectTask.getList or people.appUser.getMyProfile; some have two parts (docs.getList) or four (files.fileEntry.share.getMembers), so do not parse an id by position. It is the operationId in the OpenAPI document, so a generated client names each action the same way, and it is the base of the action's tool name on the MCP server.
Enums
An enum is a string of its name, in requests and in responses:
{ "status": "Open", "workState": "InReview" }A request may send the name or the number. A response always gives the name. Send names: the numbers are not part of the documented contract.
Dates and times
| Kind | Format | Example |
|---|---|---|
A calendar day (format: date) | yyyy-MM-dd, with no time or offset. A full timestamp is refused. | 2026-11-14 |
A point in time (format: date-time) | ISO 8601 | 2026-11-14T09:30:00Z |
Paging
Most lists page with three query parameters:
| Parameter | Type | Meaning |
|---|---|---|
SkipCount | integer, 0 or more | How many items to skip. |
MaxResultCount | integer, 1 or more | How many items to return. |
Sorting | string | The sort order, where the operation offers one. |
A paged answer is a PagedResultDto:
{
"items": [
{ "id": "0b7c4d2e-5f1a-4c3b-9e8d-1a2b3c4d5e6f", "title": "Draft the release notes" }
],
"totalCount": 37
}Keep asking with SkipCount increased by the page size until you have totalCount items. A few lists page with a cursor instead: the chat list answers a nextCursor to send back as Cursor, and the audit log export returns the next cursor in the X-Volobox-Next-Cursor response header. Some short lists, such as the caller's own projects, return a plain array.
Empty answers
A lookup that may find nothing, such as the chat of a task, answers 204 No Content with an empty body when there is no such item. The OpenAPI document lists the 204 beside the 200. Treat it as null, not as an error.
Errors
A refused or failed call answers with a JSON body that carries a code and a readable message, except 401 and 503, which have no body: read their headers (WWW-Authenticate, Retry-After) instead.
{
"error": {
"code": "Volobox:Integrations:ActionNotGranted",
"message": "This connection is not allowed to call that action."
}
}| Status | Meaning | What to do |
|---|---|---|
401 | No bearer, or the bearer is unknown, expired, revoked, or a token without the Volobox scope. The answer carries a WWW-Authenticate: Bearer challenge, never a redirect to the sign-in page. | Fix or replace the bearer. A 401 with a personal token means it was revoked, it reached its expiry date, or its owner's password or two-factor setting changed. A 401 with a client secret means it was rotated or the app was revoked. |
403 | The bearer is valid but may not call this action: the action is outside its groups (Volobox:Integrations:ActionNotGranted), or it acts as a person and the caller is an app's own secret (Volobox:Integrations:MemberConnectionRequired). | Grant the group, or call as a person. |
503 with Retry-After | Volobox is busy and shed the request. | Wait the number of seconds in Retry-After, then retry. |
Read error.code to decide what to do, and show error.message to a person.
What outside callers can never do
Some things are not reachable from outside Volobox whatever the bearer:
- Custom app records. An app's records themselves are not reachable over the API or MCP today; only a published record's discussion is, through the Conversations group.
- Volobox's own configuration. Settings, coding sessions, agents, workflows and the other calls the Volobox app makes for itself are not public actions.
- A person's work through an app's secret. An app's own secret acts as nobody, so it reaches only Audit log.
- More than the person behind the bearer. A token never reaches a group it was not given, or one its owner cannot use.
When an AI agent calls through the MCP server, some actions stay a person's own and are refused: a reply that a customer would see on a ticket, a write to a client's drive, and a write into the discussion of an app record whose app keeps agents out. An outside agent also never adds a Volobox agent to a space, project, drive, file, chat or group, and never changes an agent's role there, because that access would outlast the call. Removing an agent still works.