Skip to navigation
API ReferenceTasks

Create a task

Beta

Create a task (an assignable to-do) in a workspace the caller belongs to, with an optional due date and time, priority, assignee, labels, links to the records it is about and a folder or project to put it in. It is the caller’s own unless assignee_ref names someone who can already open it (assigning never shares it) or is null. Each link must be a record the caller can open, and a parent folder needs edit access.

Authentication

X-API-KEYstring
API Key authentication via header

Headers

X-Athena-Session-CredentialstringOptional

Request

This endpoint expects an object.
titlestringRequired

What to do, in a short line (at most 500 characters).

workspace_idstringRequired

The workspace to create it in; the caller must be a member.

assignee_refstring or nullOptional

Who it is for: user_… for a person, agent_asset_… for an agent, or me. Left out, the task is the caller’s own; null, nobody’s. Assigning never shares the task: the assignee must already be able to open it.

descriptionstring or nullOptional
Details, in markdown.
due_datestring or nullOptional

YYYY-MM-DD: a calendar day, with no time zone.

due_timestring or nullOptional

HH:MM on a 24-hour clock; needs due_date and due_time_zone.

due_time_zonestring or nullOptional

The IANA time zone of due_time, such as America/New_York.

labelslist of objects or nullOptional
Labels to put on it.
parent_folder_idstring or nullOptional

A folder or project to put it in; needs edit access there.

priorityenum or nullOptional

How much it matters; left out, none.

Allowed values:

Response

The task, read as the caller.
assigneeobject or null
Who it is for, or null for nobody.
can_editboolean or null

Whether the caller may change it; null in a list.

completed_atdatetime or null
When it was marked done.
completed_by_refstring or null
Who marked it done.
created_atdatetime or null
created_bystring or null
The user who created it.
descriptionstring or null
Markdown.
due_datestring or null

YYYY-MM-DD, or null.

due_timestring or null

HH:MM (24-hour), or null.

due_time_zonestring or null

The IANA time zone of due_time.

idstring
The task's asset id.
is_archivedboolean
Whether it is in the trash.
labelslist of objects
priorityenum
Allowed values:
statusenum
Allowed values:
titlestring
updated_atdatetime or null
workspace_idstring

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
422
Unprocessable Entity Error
503
Service Unavailable Error