Tasks attached to Document

Summary

APIs for to-dos tied to a Document, served by the Tasks API under /tasks/document/{documentId}/todo (and .../todo/{todoId} for a single item).

Status

Method	Path	Purpose	Details
GET	-	Retrieve the to-do collection for attached document	Jump
POST	-	Create a to-do and attach the document	Jump
DELETE	-	Delete a to-do against the document	Jump

Operations

Method	Path	Purpose	Details
GET	/tasks/document/123/todo	Retrieve To-dos attached Document	Jump
GET	/tasks/document/123/todo	Get Request	Jump
GET	/tasks/document/123/todo	Get Link Relations	Jump
POST	/tasks/document/123/todo	Get Error Responses	Jump
POST	/tasks/document/123/todo	Create To-do Against Document	Jump
POST	/tasks/document/123/todo	Create Request	Jump
DELETE	/tasks/document/123/todo/987	Create Response	Jump
DELETE	/tasks/document/123/todo/987	Create Error Responses	Jump
DELETE	/tasks/document/123/todo/987	Delete To-do Against-Document	Jump
DELETE	/tasks/document/123/todo/987	Delete Request	Jump

Retrieve To-dos attached Document

This endpoint returns the title, description, assignments, status, start and due dates for all To-do Tasks that have been created for a Document.

Get Request

GET /tasks/document/123/todo HTTP/1.1
Accept: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

Get Response

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

{
    "tasks": [
        {
            "title": "The title of the To-do task",
            "description": "The description, if supplied, of the to-do task",
            "status": "InProgress",
            "plannedStartDate": "2019-02-28",
            "dueDate": "2019-03-01",
            "createdDate": "Thu, 28 Mar 2019 12:36:52 GMT",
            "updatedDate": "Thu, 29 Mar 2019 13:36:52 GMT",
            "actors": [
                {
                    "name": "Bob",
                    "email": "[email protected]",
                    "rel": "owner",
                    "links": [
                        {
                            "rel": "self",
                            "href": "..."
                        },
                        {
                            "rel": "avatar",
                            "href": "...",
                            "type": "image/jpeg"
                        },
                        {
                            "rel": "alternate",
                            "href": "...",
                            "type": "text/html"
                        }
                    ]
                },
                {
                    "name": "Jonny",
                    "email": "[email protected]",
                    "rel": "assignee",
                    "links": [
                        {
                            "rel": "self",
                            "href": "..."
                        },
                        {
                            "rel": "avatar",
                            "href": "...",
                            "type": "image/jpeg"
                        },
                        {
                            "rel": "alternate",
                            "href": "...",
                            "type": "text/html"
                        }
                    ]
                }
            ],
            "links": [
                {
                    "rel": "self",
                    "href": "..."
                },
                {
                    "rel": "alternate",
                    "type": "text/html",
                    "href": "..."
                },
                {
                    "rel": "parent",
                    "href": "...",
                    "title": "The Workspace this take belongs to"
                },
                {
                    "rel": "edit",
                    "href": "..."
                },
                {
                    "rel": "replace",
                    "href": "..."
                },
                {
                    "rel": "update-status",
                    "href": "..."
                },
                {
                    "rel": "delete",
                    "href": "..."
                },
                {
                    "rel": "audit-trail",
                    "href": "..."
                },
                {
                    "rel": "comments",
                    "count": 2,
                    "href": "..."
                },
                {
                    "rel": "attachments",
                    "count": 1,
                    "href": "..."
                },
                {
                    "rel": "assignments",
                    "count": 1,
                    "href": "..."
                },
                {
                    "rel": "custom-fields",
                    "count": 2,
                    "href": "...",
                    "note": "only present when custom fields exist"
                },
                {
                    "rel": "share-task",
                    "href": "..."
                },
                {
                    "rel": "update-task",
                    "href": "...",
                    "note": "only present when user has update permission"
                }
            ]
        }
    ],
    "links": [
        {
            "rel": "self",
            "href": "..."
        },
        {
            "rel": "parent",
            "href": "..."
        },
        {
            "rel": "create",
            "href": "..."
        }
    ]
}

Get Link Relations

Type	Name	Description	Methods
tasks	self	The current API URI of this Documents To-do	GET
tasks	parent	The URI for the current Document	GET
tasks	create	The URI for creating a new To-do against the Document	POST
task	self	The URI for the To-do task	GET
task	alternate	The web URI of the To-do task	GET
task	parent	The URI for the workspace this To-do task is in	GET
task	audit-trail	The URI for the audit trail of the To-do task	GET
task	comments	The URI for the comments on the To-do task	GET
task	attachments	The URI for the attachments on the To-do task	GET
task	assignments	The URI for the assignments on the To-do task	GET
task	custom-fields	The URI for the custom fields on the To-do task (only present when custom fields exist)	GET
task	share-task	The URI for sharing the To-do task	GET
task	edit	The URI for updating a To-do task (requires update permission)	PUT
task	update-task	The URI for updating a To-do task (requires update permission)	PUT
task	replace	The URI for replacing assignees on the To-do task (requires update permission)	PUT
task	update-status	The URI for updating the status of a To-do task (requires update-status permission)	PUT
task	delete	The URI for setting the To-do task to deleted (requires delete permission)	DELETE
actor	self	The URI for the User	GET
actor	avatar	The URI for the Users avatar	GET
actor	alternate	The web Uri for the Users profile	GET
actor	delete	The URI for deleting an assignment i.e. rel="assignee" (requires update permission)	DELETE

Get Error Responses

Case	Response Code	Error Code
Document is deleted	404 Not Found	DocumentDeleted
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 To-do Against Document

This endpoint is used to create new To-do tasks that have the current document as an attachment.

Create Request

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

{
  "workspaceId": 456,
  "title": "A new task",
  "description": "This is a task to do something",
  "status": "NotStarted",
  "dueDate": "2019-03-05",
  "plannedStartDate": "2019-03-04",
  "links": [
      {
          "rel": "assignee",
          "href": "..."
      }
  ]
}

Name	Description	Required	Default
workspaceId	Workspace in which to create the task	Yes
title	Title of the new task	Yes
description	Description of the new task	No	Empty
status	The starting status of the Task. Options are NotStarted,InProgress, and Complete	No	NotStarted
dueDate	Date that the task is completed by	No
plannedStartDate	Date that the task should be started	No	null
links	Links to the assignees for this task	No	Empty

Create Response

If successful, this endpoint will return an empty response with a status code of 201 and a Location header containing the URI of the created to-do task.

HTTP/1.1 201 Created
Location: /tasks/123

Create Error Responses

Case	Response Code	Error Code
Title is missing or empty	400 Bad Request	Invalid
Status is invalid	400 Bad Request	Invalid
Any date is malformed	400 Bad Request	Invalid
Document is deleted	404 Not Found	DocumentDeleted
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

Delete To-do Against-Document

This endpoint is used to delete a to-do that has the current document as an attachment.

Delete Request

DELETE /tasks/document/123/todo/987 HTTP/1.1
Authorization: Bearer frootymcnooty/vonbootycherooty

Delete Response

If successful, this method will return an empty response with a No Content status code.

HTTP/1.1 204 No Content

Delete Notes

If there is no attachment linking the document to the to-do (either "No Attachment for Document" or "No Attachment for Task"), the endpoint still returns 204 No Content — it is idempotent.

Delete Error Responses

Case	Response Code	Error Code
Task against the Document 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 archived	403 Forbidden	WorkspaceArchived
User is not Task Owner or Workspace Manager	403 Forbidden	InsufficientPermissions