Mambu Flows REST API Guide
Base URL
All Mambu Flows API calls are made against your tenant's Mambu instance, the same base URL used by the rest of the Mambu v2 API:
https://<tenant>.mambu.com/api
Relative paths in this reference omit the base URL. For example, /destinations means https://<tenant>.mambu.com/api/destinations.
Content-Type and Accept headers
All requests must include the following headers:
| Header | Value | Notes |
|---|---|---|
Accept | application/vnd.mambu.v2+json | Required for all requests |
Content-Type | application/vnd.mambu.v2+json | For JSON request bodies (POST, PUT). Other values return 415 Unsupported Media Type. Only POST /processinstances/{processKey}:start also accepts application/json |
Content-Type | application/octet-stream | For binary file uploads (BPMN/DMN deploy) |
Authentication
All endpoints require HTTP Basic authentication. Provide your Mambu API credentials (username and password) with every request.
GET /api/destinations
Accept: application/vnd.mambu.v2+json
Authorization: Basic <base64-encoded username:password>
Requests without valid credentials return 401 Unauthorized.
For maker-checker endpoints (approve or reject staged definitions), the approving user's credentials must differ from the submitting user's credentials. Attempting self-approval returns 400 Bad Request with errorSource reviewedBy.
Error format
All error responses use the standard Mambu error envelope:
{
"errors": [
{
"errorCode": 4,
"errorSource": "reviewedBy",
"errorReason": "INVALID_PARAMETERS"
}
]
}
| Field | Type | Description |
|---|---|---|
errorCode | integer | Mambu internal error code |
errorSource | string | The field or element that caused the error. For a process error, it also describes the cause, for example serviceTask[id='callRiskApi']: destination 'riskApi' not found or not available |
errorReason | string | Name of the error code, for example INVALID_PARAMETERS or PROCESS_EXECUTION_FAILED. For a readable description, see errorSource and details |
details | array of strings | Extra information, when the error has any. For example, a 409 Conflict on DELETE /processdefinitions/{key} names the process definitions that still call the key |
Common HTTP status codes used across the Mambu Flows API:
| Status | Meaning |
|---|---|
200 OK | Successful GET or action |
201 Created | Resource created (POST) |
204 No Content | Successful request with no response body, for example a DELETE, or a process start that returns no processResult |
400 Bad Request | Invalid request body or parameters, or a rule that the request breaks, for example self-approval or making current a definition that is not approved |
401 Unauthorized | Missing or invalid credentials |
403 Forbidden | Authenticated but not authorised for this operation |
404 Not Found | Resource does not exist |
409 Conflict | The resource is in use (for example, deleting a process definition that another process still calls) |
415 Unsupported Media Type | Wrong Content-Type. See Content-Type and Accept headers |
422 Unprocessable Entity | The process failed while it ran during the call, for example a failing service task during :start (PROCESS_EXECUTION_FAILED) |
Pagination
List endpoints follow standard Mambu pagination. Use offset and limit query parameters to page through results:
GET /api/destinations?offset=0&limit=50
Accept: application/vnd.mambu.v2+json
Authorization: Basic <base64-encoded username:password>
Default and maximum page sizes follow the standard Mambu API limits documented in the core platform API reference.
POST /processinstances:search uses cursor pagination instead of offset: see Searching process instances.
Rate limits
Mambu Flows endpoints are subject to the standard Mambu API rate limits. In addition, some endpoints have their own, stricter limits that apply on top of the standard ones. For example, POST /processinstances/{key}:start is limited by a per-tenant cap on concurrent process starts and by a per-tenant start rate. You may reach these limits before you reach the general API limit.
Requests that exceed any limit return 429 Too Many Requests. Implement exponential back-off when retrying.