` (for example `files.downloadUrl`) to include the
attached files; both nested objects always carry their `id`, `object`
and `url`
schema:
type: array
items:
type: string
enum:
- taskId
- body
- author.createdAt
- author.updatedAt
- author.firstName
- author.lastName
- author.avatar
- author.email
- author.name
- files.name
- files.thumbnail
- files.size
- files.downloadUrl
- files.expiresAt
- files.uploadStatus
- files.mimeType
- createdAt
- updatedAt
schemas:
WorkspacePlanTaskComment:
allOf:
- $ref: '#/components/schemas/BaseObject'
- type: object
properties:
object:
type: string
description: Type of the object
enum:
- workspace-plan-task-comment
example: workspace-plan-task-comment
readOnly: true
taskId:
type: string
description: ID of the workspace plan task the comment belongs to
example: RiHO4e0Ju3DS
readOnly: true
body:
type: string
description: >-
Comment text as HTML rich text (the same format as `richText`
custom field values): paragraphs, bold, italic, underline, text
color, links and bulleted/numbered lists. Mentions render as
`@Name`. Empty for a comment that only has files
example: >-
Uploaded the signed
contract @Jane Doe
author:
description: >-
User who wrote the comment, as a
[user](/api-reference/endpoint/users/retrieve-a-user) object.
Requested with `author.`. `null` for comments synced
from a connected ticketing integration
nullable: true
allOf:
- $ref: '#/components/schemas/User'
files:
type: array
description: >-
Files attached to the comment, as the same file objects returned
by Retrieve a file. Requested with `files.`: each file
has `id`, `object` and `url` (the file's API URL) plus the
requested properties, such as `downloadUrl`. File ids passed in
`fileIds` come back here unchanged. Download links expire; read
the comment again or retrieve the file for a fresh link
readOnly: true
items:
$ref: '#/components/schemas/File'
Pagination:
type: object
properties:
page:
type: integer
description: Current page number
example: 1
pages:
type: integer
description: Total number of pages
example: 10
total:
type: integer
description: Total number of items
example: 100
pageTotal:
type: integer
description: Number of items on the current page
example: 10
hasNextPage:
type: boolean
description: Whether there is a next page
example: true
hasPrevPage:
type: boolean
description: Whether there is a previous page
example: false
BaseObject:
type: object
properties:
id:
$ref: '#/components/schemas/Id'
updatedAt:
type: string
format: date-time
description: Last updated date
example: '2021-01-01T00:00:00.000Z'
readOnly: true
createdAt:
type: string
format: date-time
description: Created at date
example: '2021-01-01T00:00:00.000Z'
readOnly: true
User:
allOf:
- $ref: '#/components/schemas/BaseObject'
- type: object
properties:
object:
type: string
description: Type of the object
enum:
- user
example: user
readOnly: true
url:
type: string
example: https://api.dock.us/v1/users/RiHO4e0Ju3DS
description: URL to the resource
readOnly: true
firstName:
type: string
description: First name of the user
example: John
nullable: true
lastName:
type: string
description: Last name of the user
example: Doe
nullable: true
avatar:
type: string
format: uri
description: Avatar of the user
example: https://dock.us/avatar.png
nullable: true
email:
type: string
description: Email of the user
example: john.doe@example.com
name:
type: string
description: Name of the user
example: John Doe
File:
allOf:
- $ref: '#/components/schemas/BaseObject'
- type: object
properties:
object:
type: string
description: Type of the object
enum:
- file
example: file
readOnly: true
name:
type: string
description: Name of the file
example: contract.pdf
nullable: true
thumbnail:
type: string
description: Thumbnail URL for the file when available
example: >-
https://storage.googleapis.com/dock-production-private/thumbnails/contract.png
nullable: true
size:
type: integer
description: File size in bytes
example: 24576
nullable: true
url:
type: string
description: URL to the resource
example: https://api.dock.us/v1/files/RiHO4e0Ju3DS
readOnly: true
downloadUrl:
type: string
description: >-
Download link for the file's contents. Private files get a
presigned link valid until `expiresAt`; retrieve the file again
for a fresh link instead of storing it. `null` until the upload
has completed
example: >-
https://storage.googleapis.com/dock-production-private/signed-url
nullable: true
expiresAt:
type: string
format: date-time
description: When `downloadUrl` expires. `null` for links that do not expire
example: '2026-06-12T12:00:00.000Z'
nullable: true
uploadStatus:
type: string
description: >-
Upload/processing state of the file. Files created via POST
/files stay `in_progress` until their bytes are uploaded and an
asset is created from them; converted office files stay
`in_progress` until conversion completes.
enum:
- success
- in_progress
- failed
example: success
nullable: true
mimeType:
type: string
description: MIME type of the file
example: application/pdf
nullable: true
Id:
type: string
description: Id of the object
example: RiHO4e0Ju3DS
readOnly: true
responses:
'400':
description: >-
The server cannot or will not process the request due to something that
is perceived to be a client error (e.g., malformed request syntax,
invalid request message framing, or deceptive request routing)
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- BAD_REQUEST
description: A short code indicating the error code returned
example: BAD_REQUEST
message:
type: string
description: A human readable explanation of what went wrong
example: >-
The request could not be understood or was missing
required parameters
required:
- code
- message
required:
- error
'401':
description: >-
Although the HTTP standard specifies "unauthorized", semantically this
response means "unauthenticated". That is, the client must authenticate
itself to get the requested response
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- UNAUTHORIZED
description: A short code indicating the error code returned
example: UNAUTHORIZED
message:
type: string
description: A human readable explanation of what went wrong
example: >-
Access denied. You are not authorized to access this
resource
required:
- code
- message
required:
- error
'403':
description: >-
The client does not have access rights to the content; that is, it is
unauthorized, so the server is refusing to give the requested resource.
Unlike 401 Unauthorized, the client's identity is known to the server
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- FORBIDDEN
description: A short code indicating the error code returned
example: FORBIDDEN
message:
type: string
description: A human readable explanation of what went wrong
example: Access to this resource is restricted
required:
- code
- message
required:
- error
'404':
description: The server cannot find the requested resource
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- NOT_FOUND
description: A short code indicating the error code returned
example: NOT_FOUND
message:
type: string
description: A human readable explanation of what went wrong
example: The requested resource could not be found
required:
- code
- message
required:
- error
'429':
description: >-
The user has sent too many requests in a given amount of time ("rate
limiting")
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- RATE_LIMIT_EXCEEDED
description: A short code indicating the error code returned
example: RATE_LIMIT_EXCEEDED
message:
type: string
description: A human readable explanation of what went wrong
example: Rate limit exceeded. Please try again later
required:
- code
- message
required:
- error
'500':
description: The server has encountered a situation it does not know how to handle
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- INTERNAL_SERVER_ERROR
description: A short code indicating the error code returned
example: INTERNAL_SERVER_ERROR
message:
type: string
description: A human readable explanation of what went wrong
example: >-
The server has encountered a situation it does not know
how to handle
required:
- code
- message
required:
- error
securitySchemes:
bearerAuth:
type: http
scheme: bearer
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.