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 subdived in three types: To-Do (task), file request, and approval. The default response format is JSON, but XML is also supported.

To add or remove assignees, once a task is created, see Task Assignments. To add or remove attachments, once a task is created, see Task Attachments. To add or remove comments, once a task is created, see Task Comments.

Status

Operation
Retrieve a Task
Retrieve all Tasks in a workspace
Retrieve all Tasks for the current user
Retrieve Workspace Task stats
Create a Todo
Create an Approval
Create a File Request
Edit a Todo
Edit a File Request
Update Task status
Export Tasks to CSV
Delete a Task
Restore a Task
Update a Task's assignments, attachments and custom fields

Operations

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 Tasks's custom field entries GET
task edit The URI to edit the Task. PUT
task replace The URI to allow assignees to be replaced '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. GET
task document (Only Approval) The URI to delete 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: OAuth2 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=desc&include=assignments&customfield=3,Red
Parameter Default value Additional notes
types FileRequest Todo, FileRequest, Approval.
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 Available fields: title, startdate, duedate, status, latestattachmentdate, updateddate; Available directions: asc, desc.
include At the moment only assignments is supported.
customfield 3,Red Two values comma separated, the first is the customFieldId and the second is the customFieldValue you want to filter on

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
stats The URI of the Workspace stats, using the specified filters. 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

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 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 the tasks in your workspace, 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=desc&include=assignments
Parameter Default value Additional notes
types FileRequest Todo, FileRequest, Approval.
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 Available fields: title, startdate, duedate, status, latestattachmentdate, updateddate; Available 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 response

Retrieve workspace task stats

This endpoint returns task statistics of the selected Workspace.

Filters

This endpoint supports the same filters as the Retrieve all file requests in a workspace endpoint.

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?type=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: OAuth2 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
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

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 Task Assignments.

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

Example

Request

PUT /tasks/12345 HTTP/1.1
Content-Type: application/json
Authorization: OAuth2 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 a OK status code. The reponse body will 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 Task Assignments.

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

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 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 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 a OK status code. The reponse 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=MMddyyyy&&latestduedate=MMddyyyy&statuses=InProgress HTTP/1.1
Accept: application/vnd.huddle.data+json
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 file request

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 to restore the deleted Task. This response uses the standard error codes and returns standard response headers.

HTTP/1.1 204 No Content
Link: <...>;rel="restore"

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 file request

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 the assignments, attachments and custom fields of a Task to be modified.

Example

Request

POST /tasks/12345/update HTTP/1.1
Content-Type: application/json
Authorization: OAuth2 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, this method will return with a No Content status code. 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

Response

If successful, this method will return with a OK status code. The reponse body will contain the the same as if you did a GET /tasks/12345

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

{
  "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
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
⚠️ **GitHub.com Fallback** ⚠️