API v3 reference
Every call acts as one user: a user's token (Authorization: Bearer), or the service key (x-api-key) for the service account. How to use it: the client API.
The address is https://<site>/api/v3. The server serves this document at /api/v3/openapi.json, with no credential: a client, or an agent, can read it there.
Credentials
token: A user's token, from POST /tokens (Authorization: Bearer <token>).serviceKey: The service key (API_KEY): the service account (header x-api-key).
Errors are { "error": { "code", "message" } }, with the status the error's kind gives. Lists are { "items", "next" }: ask for the next page with ?cursor=<next>; next is absent on the last page.
Operations
| Operation |
Does |
| GET /me |
Who this call acts as, and what they may do |
| GET /processes/startable |
The start events this user may use, with their forms |
| POST /processes/{name}/start |
Start a process as this user |
| GET /tasks |
The waiting tasks this user has a part in, oldest first; with status=completed, the ones they completed, newest first |
| GET /tasks/{id} |
One task, with its instance's data and its form |
| POST /tasks/{id}/claim |
The task becomes this user's |
| POST /tasks/{id}/complete |
Complete the task, recording this user |
| GET /instances |
The instances this user may see, newest first |
| GET /instances/{id} |
One instance: its data and items |
| DELETE /instances/{id} |
Delete it (administrators) |
| GET /instances/{id}/rationale |
Why it went the way it did, step by step |
| POST /instances/{id}/events/{elementId} |
A start event of the running instance |
| POST /instances/{id}/restart |
Run an item again, and the instance on from it |
| GET /models |
The models, with where a person opens each |
| GET /models/{name} |
A model: its BPMN XML, its .feature, where a person opens it |
| PUT /models/{name} |
Create or change a model: checked first (with errors, refused unless force=true); laid out when it has no diagram (design) |
| DELETE /models/{name} |
Delete a model (design) |
| POST /models/{name}/rename |
Rename a model (design) |
| POST /models/{name}/verify |
Check a model without saving it: the source given, else the saved model |
| GET /models/{name}/elements/{elementId} |
One element: its type, name, documentation, lane, assignment and form |
| GET /models/{name}/feature |
The tests of the model: its .feature |
| PUT /models/{name}/feature |
Write the tests of the model: a .feature that reads as tests; with base, only over the text it came from (design) |
| POST /models/{name}/test |
Run the tests of the model (its .feature, or the one given), in the engine (design) |
| POST /rules/{name} |
Evaluate a decision table of the models folder with the data given, as a business rule task does; nothing changes |
| POST /messages/{id} |
A message, to what waits for it or starts on it (the system) |
| POST /signals/{id} |
A signal, to everything that waits for it (the system) |
| GET /users |
The users (an administrator; never an AI link) |
| POST /users |
Add a user (an administrator) |
| DELETE /users/{userName} |
Delete a user, and end their tokens (an administrator; not themselves) |
| PUT /users/{userName}/groups |
Set a user’s groups, and end their tokens (an administrator) |
| POST /users/{userName}/password |
Set a user’s password (an administrator) |
| GET /settings |
Every setting by group: its value (secrets as ***), where it comes from (an administrator; an AI link at the administer level) |
| GET /settings/schema |
The settings’ schema: each setting’s type, default, description, group, and whether it is a secret |
| POST /settings/checks/{name} |
Run a check: database, engine, url (SITE_URL) or email |
| POST /tokens |
A token for one of the application's users (the service key) |
| DELETE /tokens |
Revoke every token of a user (the service key) |
Who am I
GET /me
Who this call acts as, and what they may do.
| Answer |
Means |
Body |
| 200 |
The user |
Me |
| 401 |
No credential, or an unknown, expired or revoked token |
Error |
Processes
GET /processes/startable
The start events this user may use, with their forms.
| Answer |
Means |
Body |
| 200 |
A list |
{ items, next } |
| 401 |
No credential, or an unknown, expired or revoked token |
Error |
POST /processes/{name}/start
Start a process as this user.
| Parameter |
In |
Type |
Required |
Description |
name |
path |
string |
yes |
The model |
Body (JSON):
| Field |
Type |
Required |
Description |
data |
object |
|
|
startNodeId |
string |
|
|
| Answer |
Means |
Body |
| 201 |
The instance, and this user's first task in it |
{ instance: Instance, task: Task or null } |
| 400 |
The input is not right |
Error |
| 401 |
No credential, or an unknown, expired or revoked token |
Error |
| 404 |
No such thing, or not this user's to see |
Error |
Tasks
GET /tasks
The waiting tasks this user has a part in, oldest first; with status=completed, the ones they completed, newest first.
| Parameter |
In |
Type |
Required |
Description |
limit |
query |
integer |
|
default 50, at least 1, at most 200 |
cursor |
query |
string |
|
A page's next |
status |
query |
"waiting" or "completed" |
|
completed: the latest this user completed (limit, default 10) |
| Answer |
Means |
Body |
| 200 |
A page |
{ items, next } |
| 400 |
The input is not right |
Error |
| 401 |
No credential, or an unknown, expired or revoked token |
Error |
GET /tasks/{id}
One task, with its instance's data and its form.
| Parameter |
In |
Type |
Required |
Description |
id |
path |
string |
yes |
The task |
| Answer |
Means |
Body |
| 200 |
The task |
TaskWithForm |
| 401 |
No credential, or an unknown, expired or revoked token |
Error |
| 404 |
No such thing, or not this user's to see |
Error |
POST /tasks/{id}/claim
The task becomes this user's.
| Parameter |
In |
Type |
Required |
Description |
id |
path |
string |
yes |
The task |
| Answer |
Means |
Body |
| 200 |
The task |
{ task: Task } |
| 401 |
No credential, or an unknown, expired or revoked token |
Error |
| 404 |
No such thing, or not this user's to see |
Error |
| 409 |
It is not waiting, or it is someone else's |
Error |
POST /tasks/{id}/complete
Complete the task, recording this user.
| Parameter |
In |
Type |
Required |
Description |
id |
path |
string |
yes |
The task |
Body (JSON):
| Field |
Type |
Required |
Description |
data |
object |
|
|
| Answer |
Means |
Body |
| 200 |
The task and its instance |
{ task: Task, instance: Instance } |
| 400 |
The input is not right |
Error |
| 401 |
No credential, or an unknown, expired or revoked token |
Error |
| 403 |
Not this user's to do |
Error |
| 404 |
No such thing, or not this user's to see |
Error |
| 409 |
It is not waiting, or it is someone else's |
Error |
Instances
GET /instances
The instances this user may see, newest first.
| Parameter |
In |
Type |
Required |
Description |
status |
query |
string |
|
|
name |
query |
string |
|
|
limit |
query |
integer |
|
default 50, at least 1, at most 200 |
cursor |
query |
string |
|
A page's next |
| Answer |
Means |
Body |
| 200 |
A page |
{ items, next } |
| 400 |
The input is not right |
Error |
| 401 |
No credential, or an unknown, expired or revoked token |
Error |
GET /instances/{id}
One instance: its data and items.
| Parameter |
In |
Type |
Required |
Description |
id |
path |
string |
yes |
The instance |
| Answer |
Means |
Body |
| 200 |
The instance |
InstanceWithItems |
| 401 |
No credential, or an unknown, expired or revoked token |
Error |
| 404 |
No such thing, or not this user's to see |
Error |
DELETE /instances/{id}
Delete it (administrators).
| Parameter |
In |
Type |
Required |
Description |
id |
path |
string |
yes |
The instance |
| Answer |
Means |
Body |
| 200 |
Deleted |
{ deleted } |
| 401 |
No credential, or an unknown, expired or revoked token |
Error |
| 403 |
Not this user's to do |
Error |
| 404 |
No such thing, or not this user's to see |
Error |
GET /instances/{id}/rationale
Why it went the way it did, step by step.
| Parameter |
In |
Type |
Required |
Description |
id |
path |
string |
yes |
The instance |
| Answer |
Means |
Body |
| 200 |
Its steps |
{ id, name, status, data, steps } |
| 401 |
No credential, or an unknown, expired or revoked token |
Error |
| 404 |
No such thing, or not this user's to see |
Error |
POST /instances/{id}/events/{elementId}
A start event of the running instance.
| Parameter |
In |
Type |
Required |
Description |
id |
path |
string |
yes |
The instance |
elementId |
path |
string |
yes |
The start event |
Body (JSON):
| Field |
Type |
Required |
Description |
data |
object |
|
|
| Answer |
Means |
Body |
| 200 |
The instance |
{ instance: Instance } |
| 401 |
No credential, or an unknown, expired or revoked token |
Error |
| 404 |
No such thing, or not this user's to see |
Error |
| 422 |
The engine refused it |
Error |
POST /instances/{id}/restart
Run an item again, and the instance on from it.
| Parameter |
In |
Type |
Required |
Description |
id |
path |
string |
yes |
The instance |
Body (JSON, required):
| Field |
Type |
Required |
Description |
itemId |
string |
yes |
|
data |
object |
|
|
| Answer |
Means |
Body |
| 200 |
The instance |
{ instance: Instance } |
| 400 |
The input is not right |
Error |
| 401 |
No credential, or an unknown, expired or revoked token |
Error |
| 404 |
No such thing, or not this user's to see |
Error |
| 422 |
The engine refused it |
Error |
Models and their tests
GET /models
The models, with where a person opens each.
| Answer |
Means |
Body |
| 200 |
A list |
{ items, next } |
| 401 |
No credential, or an unknown, expired or revoked token |
Error |
GET /models/{name}
A model: its BPMN XML, its .feature, where a person opens it.
| Parameter |
In |
Type |
Required |
Description |
name |
path |
string |
yes |
The model |
| Answer |
Means |
Body |
| 200 |
The model |
{ name, source, feature, url } |
| 400 |
The input is not right |
Error |
| 401 |
No credential, or an unknown, expired or revoked token |
Error |
| 404 |
No such thing, or not this user's to see |
Error |
PUT /models/{name}
Create or change a model: checked first (with errors, refused unless force=true); laid out when it has no diagram (design).
| Parameter |
In |
Type |
Required |
Description |
name |
path |
string |
yes |
The model |
force |
query |
boolean |
|
|
Body (JSON, required):
| Field |
Type |
Required |
Description |
source |
string |
yes |
The BPMN XML |
| Answer |
Means |
Body |
| 200 |
Changed |
ModelSaved |
| 201 |
Created |
ModelSaved |
| 400 |
The input is not right |
Error |
| 401 |
No credential, or an unknown, expired or revoked token |
Error |
| 403 |
Not this user's to do |
Error |
| 404 |
No such thing, or not this user's to see |
Error |
| 422 |
The engine refused it |
Error |
DELETE /models/{name}
Delete a model (design).
| Parameter |
In |
Type |
Required |
Description |
name |
path |
string |
yes |
The model |
| Answer |
Means |
Body |
| 200 |
Deleted |
{ deleted } |
| 401 |
No credential, or an unknown, expired or revoked token |
Error |
| 403 |
Not this user's to do |
Error |
| 404 |
No such thing, or not this user's to see |
Error |
POST /models/{name}/rename
Rename a model (design).
| Parameter |
In |
Type |
Required |
Description |
name |
path |
string |
yes |
The model |
Body (JSON, required):
| Field |
Type |
Required |
Description |
newName |
string |
yes |
|
| Answer |
Means |
Body |
| 200 |
Renamed |
{ name, renamedFrom } |
| 400 |
The input is not right |
Error |
| 401 |
No credential, or an unknown, expired or revoked token |
Error |
| 403 |
Not this user's to do |
Error |
| 404 |
No such thing, or not this user's to see |
Error |
| 409 |
It is not waiting, or it is someone else's |
Error |
POST /models/{name}/verify
Check a model without saving it: the source given, else the saved model.
| Parameter |
In |
Type |
Required |
Description |
name |
path |
string |
yes |
The model |
Body (JSON):
| Field |
Type |
Required |
Description |
source |
string |
|
|
| Answer |
Means |
Body |
| 200 |
Its check |
Check |
| 400 |
The input is not right |
Error |
| 401 |
No credential, or an unknown, expired or revoked token |
Error |
| 404 |
No such thing, or not this user's to see |
Error |
GET /models/{name}/elements/{elementId}
One element: its type, name, documentation, lane, assignment and form.
| Parameter |
In |
Type |
Required |
Description |
name |
path |
string |
yes |
The model |
elementId |
path |
string |
yes |
The element |
| Answer |
Means |
Body |
| 200 |
The element |
{ id, type, name, documentation, lane, assignment, form: Form } |
| 400 |
The input is not right |
Error |
| 401 |
No credential, or an unknown, expired or revoked token |
Error |
| 404 |
No such thing, or not this user's to see |
Error |
GET /models/{name}/feature
The tests of the model: its .feature.
| Parameter |
In |
Type |
Required |
Description |
name |
path |
string |
yes |
The model |
| Answer |
Means |
Body |
| 200 |
The text |
{ name, text } |
| 400 |
The input is not right |
Error |
| 401 |
No credential, or an unknown, expired or revoked token |
Error |
PUT /models/{name}/feature
Write the tests of the model: a .feature that reads as tests; with base, only over the text it came from (design).
| Parameter |
In |
Type |
Required |
Description |
name |
path |
string |
yes |
The model |
Body (JSON, required):
| Field |
Type |
Required |
Description |
text |
string |
yes |
|
base |
string |
|
|
| Answer |
Means |
Body |
| 200 |
Saved |
{ name, saved } |
| 400 |
The input is not right |
Error |
| 401 |
No credential, or an unknown, expired or revoked token |
Error |
| 403 |
Not this user's to do |
Error |
| 409 |
It is not waiting, or it is someone else's |
Error |
POST /models/{name}/test
Run the tests of the model (its .feature, or the one given), in the engine (design).
| Parameter |
In |
Type |
Required |
Description |
name |
path |
string |
yes |
The model |
raw |
query |
boolean |
|
|
Body (JSON):
| Field |
Type |
Required |
Description |
source |
string |
|
A .feature, not saved |
| Answer |
Means |
Body |
| 200 |
Each scenario |
TestRun |
| 400 |
The input is not right |
Error |
| 401 |
No credential, or an unknown, expired or revoked token |
Error |
| 403 |
Not this user's to do |
Error |
| 404 |
No such thing, or not this user's to see |
Error |
| 422 |
The engine refused it |
Error |
Rules
POST /rules/{name}
Evaluate a decision table of the models folder with the data given, as a business rule task does; nothing changes.
| Parameter |
In |
Type |
Required |
Description |
name |
path |
string |
yes |
A file <name>.dmn.xml, or a decision's id |
Body (JSON):
| Field |
Type |
Required |
Description |
data |
object |
|
The decision's inputs, by name |
| Answer |
Means |
Body |
| 200 |
What it decided |
RuleResult |
| 400 |
The input is not right |
Error |
| 401 |
No credential, or an unknown, expired or revoked token |
Error |
| 404 |
No such thing, or not this user's to see |
Error |
| 422 |
The engine refused it |
Error |
Messages and signals
POST /messages/{id}
A message, to what waits for it or starts on it (the system).
| Parameter |
In |
Type |
Required |
Description |
id |
path |
string |
yes |
The message |
Body (JSON):
| Field |
Type |
Required |
Description |
data |
object |
|
|
matchingKey |
object |
|
|
| Answer |
Means |
Body |
| 200 |
The instance it reached, or null |
{ instance: Instance or null } |
| 401 |
No credential, or an unknown, expired or revoked token |
Error |
| 403 |
Not this user's to do |
Error |
| 422 |
The engine refused it |
Error |
POST /signals/{id}
A signal, to everything that waits for it (the system).
| Parameter |
In |
Type |
Required |
Description |
id |
path |
string |
yes |
The signal |
Body (JSON):
| Field |
Type |
Required |
Description |
data |
object |
|
|
matchingKey |
object |
|
|
| Answer |
Means |
Body |
| 200 |
Signalled |
{ signalled } |
| 401 |
No credential, or an unknown, expired or revoked token |
Error |
| 403 |
Not this user's to do |
Error |
Users
GET /users
The users (an administrator; never an AI link).
| Answer |
Means |
Body |
| 200 |
A list |
{ items, next } |
| 401 |
No credential, or an unknown, expired or revoked token |
Error |
| 403 |
Not this user's to do |
Error |
POST /users
Add a user (an administrator).
Body (JSON, required):
| Field |
Type |
Required |
Description |
userName |
string |
yes |
|
email |
string |
|
|
password |
string |
yes |
8 characters or more |
groups |
list of string |
|
|
| Answer |
Means |
Body |
| 201 |
The user |
User |
| 400 |
The input is not right |
Error |
| 401 |
No credential, or an unknown, expired or revoked token |
Error |
| 403 |
Not this user's to do |
Error |
| 409 |
It is not waiting, or it is someone else's |
Error |
DELETE /users/{userName}
Delete a user, and end their tokens (an administrator; not themselves).
| Parameter |
In |
Type |
Required |
Description |
userName |
path |
string |
yes |
The user |
| Answer |
Means |
Body |
| 200 |
Deleted |
{ deleted } |
| 401 |
No credential, or an unknown, expired or revoked token |
Error |
| 403 |
Not this user's to do |
Error |
| 404 |
No such thing, or not this user's to see |
Error |
| 409 |
It is not waiting, or it is someone else's |
Error |
PUT /users/{userName}/groups
Set a user’s groups, and end their tokens (an administrator).
| Parameter |
In |
Type |
Required |
Description |
userName |
path |
string |
yes |
The user |
Body (JSON, required):
| Field |
Type |
Required |
Description |
groups |
list of string |
yes |
|
| Answer |
Means |
Body |
| 200 |
The user |
User |
| 400 |
The input is not right |
Error |
| 401 |
No credential, or an unknown, expired or revoked token |
Error |
| 403 |
Not this user's to do |
Error |
| 404 |
No such thing, or not this user's to see |
Error |
POST /users/{userName}/password
Set a user’s password (an administrator).
| Parameter |
In |
Type |
Required |
Description |
userName |
path |
string |
yes |
The user |
Body (JSON, required):
| Field |
Type |
Required |
Description |
password |
string |
yes |
8 characters or more |
| Answer |
Means |
Body |
| 200 |
Set |
{ userName, passwordSet } |
| 400 |
The input is not right |
Error |
| 401 |
No credential, or an unknown, expired or revoked token |
Error |
| 403 |
Not this user's to do |
Error |
| 404 |
No such thing, or not this user's to see |
Error |
Settings
GET /settings
Every setting by group: its value (secrets as ***), where it comes from (an administrator; an AI link at the administer level).
| Answer |
Means |
Body |
| 200 |
The settings |
{ groups } |
| 401 |
No credential, or an unknown, expired or revoked token |
Error |
| 403 |
Not this user's to do |
Error |
GET /settings/schema
The settings’ schema: each setting’s type, default, description, group, and whether it is a secret.
| Answer |
Means |
Body |
| 200 |
The JSON Schema |
object |
| 401 |
No credential, or an unknown, expired or revoked token |
Error |
| 403 |
Not this user's to do |
Error |
POST /settings/checks/{name}
Run a check: database, engine, url (SITE_URL) or email.
| Parameter |
In |
Type |
Required |
Description |
name |
path |
string |
yes |
The check |
| Answer |
Means |
Body |
| 200 |
Its result |
{ check, ok, message } |
| 401 |
No credential, or an unknown, expired or revoked token |
Error |
| 403 |
Not this user's to do |
Error |
| 404 |
No such thing, or not this user's to see |
Error |
Tokens
POST /tokens
A token for one of the application's users (the service key).
Credential: The service key (API_KEY): the service account only.
Body (JSON, required):
| Field |
Type |
Required |
Description |
userName |
string |
yes |
|
groups |
list of string |
|
The groups the application gives the user: not SYSTEM, ADMIN or DESIGNER |
minutes |
number |
|
default 15, at most 1440 |
| Answer |
Means |
Body |
| 201 |
The token: keep it secret |
{ token, expiresAt, userName, groups } |
| 400 |
The input is not right |
Error |
| 401 |
No credential, or an unknown, expired or revoked token |
Error |
| 403 |
Not this user's to do |
Error |
DELETE /tokens
Revoke every token of a user (the service key).
Credential: The service key (API_KEY): the service account only.
| Parameter |
In |
Type |
Required |
Description |
userName |
query |
string |
yes |
|
| Answer |
Means |
Body |
| 200 |
How many went |
{ revoked } |
| 400 |
The input is not right |
Error |
| 401 |
No credential, or an unknown, expired or revoked token |
Error |
| 403 |
Not this user's to do |
Error |
Shapes
Error
| Field |
Type |
Required |
Description |
error |
{ code, message } |
yes |
|
Me
| Field |
Type |
Required |
Description |
userName |
string |
|
|
groups |
list of string |
|
|
credential |
"token" or "service" |
|
|
may |
{ start, design, administer } |
|
|
| Field |
Type |
Required |
Description |
fields |
list of |
|
|
formKey |
string |
|
|
Startable
| Field |
Type |
Required |
Description |
processName |
string |
|
|
startNodeId |
string |
|
|
name |
string |
|
|
documentation |
string |
|
|
form |
Form |
|
|
Task
| Field |
Type |
Required |
Description |
id |
string |
|
|
instanceId |
string |
|
|
processName |
string |
|
|
elementId |
string |
|
|
name |
string |
|
|
status |
string |
|
|
assignee |
string |
|
|
candidateUsers |
any |
|
|
candidateGroups |
any |
|
|
startedAt |
string |
|
|
endedAt |
string |
|
|
dueDate |
string |
|
|
followUpDate |
string |
|
|
priority |
any |
|
|
completedBy |
string |
|
|
Everything of Task, and:
| Field |
Type |
Required |
Description |
data |
object |
|
|
form |
Form |
|
|
Instance
| Field |
Type |
Required |
Description |
id |
string |
|
|
name |
string |
|
|
status |
string |
|
|
startedAt |
string |
|
|
endedAt |
string or null |
|
|
data |
object |
|
|
User
| Field |
Type |
Required |
Description |
userName |
string |
|
|
email |
string or null |
|
|
groups |
list of string |
|
|
Issue
| Field |
Type |
Required |
Description |
code |
string |
|
|
element |
string or null |
|
|
message |
string |
|
|
Check
| Field |
Type |
Required |
Description |
name |
string |
|
|
valid |
boolean |
|
|
errors |
list of Issue |
|
|
warnings |
list of Issue |
|
|
ModelSaved
Everything of Check, and:
| Field |
Type |
Required |
Description |
created |
boolean |
|
|
laidOut |
boolean |
|
|
url |
string |
|
|
TestRun
| Field |
Type |
Required |
Description |
name |
string |
|
|
passed |
integer |
|
|
failed |
integer |
|
|
skipped |
integer |
|
|
scenarios |
list of |
|
|
RuleResult
| Field |
Type |
Required |
Description |
decision |
string |
|
The decision's id |
file |
string |
|
|
result |
any |
|
Its output: an object, or a list of them for a table with several hits |
InstanceWithItems
Everything of Instance, and:
| Field |
Type |
Required |
Description |
items |
list of object |
|
|