> For the complete documentation index, see [llms.txt](https://bernatf.gitbook.io/human-lambdas-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bernatf.gitbook.io/human-lambdas-documentation/api/tasks.md).

# Tasks

Tasks are work instances within a workflow

Required parameters:

* **Organization ID.** Visible in Settings.
* **Queue ID.** Found in the URL when inside a queue.

## The task object

A task is defined by the following properties:

* `id` - A unique task identifier.
* `status` - The task's status, which can be `new`, `open`, `in_progress` or `completed`.
* `completed_at`. ISO 8601 formatted timestamp.
* `created_at`. ISO 8601 formatted timestamp.
* `completed_by`. The user's email address.
* `queue`. The queue name.
* `queue_id`. A unique identifier for the queue the task belongs to.
* `data`. A dictionary with all the attributes that characterize the queue, according to its user defined configuration. Each key nested in the object takes the name of each block's identifier. See [Blocks](/human-lambdas-documentation/api/blocks.md) to learn more.
* `source`. The name of the source that originated the task. Can take `api` , `zapier`, `manual` or `$filename.csv` as its value.

An example task would look like this:

```javascript
{
  "id": 169578,
  "status": "completed",
  "completed_at": "2020-10-08T12:56:04.206Z",
  "created_at": "2020-10-08T12:55:08.546Z",
  "completed_by": "joe@example.com",
  "queue": "Sample Workflow Name",
  "queue_id": 79,
  "data": {
    "comment": "A random benign comment that needs to get approved"
    "approve": true
  },
  "source": "api"
}
```

## Create a task

<mark style="color:green;">`POST`</mark> `https://api.humanlambdas.com/orgs/$ORGANIZATION_ID/queues/$QUEUE_ID/tasks/create`

This endpoint creates a task.

#### Path Parameters

| Name             | Type    | Description                  |
| ---------------- | ------- | ---------------------------- |
| ORGANIZATION\_ID | integer | The ID of your organization. |
| QUEUE\_ID        | string  | The ID of your queue.        |

#### Headers

| Name          | Type   | Description                                       |
| ------------- | ------ | ------------------------------------------------- |
| Content-Type  | string | application/json                                  |
| Authorization | string | Your API Key (see Introduction for more details). |

#### Request Body

| Name | Type   | Description                                                             |
| ---- | ------ | ----------------------------------------------------------------------- |
| data | object | The workflow specific attributes that you want to include in this task. |

{% tabs %}
{% tab title="200 Task successfully created." %}

```javascript
{
    "completed_at": null,
    "completed_by": null,
    "created_at": "2020-10-08T15:27:08.632837Z",
    "data": {
        "approve": null,
        "comment": "This is some random text"
    },
    "id": 169581,
    "source": "api",
    "status": "new",
    "queue": "Moderate Comments",
    "queue_id": 166
}
```

{% endtab %}
{% endtabs %}

Sample request:

```bash
curl -v https://api.humanlambdas.com/orgs/$ORGANIZATION_ID/queues/$QUEUE_ID/tasks/create \
      -H "Content-Type: application/json" \
      -H "Authorization: Token $API_KEY" \
      -d '{"data":
        {
          "comment": "This is some random text"
        }
      }'
```

## List a queue's completed tasks

<mark style="color:blue;">`GET`</mark> `https://api.humanlambdas.com/orgs/$ORGANIZATION_ID/queues/$QUEUE_ID/tasks/completed`

This endpoint returns a list of a queue's completed tasks.

#### Path Parameters

| Name             | Type    | Description                  |
| ---------------- | ------- | ---------------------------- |
| ORGANIZATION\_ID | integer | The ID of your organization. |
| QUEUE\_ID        | string  | The ID of your queue.        |

#### Query Parameters

| Name   | Type    | Description                                                                              |
| ------ | ------- | ---------------------------------------------------------------------------------------- |
| offset | integer | The starting index in the returned list. See Pagination for more details.                |
| limit  | integer | The maximum number of items to include in the response. See Pagination for more details. |

#### Headers

| Name          | Type   | Description                                       |
| ------------- | ------ | ------------------------------------------------- |
| Authorization | string | Your API Key (see Introduction for more details). |

{% tabs %}
{% tab title="200 Returns a list of completed tasks:" %}

```javascript
{
    "count": 2,
    "next": null,
    "previous": null,
    "tasks": [
        {
            "completed_at": "2020-10-08T16:28:22.633450Z",
            "completed_by": "joe@example.com",
            "created_at": "2020-10-08T16:28:16.408194Z",
            "data": {
                "approve": false,
                "comment": "This sucks..."
            },
            "id": 169583,
            "source": "manual",
            "status": "completed",
            "queue": "Moderate Comments",
            "queue_id": 166
        },
        {
            "completed_at": "2020-10-08T15:28:33.664113Z",
            "completed_by": "joe@example.com",
            "created_at": "2020-10-08T15:27:08.632837Z",
            "data": {
                "approve": true,
                "comment": "This is some random text"
            },
            "id": 169581,
            "source": "api",
            "status": "completed",
            "queue": "Moderate Comments",
            "queue_id": 166
        }
    ]
}
```

{% endtab %}
{% endtabs %}