Skip to main content

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:

HeaderValueNotes
Acceptapplication/vnd.mambu.v2+jsonRequired for all requests
Content-Typeapplication/vnd.mambu.v2+jsonFor JSON request bodies (POST, PUT). Other values return 415 Unsupported Media Type. Only POST /processinstances/{processKey}:start also accepts application/json
Content-Typeapplication/octet-streamFor 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"
}
]
}
FieldTypeDescription
errorCodeintegerMambu internal error code
errorSourcestringThe 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
errorReasonstringName of the error code, for example INVALID_PARAMETERS or PROCESS_EXECUTION_FAILED. For a readable description, see errorSource and details
detailsarray of stringsExtra 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:

StatusMeaning
200 OKSuccessful GET or action
201 CreatedResource created (POST)
204 No ContentSuccessful request with no response body, for example a DELETE, or a process start that returns no processResult
400 Bad RequestInvalid 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 UnauthorizedMissing or invalid credentials
403 ForbiddenAuthenticated but not authorised for this operation
404 Not FoundResource does not exist
409 ConflictThe resource is in use (for example, deleting a process definition that another process still calls)
415 Unsupported Media TypeWrong Content-Type. See Content-Type and Accept headers
422 Unprocessable EntityThe 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.