Flowenti Robots API Help Reference

Returns the organization context bound to the API Key issued to the robot. Call it before any other request.

{
  "organizations": [
    {
      "id": 14299,
      "name": "robots snippet",
      "administrator": false,
      "subscriptionname": "",
      "hasmultipleuser": false,
      "creation": "2026-09-07T14:00:12.282+02:00",
      "deleted": false,
      "icon": null
    }
  ]
}

• organizationsList of organizations bound to the robot's API key: with a robot token it contains only one entry.
• idNumeric ID of the organization: the value to use as {idorganization} in the other endpoints.
• nameDisplay name of the organization.
• administratortrue if the robot operates with administrator permissions on the organization.
• subscriptionnameName of the organization's plan/subscription (may be empty).
• hasmultipleusertrue if the organization has multiple associated users.
• creationOrganization creation date/time (ISO 8601).
• deletedtrue if the organization was deleted (soft delete).
• iconOrganization icon/logo (null if not set).

Discover which processes the robot is allowed to start in the given organization.

{
  "possiblestart": [
    {
      "id": 21,
      "name": "",
      "idtype": 0,
      "idprocessmodel": 88,
      "processmodelname": "Gestione Ordini",
      "idswimlane": 1,
      "swimlanename": "Lane 1",
      "idorganization": 14207,
      "assignmentmode": 0,
      "userschema": "[]"
    }
  ]
}

• possiblestartList of startable start events: each entry is a process the robot can instantiate.
• idID of the start event: the value to use as {idevent} when starting the process.
• nameName of the start event (may be empty).
• idtypeType of start event defined in the BPMN model.
• idprocessmodelID of the process model (BPMN) the operation refers to.
• processmodelnameName of the process model (BPMN) the start event belongs to.
• idswimlaneID of the lane (swimlane) assigned to the activities of the started process.
• swimlanenameName of the associated lane.
• idorganizationID of the organization the operation runs in: the same one bound to the robot's API key (JWT).
• assignmentmodeTask assignment mode defined on the model (0 = automatic assignment from the queue).
• userschemaAllowed-user schema (serialized JSON) bound to the start event.

Instantiates a new BPMN process, generating the initial advancement token.

{
  "idprocessmodel": 88,
  "idorganization": 14207,
  "idevent": 21,
  "startdate": "2026-08-26T08:00:00Z",
  "enddate": null,
  "description": "Fattura #2026-0451",
  "descriptiondetail": "Emissione automatica da robot",
  "userdata": { "cliente": "Acme Spa" }
}

• idprocessmodelID of the process model (BPMN) the operation refers to.
• idorganizationID of the organization the operation runs in: the same one bound to the robot's API key (JWT).
• ideventID of the model's start event that instantiates the process: pick it from /startevents/organizations/{idorganization}.
• startdateProcess start date/time in ISO 8601 format (e.g. 2026-08-26T08:00:00Z).
• enddateProcess end date/time; null until the process is closed.
• descriptionShort description of the process, visible in the UI (e.g. Invoice #2026-0451).
• descriptiondetailOptional extended description with the operational details of the process instance.
• userdataObject with free-form instance-bound data (e.g. customer): persistent for the whole process lifetime.

{
  "process": {
    "id": 773019
  },
  "processtoken": {
    "id": 901,
    "state": 0
  },
  "previousprocesstoken": {
    "id": 901
  }
}

• processInstantiated process: the id field is the global reference for reading attachments and querying the process.
• processtokenAdvancement token created or moved by the operation: the unit of work the robot drives node by node.
• idID of the advancement token: unique identifier of the unit of work.
• stateToken state: 0 = waiting (todo), 1 = in progress (doing), 2 = completed (done).
• previousprocesstokenState of the token before the operation: useful for auditing and reconstructing process history.

Queries the system for available tasks the robot can take on.

{
  "waitingflownodes": [
    {
      "idprocesstoken": 901,
      "idflownode": 41,
      "designerid": "Task_EstrarreFatturePDF",
      "flownodename": "EstrarreFatturePDF",
      "idprocess": 773019,
      "idprocessmodel": 88,
      "idorganization": 14207,
      "processmodelname": "Gestione Ordini",
      "state": 0,
      "priority_name": "HIGH",
      "countcomments": 0,
      "countattachments": 2
    }
  ],
  "doingflownodes": []
}

• waitingflownodesWaiting tasks (todo state) the robot can claim with nextstate/doing.
• doingflownodesTasks currently in progress (doing state) by the robot.
• idprocesstokenID of the advancement token to operate on in subsequent calls (nextstate, attachments, exit).
• idflownodeID of the activity node: the value to use as {idflownode} in the nextstate body.
• designeridAlphanumeric ID of the node in the BPMN diagram (designer XML id): needed for /exit/{designerid} at gateways.
• flownodenameHuman-readable name of the activity as drawn in the BPMN model.
• idprocessID of the process the task belongs to: needed to read attachments (/processes/{idprocess}/attachments/light).
• idprocessmodelID of the process model (BPMN) the operation refers to.
• idorganizationID of the organization the operation runs in: the same one bound to the robot's API key (JWT).
• processmodelnameName of the process model (BPMN) the start event belongs to.
• stateToken state: 0 = waiting (todo), 1 = in progress (doing), 2 = completed (done).
• priority_nameTask priority set on the model (e.g. HIGH): drives the processing order.
• countcommentsNumber of comments on the task (read-only).
• countattachmentsNumber of attachments already on the task (read-only).

Notifies Flowenti that the robot has taken the task, changing the token state to

{
  "idflownode": 555,
  "iduserrobot": 17
}

• idflownodeID of the activity node (flownode) the action refers to: it comes from the waitingflownodes list returned by polling.
• iduserrobotID of the user/robot performing the action: the one bound to the robot's JWT token.

{
  "idtoken": 888111,
  "state": 1,
  "claimedAt": "2026-08-27T14:33:02Z",
  "iduserrobot": 17
}

• idtokenID of the token whose state changed as a result of the operation.
• stateToken state: 0 = waiting (todo), 1 = in progress (doing), 2 = completed (done).
• claimedAtDate/time of the claim (ISO 8601).
• iduserrobotID of the user/robot performing the action: the one bound to the robot's JWT token.

Marks the task as successfully completed and advances the flow to the next node.

{
  "idflownode": 555,
  "result": {
    "validated": true,
    "extractedFields": {
      "total": 1234.56,
      "vat": 258.86
    }
  }
}

• idflownodeID of the activity node (flownode) the action refers to: it comes from the waitingflownodes list returned by polling.
• resultFree-form result payload with the data produced by the task (e.g. extracted fields): stored on the process and made available to the next nodes.

{
  "process": {
    "id": 1661721,
    "idprocessmodel": 27613,
    "idorganization": 14299,
    "state": 0
  },
  "processtoken": {
    "id": 35093744,
    "idprocess": 1661721,
    "idflownode": 38882,
    "flownodetype": 0,
    "iduser": 21976,
    "state": 2,
    "previous": 35093743,
    "created": "...",
    "startdoing": "...",
    "done": "..."
  },
  "previousprocesstoken": {
    "id": 35093743,
    "state": 2,
    "idflownode": 40414
  },
  "previousflownode": {
    "id": 40414,
    "designerid": "Activity_1",
    "name": "prima task"
  },
  "flownode": {
    "id": 38882,
    "designerid": "Event_1blr1wv",
    "idtype": 1
  },
  "sequenceflows": []
}

• processInstantiated process: the id field is the global reference for reading attachments and querying the process.
• processtokenAdvancement token created or moved by the operation: the unit of work the robot drives node by node.
• idID of the advancement token: unique identifier of the unit of work.
• idprocessID of the process the token belongs to.
• idflownodeID of the node (activity or event) the token sits on.
• flownodetypeNode type (0 = event, 1 = activity, ...).
• iduserID of the user/robot holding the token (0 if queued).
• stateToken state: 0 = waiting (todo), 1 = in progress (doing), 2 = completed (done).
• previousID of the previous token in the process history.
• createdToken creation date/time (ISO 8601).
• startdoingClaim date/time; null until the token moves to doing.
• doneCompletion date/time; null until the token moves to done.
• previousprocesstokenState of the token before the operation: useful for auditing and reconstructing process history.
• previousflownodeNode the token came from before the operation.
• flownodeNode (activity or event) the token currently sits on.
• sequenceflowsSequence flows reachable from the current node: non-empty when subsequent decisions are needed.

Undoes the robot's last action on the task: brings the token state back from Doing (1) to Waiting (0), returning the task to the available queue. It is the only recovery mechanism supported today — there is no nextstate/error, failed, or abort. Use it when the robot runtime fails before completing a task.

{
  "process": {
    "id": 1,
    "idorganization": 1,
    "idprocessmodel": 1,
    "startdate": "...",
    "enddate": null,
    "userdata": "{}"
  },
  "processtoken": {
    "id": 2,
    "idprocess": 1,
    "idflownode": 7,
    "flownodetype": 1,
    "iduser": 2,
    "state": 0,
    "previous": 0,
    "created": "...",
    "startdoing": null,
    "done": null
  },
  "flownode": {
    "id": 7,
    "name": "Attività 1",
    "designerid": "Activity_1"
  },
  "previousflownode": {
    "id": 6,
    "name": "Evento",
    "designerid": "StartEvent_1"
  },
  "previousprocesstoken": {
    "id": 1,
    "state": 2,
    "idflownode": 6,
    "flownodetype": 0,
    "iduser": 2,
    "previous": 0
  }
}

• processInstantiated process: the id field is the global reference for reading attachments and querying the process.
• processtokenAdvancement token created or moved by the operation: the unit of work the robot drives node by node.
• idID of the advancement token: unique identifier of the unit of work.
• idprocessID of the process the token belongs to.
• idflownodeID of the node (activity or event) the token sits on.
• flownodetypeNode type (0 = event, 1 = activity, ...).
• iduserID of the user/robot holding the token (0 if queued).
• stateToken state: 0 = waiting (todo), 1 = in progress (doing), 2 = completed (done).
• previousID of the previous token in the process history.
• createdToken creation date/time (ISO 8601).
• startdoingClaim date/time; null until the token moves to doing.
• doneCompletion date/time; null until the token moves to done.
• flownodeNode (activity or event) the token currently sits on.
• previousflownodeNode the token came from before the operation.
• previousprocesstokenState of the token before the operation: useful for auditing and reconstructing process history.

Selects the specific gateway exit when the BPMN flow reaches a conditional decision or a robot-driven branch.

{
  "reason": "validated_by_robot",
  "metadata": {
    "validationScore": 0.97
  }
}

• reasonFree-form label documenting why the gateway branch was chosen (e.g. validated_by_robot).
• metadataOptional object with extra data about the decision (e.g. validation score).

{
  "idtoken": 888111,
  "selectedExit": "approve",
  "designerid": "Gateway_approve_01",
  "advancedAt": "2026-08-27T14:34:01Z"
}

• idtokenID of the token whose state changed as a result of the operation.
• selectedExitName of the gateway exit selected by the robot.
• designeridAlphanumeric ID of the node in the BPMN diagram (designer XML id): needed for /exit/{designerid} at gateways.
• advancedAtDate/time of the advancement (ISO 8601).

Uploads an attached file/document linked to the current process node (uses

{
  "idorganization": 14207,
  "filename": "fattura_2026.pdf",
  "cloudlink": "",
  "idtype": 1,
  "description": "Fattura 2026",
  "blob": "<base64 del file>",
  "size": 24576
}

• idorganizationID of the organization the operation runs in: the same one bound to the robot's API key (JWT).
• filenameFile name with extension, as it should appear on the attachment.
• cloudlinkCloud URL alternative to the binary upload: when set, the attachment points to a remote resource instead of the blob.
• idtypeAttachment type (idtype): the file category identifier managed by the platform.
• descriptionShort description of the process, visible in the UI (e.g. Invoice #2026-0451).
• blobFile content encoded in base64; size is its size in bytes.
• sizeFile size in bytes, consistent with the blob content.

{
  "idattachment": 7890,
  "idprocesstoken": 888111,
  "filename": "fattura_2026.pdf",
  "size": 24576,
  "uploadedAt": "2026-08-27T14:34:10Z"
}

• idattachmentID of the created attachment: to reference in any subsequent operations.
• idprocesstokenID of the advancement token to operate on in subsequent calls (nextstate, attachments, exit).
• filenameFile name with extension, as it should appear on the attachment.
• sizeFile size in bytes, consistent with the blob content.
• uploadedAtUpload date/time (ISO 8601).

Reads the lightweight list of all attachments associated with the process (uses

{
  "attachments": [
    {
      "id": 7890,
      "idorganization": 1,
      "filename": "invoice-98765.pdf",
      "description": "",
      "idtype": 1,
      "cloudlink": "",
      "creation": "2026-09-09T14:34:10Z",
      "iduser": 0,
      "username": "",
      "activityname": "acct1"
    }
  ]
}

• attachmentsList of process attachments: one entry per uploaded file.
• idID of the attachment.
• idorganizationID of the organization the operation runs in: the same one bound to the robot's API key (JWT).
• filenameFile name with extension, as it should appear on the attachment.
• descriptionAttachment description (empty if not provided at upload).
• idtypeAttachment type (idtype): the file category identifier managed by the platform.
• cloudlinkCloud URL alternative to the binary upload: when set, the attachment points to a remote resource instead of the blob.
• creationAttachment creation date/time (ISO 8601).
• iduserID of the user who uploaded the attachment (0 for robots).
• usernameUsername of who uploaded the attachment (empty for robots).
• activitynameName of the activity (BPMN node) the attachment is linked to.

Variant of /tasks/doing filtered by organization. Returns the Doing tasks of the current robot for a single organization.

{
  "doingflownodes": [
    {
      "idprocesstoken": 1,
      "idprocess": 1,
      "idflownode": 7,
      "flownodename": "Attività 1",
      "priority_name": "Alta"
    }
  ]
}

• doingflownodesTasks currently in progress (doing state) by the robot.
• idprocesstokenID of the advancement token to operate on in subsequent calls (nextstate, attachments, exit).
• idprocessID of the process the task belongs to: needed to read attachments (/processes/{idprocess}/attachments/light).
• idflownodeID of the activity node: the value to use as {idflownode} in the nextstate body.
• flownodenameHuman-readable name of the activity as drawn in the BPMN model.
• priority_nameTask priority set on the model (e.g. HIGH): drives the processing order.

Global discovery of all start events available to the robot across all organizations. Cross-org alternative to /startevents/organizations/{id}.

{
  "possiblestart": [
    {
      "id": 1,
      "name": "StartEvent_1",
      "idtype": 0,
      "idprocessmodel": 1,
      "processmodelname": "Modello A",
      "idswimlane": 1,
      "swimlanename": "Lane 1",
      "idorganization": 1,
      "assignmentmode": 1,
      "userschema": "..."
    }
  ]
}

• possiblestartList of startable start events: each entry is a process the robot can instantiate.
• idID of the start event: the value to use as {idevent} when starting the process.
• nameName of the start event (may be empty).
• idtypeType of start event defined in the BPMN model.
• idprocessmodelID of the process model (BPMN) the operation refers to.
• processmodelnameName of the process model (BPMN) the start event belongs to.
• idswimlaneID of the lane (swimlane) assigned to the activities of the started process.
• swimlanenameName of the associated lane.
• idorganizationID of the organization the operation runs in: the same one bound to the robot's API key (JWT).
• assignmentmodeTask assignment mode defined on the model (0 = automatic assignment from the queue).
• userschemaAllowed-user schema (serialized JSON) bound to the start event.

Retrieves the JSON configuration of the robot for the given organization and process model. Used in bootstrap to read driver parameters, remote endpoints, integration credentials.

{
  "id": 1,
  "idorganization": 1,
  "idrobot": 1,
  "idprocessmodel": 1,
  "linkedto": "",
  "datajson": {
    "chiave": "valore"
  }
}

• idID of the configuration row.
• idorganizationID of the organization the operation runs in: the same one bound to the robot's API key (JWT).
• idrobotID of the robot the data refers to.
• idprocessmodelID of the process model (BPMN) the operation refers to.
• linkedtoInternal linking reference (usually empty).
• datajsonRobot runtime configuration and parameters in free-form JSON: read at bootstrap and interpreted by the robot.

Lists the organizations associated with the current robot along with their tags (urgent, routine, batch, etc.). Useful to route tasks to the right organization before claiming them.

{
  "idrobot": 1,
  "organizations": [
    {
      "id": 1,
      "name": "Org1",
      "tags": [
        {
          "id": 1,
          "name": "urgente",
          "idorganization": 1,
          "color": "#ff0000"
        }
      ]
    }
  ]
}

• idrobotID of the robot the data refers to.
• organizationsList of organizations bound to the robot's API key: with a robot token it contains only one entry.
• idNumeric ID of the organization: the value to use as {idorganization} in the other endpoints.
• nameDisplay name of the organization.
• tagsTags associated with the organization (e.g. urgent, routine, batch).
• tags.idID of the tag.
• tags.nameTag name (e.g. urgent).
• tags.idorganizationID of the organization the operation runs in: the same one bound to the robot's API key (JWT).
• tags.colorTag color in hex format (e.g. #ff0000).

Per-robot settings for a specific organization and process model. The `idprocessmodel` query param is required: without it the server looks for the org-level row (idprocessmodel is null), which normally does not exist. Includes the datajson payload with the robot runtime parameters.

{
  "id": 1,
  "idorganization": 1,
  "idrobot": 1,
  "idprocessmodel": null,
  "linkedto": "",
  "datajson": {
    "properties": {
      "campo1 ssss": {
        "type": "...",
        "value": "Test"
      }
    }
  }
}

• idID of the configuration row.
• idorganizationID of the organization the operation runs in: the same one bound to the robot's API key (JWT).
• idrobotID of the robot the data refers to.
• idprocessmodelID of the process model (BPMN) the operation refers to.
• linkedtoInternal linking reference (usually empty).
• datajsonRobot runtime configuration and parameters in free-form JSON: read at bootstrap and interpreted by the robot.
• propertiesName → {type, value} map with the robot runtime parameters.