Tasks

All Swarm REST API resources use the following base URL:

https://swarm.unmand.app/

Trigger New Task

A new task can be created and queued at any time by invoking this endpoint. A task will always need an initial data packet and therefore it is expected to be included in the JSON payload of the request. If there is no initial data to provide, send an empty JSON object {}.

URL : /tasks/trigger

Method : POST

Example

Python
cURL

from typing import Dict, Any
import os
import requests
from requests.auth import AuthBase

class TokenAuth(AuthBase):
    """Implements a custom authentication scheme."""

    def __init__(self, token: str):
        self.token: str = token

    def __call__(self, r: requests.PreparedRequest):
        """Attach an API token to a custom auth header."""
        r.headers['Authorization'] = self.token
        return r

# Example request using TokenAuth class
API_TOKEN: str = os.environ['YOUR_API_TOKEN']
PAYLOAD: Dict[str, Any] = {
    "first_name": "John",
    "last_name": "Smith",
    "amount": 100.02
}
response: requests.Response = requests.post(
    'https://swarm.unmand.app/tasks/trigger',
    json=PAYLOAD,
    params=PARAMS,
    auth=TokenAuth(API_TOKEN)
    )

# We recommend setting up a variable for API_TOKEN to avoid leaving your token in the shell history, which should be avoided.

curl -X POST https://swarm.unmand.app/tasks/trigger
    -H "Authorization: $API_TOKEN"
    -H "Content-Type: application/json"
    -d '{"first_name": "John", "last_name": "Smith", "amount": 100.02}'

Response

201 CREATED
{
    "taskGuid": "T1209e5fd-eb1f-4eu4-a9f8-628326ed62a0"
}

List Tasks (Version 2)

Retrieve a list of tasks matching a specified query, with advanced filtering options. This endpoint provides similar functionality to the original /projects/<PROJECT_GUID>/tasks endpoint but offers a different way of filtering the results. Limited to 50 results.

URL : /projects/<PROJECT_GUID>/tasks/v2

Method : `GET```

Query Parameters (optional) : ?outcome__ilike=Mango

The following query parameters can be included in the request to customize the results:

Parameter	Description	Example
`page`	Page number for pagination. Default value: 1.	`page=2`
`perPage`	Number of results per page.	`perPage=10`
`status__in`	Filter the results by task status.	`status__in=SUCCESS&status__in=QUEUED`
`search__ilike`	Required for search. Search for a specific value using ILIKE (case-insensitive).	`outcome__ilike=Mango`
`created__gte` and `created__lte`	Date range for the 'created' field date range filter.	`created__gte=2022-01-15T08:20:10.987654Z&created__lte=2023-08-30T15:45:30.123456Z`
`updated__gte` and `updated__lte`	Date range for the 'updated' field date range filter.	`updated__gte=2022-01-15T08:20:10.987654Z&updated__lte=2023-08-30T15:45:30.123456Z`
`sort__asc` or `sort__desc`	Required for sorting. Order in which to sort the results. Value must be either `updated` or `created`	`sort__desc=updated`

Note

For status__in, and other multi-value filters, multiple values can be included by repeating the parameter (e.g., status__in=SUCCESS&status__in=QUEUED).
For the search__ilike parameter, search is required to specify the field to search in. Search subjects include outcome for the task outcome, guid for the task identifier, and custom project task fields as field1, field2, etc. For example, guid__ilike=123456 or field2__ilike=test
The sort parameter can be either updated or created

Example

Python
cURL

import os
import requests
from requests.auth import AuthBase

class TokenAuth(AuthBase):
    """Implements a custom authentication scheme."""

    def __init__(self, token: str):
        self.token: str = token

    def __call__(self, r: requests.PreparedRequest):
        """Attach an API token to a custom auth header."""
        r.headers['Authorization'] = self.token
        return r

# Example request using TokenAuth class
API_TOKEN: str = os.environ['YOUR_API_TOKEN']
PROJECT_GUID: str = "YOUR_PROJECT_GUID"
PARAMS: Dict[str, str] = {
    "status__in": ["SUCCESS", "FAILURE"]
}
response: requests.Response = requests.get(
    f'https://swarm.unmand.app/projects/{PROJECT_GUID}/tasks/v2',
    params=PARAMS,
    auth=TokenAuth(API_TOKEN)
    )

# We recommend setting up a variable for API_TOKEN to avoid leaving your token in the shell history, which should be avoided.

curl https://swarm.unmand.app/projects/$PROJECT_GUID/tasks -H "Authorization: $API_TOKEN"

Response

200 OK
{
    "tasks": [
        {
            "guid": "Tb4ff2642-6655-48b4-8362-edc2c3f77255",
            "status": "SUCCESS",
            "outcome": "Task completed",
            "created": "2022-02-17T00:23:08.899996+00:00",
            "updated": "2022-02-17T00:25:06.090146+00:00",
            "field1": "5614523",
            "field2": "John Doe",
            "field3": "01/01/2000",
            "field5": "Melbourne",
            "field6": "Male",
            "field7": "High",
            "field8": "$42.16",
            "field9": "Yes",
        },
        {...},
        {...}
    ],
    "totalCount": 3
}

Get Task

Retrieves a representation of the Task's current state. In addition to the Task's metadata, this notably also returns an array of Stage objects and the Task data packet.

URL : /tasks/<TASK_GUID>

Method : GET

Query Parameters : None

Example

Python
cURL

from typing import Dict, Any
import os
import requests
from requests.auth import AuthBase

class TokenAuth(AuthBase):
    """Implements a custom authentication scheme."""

    def __init__(self, token: str):
        self.token: str = token

    def __call__(self, r: requests.PreparedRequest):
        """Attach an API token to a custom auth header."""
        r.headers['Authorization'] = self.token
        return r

# Example request using TokenAuth class
API_TOKEN: str = os.environ['YOUR_API_TOKEN']
TASK_GUID: str = 'YOUR_TASK_GUID'
response: requests.Response = requests.get(
    f'https://swarm.unmand.app/tasks/{TASK_GUID}',
    auth=TokenAuth(API_TOKEN)
    )

# We recommend setting up a variable for API_TOKEN to avoid leaving your token in the shell history, which should be avoided.

curl https://swarm.unmand.app/tasks/TASK_GUID
    -H "Authorization: $API_TOKEN"

Response

200 OK
{
    "task": {
        "guid": "T7381f817-5cb5-4354-952c-66d80e12f9e6",
        "status": "SUCCESS",
        "created": "2022-02-23T04:03:07.652470+00:00",
        "updated": "2022-02-23T04:04:42.279940+00:00",
        "data": {
            "amount": {
                "value": 436.2,
                "originalString": null
            },
            {...},
            {...}
        },
        "stages": [
            {
              "guid": "0d8f06d6-69c0-4594-81b0-960d1a96b67e",
              "name": "Update Quote",
              "type": "SEQUENCE",
              "status": "SUCCESS",
              "started": "2022-02-23T04:03:17.478706",
              "finished": "2022-02-23T04:03:47.824803",
              "outcome_message": null
            },
            {...},
            {...}
        ],
        "outcome": "Policy bound",
        "swarm_version": "dfd5e8a",
        "rawData": {
            "amount": 436.2,
            ...,
            ...,
        }
    }
}

The data property of the task object contains a pre-processed representation of the Task data that powers the Task Data editor in the Portal. The rawData property contains the actual Task data packet.

Resubmit Task

Resubmitting a task will run the job against the latest data in Task data and flow logic.

URL : /tasks/<TASK_GUID>/resubmit

Method : POST

Query Parameters : None

JSON Payload :

Key	Required	Type	Description	Default
force	No	boolean	A resubmission is blocked if the stages in the flow have changed from when the task was last run. Set this to True to confirm the stage index provided is correct in the currently active flow version	False
stage	Yes	number	Index of the stage you want to run from

Example

Python
cURL

from typing import Dict, Any
import os
import requests
from requests.auth import AuthBase

class TokenAuth(AuthBase):
    """Implements a custom authentication scheme."""

    def __init__(self, token: str):
        self.token: str = token

    def __call__(self, r: requests.PreparedRequest):
        """Attach an API token to a custom auth header."""
        r.headers['Authorization'] = self.token
        return r

# Example request using TokenAuth class
API_TOKEN: str = os.environ['YOUR_API_TOKEN']
TASK_GUID: str = 'YOUR_TASK_GUID'
PAYLOAD: Dict[str, Any] = {
    "force": True,
    "stage": 0,
}

response: requests.Response = requests.post(
    f'https://swarm.unmand.app/tasks/{TASK_GUID}/resubmit',
    json=PAYLOAD,
    auth=TokenAuth(API_TOKEN)
    )

# We recommend setting up a variable for API_TOKEN to avoid leaving your token in the shell history, which should be avoided.

curl -X POST https://swarm.unmand.app/tasks/TASK_GUID/trigger
    -H "Authorization: $API_TOKEN"
    -H "Content-Type: application/json"
    -d '{"force": true, "stage": 0}'

Response

200 OK
{
    "job_guid": "J7453g954-5cb5-4354-952c-54d80e13f9e6"
}

Trigger New Task​

List Tasks (Version 2)​

Note​

Get Task​

Resubmit Task​

Trigger New Task

List Tasks (Version 2)

Note

Get Task

Resubmit Task