HTTP API: comments

The 8 operations tagged comments, each with its parameters, its body and what it answers.

Edit your own comment

PATCH /v1/comments/{comment_id}

Edit a comment's text. Only its author may (docs/design.md §5.10).

Parameters

• comment_id (string (uuid), in path, required)

Request body: Update as application/json, required.

Responses

• 200: Comment. Successful Response
• 422: HTTPValidationError. Validation Error

Delete a comment

DELETE /v1/comments/{comment_id}

Move a comment to the trash. Its author may; so may a workspace administrator.

Parameters

• comment_id (string (uuid), in path, required)

Responses

• 200: Comment. Successful Response
• 422: HTTPValidationError. Validation Error

List a document's comments

GET /v1/documents/{id_or_ref}/comments

Return what happened on this item, oldest first.

Parameters

• workspace_id (string or null, in query): Which workspace, by id or slug. Needed when you can reach several.
• limit (integer or null, in query): How many to return. At least 1; capped at the instance's max_page_size.
• cursor (string or null, in query): Continue after a page.
• format (string or null, in query): 'full' (default), 'compact' for one aligned line per item, or 'ids' for the addresses alone. Compact is roughly a twentieth the size of full.
• fields (string or null, in query): Comma-separated field names to return instead of the whole item, e.g. 'ref,title,due_at'. GET /v1/meta lists what each entity has. Cannot be combined with 'format'.

Responses

• 200: Collection_Comment_. Successful Response
• 422: HTTPValidationError. Validation Error

Comment on a document

POST /v1/documents/{id_or_ref}/comments

Record what happened on this item.

Parameters

• workspace_id (string or null, in query): Which workspace, by id or slug. Needed when you can reach several.

Request body: Create as application/json, required.

Responses

• 201: Comment. Successful Response
• 422: HTTPValidationError. Validation Error

List a project's comments

GET /v1/projects/{id_or_key}/comments

Return what happened on this item, oldest first.

Parameters

• workspace_id (string or null, in query): Which workspace, by id or slug. Needed when you can reach several.
• limit (integer or null, in query): How many to return. At least 1; capped at the instance's max_page_size.
• cursor (string or null, in query): Continue after a page.
• format (string or null, in query): 'full' (default), 'compact' for one aligned line per item, or 'ids' for the addresses alone. Compact is roughly a twentieth the size of full.
• fields (string or null, in query): Comma-separated field names to return instead of the whole item, e.g. 'ref,title,due_at'. GET /v1/meta lists what each entity has. Cannot be combined with 'format'.

Responses

• 200: Collection_Comment_. Successful Response
• 422: HTTPValidationError. Validation Error

Comment on a project

POST /v1/projects/{id_or_key}/comments

Record what happened on this item.

Parameters

• workspace_id (string or null, in query): Which workspace, by id or slug. Needed when you can reach several.

Request body: Create as application/json, required.

Responses

• 201: Comment. Successful Response
• 422: HTTPValidationError. Validation Error

List a task's comments

GET /v1/tasks/{id_or_ref}/comments

Return what happened on this item, oldest first.

Parameters

• workspace_id (string or null, in query): Which workspace, by id or slug. Needed when you can reach several.
• limit (integer or null, in query): How many to return. At least 1; capped at the instance's max_page_size.
• cursor (string or null, in query): Continue after a page.
• format (string or null, in query): 'full' (default), 'compact' for one aligned line per item, or 'ids' for the addresses alone. Compact is roughly a twentieth the size of full.
• fields (string or null, in query): Comma-separated field names to return instead of the whole item, e.g. 'ref,title,due_at'. GET /v1/meta lists what each entity has. Cannot be combined with 'format'.

Responses

• 200: Collection_Comment_. Successful Response
• 422: HTTPValidationError. Validation Error

Comment on a task

POST /v1/tasks/{id_or_ref}/comments

Record what happened on this item.

Parameters

• workspace_id (string or null, in query): Which workspace, by id or slug. Needed when you can reach several.

Request body: Create as application/json, required.

Responses

• 201: Comment. Successful Response
• 422: HTTPValidationError. Validation Error