Developers

Guide

Make your first API call

Create a personal access token, read your own profile and list your open tasks over the Volobox HTTP API, with curl, Node.js, C# or Python.

At the end of this guide you have a personal access token and a script that reads your own Volobox profile and lists the open tasks assigned to you. Any member of a workspace can do it: the token acts as you, so it reaches only what you can open yourself.

Before you begin

  • A Volobox account in your workspace, and its address (this guide uses https://volobox.example.com).
  • One of: curl, Node.js 18 or later (save the example as an .mjs file), .NET 8 or later, or Python 3 with the requests package.

Create a personal access token

  1. In Volobox, open your menu, choose Settings, and open API & MCP.
  2. Under Personal tokens, click Create token.
  3. Give the token a name, such as "First API call".
  4. Select the action groups it may use. For this guide, select People and Projects and tasks. You can only select groups you can use yourself.
  5. Choose when it expires. 30 days is enough to try the API.
  6. Create the token and copy it. It starts with vbpt_.

Warning: The token is shown once

Copy the token before you close the dialog; Volobox cannot show it again. Anyone who holds it acts as you within its groups, so keep it out of source control. If you lose it, revoke it and create another.

Personal Settings, API & MCP, API tab: the Create token dialog with a token name, the action groups the token may use (Agenda, People, Projects and tasks, Conversations and more) and an expiry, over the list of personal tokens.
The Create token dialog in Personal Settings, API & MCP: a name, the action groups the token may use, and when it expires.

Keep the token in an environment variable for the rest of this guide:

export VOLOBOX_TOKEN='vbpt_...'

Read your profile

Send the token as a bearer to GET /api/v1/app-user/my-profile:

curl -s https://volobox.example.com/api/v1/app-user/my-profile \
  -H "Authorization: Bearer $VOLOBOX_TOKEN"

The answer is your profile as JSON: id, userName, name, surname, email, jobTitle and more. The OpenAPI document described in the API overview has the full response schema.

List your open tasks

GET /api/v1/project-task/by-assignee lists the tasks assigned to a person across the projects you can open. Without an assignee it lists yours. Status filters by status name, and SkipCount and MaxResultCount page the answer. The examples continue the scripts above:

curl -s "https://volobox.example.com/api/v1/project-task/by-assignee?Status=Open&MaxResultCount=10" \
  -H "Authorization: Bearer $VOLOBOX_TOKEN"

The answer is one page, { "items": [...], "totalCount": ... }. To read the next page, send SkipCount=10 with the same filters. Status and work state come back as names, such as "Open" and "InProgress".

Check that it works

  • The profile call prints your own user name and email address.
  • The task call prints how many open tasks are assigned to you, then up to ten of them with their number, title, project and work state. With none assigned, it prints 0 open tasks.
  • On Personal Settings > API & MCP, the token's row shows when it was last used.

Troubleshooting

SymptomFix
401 on every callThe Authorization header is missing or not Bearer followed by the token. Check that VOLOBOX_TOKEN is set in the shell that runs the script.
401 with a token that worked beforeThe token was revoked or reached its expiry date, or your password was changed or reset, or two-factor authentication was turned on or off, which ends every personal token. Create a new token.
403 with Volobox:Integrations:ActionNotGrantedThe action is in a group the token does not have. A token's groups are fixed when it is made: create another token with that group.
You lost the tokenIt cannot be shown again. Revoke it on its row and create another.
The task list is empty but you have tasksStatus=Open leaves out drafts and closed tasks, and the list covers only projects you can open.

Next steps