User Content

Tasks

The Tasks API allows to manage user task lists and tasks in it, work in collaboration with other users.

Basic information

Basic entities:

  • Project
  • Task
  • ACL (Access Control List)

Some of requests may return related_changes as a field of result object.
related_changes is an object with two arrays unavailable and changed.
unavailable contains task ids that was deleted in current operation.
changed is a list of task changes that was done in this operation (except task that was excplicity changed)
Changes objects will provide sync_token (new one) and prev_sync_token (old one)
to simplify tracking of changes in tasks.

{
  "related_changes": {
    "unavailable": [
        1032
    ],
    changed: [
      {
        "id": 1032,
        "sort": 2112312,
        "mod_time": 1922321312,
        "mod_uid": 123123
        "sync_token": "20",
        "prev_sync_token": "14"
      }
    ]
  }
}

Base URI

Scopes

  • tasks_read
  • tasks_write
  • tasks_access_protected

tasks_access_protected designed to restrict an access to user's protected projects.
Without this scope application will not recieve protected projects from tasks/projects
endpoint and will not get access into any endpoint under PROJECT_RESOURCE_URI of protected project.
tasks_access_protected scope also needed to update needs_protection attribute of project.

Endpoints

RESOURCE_URI — URI is obtained from token exchange point.
PROJECT_RESOURCE_URI — URI is obtained from the project details response.

Prefix Endpoint Description
RESOURCE_URI tasks/projects/ Getting a list of projects
RESOURCE_URI tasks/projects/add/ Creating a project
RESOURCE_URI tasks/invitations Get pending project join invitations
RESOURCE_URI tasks/invitations/PROJECT_ID/accept Accept project join invitation
RESOURCE_URI tasks/invitations/PROJECT_ID/decline Decline project join invitation
RESOURCE_URI tasks/projects/ID/sort/ Sorting a project
RESOURCE_URI tasks/projects/ID/disconnect/ Disconnecting from a project
RESOURCE_URI tasks/projects/ID/acls/order/get Get user defined order of acls in particular project
RESOURCE_URI tasks/projects/ID/acls/order/set Get user defined order of acls in particular project
PROJECT_RESOURCE_URI null Retrieving project details
PROJECT_RESOURCE_URI stats/ Getting statistics
PROJECT_RESOURCE_URI edit/ Editing a project
PROJECT_RESOURCE_URI delete/ Deleting a project
PROJECT_RESOURCE_URI upload_tempfile/ Upload temporrary file for further attachmens creation
PROJECT_RESOURCE_URI sync/ Get tasks updates
PROJECT_RESOURCE_URI acls/ Getting a list of ACLs
PROJECT_RESOURCE_URI acls/add Add ACLs to project
PROJECT_RESOURCE_URI acls/ID Retrieving ACL details
PROJECT_RESOURCE_URI acls/ID/edit/ Editing an ACL
PROJECT_RESOURCE_URI acls/ID/delete/ Deleting an ACL
PROJECT_RESOURCE_URI tasks/ Getting a list of tasks
PROJECT_RESOURCE_URI tasks/add/ Adding a task
PROJECT_RESOURCE_URI tasks/ID Retrieving task details
PROJECT_RESOURCE_URI tasks/ID/assign/ Assigning a task
PROJECT_RESOURCE_URI tasks/ID/move/ Moving a task
PROJECT_RESOURCE_URI tasks/ID/sort/ Sorting a task
PROJECT_RESOURCE_URI tasks/ID/edit/ Editing a task
PROJECT_RESOURCE_URI tasks/ID/relocate/TARGET_PROJECT_ID Move task to another project
PROJECT_RESOURCE_URI tasks/ID/delete/ Deleting a task
PROJECT_RESOURCE_URI tasks/ID/history/ Getting a task update history

+Getting a list of projects

Endpoint

Scopes

  • tasks_read

Request

Response

+Creating a project

Endpoint

Scopes

  • tasks_write

Request

Response

+Get pending project join invitations

Endpoint

Scopes

  • tasks_read

Request

  • No specific request params

Response

+Accept project join invitation

Endpoint

Scopes

  • tasks_write

Request

  • No specific request params

Response

+Decline project join invitation

Endpoint

Scopes

  • tasks_write

Request

  • No specific request params

Response

  • Response is empty object

+Retrieving project details

Endpoint

  • PROJECT_RESOURCE_URI

Scopes

  • tasks_read

Request

Response

+Getting statistics

Endpoint

  • PROJECT_RESOURCE_URIstats/

Scopes

  • tasks_read

Request

Response

+Sorting a project

Endpoint

  • RESOURCE_URItasks/projects/ID/sort/

Scopes

  • tasks_write

Request

Response

+Editing a project

Endpoint

  • PROJECT_RESOURCE_URIedit/

Scopes

  • tasks_write

Request

Response

+Disconnecting from a project

Endpont

  • PROJECT_RESOURCE_URIdisconnect/

Scopes

  • tasks_write

Request

  • No specific request params

Response

  • No specific response params

+Get user defined acl's sort in project

Endpoint

  • RESOURCE_URItasks/projects/ID/acls/order/get

Scopes

  • tasks_read

Request

  • No specific request params

Response

  • Response object type is unsigned integer[]

+Set user defined acl's sort in project

Endpoint

  • RESOURCE_URItasks/projects/ID/acls/order/get

Scopes

  • tasks_write

Request

  • Request object type is unsigned integer[]

Response

  • Response object type is unsigned integer[]

+Deleting a project

Endpont

  • PROJECT_RESOURCE_URIdelete/

Scopes

  • tasks_write

Request

  • No specific request params

Response

  • No specific response params

+Getting tasks and project updates

Endpoint

  • PROJECT_RESOURCE_URIsync/

Scopes

  • tasks_read

Request

Response

+Upload temporrary file for further attachment creation

Endpoint

  • PROJECT_RESOURCE_URIupload_tempfile/

Scopes

  • tasks_write

Request

  • Request method is POST
  • Request content type is multipart/form-data
  • Request should contain file contents in param file or in param wich name is specified by 'upload_parameter_name' inside 'q' param
  • Further data should be in param q i.e. (q={"key":"value"})
  • No request data needed

Response

+Resumable File (temporrary) Upload for further attachment creation

Endpoint

  • PROJECT_RESOURCE_URIupload_tempfile/

Scopes

  • tasks_write

Request

Response

Upload proccess

To upload file use returned put_uri. If chunks_expected is equal 1 then upload
file with a single request.If chunks_expected > 1 then file must be sent in separate
requests with propper Range header set. Content-Range: bytes START_POS-END_POS/FILE_SIZE where

  • FILE_SIZE: size of file
  • START_POS: 0 based position of upload
  • END_POS: START_POS + chunk_size - 1

On successful chunk upload server will response with 201 status.
On last chunk upload server will response with @Attachment

+Getting a list of ACLs

Endpoint

  • PROJECT_RESOURCE_URIacls/

Scopes

  • tasks_read

Request

Response

+Add ACLs to project

Endpoint

  • PROJECT_RESOURCE_URIacls/add

Scopes

  • tasks_write

Request

Response

+Retrieving ACL details

Endpoint

  • PROJECT_RESOURCE_URIacls/ID

Scopes

  • tasks_read

Request

  • No specific request params

Response

+Editing an ACL

Endpoint

  • PROJECT_RESOURCE_URIacls/ID/edit/

Scopes

  • tasks_write

Request

Response

+Deleting an ACL

Endpoint

  • PROJECT_RESOURCE_URIacls/ID/delete/

Scopes

  • tasks_write

Request

Response

  • No specific response params
  • Response object can have additional field related_changes @see Related changes in case this operation caused other tasks to be changed.

+Getting a list of tasks

Endpoint

  • PROJECT_RESOURCE_URItasks/

Scopes

  • tasks_read

Request

Response

+Retrieving task details

Endpoint

  • PROJECT_RESOURCE_URItasks/ID

Scopes

  • tasks_read

Request

Response

+Adding a task

Endpoint

  • PROJECT_RESOURCE_URItasks/add/

Scopes

  • tasks_write

Request

Response

  • Response object type is @TaskInfo
  • Response object can have additional field related_changes @see Related changes in case this operation caused other tasks to be changed.

+Assigning a task

Endpoint

  • PROJECT_RESOURCE_URItasks/ID/assign/

Scopes

  • tasks_write

Request

Response

  • Response object type is @TaskInfo
  • Response object can have additional field related_changes @see Related changes in case this operation caused other tasks to be changed.

+Moving a task

Endpoint

  • PROJECT_RESOURCE_URItasks/ID/move/

Scopes

  • tasks_write

Request

Response

  • Response object type is @TaskInfo
  • Response object can have additional field related_changes @see Related changes in case this operation caused other tasks to be changed.

+Moving a task to another project

This will move task and all it descendant tasks into project specified by TARGET_PROJECT_ID.
User must be admin for both source and target projects.

Endpoint

  • PROJECT_RESOURCE_URItasks/ID/relocate/TARGET_PROJECT_ID

Scopes

  • tasks_write

Request

  • No specific request params

Response

+Sorting a task

Endpoint

  • PROJECT_RESOURCE_URItasks/ID/sort/

Scopes

  • tasks_write

Request

Response

  • Response object type is @TaskInfo
  • Response object can have additional field related_changes @see Related changes in case this operation caused other tasks to be changed.

+Editing a task

Endpoint

  • PROJECT_RESOURCE_URItasks/ID/edit/

Scopes

  • tasks_write

Request

Response

  • Response object type is @TaskInfo
  • Response object can have additional field related_changes @see Related changes in case this operation caused other tasks to be changed.

+Deleting a task

Deleting a task which has subtasks will lead to move nested tasks to a higher level.

Endpoint

  • PROJECT_RESOURCE_URItasks/ID/delete/

Scopes

  • tasks_write

Request

Response

  • Response object is type of @DeleteTaskResponse
  • Response object can have additional field related_changes @see Related changes in case this operation caused other tasks to be changed.

+Getting a task update history

Endpoint

  • PROJECT_RESOURCE_URItasks/ID/history/

Scopes

  • tasks_read

Request

  • No specific request params

Response

Definitions

ProjectsListRequest

Name Description

withremote
boolean

Whether to retrieve info about remote lists (not owned by user, but shared with him by its owner)
(default: false)

ProjectsListResponse

Name Description

items[]
object

@ProjectBriefInfo

ProjectBriefInfo

Name Description

id
string

Unique project identifier

resource_uri
string

URL to use as PROJECT_RESOURCE_URI

title
string

Project title

is_remote
boolean

if false - project is owned by user, otherwise it is shared with him

is_multiuser
boolean

If project has more than one user

sort
unsigned integer

Project order

acl_order[]
unsigned integer

Order of acl ids - may not contain all acl ids

admin_uid
unsigned integer

user id of project owner - for remote == false it is always current user

needs_protection
boolean

This flag signals that project owner wishes access to this
project to be more secured from third eyes (it can be extra
user verify with custom password or some other sort of client side protection)

sync_token
string

Current sync token for this project.
Can be used to determine if this project should be re-synced.

ProjectGetRequest

Name Description

populate_users
boolean

return additional user info
(default: false)

ProjectFullInfo

Name Description

id
string

Unique project identifier

resource_uri
string

URL to use as PROJECT_RESOURCE_URI

title
string

Project title

is_remote
boolean

If false - project is owned by user, otherwise it is shared with him

is_multiuser
boolean

If project has more than one user

admin_uid
unsigned integer

User id of project owner - for remote == false it is always current user

role
string

@ProjectRole Project role of current user (for local projects it is always "admin")

users[]
object

@ProjectACL List of project acls

needs_protection
boolean

This flag signals that project owner wishes access to this
project to be more secured from third eyes (it can be extra
user verify with custom password or some other sort of client side protection)

sync_token
string

Current sync token for this project.
Can be used to determine if this project should be re-synced.

ProjectACL

Name Description

id
unsigned integer

Unique user identifier

role
string

@ProjectRole User role in project

can_add
boolean

if true user has rights to add new tasks
For admin and manger it is awlays "true", for executor it can be changed (default "true")
Executor still have its own limitations, he can only add tasks into trees where he is assigned as executor or at top level

state
string

@UserState

sync_token
string

Personal sync_token for this ACL

ProjectCreateRequest

Name Description

title (required)
string

Project title.

after_item
string

Project id to place project after it or "" (empty string)
to place project at first position. If sort was successfull
updated_sorts field will be added to response object to
represent changes in sort values for other projects. If this
field ommited project will be added to the last position in
projects list

ProjectEditRequest

Name Description

title (required)
string

Project title.

needs_protection
boolean

Requires tasks_access_protected scope

sync_token
string

If provided will ensure that changed project sync_token is not older
, otherwise error will be returned

ProjectSortRequest

Name Description

after_item (required)
string

Project id to place project after it or "" (empty string)
to place project at first position

ProjectSortRequestResponse

Name Description

sorts[]
object

sorts[n].id
string

Project ID

sorts[n].sort
unsigned integer

Sort value

ProjectsStatsRequest

Name Description

year
unsigned integer

4 digit year
(default: current year)

month
unsigned integer

Month number starting from 1
If ommited returned range is 'year'

date
unsigned integer

Date in month starting from 1
If ommited returned range is 'month' (unless month is ommited too)

executor_uid
unsigned integer

User id to filter tasks by

timezone
string

Timezone to use, format as in Olson DB
(default: as in unet user settings)

ProjectsStatsResponse

Name Description

created
unsigned integer

Number of created tasks

overdued
unsigned integer

Number of overdued tasks
(tasks that have deadline in period and not yet completed or completed after deadline)

completed
unsigned integer

Number of completed tasks

AclsListResponse

Name Description

items[]
object

@ProjectACL

AclEditRequest

Name Description

role
string

@ProjectRole
new role for a user (user with admin role can be only one and it is not editable)

can_add
boolean

new value for "can_add", editable only if user role is executor (whether it was set in this request or before)

populate_users
boolean

whether to populate user before return

sync_token
string

If provided will ensure that changed acl sync_token is not older
, otherwise error will be returned

AclAddRequest

Name Description

uid (required)
string

User UID or profile url to add.

role
string

@ProjectRole
role for a new user (user with admin role can be only one and it is not editable)

can_add
boolean

new value for "can_add", editable only if user role is executor (whether it was set in this request or before)

populate_users
boolean

whether to populate user before return

AclDeleteRequest

Name Description

delete_tasks
boolean

if true then tasks that were assigned to this user will be deleted as well
otherwise no tasks will be changed and user state will be changed to 'deactivated' (default: false)

TasksListRequest

Name Description

ids[]
unsigned integer

exact list of task ids to retrieve (no createria will be checked)

criteria
object

@TasksListCriteria special criteria to search for tasks

fields[]
string

TODO
Read more about the Fields model.

TasksListCriteria

Name Description

status
string

@TaskStatus

color
string

@TaskColor

parent_id
unsigned integer

parent task id

executor_uid
unsigned integer

user id

owner_uid
unsigned integer

user id

modified_after
timestamp

timestamp to retrieve tasks created or modified after it

min_create_time
timestamp

get tasks created not earlier than specified value

max_create_time
timestamp

get tasks created not later than specified value

min_finish_time
timestamp

get tasks finished not earlier than specified value

max_finish_time
timestamp

get tasks finished not later than specified value

min_deadline_time
timestamp

get tasks that has deadline not earlier than specified value

max_deadline_time
timestamp

get tasks that has deadline not later than specified value

TasksListResponse

Name Description

items[]
object

@TaskInfo

TaskGetRequest

Name Description

fields[]
string

TODO
Read more about the Fields model.

TaskAddRequest

Name Description

title (required)
string

Task title

color
string

@TaskColor
(default: "black")

parent_id
unsigned integer

ID of parent task or omit to add task into top level

previous_id
unsigned integer

ID of previous task or omit to add task into start position in nest level

executor_uid
unsigned integer

Executor user id (only if user has rights to set it)
(default: )

deadline_time
timestamp

Time user plan to close task, 0 - no deadline
(default: 0)

description
string

Task description (may contain html)

attachments[]
object

@AttachmentsConfiguration

fields[]
string

TODO
Read more about theFields model.

TaskEditRequest

Name Description

title
string

Task title

color
string

@TaskColor

status
string

@TaskStatus

deadline_time
timestamp

Time user plan to close task, 0 - no deadline

description
string

Task description (may contain html)

attachments[]
object

@AttachmentsConfiguration

force_title
boolean

Rewrite title even if server content_mod_time is newer than content_mod_time

force_description
boolean

Rewrite description even if server content_mod_time is newer than content_mod_time

content_mod_time
timestamp

Last recieved content_mod_time for a task to check for concurent title or description change

sync_token
string

Last known sync_token - if this token will be different from server current sync token
server will return error (sync token error). If sync_token specified then force_description, force_title and
content_mod_time will be ignored

fields[]
string

TODO
Read more about the Fields model.

DeleteTaskRequest

Name Description

nested
boolean

true - remove task with its children
(default: false)

DeleteTaskResponse

Name Description

level_resorted
boolean

true - if level re-sort was occured

ids[]
unsigned integer

IDs of moved or deleted tasks (children only). For nested delete will contain all nested task ids. For not nested delete will contain only first level tasks as only they will have their parent_ids changed

TaskInfo

Name Description

id
unsigned integer

Task ID.

project_id
string

Project ID.

title
string

Task title.

description
string

Description text (HTML formatted).

color
string

@TaskColor

parent_id
unsigned integer

ID of the parent task.

sort
unsigned integer

The task sorting position.

status
string

@TaskStatus

owner_uid
unsigned integer

User who created the task.

executor_uid
unsigned integer

User who is the executor of the task.

create_time
timestamp

Time the task was created.

finish_time
timestamp

Time of the task complete.

deadline_time
timestamp

Deadline time.

mod_time
timestamp

Modification time.

mod_uid
unsigned integer

User who modified any parameter of the task.

content_mod_time
timestamp

Modification time of the task's content.

content_mod_uid
unsigned integer

User who modified the task's content.

attachments
object

@AttachmentStructure

has_attachments
boolean

Flag indicates that the task has attachments.

has_description
boolean

Flag indicates that the task has description.

has_rich_decor
boolean

Flag indicates that the description text is formatted using complex HTML tags, such as TABLE, FIELDSET, etc.

comments_count
unsigned integer

Number of comments.

sync_token
string

Personal sync_token for this task

AssignTaskRequest

Name Description

executor_uid (r)
unsigned integer

New executor user id

parent_task
unsigned integer

ID of a task to set as parent_id. 0 - place task at top level
(Default: 0)

after_task
unsigned integer

ID of a task to place this task after it. 0 - place task at first position
(Default: 0)

fields[]
string

TODO
Read more about the Fields model.

sync_token
string

If provided will ensure that changed task sync_token is not older
, otherwise error will be returned

MoveTaskRequest

Name Description

parent_task (required)
unsigned integer

ID of a task to set as parent_id. 0 - place task at top level

after_task
unsigned integer

ID of a task to place this task after it. 0 - place task at first position
(Default: 0)

fields[]
string

TODO
Read more about the Fields model.

sync_token
string

If provided will ensure that changed task sync_token is not older
, otherwise error will be returned

SortTaskRequest

Name Description

after_task (r)
unsigned integer

ID of a task to place this task after it.

fields[]
string

TODO
Read more about the Fields model.

sync_token
string

If provided will ensure that changed task sync_token is not older
, otherwise error will be returned

TasksRelocateResponse

Name Description

moved_ids[]
unsigned integer

Ids of moved tasks

TaskHistoryResponse

Name Description

items[]
object

@StatusRecord

TasksSyncRequest

Name Description

sync_token
string

Token recieved from previous sync request or empty string
if it is first sync request

check_ids[]
unsigned integer

If from last sync has past a lot of time, server will reject
sync request from clients that does not provide their known task IDs.
This IDs are needed to construct proper "unavailable" field of response.

populate_users
boolean

return additional user info
(default: false)

fields[]
string

TODO
Read more about the Fields model.

TasksSyncResponse

Name Description

project
object

@ProjectFullInfo or null if
no changes to project was made since last sync.
This object will NOT contain users block

tasks
object

tasks.updated[]
object

@TaskInfo

tasks.unavailable[]
unsigned integer

IDs of unavailable tasks (this can be deleted or tasks that
is no longer accesible by current user due rights limitation)

acls
object

acls.updated[]
object

@ProjectACL

acls.unavailable[]
unsigned integer

Unavailable ProjectACL ids (deleted)

sync_token
string

New sync token - app should use it in next sync request

TasksResumableUploadRequest

Name Description

put_method (required)
boolean

true

file_size (required)
unsigned integer

Size of file to be uploaded

file_name (required)
string

File name

chunk_size
unsigned integer

Must be multiple of 256Kb

TasksResumableUploadResponse

Name Description

put_uri
string

Upload endpoint to send file to via PUT method

chunks_expected
unsigned integer

file_types_expected
string[]

Of file, image, video, audio

timeout
unsigned integer

How long in seconds returned upload endpoint will be available if not in use.

StatusRecord

Name Description

time
timestamp

When this status record was added

type
string

Possible values:

  • add
  • edit
  • status
  • pchange

actor_uid
unsigned integer

ID of user that does changes

new_values
object

@StatusRecordValues New values for some of changed fields

updated[]
string

Array of changes that was made.
Possible values:

  • executor_uid
  • title
  • description
  • attachments
  • deadline_time
  • status

StatusRecordValues

Name Description

status
string

@TaskStatus new task status if it was changed

executor_uid
unsigned integer

ID of new executor if it was changed

ProjectInvitationsResponse

Name Description

items[]
object

@ProjectJoinInvitation

ProjectJoinInvitation

Name Description

project_id
string

project_title
string

admin_uid
unsigned integer

UID of project's admin

add_time
unsigned integer

Time in seconds when invitation was added

ProjectRole

  • admin
  • executor
  • supervisor

TaskStatus

  • draft — created but not sent to an executor
  • sent — sent to an executor
  • taken — taken by an executor
  • pending — pending for approval by a supervisor
  • complete — marked as accomplished

TaskColor

  • red
  • orange
  • yellow
  • light-green
  • green
  • sky-blue
  • blue
  • purple
  • pink
  • gray
  • black

UserState

  • pending - invitation was sent to user but not yet accepted
  • active - user accepted the invitation
  • disconnected - user has leaved the project
  • deactivated - user was rejected by admin
  • deleted - user was deleted from project