HTTP API

Reference

API 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/:

Text
https://volobox.example.com/api/v1/

The OpenAPI document of version 1 and an interactive reference are on the same address:

WhatPath
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:

ChangeHow it ships
A new optional parameter or a new response fieldIn place, in v1.
Removing or retyping a parameter or field, changing a verb, a route or a meaningA 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:

HTTP
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:

BearerLooks likeWho creates itActs asLasts
Personal access tokenvbpt_...A person, under Personal Settings > API & MCP > Personal tokensThat person, within the token's action groupsUntil the expiry chosen at creation, or until revoked
Integration app client secretvbox_...An administrator, under Organization Settings > API & MCPThe app itself, not a personUntil the secret is rotated or the app is revoked
OAuth access tokenIssued by /connect/tokenAn integration app, through a person's sign-in or the client credentials grantThe person who signed in, or the appOne 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:

EndpointPath
Authorization/connect/authorize
Token/connect/token
RuleDetail
ScopeEvery token request asks for Volobox. A token issued without it is refused with 401 on every call.
RefreshAdd offline_access to the scope of an authorization code request to get a refresh token.
PKCEThe authorization code flow requires PKCE with code_challenge_method=S256.
Public clientsA 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 credentialsgrant_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 lifetimeOne hour. Use the refresh token, or request another client credentials token, when it expires.
Sign-in lifetimeWith 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.

CallerReaches
Personal access tokenThe groups chosen for the token.
A person signed in through an appThe app's groups, less any group the person unticked on the consent page.
An app's own secret, or a client credentials tokenAudit 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 idNameWhat it coversWith a client secretReference
agendaAgendaThe signed-in person's agenda, and agenda requestsNoAgenda API
auditAudit logExporting the organization audit logYesAudit log API
calendarCalendar and time offTime off, bookings, the working calendar's holidays and schedulesNoCalendar API
conversationsConversationsChats, messages, reactions, stars, polls and remindersNoConversations API
docsDocsDocs spaces and pagesNoDocs API
filesFiles, inbox, and alertsFiles and shared drives, Inbox items and notifications, alertsNoFiles API
meetingsMeetings and groupsMeetings, scheduled calls, groups and their membersNoMeetings API
peoplePeopleThe directory, the signed-in person's own profile and status, expertise tagsNoPeople API
projectsProjects and tasksProjects, tasks and requestsNoProjects API
supportSupportSupport tickets and their links to tasks and requestsNoSupport API
workspaceWorkspaceAnnouncements, workspace search and referencesNoWorkspace 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:

JSON
{ "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

KindFormatExample
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 86012026-11-14T09:30:00Z

Paging

Most lists page with three query parameters:

ParameterTypeMeaning
SkipCountinteger, 0 or moreHow many items to skip.
MaxResultCountinteger, 1 or moreHow many items to return.
SortingstringThe sort order, where the operation offers one.

A paged answer is a PagedResultDto:

JSON
{
  "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.

JSON
{
  "error": {
    "code": "Volobox:Integrations:ActionNotGranted",
    "message": "This connection is not allowed to call that action."
  }
}
StatusMeaningWhat to do
401No 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.
403The 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-AfterVolobox 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.