Tasks API | Genaya API Reference

Work

Tasks

Tasks inside task environments and groups.

GET/tasks

List tasks

Returns a cursor-paginated list of tasks for the authenticated organization, ordered by document id. Soft-deleted tasks are excluded. Supports optional equality filters environmentId and groupId. Tasks have no leadId field, so no lead filter is available. Requires scope: tasks:read.

Parameters

Query

environmentId

string

Filter to tasks belonging to this environment (exact match).

groupId

string

Filter to tasks belonging to this group (exact match).

Response 200

No fields.

Errors

400Malformed or missing parameters

401Bad, missing, or revoked key

402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up

403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off

429Rate limited

500Unexpected server error

curl -X GET https://api.genaya.com/v1/tasks \
  -H "Authorization: Bearer gny_live_xxx"

Example response

{
  "object": "list",
  "data": [
    {
      "id": "tsk_8fK2mZ",
      "object": "task",
      "environmentId": "env_3aQ9",
      "groupId": "grp_71Lp",
      "subGroupId": null,
      "title": "Replace condenser fan motor",
      "description": "Customer reports unit not cooling. Bring 1/3 HP motor.",
      "priority": "high",
      "assignees": [
        {
          "id": "usr_4Dx2",
          "name": "Jordan Lee",
          "role": "technician"
        }
      ],
      "assigneeIds": [
        "usr_4Dx2"
      ],
      "tags": [
        "warranty",
        "urgent-route"
      ],
      "fields": {
        "poNumber": "PO-10482"
      },
      "dueDate": "2026-06-20T15:00:00.000Z",
      "endDate": "2026-06-20",
      "position": 3,
      "createdAt": "2026-06-17T12:01:09.000Z",
      "updatedAt": "2026-06-17T12:01:09.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": ""
}

POST/tasks

Create a task

Creates a task. title and groupId are required. environmentId is DERIVED from the group (it cannot be set directly); the group must be live and belong to the organization or a 422 is returned. subGroupId is honored only when it exactly matches one of the group's subGroups, otherwise the task is left ungrouped (null). priority defaults to normal when omitted or invalid. position is auto-computed as max(existing in group)+1 when omitted. The fields map is stored raw with no validation. Send an Idempotency-Key header to safely retry. Requires scope: tasks:write.

Request body

FieldTypeDescription

titlerequired

string

The task title (required, non-empty).

groupIdrequired

string

The group this task belongs to (required, must be a live same-org group).

description

string

The task description.

subGroupId

string

A sub-group id; ignored unless it matches one of the group's sub-groups.nullable

assignees

array of object

Members to assign. Entries without an id are dropped and duplicates collapsed.

id

string

The member id.

name

string

The member's display name.

role

string

The member's role on the task.

tags

array of string

Free-form tags.

fields

object

Raw custom-field values. Stored without validation.

dueDate

string <date-time>

Due date and time; parsed to an ISO-8601 datetime or null.nullable

endDate

string

End date; normalized to a date-only string (YYYY-MM-DD) or null.nullable

priority

enumlowest | low | normal | high | urgent

Task priority; defaults to normal when omitted or invalid.

position

number

Sort position; auto-computed as max(existing in group)+1 when omitted.

Response 201

FieldTypeDescription

id

string

Unique identifier for the task.

object

string

The object type, always "task".

environmentId

string

The environment the task belongs to (derived from its group).nullable

groupId

string

The group the task belongs to.nullable

subGroupId

string

The sub-group within the group, or null when ungrouped.nullable

title

string

The task title.

description

string

The task description.

priority

enumlowest | low | normal | high | urgent

The task priority.

assignees

array of object

The members assigned to the task.

id

string

The member id.

name

string

The member's display name.

role

string

The member's role on the task.

assigneeIds

array of string

Read-only parallel list of assigned member ids (mirrors assignees). Derived server-side from assignees; not accepted on create or update.

tags

array of string

Free-form tags on the task.

fields

object

Raw custom-field values keyed by field id. Stored without validation.

dueDate

string <date-time>

The due date and time as an ISO-8601 datetime, or null.nullable

endDate

string

The end date as a date-only string (YYYY-MM-DD), or null.nullable

position

number

Sort position within the group.

createdAt

string <date-time>

When the task was created (ISO-8601).nullable

updatedAt

string <date-time>

When the task was last updated (ISO-8601).nullable

Errors

400Malformed or missing parameters

401Bad, missing, or revoked key

402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up

403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off

409Idempotency-Key reused with a different body

422Rejected by a business rule

429Rate limited

500Unexpected server error

curl -X POST https://api.genaya.com/v1/tasks \
  -H "Authorization: Bearer gny_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "title": "Replace condenser fan motor",
  "groupId": "grp_71Lp",
  "description": "Customer reports unit not cooling. Bring 1/3 HP motor.",
  "priority": "high",
  "assignees": [
    {
      "id": "usr_4Dx2",
      "name": "Jordan Lee",
      "role": "technician"
    }
  ],
  "tags": [
    "warranty"
  ],
  "dueDate": "2026-06-20T15:00:00.000Z",
  "endDate": "2026-06-20"
}'

Example response

{
  "data": {
    "id": "tsk_8fK2mZ",
    "object": "task",
    "environmentId": "env_3aQ9",
    "groupId": "grp_71Lp",
    "subGroupId": null,
    "title": "Replace condenser fan motor",
    "description": "Customer reports unit not cooling. Bring 1/3 HP motor.",
    "priority": "high",
    "assignees": [
      {
        "id": "usr_4Dx2",
        "name": "Jordan Lee",
        "role": "technician"
      }
    ],
    "assigneeIds": [
      "usr_4Dx2"
    ],
    "tags": [
      "warranty",
      "urgent-route"
    ],
    "fields": {
      "poNumber": "PO-10482"
    },
    "dueDate": "2026-06-20T15:00:00.000Z",
    "endDate": "2026-06-20",
    "position": 3,
    "createdAt": "2026-06-17T12:01:09.000Z",
    "updatedAt": "2026-06-17T12:01:09.000Z"
  }
}

GET/tasks/{id}

Retrieve a task

Returns a single task by id. A record belonging to another organization returns 404 rather than 403, so this can never confirm cross-tenant existence. Requires scope: tasks:read.

Parameters

Path

idrequired

string

The task id.

Response 200

FieldTypeDescription

id

string

Unique identifier for the task.

object

string

The object type, always "task".

environmentId

string

The environment the task belongs to (derived from its group).nullable

groupId

string

The group the task belongs to.nullable

subGroupId

string

The sub-group within the group, or null when ungrouped.nullable

title

string

The task title.

description

string

The task description.

priority

enumlowest | low | normal | high | urgent

The task priority.

assignees

array of object

The members assigned to the task.

id

string

The member id.

name

string

The member's display name.

role

string

The member's role on the task.

assigneeIds

array of string

Read-only parallel list of assigned member ids (mirrors assignees). Derived server-side from assignees; not accepted on create or update.

tags

array of string

Free-form tags on the task.

fields

object

Raw custom-field values keyed by field id. Stored without validation.

dueDate

string <date-time>

The due date and time as an ISO-8601 datetime, or null.nullable

endDate

string

The end date as a date-only string (YYYY-MM-DD), or null.nullable

position

number

Sort position within the group.

createdAt

string <date-time>

When the task was created (ISO-8601).nullable

updatedAt

string <date-time>

When the task was last updated (ISO-8601).nullable

Errors

401Bad, missing, or revoked key

402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up

403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off

404No such resource in this organization

429Rate limited

500Unexpected server error

curl -X GET https://api.genaya.com/v1/tasks/{id} \
  -H "Authorization: Bearer gny_live_xxx"

Example response

{
  "data": {
    "id": "tsk_8fK2mZ",
    "object": "task",
    "environmentId": "env_3aQ9",
    "groupId": "grp_71Lp",
    "subGroupId": null,
    "title": "Replace condenser fan motor",
    "description": "Customer reports unit not cooling. Bring 1/3 HP motor.",
    "priority": "high",
    "assignees": [
      {
        "id": "usr_4Dx2",
        "name": "Jordan Lee",
        "role": "technician"
      }
    ],
    "assigneeIds": [
      "usr_4Dx2"
    ],
    "tags": [
      "warranty",
      "urgent-route"
    ],
    "fields": {
      "poNumber": "PO-10482"
    },
    "dueDate": "2026-06-20T15:00:00.000Z",
    "endDate": "2026-06-20",
    "position": 3,
    "createdAt": "2026-06-17T12:01:09.000Z",
    "updatedAt": "2026-06-17T12:01:09.000Z"
  }
}

PATCH/tasks/{id}

Update a task

Partially updates a task. Only supplied fields are changed. title cannot be set to empty. Changing groupId re-derives environmentId from the new (live, same-org) group and clears any now-stale subGroupId unless a new subGroupId is supplied. subGroupId is validated against the effective group; an empty or unknown value clears it. priority falls back to normal when invalid. The fields map replaces customFields raw. Requires scope: tasks:write.

Parameters

Path

idrequired

string

The task id.

Request body

FieldTypeDescription

title

string

New title (cannot be empty).

groupId

string

Move the task to this group (must be a live same-org group).

description

string

New description.

subGroupId

string

New sub-group id; empty or unknown clears it.nullable

assignees

array of object

Replacement assignees list.

id

string

The member id.

name

string

The member's display name.

role

string

The member's role on the task.

tags

array of string

Replacement tags list.

fields

object

Replacement raw custom-field values.

dueDate

string <date-time>

New due date and time, or null to clear.nullable

endDate

string

New end date (date-only), or null to clear.nullable

priority

enumlowest | low | normal | high | urgent

New priority; falls back to normal when invalid.

position

number

New sort position.

Response 200

FieldTypeDescription

id

string

Unique identifier for the task.

object

string

The object type, always "task".

environmentId

string

The environment the task belongs to (derived from its group).nullable

groupId

string

The group the task belongs to.nullable

subGroupId

string

The sub-group within the group, or null when ungrouped.nullable

title

string

The task title.

description

string

The task description.

priority

enumlowest | low | normal | high | urgent

The task priority.

assignees

array of object

The members assigned to the task.

id

string

The member id.

name

string

The member's display name.

role

string

The member's role on the task.

assigneeIds

array of string

Read-only parallel list of assigned member ids (mirrors assignees). Derived server-side from assignees; not accepted on create or update.

tags

array of string

Free-form tags on the task.

fields

object

Raw custom-field values keyed by field id. Stored without validation.

dueDate

string <date-time>

The due date and time as an ISO-8601 datetime, or null.nullable

endDate

string

The end date as a date-only string (YYYY-MM-DD), or null.nullable

position

number

Sort position within the group.

createdAt

string <date-time>

When the task was created (ISO-8601).nullable

updatedAt

string <date-time>

When the task was last updated (ISO-8601).nullable

Errors

400Malformed or missing parameters

401Bad, missing, or revoked key

402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up

403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off

404No such resource in this organization

422Rejected by a business rule

429Rate limited

500Unexpected server error

curl -X PATCH https://api.genaya.com/v1/tasks/{id} \
  -H "Authorization: Bearer gny_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "priority": "urgent",
  "assignees": [
    {
      "id": "usr_4Dx2",
      "name": "Jordan Lee",
      "role": "technician"
    }
  ]
}'

Example response

{
  "data": {
    "id": "tsk_8fK2mZ",
    "object": "task",
    "environmentId": "env_3aQ9",
    "groupId": "grp_71Lp",
    "subGroupId": null,
    "title": "Replace condenser fan motor",
    "description": "Customer reports unit not cooling. Bring 1/3 HP motor.",
    "priority": "high",
    "assignees": [
      {
        "id": "usr_4Dx2",
        "name": "Jordan Lee",
        "role": "technician"
      }
    ],
    "assigneeIds": [
      "usr_4Dx2"
    ],
    "tags": [
      "warranty",
      "urgent-route"
    ],
    "fields": {
      "poNumber": "PO-10482"
    },
    "dueDate": "2026-06-20T15:00:00.000Z",
    "endDate": "2026-06-20",
    "position": 3,
    "createdAt": "2026-06-17T12:01:09.000Z",
    "updatedAt": "2026-06-17T12:01:09.000Z"
  }
}

DELETE/tasks/{id}

Delete a task

Soft-deletes a task (sets deletedAt). The task is never hard-deleted and will no longer appear in lists or single retrievals. Requires scope: tasks:write.

Parameters

Path

idrequired

string

The task id.

Response 200

FieldTypeDescription

id

string

The id of the deleted task.

object

string

deleted

boolean

Errors

401Bad, missing, or revoked key

402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up

403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off

404No such resource in this organization

429Rate limited

500Unexpected server error

curl -X DELETE https://api.genaya.com/v1/tasks/{id} \
  -H "Authorization: Bearer gny_live_xxx"

Example response

{
  "data": {
    "id": "tsk_8fK2mZ",
    "object": "task",
    "deleted": true
  }
}