Introduction
How the BPMS.ai HTTP API is organized.
BPMS.ai is headless: everything the platform does is available through one HTTP API, the same for the dashboard, the command-line interface, and your integrations. Permissions, not separate APIs, decide what each caller may do.
Paths
Every path has the form /api/v{n}/<package>/<resource>. The version is shared by the whole API, v1 today, and the package segment names the area of the platform, for example /api/v1/auth/login or /api/v1/access/roles.
The OpenAPI contract
The platform publishes its own contract:
| URL | What it serves |
|---|---|
/v3/api-docs | The OpenAPI document of the API. |
/swagger-ui.html | An interactive Swagger UI over that document. |
Each operation has one tag, named after its package, and a stable operationId, such as listRoles. Renaming either is treated as a breaking change, so clients can generate code from the contract.
Errors
Every error is application/problem+json (RFC 9457) with the same shape. Its main members:
| Member | Content |
|---|---|
status | The HTTP status. |
title | The HTTP reason phrase, for example Unauthorized. |
detail | A sentence for the client; it never holds internal details. |
code | A stable error code, such as core.authentication-required. Branch on it, never on detail. |
requestId | The value of the X-Request-Id response header, which ties the answer to the server logs. |
errors | For invalid input only: one entry per field, with field and message. |
Get started
- Authentication: sign in and get a token.
- First call: list the roles of your tenant.
- API clients: call the API from Postman, Swagger UI, or another client.
Resources
| Page | What it covers |
|---|---|
| Users | List, create, update, disable, enable, and delete the users of a tenant, and reset their passwords. |
| Roles and authorities | Manage the roles of a tenant and their authorities, and assign roles to users. |
| Model tree | List, create, rename, move, and delete the folders and models of the process model tree. |
| MCP access tokens | Create, list, and revoke the tokens that let an MCP client act as you. |
| App agent | Chat with the AI agent of BPMS.ai, read your conversations, and see how an installation sets up its AI provider. |