# API overview

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](#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:

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

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

| 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](/docs/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](/docs/api-agenda) |
| `audit` | Audit log | Exporting the organization audit log | Yes | [Audit log API](/docs/api-audit) |
| `calendar` | Calendar and time off | Time off, bookings, the working calendar's holidays and schedules | No | [Calendar API](/docs/api-calendar) |
| `conversations` | Conversations | Chats, messages, reactions, stars, polls and reminders | No | [Conversations API](/docs/api-conversations) |
| `docs` | Docs | Docs spaces and pages | No | [Docs API](/docs/api-docs) |
| `files` | Files, inbox, and alerts | Files and shared drives, Inbox items and notifications, alerts | No | [Files API](/docs/api-files) |
| `meetings` | Meetings and groups | Meetings, scheduled calls, groups and their members | No | [Meetings API](/docs/api-meetings) |
| `people` | People | The directory, the signed-in person's own profile and status, expertise tags | No | [People API](/docs/api-people) |
| `projects` | Projects and tasks | Projects, tasks and requests | No | [Projects API](/docs/api-projects) |
| `support` | Support | Support tickets and their links to tasks and requests | No | [Support API](/docs/api-support) |
| `workspace` | Workspace | Announcements, workspace search and references | No | [Workspace API](/docs/api-workspace) |

**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](/docs/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

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

```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."
  }
}
```

| 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](/docs/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.

## Related

- [Make your first API call](/docs/first-api-call)
- [Build an OAuth integration](/docs/oauth-integration)
- [MCP server](/docs/mcp-server)
- [Webhooks](/docs/webhooks)
- [API, MCP and webhooks](/docs/api-and-mcp)
