Tasks (Todo), File Requests and Approvals - Huddle/huddle-apis GitHub Wiki

Summary

Tasks represent work items to be completed by an arbitrary set of assignees. A task is subdivided into three types: To-Do (task), file request, and approval.

These operations are served by Huddle.Tasks.Api. Public URLs use the /tasks prefix (for example GET /tasks/{taskId}, GET /tasks/workspace/{workspaceId}, GET /tasks?... for cross-workspace queries). The default response format is JSON; XML is also supported.

To add or remove assignees after a task exists, see TaskAssignments. For attachments, see TaskAttachments. For comments, see TaskComments.

Operations

Method Path Purpose Details
GET /tasks/12345 Retrieve a Task Jump
GET /tasks/workspace/123?types=todo&destinationfolderid=456&approvaldocumentId=789&workflowId=987&statuses=NotStarted&title=hola&assignedtousers=any&attacheddocuments=any&createdbyusers=2,7&earliestduedate=2016-08-13&latestduedate=2019-10-13&pagesize=5&skipitems=0&sort=duedate,desc&include=assignments&customfield=3,Red Retrieve all Tasks in a workspace Jump
GET /tasks?types=todo&destinationfolderid=456&approvaldocumentId=789&workflowId=987&statuses=NotStarted&title=hola&assignedtousers=any&attacheddocuments=any&createdbyusers=2,7&earliestduedate=2016-08-13&latestduedate=2019-10-13&pagesize=5&skipitems=0&sort=duedate,desc&include=assignments Retrieve all Tasks for the current user Jump
GET /tasks/workspace/123/stats?types=FileRequest Retrieve Workspace Task stats Jump
POST /tasks/workspace/123 Create a Todo Jump
POST /tasks/workspace/123 Create an Approval Jump
GET /tasks/workspace/123 Create a File Request Jump
PUT /tasks/12345 Edit a Todo Jump
GET /tasks/workspace/123 Edit a File Request Jump
PUT /tasks/12345/status Update Task status Jump
GET /tasks/workspace/123/csv Export Tasks to CSV Jump
DELETE /tasks/12345 Delete a Task Jump
POST /tasks/12345/restore Restore a Task Jump
POST /tasks/12345/update Update a Task's assignments, attachments and custom fields Jump

Retrieve a task

Link relations

Type Name Description Methods
task self The URI of the Task. GET
task parent The URI of the Workspace. GET
task alternate Alternate URI for task GET
task audit-trail The URI of the Task's audit trail. GET
task comments The URI of the Task's comments. GET, POST
task attachments The URI of the Task's attachments. GET, POST
task assignments The URI of the Task's assignments. GET, POST
task custom-fields The URI of the task's custom field entries (typically on Todo when custom fields exist). GET
task edit The URI to replace the full task (PUT). PUT
task update-task The URI to apply partial updates (assignments, attachments, custom fields, etc.) in one request. POST
task replace The URI to replace assignees (POST to .../assignments/replace). Also listed on the assignments collection. POST
task update-status The URI to update Task status. PUT
task delete The URI to delete the Task. DELETE
task completed-by The URI of the user who completed the task. GET
task share-task (Only FileRequest & Todo) The URI to share the task with recipients. POST
task document (Only Approval) The URI of the document to approve. GET
task workflow (Only Approval) The URI to get the Task workflow GET
task destination-folder (Only File Request) The URI of the Destination Folder. GET
actor owner The URI of the owner user for the task. GET

Example

Request XML

GET /tasks/12345 HTTP/1.1
Accept: application/vnd.huddle.data+xml
Authorization: Bearer frootymcnooty/vonbootycherooty

Request JSON

GET /tasks/12345 HTTP/1.1
Accept: application/json
Authorization: Bearer frootymcnooty/vonbootycherooty

Response

If successful, this method will return a response with an OK status code. This response uses the standard error codes and returns standard response headers. This response shows an example of a Task of type Todo.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "title": "Not another task title",
  "description": "Report documents for business intelligence",
  "type": "Todo",
  "links": [
    { "rel": "self", "href": "..." },
    { "rel": "parent", "href": "...", "title": "Ramona's workspace" },
    { "rel": "alternate", "href": "..."},
    { "rel": "audit-trail", "href": "..." },
    { "rel": "comments", "href": "...", "count": 3 },
    { "rel": "attachments", "href": "...", "count": 0 },
    { "rel": "assignments", "href": "...", "count": 1 },
    { "rel": "edit", "href": "..." },
    { "rel": "update-status", "href": "..." },
    { "rel": "delete", "href": "..." }
  ],
  "actors": [
    {
      "name": "Ramona Flowers",
      "email": "[email protected]",
      "rel": "owner",
      "links": [
        { "rel": "self", "href": "..." },
        { "rel": "avatar", "href": "...", "type": "image/jpeg" },
        { "rel": "alternate", "href": "...", "type": "text/html" }
      ]
    }
  ],
  "status": "NotStarted",
  "created": "Mon, 15 Jul 2019 00:00:00 GMT",
  "updated": "Mon, 28 Jul 2019 00:00:00 GMT"
}

Error Responses

Case Response Code Error Code
Task does not exist 404 Not Found TaskNotFound
Task is deleted 404 Not Found TaskDeleted
User is not a member of the Workspace 403 Forbidden WorkspaceMembershipRequired
Workspace is locked 403 Forbidden WorkspaceLocked
Workspace is deleted 404 Not Found WorkspaceDeleted

Retrieve all Tasks in a workspace

This endpoint returns all the tasks in a Workspace.

Filters

Filters are query string parameters that are used to filter the tasks in your workspace, e.g.

GET /tasks/workspace/123?types=todo&destinationfolderid=456&approvaldocumentId=789&workflowId=987&statuses=NotStarted&title=hola&assignedtousers=any&attacheddocuments=any&createdbyusers=2,7&earliestduedate=2016-08-13&latestduedate=2019-10-13&pagesize=5&skipitems=0&sort=duedate,desc&include=assignments&customfield=3,Red
Parameter Default value Additional notes
types (see note) Comma-separated Todo, FileRequest, Approval. If omitted, the API defaults to FileRequest only (legacy behaviour).
destinationfolderid Single integer id. Valid only for File Request type.
approvaldocumentId Single integer id. Valid only for Approval type.
workflowId Single integer id. Valid only for Approval type.
statuses Comma separated list of statuses: NotStarted, InProgress, Complete. If no value supplied Tasks are not filtered on Status.
title Tasks with titles containing the text. If no value supplied Tasks are not filtered on title.
assignedtousers me, none, any, or a comma separated list of user ids, e.g. 10,20,30. If no value supplied Tasks are not filtered on Assignment.
attacheddocuments none, any, or a comma separated list of document ids, e.g. 10,20,30. If no value supplied Tasks are not filtered on Attachment.
createdbyusers Comma separated list of user ids, e.g. 10,20,30
earliestduedate Expected date format is YYYY-MM-DD, e.g. 2016-08-13
latestduedate Expected date format is YYYY-MM-DD, e.g. 2016-08-13
pagesize 50 Minimum value: 1; Maximum value: 500.
skipitems 0
sort duedate,desc Use field or field,direction (e.g. duedate,desc). A direction alone (e.g. desc) is not valid. Fields: title, startdate, duedate, status, latestattachmentdate, updateddate. Directions: asc, desc.
include At the moment only assignments is supported.
customfield Optional filter: two comma-separated values — custom field id and value to match (example: 3,Red)

All filters are disabled by default. If there are more tasks than the current page size, the link collection will contain a next link. If there are one or more previous pages, the link collection will return a prev and a first link. Use these links to navigate between pages.

Link relations

Name Description Methods
self The URI of the Task collection. GET
parent The URI of the Workspace. GET
current The URI of the current page, using the specified sort order and filters. GET
first The URI of the first page, using the specified sort order and filters. GET
next The URI of the next page, using the specified sort order and filters. GET
prev The URI of the previous page, using the specified sort order and filters. GET
create The URI to create Tasks. POST
custom-fields The URI to workspace custom fields. GET
audit-trail The URI to workspace audits. GET
bulk-delete The URI to bulk delete tasks. POST

Bulk create and bulk edit use POST /tasks/workspace/{workspaceId}/bulk-create and .../bulk-edit (see TaskBulkOperations); those URLs are not currently exposed as link relations on this collection.

Workspace statistics are GET /tasks/workspace/{workspaceId}/stats (see Retrieve workspace task stats); that URL is not currently returned as a link on this collection either.

Example

Request

GET /tasks/workspace/123 HTTP/1.1
Accept: application/json
Authorization: Bearer frootymcnooty/vonbootycherooty

Response

If successful, this method will return a response with an OK status code. This response uses the standard error codes and returns standard response headers. This response shows an example of type FileRequest.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "links": [
    { "rel": "self", "href": "..." },
    { "rel": "parent", "href": "..." },
    { "rel": "current", "href": "..." },
    { "rel": "create", "href": "..." },
    { "rel": "custom-fields", "href": "..." }
  ],
  "tasks": [
    {
      "title": "Engineering supervise",
      "description": "",
      "type": "FileRequest",
      "links": [
        { "rel": "self", "href": "..." },
        { "rel": "parent", "href": "...", "title": "Engineering workspace" },
        { "rel": "alternate", "href": "..."},
        { "rel": "audit-trail", "href": "..." },
        { "rel": "comments", "href": "...", "count": 0 },
        { "rel": "attachments", "href": "...", "count": 0 },
        { "rel": "assignments", "href": "...", "count": 1 },
        { "rel": "edit", "href": "..." },
        { "rel": "update-status", "href": "..." },
        { "rel": "delete", "href": "..." },
        { "rel": "destination-folder", "href": "..." }
      ],
      "actors": [
        {
          "name": "Jessica Hyde",
          "email": "[email protected]",
          "rel": "owner",
          "links": [
            { "rel": "self", "href": "..." },
            { "rel": "avatar", "href": "...", "type": "image/jpeg" },
            { "rel": "alternate", "href": "...", "type": "text/html" }
          ]
        },
        {
          "name": "Wilson Wilson",
          "email": "[email protected]",
          "rel": "completed-by",
          "links": [
            { "rel": "self", "href": "..." },
            { "rel": "avatar", "href": "...", "type": "image/jpeg" },
            { "rel": "alternate", "href": "...", "type": "text/html" }
          ]
        }
      ],
      "assignments": [
        {
          ...See assignment response*
        }
      ],
      "status": "Complete",
      "created": "Mon, 25 Nov 2019 00:00:00 GMT",
      "updated": "Mon, 25 Nov 2019 00:00:00 GMT",
      "completed": "Mon, 25 Nov 2019 00:00:00 GMT",
      "dueDate": "Thu, 13 Dec 2029 00:00:00 GMT"
    },
    {
      ...Another task element
    }
  ]
}

*See Task Assignments — JSON response

Error Responses

Case Response Code Error Code
User is not a member of the Workspace 403 Forbidden WorkspaceMembershipRequired
Workspace is locked 403 Forbidden WorkspaceLocked
Workspace is deleted 404 Not Found WorkspaceDeleted

Retrieve all Tasks for the current user

This endpoint returns all the tasks visible to the current User, regardless of Workspace.

Filters

Filters are query string parameters that are used to filter tasks across workspaces for the current user, e.g.

GET /tasks?types=todo&destinationfolderid=456&approvaldocumentId=789&workflowId=987&statuses=NotStarted&title=hola&assignedtousers=any&attacheddocuments=any&createdbyusers=2,7&earliestduedate=2016-08-13&latestduedate=2019-10-13&pagesize=5&skipitems=0&sort=duedate,desc&include=assignments
Parameter Default value Additional notes
types (see note) Comma-separated Todo, FileRequest, Approval. If omitted, the API defaults to FileRequest only (legacy behaviour).
destinationfolderid Single integer id. Valid only for File Request type.
approvaldocumentId Single integer id. Valid only for Approval type.
workflowId Single integer id. Valid only for Approval type.
statuses Comma separated list of statuses: NotStarted, InProgress, Complete. If no value supplied Tasks are not filtered on Status.
title Tasks with titles containing the text. If no value supplied Tasks are not filtered on title.
assignedtousers me, none, any, or a comma separated list of user ids, e.g. 10,20,30. If no value supplied Tasks are not filtered on Assignment.
attacheddocuments none, any, or a comma separated list of document ids, e.g. 10,20,30. If no value supplied Tasks are not filtered on Attachment.
createdbyusers Comma separated list of user ids, e.g. 10,20,30
earliestduedate Expected date format is YYYY-MM-DD, e.g. 2016-08-13
latestduedate Expected date format is YYYY-MM-DD, e.g. 2016-08-13
pagesize 50 Minimum value: 1; Maximum value: 500.
skipitems 0
sort duedate,desc Use field or field,direction (e.g. duedate,desc). A direction alone (e.g. desc) is not valid. Fields: title, startdate, duedate, status, latestattachmentdate, updateddate. Directions: asc, desc.
include At the moment only assignments is supported.

All filters are disabled by default. If there are more tasks than the current page size, the link collection will contain a next link. If there are one or more previous pages, the link collection will return a prev and a first link. Use these links to navigate between pages.

Link relations

Name Description Methods
self The URI of the Task collection. GET
parent The URI of the User. GET
current The URI of the current page, using the specified sort order and filters. GET
first The URI of the first page, using the specified sort order and filters. GET
next The URI of the next page, using the specified sort order and filters. GET
prev The URI of the previous page, using the specified sort order and filters. GET

Example

Request

GET /tasks HTTP/1.1
Accept: application/json
Authorization: Bearer frootymcnooty/vonbootycherooty

Response

If successful, this method will return a response with an OK status code. This response uses the standard error codes and returns standard response headers. This response shows an example of type Approval.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "links": [
    { "rel": "self", "href": "..." },
    { "rel": "parent", "href": "..." },
    { "rel": "current", "href": "..." }
  ],
  "tasks": [
    {
      "title": "",
      "description": "",
      "type": "Approval",
      "links": [
        { "rel": "self", "href": "..." },
        { "rel": "parent", "href": "...", "title": "Sales workspace" },
        { "rel": "alternate", "href": "..."},
        { "rel": "audit-trail", "href": "..." },
        { "rel": "comments", "href": "...", "count": 0 },
        { "rel": "attachments", "href": "...", "count": 0 },
        { "rel": "assignments", "href": "...", "count": 1 },
        { "rel": "edit", "href": "..." },
        { "rel": "update-status", "href": "..." },
        { "rel": "delete", "href": "..." },
        { "rel": "document", "href": "..." },
        { "rel": "workflow", "href": "..." }
      ],
      "assignments": [
        {
          ...See assignment response*
        }
      ],
      "actors": [
        {
          "name": "Valentin Casanova",
          "email": "[email protected]",
          "rel": "owner",
          "links": [
            { "rel": "self", "href": "..." },
            { "rel": "avatar", "href": "...", "type": "image/jpeg" },
            { "rel": "alternate", "href": "...", "type": "text/html" }
          ]
        }
      ],
      "status": "InProgress",
      "created": "Mon, 09 Dec 2019 14:42:13 GMT",
      "updated": "Mon, 09 Dec 2019 14:42:13 GMT",
      "dueDate": "Fri, 10 Jan 2020 00:00:00 GMT",
      "createdDocumentContentVersion": 1,
      "document": {
        "title": "X-File",
        "contentType": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
        "version": 1,
        "links": [
          { "rel": "self", "href": "..." },
          { "rel": "alternate", "href": "...", "type": "text/html" }
        ],
        "workspace": {
          "title": "Secret dep workspace",
          "links": [
            { "rel": "self", "href": "..." },
            { "rel": "alternate", "href": "...", "type": "text/html" }
          ]
        }
      }
    },
    { ...other tasks elements }
  ]
}

*See Task Assignments — JSON response

Retrieve workspace task stats

This endpoint returns task statistics of the selected Workspace.

Filters

Stats use a subset of the workspace task list filters. Supported query parameters:

Parameter Default Notes
types Comma-separated Todo, FileRequest, Approval. Preferred. If both types and type are omitted, the server defaults to FileRequest only (same as the workspace task list).
type Legacy single-type alias; treated like a one-value types filter.
statuses Comma-separated NotStarted, InProgress, Complete.
assignedtousers Same values as the workspace task list (me, none, any, or user ids).
attacheddocuments Same as workspace task list.
createdbyusers Comma-separated user ids.
earliestduedate YYYY-MM-DD.
latestduedate YYYY-MM-DD.
destinationfolderid File-request folder filter when applicable.

Not applied to stats (even though they exist on GET /tasks/workspace/{id}): title, workflowId, approvaldocumentId, customfield, include, pagesize, skipitems, sort.

Link relations

Name Description Methods
self The URI of the workspace stats. GET
parent The URI of the tasks in the workspace collection. GET

Request

GET /tasks/workspace/123/stats?types=FileRequest HTTP/1.1
Accept: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

Response

If successful, this method will return a response with an OK status code. This response uses the standard error codes and returns standard response headers.

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json

{
  "links": [
    { "rel": "self", "href": "..." },
    { "rel": "parent", "href": "..." }
  ],
  "counts": {
    "notStarted": {
      "total": 2,
      "late": 0
    },
    "inProgress": {
      "total": 0,
      "late": 0
    },
    "complete": {
      "total": 1,
      "late": 0
    }
  }
}

Error Responses

Case Response Code Error Code
User is not a member of the Workspace 403 Forbidden WorkspaceMembershipRequired
Workspace is locked 403 Forbidden WorkspaceLocked
Workspace is deleted 404 Not Found WorkspaceDeleted

Create a Todo

Request

POST /tasks/workspace/123 HTTP/1.1
Content-Type: application/json
Authorization: Bearer frootymcnooty/vonbootycherooty

{
  "type": "todo",
  "title": "A new task",
  "status": "NotStarted",
  "plannedStartDate": "2011-05-01",
  "dueDate": "2011-05-10",
  "customFields": {
    "customFieldId": 123,
    "value": "Value One"
  },
  "links": [
    {
      "rel": "assignee",
      "href": "..."
    },
    {
      "rel": "attachment",
      "href": "..."
    }
  ]
}

Response

If successful, this method will return an empty response with a Created status code and a Location header containing the URI of the created task. This response uses the standard error codes and returns standard response headers.

HTTP/1.1 201 Created
Location: /tasks/12345

Error Responses

Case Response Code Error Code
Title is missing or empty 400 Bad Request Invalid
Status is missing or empty 400 Bad Request Invalid
Any date is malformed 400 Bad Request Invalid
User is not a member of the Workspace 403 Forbidden WorkspaceMembershipRequired
Workspace is locked 403 Forbidden WorkspaceLocked
Workspace is archived 403 Forbidden WorkspaceArchived
Workspace is deleted 404 Not Found WorkspaceDeleted

Create an approval

Example

Request

POST /tasks/workspace/123 HTTP/1.1
Content-Type: application/json
Authorization: Bearer frootymcnooty/vonbootycherooty

{
  "type": "approval",
  "status": "InProgress",
  "dueDate": "2011-05-10",
  "documentContentVersion": 123,
  "links":
    [
      { "rel": "document", "href": "...", },
      { "rel": "assignee", "href": "..." }
    ]
}

Response

If successful, this method will return an empty response with a Created status code and a Location header containing the URI of the created task. This response uses the standard error codes and returns standard response headers.

HTTP/1.1 201 Created
Location: /tasks/12345

Error Responses

Case Response Code Error Code
Title is missing or empty 400 Bad Request Invalid
Status is missing or empty 400 Bad Request Invalid
Document link missing or invalid 400 Bad Request Invalid
Any date is malformed 400 Bad Request Invalid
User is not a member of the Workspace 403 Forbidden WorkspaceMembershipRequired
Workspace is locked 403 Forbidden WorkspaceLocked
Workspace is archived 403 Forbidden WorkspaceArchived
Workspace is deleted 404 Not Found WorkspaceDeleted

Create a file request

Example

Request

POST /tasks/workspace/123 HTTP/1.1
Content-Type: application/json
Authorization: Bearer frootymcnooty/vonbootycherooty

{
  "title": "A new task",
  "status": "NotStarted",
  "dueDate": "2011-05-10",
  "links": [{ "rel": "destination-folder", "href": "..." }]
}

Response

If successful, this method will return an empty response with a Created status code and a Location header containing the URI of the created task. This response uses the standard error codes and returns standard response headers.

HTTP/1.1 201 Created
Location: /tasks/12345

Error Responses

Case Response Code Error Code
Title is missing or empty 400 Bad Request Invalid
Status is missing or empty 400 Bad Request Invalid
Destination Folder URI is malformed 400 Bad Request Invalid
Any date is malformed 400 Bad Request Invalid
User is not a member of the Workspace 403 Forbidden WorkspaceMembershipRequired
Workspace is locked 403 Forbidden WorkspaceLocked
Workspace is archived 403 Forbidden WorkspaceArchived
Workspace is deleted 404 Not Found WorkspaceDeleted

Edit a Todo

To add or remove assignees, once a task is created, see TaskAssignments.

To add or remove attachments, once a task is created, see TaskAttachments.

Example

Request

PUT /tasks/12345 HTTP/1.1
Content-Type: application/json
Authorization: Bearer frootymcnooty/vonbootycherooty

{
  "title": "Updated Task Title",
  "description": "Updated Description",
  "status": "InProgress",
  "dueDate": "2009-06-15",
  "plannedStartDate": "2009-05-15",
  "type": "todo",  
  "customFields": {
    "customFieldId": 123,
    "value": "A different value"
  }
}

Response

If successful, this method will return with an OK status code. The response body will be the updated Todo. This response uses the standard error codes and returns standard response headers.

HTTP/1.1 200 OK

Error Responses

Case Response Code Error Code
Task does not exist 404 Not Found TaskNotFound
Task deleted 404 Not Found TaskDeleted
Title is missing or empty 400 Bad Request Invalid
Status is missing or empty 400 Bad Request Invalid
Any date is malformed 400 Bad Request Invalid
User is not a member of the Workspace 403 Forbidden WorkspaceMembershipRequired
Workspace is locked 403 Forbidden WorkspaceLocked
Workspace is archived 403 Forbidden WorkspaceArchived
Workspace is deleted 404 Not Found WorkspaceDeleted
User is not Task Owner or Workspace Manager 403 Forbidden InsufficientPermissions

Edit a file request

To add or remove assignees, once a task is created, see TaskAssignments.

To add or remove attachments, once a task is created, see TaskAttachments.

Example

Request

PUT /tasks/12345 HTTP/1.1
Content-Type: application/json
Authorization: Bearer frootymcnooty/vonbootycherooty

{
  "title": "Read the docs",
  "status": "InProgress",
  "dueDate": "2020-06-15",
  "links": [{ "rel": "destination-folder", "href": "..." }]
}

Response

If successful, this method returns 200 OK with a JSON body representing the updated file request (same shape as GET /tasks/{taskId}). This response uses the standard error codes and returns standard response headers.

HTTP/1.1 200 OK
Content-Type: application/json

Error Responses

Case Response Code Error Code
Task does not exist 404 Not Found TaskNotFound
Task deleted 404 Not Found TaskDeleted
Title is missing or empty 400 Bad Request Invalid
Status is missing or empty 400 Bad Request Invalid
Any date is malformed 400 Bad Request Invalid
User is not a member of the Workspace 403 Forbidden WorkspaceMembershipRequired
Workspace is locked 403 Forbidden WorkspaceLocked
Workspace is archived 403 Forbidden WorkspaceArchived
Workspace is deleted 404 Not Found WorkspaceDeleted
User is not Task Owner or Workspace Manager 403 Forbidden InsufficientPermissions

Update Task Status

Example

Request

PUT /tasks/12345/status HTTP/1.1
Content-Type: application/json
Authorization: Bearer frootymcnooty/vonbootycherooty

{"status": "InProgress"}

Valid statuses*

Case Status string to use
Update status to being not started NotStarted
Update status to being in progress InProgress
Update status to being complete Complete
** Update status to being rejected Rejected

*Case insensitive
**Only task type [task].[approval] supported Rejected at the moment. This will update [tasks].[task].[status] to complete and [tasks].[approval].[rejected] to true

Response

If successful, this method will return with a OK status code. The response body will be the updated Task. This response uses the standard error codes and returns standard response headers.

HTTP/1.1 200 OK
Content-Type: application/json
Content-Location: /tasks/12345

{
  "title": "Finish negotiations",
  "status": "InProgress",
  "dueDate": "2019-10-31",
  "links": [
      ... ,
      { "rel": "update-status", "href": "..." }
    ]
}

Error Responses

Case Response Code Error Code
Task does not exist 404 Not Found TaskNotFound
Task deleted 404 Not Found TaskDeleted
Status is missing, empty or invalid 400 Bad Request Invalid
User is not a member of the Workspace 403 Forbidden WorkspaceMembershipRequired
Workspace is locked 403 Forbidden WorkspaceLocked
Workspace is archived 403 Forbidden WorkspaceArchived
Workspace is deleted 404 Not Found WorkspaceDeleted
User is not Task Owner or Workspace Manager 403 Forbidden InsufficientPermissions

Export Tasks to CSV

This endpoint retrieves all the tasks in a workspace in a CSV file.

Request

GET /tasks/workspace/123/csv HTTP/1.1
Accept: text/csv
Authorization: Bearer frootymcnooty/vonbootycherooty

Response

If successful, this method will return with an OK status code. The response body will contain the CSV file to download.

HTTP/1.1 200 OK
Cache-Control: private
Content-Type: text/csv
Content-Encoding: gzip
Vary: Accept-Encoding
Server: Microsoft-IIS/10.0
Content-Disposition: attachment; filename="Your first workspace_Tasks_20021212.csv"
X-Powered-By: ASP.NET
Date: Fri, 13 Dec 2053 12:00:00 GMT
Connection: close
Content-Length: 123

[Tasks headers]
[CSV content]

CSV header row example

Id,Title,Description,PlannedStartDate,DueDate,Completed,AssignedTo,CreatedDate,CreatedBy,CompletedOn,CompletedBy,AttachedFileUrl,DocumentForApprovalUrl,CustomField1,CustomField2,CustomFieldN

Error Responses

Case Response Code Error Code
Workspace does not exist 404 Not Found WorkspaceNotFound
User has no permission 403 Forbidden WorkspaceMembershipRequired

Filters

Query string parameters are used to filter the tasks to be retrieved in the CSV. Returns empty list of tasks if no tasks were found that match your query.

Request:

GET /tasks/workspace/123/csv?assignedtousers=123&assignedtoteams=456&earliestduedate=2019-01-01&latestduedate=2019-12-31&statuses=InProgress HTTP/1.1
Accept: text/csv
Authorization: Bearer frootymcnooty/vonbootycherooty
Parameter Default value Additional notes
assignedtousers List of user IDs
assignedtoteams List of team IDs
earliestduedate DateTime value
latestduedate DateTime value
statuses NotStarted, InProgress, Complete

Delete a Task

Deletes any task type (Todo, file request, or approval). DELETE the task’s self URI (typically DELETE /tasks/{taskId}). On success the response includes a Link header with rel="restore" pointing at POST /tasks/{taskId}/restore.

Example

Request

DELETE /tasks/12345 HTTP/1.1
Authorization: Bearer frootymcnooty/vonbootycherooty

Response

If successful, this method will return an empty response with a No Content status code and a Link header with rel="restore" to restore the deleted task (see Restore a Task). This response uses the standard error codes and returns standard response headers.

HTTP/1.1 204 No Content
Link: <https://api.example.com/tasks/12345/restore>; rel=restore

The Link value uses the restore URL for that task; relation rel is restore (see RFC 5988).

Error Responses

Case Response Code Error Code
Task does not exist 404 Not Found TaskNotFound
Task is deleted 409 Conflict TaskDeleted
User is not a member of the Workspace 403 Forbidden WorkspaceMembershipRequired
Workspace is locked 403 Forbidden WorkspaceLocked
Workspace is archived 403 Forbidden WorkspaceArchived
Workspace is deleted 404 Not Found WorkspaceDeleted
User is not Task Owner or Workspace Manager 403 Forbidden InsufficientPermissions

Restore a Task

Restores a soft-deleted task. Use the URI from the Link header’s restore relation after a successful delete, or POST /tasks/{taskId}/restore when you already know the task id.

Example

Request

POST /tasks/12345/restore HTTP/1.1
Authorization: Bearer frootymcnooty/vonbootycherooty

Response

If successful, this method will return an empty response with a No Content status code. This response uses the standard error codes and returns standard response headers.

HTTP/1.1 204 No Content

Error Responses

Case Response Code Error Code
Task does not exist 404 Not Found TaskNotFound
Task is not deleted 409 Conflict TaskNotDeleted
User is not a member of the Workspace 403 Forbidden WorkspaceMembershipRequired
Workspace is locked 403 Forbidden WorkspaceLocked
Workspace is archived 403 Forbidden WorkspaceArchived
Workspace is deleted 404 Not Found WorkspaceDeleted
User is not Task Owner or Workspace Manager 403 Forbidden InsufficientPermissions

Update a Task's assignments, attachments and custom fields

Allows assignments, attachments, custom fields, and selected task fields to be changed in one request.

POST /tasks/{taskId}/update follows the update-task link on the task when the caller may update the task. If this capability is not enabled in the deployment, the API returns 404 Not Found.

Example

Request

POST /tasks/12345/update HTTP/1.1
Content-Type: application/json
Authorization: Bearer frootymcnooty/vonbootycherooty

{
    "title": "Updated Task Title",
    "description": "Updated Description",
    "status": "InProgress",
    "plannedStartDate": { "newValue": "2020-06-18" },
    "dueDate": { "newValue": "2020-06-19" },
    "destinationFolderId": "823823",
    "assignmentsToAdd" : [
        { "rel": "assignee", "href": "..." },
        { "rel": "assignee", "href": "..." },
        { "rel": "team", "href": "..." }
    ...
    ],
    "assignmentsToRemove" : [
        { "rel": "assignee", "href": "..." },
        { "rel": "assignee", "href": "..." }
    ...
    ],
    "attachmentsToAdd": [
        { "rel": "document", "href": "..."},
        { "rel": "document", "href": "..."}
    ...
    ],
    "attachmentsToRemove": [
        { "rel": "attachment", "href": "..."},
        { "rel": "attachment", "href": "..."}
    ...
    ],
    "customFields": [
        {
            "customFieldId": 123,
            "value": "value1"
        },
        {
            "customFieldId": 456,
            "value": "value2"
        },
    ...
    ]
}

Task Specific Request Properties

Property Task Type
destinationFolderId FileRequest
updateCustomFields Todo

Date Update Behaviour

newValue Result
{ "newValue": "2020-06-18" } Date updated
{ newValue: null } Date updated to null
null no change to date
no property in payload no change to date

Response

If successful, the API returns 200 OK with a JSON body for the updated task (equivalent to GET /tasks/{taskId}), including Content-Location. This response uses the standard error codes and standard response headers.

HTTP/1.1 200 OK
Content-Type: application/json
Content-Location: /tasks/12345

{
  "title": "Updated Task Title",
  "description": "Updated Description",
  "type": "Todo",
  "links": [
    { "rel": "self", "href": "..." },
    { "rel": "parent", "href": "...", "title": "Workspace1" },
    { "rel": "alternate", "href": "..."},
    { "rel": "audit-trail", "href": "..." },
    { "rel": "comments", "href": "...", "count": 3 },
    { "rel": "attachments", "href": "...", "count": 2 },
    { "rel": "assignments", "href": "...", "count": 2 },
    { "rel": "edit", "href": "..." },
    { "rel": "update-status", "href": "..." },
    { "rel": "delete", "href": "..." }
  ],
  "actors": [
    {
      "name": "Bob",
      "email": "[email protected]",
      "rel": "owner",
      "links": [
        { "rel": "self", "href": "..." },
        { "rel": "avatar", "href": "...", "type": "image/jpeg" },
        { "rel": "alternate", "href": "...", "type": "text/html" }
      ]
    }
  ],
  "status": "NotStarted",
  "created": "Mon, 15 Jul 2020 00:00:00 GMT",
  "updated": "Mon, 28 Jul 2020 00:00:00 GMT"
}

Error Responses

Case Response Code
User is not authorised 401 Unauthorised
User is either not a workspace manager or task owner 403 Forbidden
Team with specified ID does not exist 404 Not Found
Assignee with specified ID does not exist 404 Not Found
Attachment with specified ID does not exist 404 Not Found
Task with specified ID does not exist 404 Not Found
Partial-update endpoint disabled in the environment 404 Not Found
Custom field with specified ID either doesn't exist, is not enabled, has invalid workspace or specified value is not active 400 Bad Request
Task title, description, status or due date are missing or invalid 400 Bad Request
A Task Type specific property was specified but the Task was not of that type 400 Bad Request