Skip to content

Workflow


Endpoints

GET       /workflows
GET       /workflows/:id
POST      /workflows
POST      /workflows/partial
POST      /workflows/:link_uid/link_uid
PUT       /workflows/:id
PUT       /workflows/:id/partial
POST      /workflows/:id/run
DELETE    /workflows/:id
DELETE    /workflows

A workflow is a collection of digital workers linked together to perform tasks in an automated fashion. Workflows can incorporate portfolios, datastores, report templates, API, and email distributions, as well as standard and custom digital workers.

The workflow object

What a workflow object looks like?

{
  "version": "v1",
  "status": "OK",
  "updated": 1624633670,
  "description": "This is my first workflow.",
  "tags": ["first", "new", "workflow"],
  "trigger_enabled": true,
  "gui": {
    "offset_x": 0,
    "zoom": 75,
    "offset_y": 0
  },
  "created": 1624633670,
  "starter_worker_id": "wrkr_aVFPQTerHF2JaO0hILbp959v7",
  "ender_worker_id": "wrkr_Sut4ZTaePs4PkdjDliVWYseGD",
  "link_uid": null,
  "workspace": "main",
  "trigger_type": "MANUAL",
  "trigger_config": {},
  "id": "wrkf_8fRueOt4JlXV9k5o9HZDMWfw7",
  "name": "My First Workflow"
}
Property Description
id string Unique identifier (UID) for the workflow.
created timestamp Time at which the object was created. Measured in seconds since the Unix epoch.
updated timestamp Time at which the object was updated. Measured in seconds since the Unix epoch.
name string The workflow's name.
description string An arbitrary string attached to the workflow. Default is "".
tags array A list of strings. Up to 32 tags. Use them to find the workflow with a query.
version string Indicates the workflow's current version.
status string OK when every worker is complete. INCOMPLETE when a worker has missing inputs or errors.
trigger_type string The type of the workflow's trigger. It can be MANUAL, API, SCHEDULER_EVENT, INTEGRATION_EVENT or WORKER_FINISHED_EVENT.
trigger_config object Parameters used to activate the workflow's trigger.
trigger_enabled boolean Whether the trigger can start the workflow.
starter_worker_id string The id of the workflow's Starter worker.
ender_worker_id string The id of the workflow's Ender worker.
gui object The position and zoom of the workflow canvas in the editor.
link_uid string An identifier you set to link the workflow to an external system. Default is null.
workspace string The workspace where the workflow was generated.
workers array The workers of the workflow. Only included when with_workers is True.

List all workflows

To list all workflows, run the following:

curl -G https://api.everysk.com/v2/workflows \
  --data-urlencode "query=#20210622" \
  --data-urlencode "workspace=main" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

The above call returns the following JSON object:

{
  "workflows": [
    {
      "status": "OK",
      "updated": 1624633670,
      "description": "This is my first workflow.",
      "tags": [
        "first",
        "new",
        "workflow"
      ],
      "trigger_enabled": true,
      "gui": {
        "offset_x": 0,
        "zoom": 75,
        "offset_y": 0
      },
      "created": 1624633670,
      "starter_worker_id": "wrkr_aVFPQTerHF2JaO0hILbp959v7",
      "workspace": "main",
      "trigger_type": "MANUAL",
      "trigger_config": {},
      "id": "wrkf_8fRueOt4JlXV9k5o9HZDMWfw7",
      "name": "My First Workflow"
    },
    ...
  ],
  "next_page_token": null
}

Returns a list of workflows you’ve previously created. The workflows are returned in sorted order, with the most recent workflow appearing first.

HTTP Request

GET /workflows

HTTP Parameters

Parameter Description
query string optional, default is null Request a list of workflows filtering it by name or tag. When using a tag to perform a query, each term must include a hashtag prefix. (e.g: query="#april #sample")
workspace string optional, default is main The workspace to list.
page_size integer optional, default is 10 Set the number of objects that will be listed per page.
page_token string optional, default is null The next_page_token from the previous response. See the pagination guide.
with_workers boolean optional, default is False When True, each workflow in the list includes its workers.

Retrieve a workflow

Retrieves the details of an existing workflow by supplying the workflow's id.

To retrieve a workflow, run the following:

curl "https://api.everysk.com/v2/workflows/wrkf_uylMWijKauV4B4Te7UJg9cNIv?workspace=main" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -G

The above call returns the following JSON object:

{
  "workflow": {
    "status": "OK",
    "updated": 1624309266,
    "description": "This is my first workflow.",
    "tags": [
      "first",
      "new",
      "workflow"
    ],
    "trigger_enabled": true,
    "workers": [
      ...
    ],
    "created": 1624309074,
    "starter_worker_id": "wrkr_jcQBp4Hj2MX3l9xsk8wgAByi7",
    "workspace": "main",
    "id": "wrkf_uylMWijKauV4B4Te7UJg9cNIv",
    "trigger_type": "MANUAL",
    "trigger_config": {},
    "gui": {
      "offset_x": 0,
      "zoom": 75,
      "offset_y": 0
    },
    "name": "My First Workflow"
  }
}

HTTP Request

GET /workflows/:id

HTTP Parameters

Parameter Description
id string REQUIRED A unique identifier (UID) for a workflow. A workflow's id will always look like this: wrkf_uylMWijKauV4B4Te7UJg9cNIv.
workspace string optional The workspace of the object. If you send it and the object is in another workspace, the API returns 403.
with_workers boolean optional, default is True When True, the response includes the workers of the workflow.

Create a workflow

Creates a workflow and then returns it. A workflow needs a workers array with one Starter and one Ender. The easiest way to build this array is to copy it from an existing workflow: retrieve the workflow with with_workers=true and send its workers back. The API gives each new worker a new wrkr_ id.

To copy the workers of an existing workflow into a new workflow, run the following:

workers=$(curl -s "https://api.everysk.com/v2/workflows/wrkf_uylMWijKauV4B4Te7UJg9cNIv?with_workers=true" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" | jq '.workflow.workers')

curl https://api.everysk.com/v2/workflows \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d "$(jq -n --argjson workers "$workers" '{
        name: "My Second Workflow",
        description: "A copy of my first workflow.",
        tags: ["second", "workflow"],
        workspace: "main",
        workers: $workers
      }')" \
  -X POST

This example relies on jq to read and build the JSON.

The above call returns the following JSON object:

{
  "workflow": {
    "version": "v1",
    "status": "OK",
    "updated": 1624309074,
    "description": "A copy of my first workflow.",
    "tags": [
      "second",
      "workflow"
    ],
    "trigger_enabled": true,
    "workers": [
      ...
    ],
    "created": 1624309074,
    "starter_worker_id": "wrkr_jcQBp4Hj2MX3l9xsk8wgAByi7",
    "ender_worker_id": "wrkr_Sut4ZTaePs4PkdjDliVWYseGD",
    "link_uid": null,
    "workspace": "main",
    "id": "wrkf_P95OLO61oGM5NwFn3W4iMl7rs",
    "trigger_type": "MANUAL",
    "trigger_config": {},
    "gui": {
      "zoom": 100,
      "offset_x": 0,
      "offset_y": 0
    },
    "name": "My Second Workflow"
  }
}

HTTP Request

POST /workflows

HTTP Parameters

Parameter Description
name string REQUIRED The workflow's name. 1 to 200 characters.
workers array REQUIRED The workers of the workflow. It must contain one worker with type STARTER and one with type ENDER. Each worker must have the keys id, type, name, description, gui (with form_sections), script_inputs, script_outputs, script_source, script_entry_point, trigger_type, trigger_config, trigger_enabled and template_id. Copy them from a workflow that you retrieve with with_workers=true.
description string optional, default is "" An arbitrary string attached to the workflow. Up to 2000 characters.
tags array optional, default is [] A list of strings. Up to 32 tags.
trigger_type string optional, default is MANUAL The type of the workflow's trigger: MANUAL, API, SCHEDULER_EVENT or INTEGRATION_EVENT.
trigger_config object optional, default is {} The trigger parameters. For SCHEDULER_EVENT, it must contain a valid cron expression in cron_expression. For INTEGRATION_EVENT, it must contain the integration id in integration_id.select.value.
trigger_enabled boolean optional, default is True Whether the trigger can start the workflow.
gui object optional, default is {"zoom": 100, "offset_x": 0, "offset_y": 0} The position and zoom of the workflow canvas in the editor.
link_uid string optional, default is null An identifier you set to link the workflow to an external system.
with_workers boolean optional, default is True When True, the response includes the workers of the workflow.
workspace string optional, default is main The workspace where the API creates the workflow. Send it in the JSON body.

Update a workflow

Replaces a workflow and then returns it. The update is not partial: send every field again. A field that you leave out goes back to its default value, the same as on create. This also applies to workspace: if you leave it out, the API moves the workflow to main. The easiest way to update a workflow is to retrieve it with with_workers=true, change the fields, and send the object back.

To rename a workflow and keep the rest of it, run the following:

workflow=$(curl -s "https://api.everysk.com/v2/workflows/wrkf_uylMWijKauV4B4Te7UJg9cNIv?with_workers=true" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" | jq '.workflow')

curl https://api.everysk.com/v2/workflows/wrkf_uylMWijKauV4B4Te7UJg9cNIv \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d "$(echo "$workflow" | jq '{
        name: "My Renamed Workflow",
        description, tags, gui, link_uid, workspace,
        trigger_type, trigger_config, trigger_enabled,
        starter_worker_id, workers
      }')" \
  -X PUT

The call returns the updated workflow, in the same format as create.

HTTP Request

PUT /workflows/:id

HTTP Parameters

Parameter Description
id string REQUIRED The workflow's unique identifier.
name string REQUIRED The workflow's name. 1 to 200 characters.
starter_worker_id string REQUIRED The id of the workflow's Starter worker.
workers array REQUIRED The workers of the workflow, in the same format as on create. A worker that keeps its id keeps its worker id.
workspace string optional, default is main Moves the workflow to this workspace. If you leave it out, the API moves the workflow to main. To keep the workflow where it is, send its current workspace.
Others description, tags, trigger_type, trigger_config, trigger_enabled, gui, link_uid and with_workers, with the same rules and defaults as on create.

Creates or replaces the workflow that has a given link_uid. Use it to deploy the same workflow again and again from an external system. The API looks for the most recently updated workflow with this link_uid in workspace:

  • If it finds none, it creates a workflow and responds with HTTP 201.
  • If it finds one, it replaces that workflow, the same as update, and responds with HTTP 200. The workflow keeps its id and its Starter worker id.

The body is the same as on create. If the body has a link_uid that is different from the one in the URL, the API returns 400.

HTTP Request

POST /workflows/:link_uid/link_uid

Create or update a workflow with partial workers

POST /workflows/partial and PUT /workflows/:id/partial take the same body as create and update. The difference is where each worker's script_source comes from:

  • On PUT /workflows/:id/partial, a worker that keeps its id keeps its stored script source. The API ignores the script_source in the body, except for the Starter and for a worker named Workflow Outputs.
  • On POST /workflows/partial, the API takes the script source from the worker template that has the same name as the worker, or else from the template in the worker's template_id.

HTTP Request

POST /workflows/partial

PUT /workflows/:id/partial

Run a workflow

Runs a specific workflow through the api. On this example we are running a workflow that contains a File Generator worker.

By default, running a workflow is asynchronous. This endpoint responds with HTTP 202 Accepted: the request has been accepted and the workflow execution has been started/queued, but the workflow has not necessarily finished running yet. The response contains a workflow_execution object; keep its id. To wait for the result in the same request, send "synchronous": true (see Run a workflow and wait for the result).

Getting the result of an asynchronous run takes four steps:

  1. Run. Send this request. Keep workflow_execution.id.
  2. Wait. Poll Retrieve a workflow execution every poll_interval seconds (default 2) until run_status is SUCCEEDED, FAILED or CANCELED. Stop with an error after timeout seconds (default 300). A workflow that stops before it finishes, or a failure in a worker that is not the Ender, leaves run_status at RUNNING forever, so the timeout is mandatory.
  3. Judge. Treat run_status == SUCCEEDED as the only success. FAILED is a failure. CANCELED is reserved and is also a failure.
  4. Read. Fetch the Ender's worker execution with with_result=true. The business output is worker_execution.result.

See Polling for a workflow execution's completion for the full loop.

To run a workflow, run the following:

curl https://api.everysk.com/v2/workflows/wrkf_P95OLO61oGM5NwFn3W4iMl7rs/run \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
        "parameters": {
          "file": {
            "name": "SimpleTextFile.txt",
            "content_type": "text/plain",
            "data": "SGVsbG8gV29ybGQ="
          }
        },
        "workspace": "main"
      }' \
  -X POST

The above call returns the following JSON object:

{
  "workflow_execution": {
    "id": "wfex_T1eYymTSIptJ4Hyt1Z6p4uGOe",
    "run_status": "RUNNING",
    "workflow_id": "wrkf_P95OLO61oGM5NwFn3W4iMl7rs",
    "workflow_name": "File Generator Workflow",
    "trigger": "API",
    "workspace": "main",
    "started_worker_id": "wrkr_Sut4ZTaePs4PkdjDliVWYseGD",
    "ender_worker_id": "wrkr_aVFPQTerHF2JaO0hILbp959v7",
    "ender_worker_execution_id": null,
    "created": 1632835285,
    "updated": 1632835285,
    "started": 1632835285,
    "duration": null,
    "real_execution_time": null,
    "total_execution_time": null,
    "resume": null
  },
  "result": null
}

HTTP Request

POST /workflows/:id/run

HTTP Parameters

Parameter Description
id string REQUIRED The workflow's unique identifier.
parameters object optional, default is null Object sent to be used inside the workflow that will be started through the API. Usually this object contains information and data required by the workers inside the workflow in order to execute properly. If the workers inside the target workflow do not require external inputs, leave it out. In Python it must be used as kwargs.
synchronous boolean optional, default is False When True, the API waits for the run to finish and responds with the result. See Run a workflow and wait for the result.
workspace string optional The workspace of the workflow. Send it in the JSON body. If you send it and the workflow is in another workspace, the API returns 403.

Run a workflow and wait for the result

Send "synchronous": true to keep the request open until the run finishes. The API starts the workflow, waits for the Ender, and responds with HTTP 200. You do not poll.

To run a workflow and wait for the result, run the following:

curl https://api.everysk.com/v2/workflows/wrkf_P95OLO61oGM5NwFn3W4iMl7rs/run \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
        "parameters": {},
        "synchronous": true,
        "workspace": "main"
      }' \
  -X POST

The above call returns the following JSON object:

{
  "workflow_execution": {
    "id": "wfex_T1eYymTSIptJ4Hyt1Z6p4uGOe",
    "run_status": "SUCCEEDED",
    "workflow_id": "wrkf_P95OLO61oGM5NwFn3W4iMl7rs",
    "workflow_name": "File Generator Workflow",
    "trigger": "API",
    "workspace": "main",
    "ender_worker_execution_id": "wkex_3bNhXpQrLo7TmK2sJfGvWe1cA",
    ...
  },
  "result": {
    ...
  },
  "run_status": "SUCCEEDED"
}

The response has three keys:

  • workflow_execution: the finished execution, without resume.
  • result: the result of the Ender's worker execution. A run that fails still returns what the Ender produced.
  • run_status: SUCCEEDED or FAILED. Treat only SUCCEEDED as success.

The API waits up to the platform execution timeout (60 minutes). If the run does not finish in that time, the API still responds with HTTP 200, but result is null and the response has no run_status. Then poll the execution with the workflow_execution.id.

Delete a workflow

Permanently deletes a workflow. It cannot be undone. Returns an object with the workflow's id, its name and an attribute specifying whether the workflow was successfully deleted or not.

To delete a workflow, run the following:

curl "https://api.everysk.com/v2/workflows/wrkf_uylMWijKauV4B4Te7UJg9cNIv?workspace=main" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -X DELETE

The above call returns the following JSON object:

{
  "workflow": {
    "deleted": true,
    "id": "wrkf_uylMWijKauV4B4Te7UJg9cNIv",
    "name": "My First Workflow"
  }
}

HTTP Request

DELETE /workflows/:id

HTTP Parameters

Parameter Description
id string REQUIRED The workflow's unique identifier.
workspace string optional The workspace of the object. If you send it and the object is in another workspace, the API returns 403.

Delete several workflows

To delete several workflows in one call, leave the id out of the path and send the ids in ids, separated by commas.

To delete several workflows, run the following:

curl "https://api.everysk.com/v2/workflows?ids=wrkf_uylMWijKauV4B4Te7UJg9cNIv,wrkf_P95OLO61oGM5NwFn3W4iMl7rs&workspace=main" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -X DELETE

The above call returns the following JSON object:

{
  "workflows": [
    {
      "deleted": true,
      "id": "wrkf_uylMWijKauV4B4Te7UJg9cNIv",
      "name": "My First Workflow"
    },
    {
      "deleted": true,
      "id": "wrkf_P95OLO61oGM5NwFn3W4iMl7rs",
      "name": "File Generator Workflow"
    }
  ]
}

HTTP Request

DELETE /workflows

HTTP Parameters

Parameter Description
ids string REQUIRED The ids of the workflows, separated by commas. An id that the API does not find gives null in the list.
workspace string optional The workspace of the workflows. If you send it and a workflow is in another workspace, the API stops at that workflow and returns 403. The workflows before it in ids are already deleted.