openapi: 3.2.0
info:
  title: Clickup Attachments API
  version: '1.0'
  description: 'Operations tagged Attachments across 2 of this provider''s published API definitions: clickup-api-v2-reference-openapi.json, clickup-public-api-v3-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.clickup.com/api
  description: ClickUp
  variables: {}
- url: https://api.clickup.com/
  description: ClickUp
tags:
- name: Attachments
paths:
  /v2/task/{task_id}/attachment:
    post:
      summary: Create Task Attachment
      tags:
      - Attachments
      description: 'Upload a file to a task as an attachment. Files stored in the cloud cannot be used in this API request.\

        \

        ***Note:** This request uses multipart/form-data as the content type.*

        \

        ***Tip:** Try our new V3 Attachments API, which supports both tasks and File type Custom Fields!*'
      operationId: CreateTaskAttachment
      parameters:
      - name: task_id
        in: path
        description: ''
        required: true
        style: simple
        schema:
          type: string
          examples:
          - 9hv
      - name: custom_task_ids
        in: query
        description: If you want to reference a task by its custom task id, this value must be `true`.
        style: form
        explode: true
        schema:
          type: boolean
          examples:
          - true
      - name: team_id
        in: query
        description: "When the `custom_task_ids` parameter is set to `true`, the Workspace ID must be provided using the `team_id` parameter.\n \\\nFor example: `custom_task_ids=true&team_id=123`."
        style: form
        explode: true
        schema:
          type: number
          contentEncoding: double
          examples:
          - 123
      requestBody:
        description: ''
        content:
          multipart/form-data:
            schema:
              properties:
                attachment:
                  type: array
                  items: {}
        required: true
      responses:
        '200':
          description: ''
          headers: {}
          content:
            application/json:
              schema:
                title: CreateTaskAttachmentresponse
                required:
                - id
                - version
                - date
                - title
                - extension
                - thumbnail_small
                - thumbnail_large
                - url
                type: object
                properties:
                  id:
                    type: string
                  version:
                    type: string
                  date:
                    type: integer
                    contentEncoding: int64
                  title:
                    type: string
                  extension:
                    type: string
                  thumbnail_small:
                    type: string
                  thumbnail_large:
                    type: string
                  url:
                    type: string
                examples:
                - id: ac434d4e-8b1c-4571-951b-866b6d9f2ee6.png
                  version: '0'
                  date: 1569988578766
                  title: image.png
                  extension: png
                  thumbnail_small: https://attachments-public.clickup.com/ac434d4e-8b1c-4571-951b-866b6d9f2ee6/logo_small.png
                  thumbnail_large: https://attachments-public.clickup.com/ac434d4e-8b1c-4571-951b-866b6d9f2ee6/logo_small.png
                  url: https://attachments-public.clickup.com/ac434d4e-8b1c-4571-951b-866b6d9f2ee6/logo_small.png
              example:
                id: ac434d4e-8b1c-4571-951b-866b6d9f2ee6.png
                version: '0'
                date: 1569988578766
                title: image.png
                extension: png
                thumbnail_small: https://attachments-public.clickup.com/ac434d4e-8b1c-4571-951b-866b6d9f2ee6/logo_small.png
                thumbnail_large: https://attachments-public.clickup.com/ac434d4e-8b1c-4571-951b-866b6d9f2ee6/logo_small.png
                url: https://attachments-public.clickup.com/ac434d4e-8b1c-4571-951b-866b6d9f2ee6/logo_small.png
      deprecated: false
      security:
      - Authorization_Token: []
    servers:
    - url: https://api.clickup.com/api
      description: ClickUp
      variables: {}
  /api/v3/workspaces/{workspace_id}/{entity_type}/{entity_id}/attachments:
    get:
      operationId: getParentEntityAttachments
      summary: Get Attachments
      description: Return a list of attachments for the specified entity, including a task or File type Custom Field.
      parameters:
      - name: workspace_id
        in: path
        description: The ID of the Workspace.
        required: true
        schema:
          $ref: '#/components/schemas/AttachmentsPublicApiAttachmentsControllerGetParentEntityAttachmentsWorkspaceIdPath'
      - name: entity_type
        in: path
        description: The entity type. Options include `attachments` for tasks and `custom_fields` for a File type Custom Field.
        required: true
        schema:
          $ref: '#/components/schemas/AttachmentsPublicApiAttachmentsControllerGetParentEntityAttachmentsEntityTypePath'
      - name: entity_id
        in: path
        description: The ID of the task or Custom Field.
        required: true
        schema:
          type: string
      - name: cursor
        in: query
        description: The cursor to use to fetch the next page of results.
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: The maximum number of results to fetch for this page.
        required: false
        schema:
          $ref: '#/components/schemas/AttachmentsPublicApiAttachmentsControllerGetParentEntityAttachmentsLimitQuery'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttachmentsPublicApiAttachmentsControllerGetParentEntityAttachments200Response'
        '400':
          description: Returns when request was invalid when fetching attachments.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttachmentsPublicApiErrorResponse'
        '404':
          description: Returns when {entityId} not found when fetching attachments.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttachmentsPublicApiErrorResponse'
        default:
          description: Generic Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttachmentsPublicApiErrorResponse'
      tags:
      - Attachments
      x-is-workspace-endpoint: true
      security:
      - authHeader: []
    post:
      operationId: postEntityAttachment
      summary: Create an Attachment
      description: 'Upload an attachment to a task or to a file type Custom Field. \

        \

        Once a file has been uploaded to a `custom_fields` entity, use Set Custom Field Value to associate the uploaded file with a task. \

        \

        To retrieve the ID of a Custom Field, you can use Get List Custom Fields or Get task.'
      parameters:
      - name: workspace_id
        in: path
        description: The ID of the Workspace.
        required: true
        schema:
          $ref: '#/components/schemas/AttachmentsPublicApiAttachmentsControllerPostEntityAttachmentWorkspaceIdPath'
      - name: entity_type
        in: path
        description: The entity type. Options include `attachments` for tasks or `custom_fields` for a Files Custom Field.
        required: true
        schema:
          $ref: '#/components/schemas/AttachmentsPublicApiAttachmentsControllerPostEntityAttachmentEntityTypePath'
      - name: entity_id
        in: path
        description: The ID of the task or Custom Field.
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/AttachmentsPublicPostAttachmentBodyParamsDto'
      responses:
        '200':
          description: The created attachment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttachmentsAttachment'
        '400':
          description: Returns when {entityType} is not 'custom_fields'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttachmentsPublicApiErrorResponse'
        '404':
          description: Returns when {entityId} not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttachmentsPublicApiErrorResponse'
        default:
          description: Generic Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttachmentsPublicApiErrorResponse'
      tags:
      - Attachments
      x-is-workspace-endpoint: true
      security:
      - authHeader: []
    servers:
    - url: https://api.clickup.com/
      description: ClickUp
components:
  schemas:
    AttachmentsPublicApiAttachmentsControllerGetParentEntityAttachmentsEntityTypePath:
      type: string
      enum:
      - attachments
      - custom_fields
    AttachmentsPublicApiAttachmentsControllerPostEntityAttachmentEntityTypePath:
      type: string
      enum:
      - attachments
      - custom_fields
    AttachmentsPublicApiAttachmentsControllerGetParentEntityAttachmentsWorkspaceIdPath:
      type: integer
    AttachmentsPaginatedResponse:
      type: object
      properties:
        next_cursor:
          description: The next cursor to use for pagination.
          type: string
      required:
      - next_cursor
    AttachmentsPublicApiAttachmentsControllerGetParentEntityAttachmentsLimitQuery:
      type: integer
      default: 50
      maximum: 100
      minimum: 1
    AttachmentsPublicPostAttachmentBodyParamsDto:
      type: object
      properties:
        filename:
          description: Override the filename of the attachment
          type: string
    AttachmentsPublicApiAttachmentsControllerPostEntityAttachmentWorkspaceIdPath:
      type: integer
    AttachmentsAttachment:
      type: object
      properties:
        date_updated:
          description: The date & time the attachment was updated (Unix epoch milliseconds timestamp).
          type: integer
          example: 1737065673712
        date_created:
          description: The date & time the attachment was created (Unix epoch milliseconds timestamp).
          type: integer
          example: 1737065673712
        extension:
          description: The extension of the attachment.
          type: string
          example: png
        id:
          description: The ID of the attachment.
          type: string
          example: 51971815-ae25-49d5-b90c-4988f400a307.png
        mime_type:
          description: The MIME type of the attachment.
          type: string
          example: image/png
        parent_entity_type:
          description: The type of entity the attachment belongs to.
          type: string
          example: tasks
          enum:
          - attachments
          - comments
          - custom_fields
          - docs
          - posts
          - reminders
          - tasks
          - widgets
          - views
        parent_id:
          description: The ID of the entity the attachment belongs to.
          type: string
        size:
          description: The size in bytes of the attachment.
          type: integer
          example: 14697
        signed:
          description: The signed status of the attachment.
          type: boolean
          example: true
        thumbnail_small:
          description: The small size thumbnail url of the attachment.
          type: string
          format: uri
        thumbnail_medium:
          description: The medium size thumbnail url of the attachment.
          type: string
          format: uri
        thumbnail_large:
          description: The large size thumbnail url of the attachment.
          type: string
          format: uri
        title:
          description: The attachment title.
          type: string
          example: An example image
        url:
          description: The url of the attachment.
          type: string
          format: uri
        user_id:
          description: The ID of the user who created the attachment.
          type: integer
      required:
      - date_updated
      - date_created
      - extension
      - id
      - mime_type
      - parent_entity_type
      - parent_id
      - size
      - signed
      - thumbnail_small
      - thumbnail_medium
      - thumbnail_large
      - title
      - url
      - user_id
    AttachmentsPublicApiErrorResponse:
      type: object
      properties:
        status:
          description: The HTTP Status code for the error
          type: integer
        message:
          description: The message describing the error
          type: string
          example: Generic error message
        trace_id:
          description: Unique trace ID for tracking the request. Used for troubleshooting errors
          type:
          - integer
          - 'null'
          example: 123456789
        timestamp:
          description: The time of the error (Unix epoch milliseconds timestamp).
          type: integer
          example: 1671534256138
      required:
      - status
      - message
      - trace_id
      - timestamp
    AttachmentsPublicApiAttachmentsControllerGetParentEntityAttachments200Response:
      allOf:
      - $ref: '#/components/schemas/AttachmentsPaginatedResponse'
      - type: object
        description: The list of attachments for {entityId}.
        properties:
          data:
            type: array
            items:
              $ref: '#/components/schemas/AttachmentsAttachment'
  securitySchemes:
    Authorization_Token:
      name: Authorization
      type: apiKey
      in: header
      description: 'API token required for authentication. Two types of tokens are supported:

        **Personal API Key** Obtain from ClickUp''s settings page under ''Apps'' and add it to the header as `Authorization: pk_...`

        **OAuth2 Access Token** Generated through the OAuth2 flow and add it to the header as `Authorization: Bearer {access_token}`'
    authHeader:
      in: header
      type: apiKey
      name: Authorization
x-refined-from:
- clickup-api-v2-reference-openapi.json
- clickup-public-api-v3-openapi.json