Tasks API

Manage tasks, assignments, and automated workflows in your organization.

Task Types (Kind)

Available task types:

maintenance - Regular maintenance tasks
audit - Audit and compliance tasks
review - Review and assessment tasks

Task Frequencies

Available frequencies:

once - One-time task
weekly - Repeats weekly
monthly - Repeats monthly
quarterly - Repeats quarterly
semi-annual - Repeats twice yearly
annual - Repeats yearly

Task States

Available task states:

new - Newly created task
in_progress - Task is being worked on
done - Task completed
cancelled - Task was cancelled

GET `/tasks/`

List all tasks with optional filtering.

Query Parameters

Parameter	Type	Description
`kind[]`	array	Filter by task type: `maintenance`, `audit`, `review`.
`state[]`	array	Filter by state: `new`, `in_progress`, `done`, `wont_do`.
`assignee[]`	array	Filter by assignee user IDs.

curl --location GET \
--url "https://YOUR_KORDON_DOMAIN/api/v1/tasks/" \
--header "Authorization: Bearer YOUR-TOKEN"

Example with filters:

curl --location GET \
--url "https://YOUR_KORDON_DOMAIN/api/v1/tasks/?state[]=new&state[]=in_progress" \
--header "Authorization: Bearer YOUR-TOKEN"

Example Response

Status: 200

{
    "data": [
        {
            "id": "10265263-b1ed-4ddc-82a2-a59aee882840",
            "assignee": {
                "id": "98dcb717-al70-4c89-8246-0bb026wc215b",
                "name": "Jaana Manana"
            },
            "completed_at": "2024-04-13T08:20:41+00:00",
            "completion_summary": "",
            "created_at": "2024-04-13T07:51:50+00:00",
            "description": "<p>This is a description</p>",
            "due_at": "2024-04-13T00:00:00+00:00",
            "duration": 15,
            "frequency": "once",
            "instance_id": "8f54babf-397f-4119-b55e-d2fa130916a8",
            "is_overdue": false,
            "kind": "maintenance",
            "labels": [],
            "needs_evidence": false,
            "next_instance_id": "8f54babf-397f-4119-b55e-d2fa130916a8",
            "outcome": "none",
            "state": "done",
            "taskable": {
                "id": "08faa5be-bd0a-41be-826a-37170b645b7d",
                "klass": "control",
                "title": "Another test control"
            },
            "title": "One time task for something",
            "updated_at": "2024-04-13T08:20:41+00:00"
        }
    ]
}

GET `/tasks/:id`

Get detailed information about a specific task.

curl --location GET \
--url "https://YOUR_KORDON_DOMAIN/api/v1/tasks/task-id-here" \
--header "Authorization: Bearer YOUR-TOKEN"

POST `/tasks/`

Create a new task assignment.

Required Parameters:

assignee_id - User ID of the task assignee
kind - Task type (maintenance, audit, review)
frequency - Task frequency
due_at - Due date (ISO 8601 format)

Optional Parameters:

title - Task title
description - Task description (HTML supported)
needs_evidence - Whether task requires evidence (boolean)
duration - Expected duration in minutes

curl --location POST \
--url "https://YOUR_KORDON_DOMAIN/api/v1/tasks/" \
--header "Authorization: Bearer YOUR-TOKEN" \
--header "Content-Type: application/json" \
--data '{
    "title": "My new task",
    "assignee_id": "05wa1387-a987-3cyt-y2df-9e41u8569aed",
    "kind": "maintenance",
    "frequency": "once",
    "due_at": "2024-04-13T00:00:00+00:00"
}'

Example Response

Status: 200

{
    "data": {
        "id": "d477c288-96ff-4b99-9fc4-eb2fb9d86bef",
        "assignee": {
            "id": "05wa1387-a987-3cyt-y2df-9e41u8569aed",
            "name": "Martin Lootus"
        },
        "completed_at": null,
        "completion_summary": null,
        "created_at": "2024-08-28T15:03:46+00:00",
        "description": null,
        "due_at": "2024-04-13T00:00:00+00:00",
        "duration": null,
        "frequency": "once",
        "instance_id": "a02852c4-2b9a-4bd4-a461-61bfb83fc366",
        "is_overdue": true,
        "kind": "maintenance",
        "labels": [],
        "needs_evidence": false,
        "next_instance_id": "a02852c4-2b9a-4bd4-a461-61bfb83fc366",
        "outcome": "none",
        "state": "new",
        "taskable": {},
        "title": "My new task",
        "updated_at": "2024-08-28T15:03:46+00:00"
    }
}

You can connect a task to an item (control, asset, vendor, or other object) immediately upon creation by including the taskable_id parameter in your POST request:

{
    "title": "My new task",
    "assignee_id": "05wa1387-a987-3cyt-y2df-9e41u8569aed",
    "kind": "maintenance",
    "frequency": "once",
    "due_at": "2024-04-13T00:00:00+00:00",
    "taskable_id": "1f446819-d85e-4ede-a064-568760e02dde"
}

The task will be linked to the specified item on creation, and the response will include the taskable object with the connected item’s details.

PATCH `/tasks/:id`

Update an existing task.

curl --location PATCH \
--url "https://YOUR_KORDON_DOMAIN/api/v1/tasks/task-id-here" \
--header "Authorization: Bearer YOUR-TOKEN" \
--header "Content-Type: application/json" \
--data '{
    "title": "Updated task title"
}'

Connect Task to an Item

Connect a task to a specific item (control, asset, vendor, or other object) by updating the taskable_id.

curl --location PATCH \
--url "https://YOUR_KORDON_DOMAIN/api/v1/tasks/task-id-here" \
--header "Authorization: Bearer YOUR-TOKEN" \
--header "Content-Type: application/json" \
--data '{
    "task": {
        "taskable_id": "1f446819-d85e-4ede-a064-568760e02dde"
    }
}'

Example Response

Status: 200

The response will include the full task data with the updated taskable relationship.

{
    "data": {
        "id": "d477c288-96ff-4b99-9fc4-eb2fb9d86bef",
        "taskable": {
            "id": "1f446819-d85e-4ede-a064-568760e02dde",
            "klass": "control",
            "title": "Security Control"
        },
        ...
    }
}

DELETE `/tasks/:id`

Remove a task.

curl --location DELETE \
--url "https://YOUR_KORDON_DOMAIN/api/v1/tasks/task-id-here" \
--header "Authorization: Bearer YOUR-TOKEN"

Recurring task history

Recurring tasks work as a chain of instances. The ID in the task URL is the parent task ID — a stable identifier that never changes. Each time the task repeats, a new instance is created under that parent. Use the endpoints below to retrieve past and present instances.

GET `/tasks/:id/archive`

List all instances of a recurring task — past and current. The :id is the parent task ID, which you can copy from the task URL in the Kordon UI.

Each instance in the response has its own instance_id. All instances share the same parent id. The state field tells you whether an instance is still open (new, in_progress) or finished (done, cancelled).

curl --location GET \
--url "https://YOUR_KORDON_DOMAIN/api/v1/tasks/a3f7e291-c4b2-4d8a-9f1e-8b2c5d6e7f0a/archive" \
--header "Authorization: Bearer YOUR-TOKEN"

Example Response

Status: 200

{
    "data": [
        {
            "id": "a3f7e291-c4b2-4d8a-9f1e-8b2c5d6e7f0a",
            "assignee": {
                "id": "c9d2e1f0-a3b4-4c5d-8e9f-0a1b2c3d4e5f",
                "active": true,
                "color": "#1677FF",
                "kind": "person",
                "name": "Markus Tamm"
            },
            "completed_at": null,
            "completion_summary": "",
            "created_at": "2026-05-10T09:00:00+00:00",
            "description": "<p>Check all units on the floor and log the count.</p>",
            "due_at": "2028-03-01T00:00:00+00:00",
            "duration": 30,
            "frequency": "annual",
            "instance_id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
            "is_overdue": false,
            "kind": "maintenance",
            "labels": [],
            "needs_evidence": false,
            "next_instance_id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
            "outcome": "none",
            "permissions": {
                "update": true,
                "destroy": true,
                "connect": true,
                "changelog": true,
                "complete": false
            },
            "state": "new",
            "taskable": {
                "id": "7f8e9d0c-1b2a-4e3d-5c6b-7a8f9e0d1c2b",
                "klass": "asset",
                "title": "Server Room"
            },
            "title": "Inspect fire safety equipment",
            "updated_at": "2026-05-10T09:00:00+00:00"
        },
        {
            "id": "a3f7e291-c4b2-4d8a-9f1e-8b2c5d6e7f0a",
            "assignee": {
                "id": "c9d2e1f0-a3b4-4c5d-8e9f-0a1b2c3d4e5f",
                "active": true,
                "color": "#1677FF",
                "kind": "person",
                "name": "Markus Tamm"
            },
            "completed_at": "2026-06-12T14:22:00+00:00",
            "completion_summary": "<p>All units inspected. Found 2 that need servicing.</p>",
            "created_at": "2025-11-03T08:15:00+00:00",
            "description": "<p>Check all units on the floor and log the count.</p>",
            "due_at": "2027-03-01T00:00:00+00:00",
            "duration": 30,
            "frequency": "annual",
            "instance_id": "b4c5d6e7-f8a9-4b0c-1d2e-3f4a5b6c7d8e",
            "is_overdue": false,
            "kind": "maintenance",
            "labels": [],
            "needs_evidence": false,
            "next_instance_id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
            "outcome": "none",
            "permissions": {
                "update": true,
                "destroy": true,
                "connect": true,
                "changelog": true,
                "complete": false
            },
            "state": "done",
            "taskable": {
                "id": "7f8e9d0c-1b2a-4e3d-5c6b-7a8f9e0d1c2b",
                "klass": "asset",
                "title": "Server Room"
            },
            "title": "Inspect fire safety equipment",
            "updated_at": "2026-06-12T14:22:01+00:00"
        },
        {
            "id": "a3f7e291-c4b2-4d8a-9f1e-8b2c5d6e7f0a",
            "assignee": {
                "id": "c9d2e1f0-a3b4-4c5d-8e9f-0a1b2c3d4e5f",
                "active": true,
                "color": "#1677FF",
                "kind": "person",
                "name": "Markus Tamm"
            },
            "completed_at": "2025-12-15T10:05:00+00:00",
            "completion_summary": "",
            "created_at": "2025-01-20T07:30:00+00:00",
            "description": "<p>Check all units on the floor and log the count.</p>",
            "due_at": "2026-03-01T00:00:00+00:00",
            "duration": 30,
            "frequency": "annual",
            "instance_id": "d7e8f9a0-b1c2-4d3e-4f5a-6b7c8d9e0f1a",
            "is_overdue": false,
            "kind": "maintenance",
            "labels": [],
            "needs_evidence": false,
            "next_instance_id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
            "outcome": "none",
            "permissions": {
                "update": true,
                "destroy": true,
                "connect": true,
                "changelog": true,
                "complete": false
            },
            "state": "done",
            "taskable": {
                "id": "7f8e9d0c-1b2a-4e3d-5c6b-7a8f9e0d1c2b",
                "klass": "asset",
                "title": "Server Room"
            },
            "title": "Inspect fire safety equipment",
            "updated_at": "2025-12-15T10:05:01+00:00"
        }
    ],
    "meta": {
        "total_count": 3,
        "page": 1,
        "permissions": {
            "create": true
        },
        "per_page": 10
    }
}

GET `/tasks/archive/:id`

Get the full details of a single archived task instance. The :id here is the instance_id from the list above — not the parent task ID.

curl --location GET \
--url "https://YOUR_KORDON_DOMAIN/api/v1/tasks/archive/b4c5d6e7-f8a9-4b0c-1d2e-3f4a5b6c7d8e" \
--header "Authorization: Bearer YOUR-TOKEN"

Example Response

Status: 200

{
    "data": {
        "id": "a3f7e291-c4b2-4d8a-9f1e-8b2c5d6e7f0a",
        "assignee": {
            "id": "c9d2e1f0-a3b4-4c5d-8e9f-0a1b2c3d4e5f",
            "active": true,
            "color": "#1677FF",
            "kind": "person",
            "name": "Markus Tamm"
        },
        "completed_at": "2026-06-12T14:22:00+00:00",
        "completion_summary": "<p>All units inspected. Found 2 that need servicing.</p>",
        "created_at": "2025-11-03T08:15:00+00:00",
        "description": "<p>Check all units on the floor and log the count.</p>",
        "due_at": "2027-03-01T00:00:00+00:00",
        "duration": 30,
        "frequency": "annual",
        "instance_id": "b4c5d6e7-f8a9-4b0c-1d2e-3f4a5b6c7d8e",
        "is_overdue": false,
        "kind": "maintenance",
        "labels": [],
        "needs_evidence": false,
        "next_instance_id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
        "outcome": "none",
        "permissions": {
            "update": true,
            "destroy": true,
            "connect": true,
            "changelog": true,
            "complete": false
        },
        "state": "done",
        "taskable": {
            "id": "7f8e9d0c-1b2a-4e3d-5c6b-7a8f9e0d1c2b",
            "klass": "asset",
            "title": "Server Room"
        },
        "title": "Inspect fire safety equipment",
        "updated_at": "2026-06-12T14:22:01+00:00"
    }
}

Tasks API

Task Types (Kind)

Task Frequencies

Task States

GET /tasks/

GET /tasks/:id

POST /tasks/

PATCH /tasks/:id

DELETE /tasks/:id

Recurring task history

GET /tasks/:id/archive

GET /tasks/archive/:id

GET `/tasks/`

GET `/tasks/:id`

POST `/tasks/`

PATCH `/tasks/:id`

DELETE `/tasks/:id`

GET `/tasks/:id/archive`

GET `/tasks/archive/:id`