Genaya

API Reference
SupportkeyGet API key
Work

Task Environments

Containers (boards) that group tasks.

GET/task-environments

List task environments

Returns an org-wide list of every active task environment (the top level of the work-management board). No auto-seed and no per-user filtering - every active environment in the organization is returned. Requires scope: tasks:read.

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
POST/task-environments

Create a task environment

Creates a single task environment document. Unlike the internal UI endpoint, no default groups are batch-seeded - exactly the one resource requested is created. The organization and actor are derived from the API key context, never the request body. When position is omitted it is server-derived as max(existing position)+1 within the org's active environments. Requires scope: tasks:write.

Request body

FieldTypeDescription
namerequired
string
The environment name. Required, non-empty.
icon
string
Material symbol icon name. Defaults to "folder" when omitted or empty.
position
number
Ordering position. Server-derived as max(existing)+1 when omitted.
assignees
array of object
Assignee entries. Each must carry an id (id/Id/uuid); entries without an id are dropped, duplicates by id are deduped.
id
string
name
string
role
string

Response 201

FieldTypeDescription
id
string
object
string
name
string
icon
string
Material symbol icon name. Omitted when absent on the underlying doc.
color
string
Color. Normally absent on environment docs (only groups carry color); surfaced if set.
isDefault
boolean
position
number
assignees
array of object
id
string
The member ID.
name
string
The member display name.
role
string
The member role. Omitted when empty.
assigneeIds
array of string
Server-derived parallel array of assignee IDs.
createdByName
string
Display name of the member who created the environment. null on the auto-seeded default environment.nullable
groups
array of object
Expanded groups. Present only on the retrieve (GET by id) endpoint; omitted from the list endpoint.
id
string
object
string
environmentId
string
The parent environment this group belongs to.
name
string
color
string
Hex or named color. Omitted when empty.
position
number
Ordering position within the environment; also the sort key.
isDefault
boolean
collapsed
boolean
UI collapse state. Omitted when the underlying doc has never set it.
subGroups
array of object
createdByName
string
Display name of the member who created the group. null on auto-seeded default groups.nullable
createdAt
string <date-time>
nullable
updatedAt
string <date-time>
nullable
createdAt
string <date-time>
nullable
updatedAt
string <date-time>
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
GET/task-environments/{id}

Retrieve a task environment

Returns a single task environment 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 environment id.

Response 200

FieldTypeDescription
id
string
object
string
name
string
icon
string
Material symbol icon name. Omitted when absent on the underlying doc.
color
string
Color. Normally absent on environment docs (only groups carry color); surfaced if set.
isDefault
boolean
position
number
assignees
array of object
id
string
The member ID.
name
string
The member display name.
role
string
The member role. Omitted when empty.
assigneeIds
array of string
Server-derived parallel array of assignee IDs.
createdByName
string
Display name of the member who created the environment. null on the auto-seeded default environment.nullable
groups
array of object
Expanded groups. Present only on the retrieve (GET by id) endpoint; omitted from the list endpoint.
id
string
object
string
environmentId
string
The parent environment this group belongs to.
name
string
color
string
Hex or named color. Omitted when empty.
position
number
Ordering position within the environment; also the sort key.
isDefault
boolean
collapsed
boolean
UI collapse state. Omitted when the underlying doc has never set it.
subGroups
array of object
createdByName
string
Display name of the member who created the group. null on auto-seeded default groups.nullable
createdAt
string <date-time>
nullable
updatedAt
string <date-time>
nullable
createdAt
string <date-time>
nullable
updatedAt
string <date-time>
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
PATCH/task-environments/{id}

Update a task environment

Updates only the provided fields of a task environment. Cross-org or soft-deleted resources return 404. Requires scope: tasks:write.

Parameters

Path

idrequired
string
The task environment ID.

Request body

FieldTypeDescription
name
string
The environment name. Cannot be set to empty.
icon
string
Material symbol icon name. Defaults to "folder" when set to empty.
position
number
Ordering position. Falls back to 0 if not a finite number.
assignees
array of object
id
string
name
string
role
string

Response 200

FieldTypeDescription
id
string
object
string
name
string
icon
string
Material symbol icon name. Omitted when absent on the underlying doc.
color
string
Color. Normally absent on environment docs (only groups carry color); surfaced if set.
isDefault
boolean
position
number
assignees
array of object
id
string
The member ID.
name
string
The member display name.
role
string
The member role. Omitted when empty.
assigneeIds
array of string
Server-derived parallel array of assignee IDs.
createdByName
string
Display name of the member who created the environment. null on the auto-seeded default environment.nullable
groups
array of object
Expanded groups. Present only on the retrieve (GET by id) endpoint; omitted from the list endpoint.
id
string
object
string
environmentId
string
The parent environment this group belongs to.
name
string
color
string
Hex or named color. Omitted when empty.
position
number
Ordering position within the environment; also the sort key.
isDefault
boolean
collapsed
boolean
UI collapse state. Omitted when the underlying doc has never set it.
subGroups
array of object
createdByName
string
Display name of the member who created the group. null on auto-seeded default groups.nullable
createdAt
string <date-time>
nullable
updatedAt
string <date-time>
nullable
createdAt
string <date-time>
nullable
updatedAt
string <date-time>
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
DELETE/task-environments/{id}

Delete a task environment

Soft-deletes a task environment and cascades the soft-delete to every active group and task within it, in a single batch. Org-scoped throughout. Requires scope: tasks:write.

Parameters

Path

idrequired
string
The task environment ID.

Response 200

FieldTypeDescription
id
string
object
string
deleted
boolean
groupsRemoved
integer
Number of active groups soft-deleted in the cascade.
tasksRemoved
integer
Number of active tasks soft-deleted in the cascade.

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
GET/task-environments/{id}/groups

List a task environment's groups

Lists the task groups that belong to a single environment, org-scoped and soft-delete filtered, position-ordered. Use a returned group id as the groupId required to create a task (the tasks API takes a groupId, not an environmentId). A cross-org or soft-deleted environment returns 404. Requires scope: tasks:read.

Parameters

Path

idrequired
string
The task environment ID.

Response 200

No fields.

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
POST/task-environments/{id}/groups

Create a task group

Creates a task group inside an environment. A group is the container a task is filed under, so this is how you build a board from scratch and then create tasks against it (POST /tasks requires a groupId). position auto-derives to the end of the environment when omitted. A cross-org or soft-deleted environment returns 404. Supports idempotent retries via the Idempotency-Key header. Requires scope: tasks:write.

Parameters

Path

idrequired
string
The task environment ID.

Request body

FieldTypeDescription
namerequired
string
The group's name (required).
color
string
Optional hex/named color swatch for the group.
position
integer
Optional ordering position; defaults to the end of the environment.

Response 201

FieldTypeDescription
id
string
object
string
environmentId
string
The parent environment this group belongs to.
name
string
color
string
Hex or named color. Omitted when empty.
position
number
Ordering position within the environment; also the sort key.
isDefault
boolean
collapsed
boolean
UI collapse state. Omitted when the underlying doc has never set it.
subGroups
array of object
id
string
name
string
color
string
Hex or named color. Omitted when empty.
position
number
createdByName
string
Display name of the member who created the group. null on auto-seeded default groups.nullable
createdAt
string <date-time>
nullable
updatedAt
string <date-time>
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
409Idempotency-Key reused with a different body
429Rate limited
500Unexpected server error