WeKan Attachments API

openapi: 3.2.0
info:
  title: Wekan Attachments API
  version: '1.0'
  description: 'Operations tagged Attachments across 2 of this provider''s published API definitions: wekan-meteor3-openapi.yml, wekan-openapi.yml. Each path carries the servers of the definition it was published in.'
tags:
- name: Attachments
paths:
  /api/attachment/upload:
    post:
      operationId: upload_attachment
      summary: Upload a file as a card attachment
      description: 'Upload a file to a card. The file content is sent base64-encoded in the

        JSON body. The maximum size is bounded by the admin Attachment Storage

        Settings (`apiUploadMaxBytes`) and a hard server safety cap (64 MB).


        Permissions: requires a valid auth token, write access to the target

        board (read-only / comment-only / worker members are rejected), and the

        board must allow attachments.'
      tags:
      - Attachments
      security:
      - UserSecurity: []
      responses:
        '200':
          description: Attachment uploaded successfully
        '400':
          description: Missing/invalid parameters or card/board/list/swimlane mismatch
        '401':
          description: Missing or invalid authentication
        '403':
          description: Uploads disabled, not a board member, or attachments not allowed on this board
        '404':
          description: Card or board not found
        '413':
          description: Attachment exceeds the API upload limit
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - boardId
              - swimlaneId
              - listId
              - cardId
              - fileData
              - fileName
              properties:
                boardId:
                  type: string
                  description: ID of the board the card belongs to
                swimlaneId:
                  type: string
                  description: ID of the card's swimlane (must match the card)
                listId:
                  type: string
                  description: ID of the card's list (must match the card)
                cardId:
                  type: string
                  description: ID of the card to attach the file to
                fileName:
                  type: string
                  description: Name to store the file under
                fileType:
                  type: string
                  description: MIME type of the file (optional)
                fileData:
                  type: string
                  description: Base64-encoded file contents
        required: true
  /api/attachment/upload-background:
    post:
      operationId: upload_board_background
      summary: Upload a board background image
      description: 'Upload an image and set it as the board''s active background. The file

        content is sent base64-encoded in the JSON body and stored using the

        current Admin Panel / Attachments / Default Storage backend (the same

        storage used by card attachment uploads). Board-admin is required.'
      tags:
      - Attachments
      security:
      - UserSecurity: []
      responses:
        '200':
          description: Background uploaded and set as the board background
        '400':
          description: Missing or invalid parameters
        '401':
          description: Missing or invalid authentication
        '403':
          description: Uploads disabled or caller is not a board admin
        '404':
          description: Board not found
        '413':
          description: Background exceeds the API upload limit
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - boardId
              - fileData
              - fileName
              properties:
                boardId:
                  type: string
                  description: ID of the board
                fileName:
                  type: string
                  description: Name to store the image under
                fileType:
                  type: string
                  description: MIME type of the image (optional, defaults to image/png)
                fileData:
                  type: string
                  description: Base64-encoded image contents
        required: true
  /api/attachment/download-background/{boardId}:
    get:
      operationId: download_board_background
      summary: Download the board's current background image as base64
      description: 'Returns the board''s active background image metadata together with the

        image bytes base64-encoded in `base64Data`. Requires board membership.'
      tags:
      - Attachments
      security:
      - UserSecurity: []
      parameters:
      - name: boardId
        in: path
        required: true
        description: ID of the board
        schema:
          type: string
      responses:
        '200':
          description: Background image returned
        '401':
          description: Missing or invalid authentication
        '403':
          description: Downloads disabled or caller is not a board member
        '404':
          description: Board has no background, or board not found
        '413':
          description: Background exceeds the API download limit
  /api/attachment/download/{attachmentId}:
    get:
      operationId: download_attachment
      summary: Download an attachment as base64
      description: 'Returns the attachment metadata together with the file contents

        base64-encoded in `base64Data`. The maximum size is bounded by the admin

        Attachment Storage Settings (`apiDownloadMaxBytes`).


        Permissions: requires active membership of the attachment''s board.'
      tags:
      - Attachments
      security:
      - UserSecurity: []
      parameters:
      - name: attachmentId
        in: path
        required: true
        description: ID of the attachment to download
        schema:
          type: string
      responses:
        '200':
          description: Attachment contents returned (base64Data)
        '401':
          description: Missing or invalid authentication
        '403':
          description: Downloads disabled, or not a member of the attachment's board
        '404':
          description: Attachment or stored file not found
        '413':
          description: Attachment exceeds the API download limit
  /api/attachment/info/{attachmentId}:
    get:
      operationId: get_attachment_info
      summary: Get attachment metadata
      description: 'Returns attachment metadata (name, size, type, storage backend, board /

        swimlane / list / card IDs and available versions) without the file

        contents.


        Permissions: requires active membership of the attachment''s board.'
      tags:
      - Attachments
      security:
      - UserSecurity: []
      parameters:
      - name: attachmentId
        in: path
        required: true
        description: ID of the attachment
        schema:
          type: string
      responses:
        '200':
          description: Attachment metadata returned
        '401':
          description: Missing or invalid authentication
        '403':
          description: Not a member of the attachment's board
        '404':
          description: Attachment not found
  /api/attachment/list/{boardId}:
    get:
      operationId: list_board_attachments
      summary: List all attachments of a board
      description: 'List every attachment on a board. Use the swimlane / list / card

        variants of this path to narrow the result.


        Permissions: requires active membership of the board.'
      tags:
      - Attachments
      security:
      - UserSecurity: []
      parameters:
      - name: boardId
        in: path
        required: true
        description: ID of the board
        schema:
          type: string
      responses:
        '200':
          description: List of attachments with metadata
        '401':
          description: Missing or invalid authentication
        '403':
          description: Not a member of the board
  /api/attachment/list/{boardId}/{swimlaneId}:
    get:
      operationId: list_swimlane_attachments
      summary: List attachments of a board filtered by swimlane
      tags:
      - Attachments
      security:
      - UserSecurity: []
      parameters:
      - name: boardId
        in: path
        required: true
        schema:
          type: string
      - name: swimlaneId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: List of attachments with metadata
        '401':
          description: Missing or invalid authentication
        '403':
          description: Not a member of the board
  /api/attachment/list/{boardId}/{swimlaneId}/{listId}:
    get:
      operationId: list_list_attachments
      summary: List attachments of a board filtered by swimlane and list
      tags:
      - Attachments
      security:
      - UserSecurity: []
      parameters:
      - name: boardId
        in: path
        required: true
        schema:
          type: string
      - name: swimlaneId
        in: path
        required: true
        schema:
          type: string
      - name: listId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: List of attachments with metadata
        '401':
          description: Missing or invalid authentication
        '403':
          description: Not a member of the board
  /api/attachment/list/{boardId}/{swimlaneId}/{listId}/{cardId}:
    get:
      operationId: list_card_attachments
      summary: List attachments of a single card
      description: 'List attachments filtered down to one card. The card must belong to the

        given board.


        Permissions: requires active membership of the board.'
      tags:
      - Attachments
      security:
      - UserSecurity: []
      parameters:
      - name: boardId
        in: path
        required: true
        schema:
          type: string
      - name: swimlaneId
        in: path
        required: true
        schema:
          type: string
      - name: listId
        in: path
        required: true
        schema:
          type: string
      - name: cardId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: List of attachments with metadata
        '401':
          description: Missing or invalid authentication
        '403':
          description: Not a member of the board
        '404':
          description: Card not found or does not belong to the board
  /api/attachment/copy:
    post:
      operationId: copy_attachment
      summary: Copy an attachment to another card
      description: 'Copy an existing attachment to a target card, creating a new attachment.


        Permissions: requires membership of the source board (to read it) and

        write access to the target board, which must allow attachments. Honours

        the admin API upload limits.'
      tags:
      - Attachments
      security:
      - UserSecurity: []
      responses:
        '200':
          description: Attachment copied (newAttachmentId returned)
        '400':
          description: Target card/board/list/swimlane mismatch
        '401':
          description: Missing or invalid authentication
        '403':
          description: Not a member of source or target board, or attachments not allowed
        '404':
          description: Source attachment, target card, or stored file not found
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - attachmentId
              - targetBoardId
              - targetSwimlaneId
              - targetListId
              - targetCardId
              properties:
                attachmentId:
                  type: string
                  description: ID of the source attachment
                targetBoardId:
                  type: string
                targetSwimlaneId:
                  type: string
                targetListId:
                  type: string
                targetCardId:
                  type: string
        required: true
  /api/attachment/move:
    post:
      operationId: move_attachment
      summary: Move an attachment to another card
      description: 'Move an existing attachment to a target card by updating its metadata.


        Permissions: requires write access to both the source board (the

        attachment is removed from it) and the target board, which must allow

        attachments.'
      tags:
      - Attachments
      security:
      - UserSecurity: []
      responses:
        '200':
          description: Attachment moved
        '400':
          description: Target card/board/list/swimlane mismatch
        '401':
          description: Missing or invalid authentication
        '403':
          description: Not a member of source or target board, or attachments not allowed
        '404':
          description: Source attachment or target card not found
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - attachmentId
              - targetBoardId
              - targetSwimlaneId
              - targetListId
              - targetCardId
              properties:
                attachmentId:
                  type: string
                  description: ID of the attachment to move
                targetBoardId:
                  type: string
                targetSwimlaneId:
                  type: string
                targetListId:
                  type: string
                targetCardId:
                  type: string
        required: true
  /api/attachment/delete/{attachmentId}:
    delete:
      operationId: delete_attachment
      summary: Delete an attachment
      description: 'Delete an attachment.


        Permissions: requires write access to the attachment''s board (read-only /

        comment-only / worker members are rejected).'
      tags:
      - Attachments
      security:
      - UserSecurity: []
      parameters:
      - name: attachmentId
        in: path
        required: true
        description: ID of the attachment to delete
        schema:
          type: string
      responses:
        '200':
          description: Attachment deleted
        '401':
          description: Missing or invalid authentication
        '403':
          description: Not a member of the attachment's board
        '404':
          description: Attachment not found
  /api/boards/{board}/attachments/{attachment}:
    delete:
      operationId: delete_board_attachment
      summary: Soft-delete an attachment
      description: 'The same "Delete" the card offers: the attachment gets

        `deletedAt`, `deletedBy` and `deleteBatchId`, its file is kept, the card and

        the minicard badge hide it, its cover is unset if it was the card''s cover,

        and the card history records who deleted it. Restore it with

        `POST /api/boards/:boardId/attachments/:attachmentId/restore`. There is no

        hard delete of a single attachment over the API. Requires permission to

        edit the card the attachment is on (or write access to the board for a

        board-level attachment). Idempotent: an already-deleted attachment is left

        as it is.'
      tags:
      - Attachments
      parameters:
      - name: board
        in: path
        description: 'the board ID

          '
        required: true
        schema:
          type: string
      - name: attachment
        in: path
        description: 'the attachment ID

          '
        required: true
        schema:
          type: string
      security:
      - UserSecurity: []
      responses:
        '200':
          description: 200 response
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted:
                    type: boolean
                  batchId:
                    type: string
  /api/boards/{board}/attachments/{attachment}/restore:
    post:
      operationId: restore_board_attachment
      summary: Restore a soft-deleted attachment
      description: 'The card history''s Restore for an attachment row: clears the

        delete mark so the card, its attachment count and the minicard badge include

        the attachment again, and records the restore in the card history. The

        cover is never re-set by a restore. Requires the same permission as

        deleting. Idempotent: `restored` is false for an attachment that is not

        deleted.'
      tags:
      - Attachments
      parameters:
      - name: board
        in: path
        description: 'the board ID

          '
        required: true
        schema:
          type: string
      - name: attachment
        in: path
        description: 'the attachment ID

          '
        required: true
        schema:
          type: string
      security:
      - UserSecurity: []
      responses:
        '200':
          description: 200 response
          content:
            application/json:
              schema:
                type: object
                properties:
                  restored:
                    type: boolean
  /api/boards/{board}/attachments/deleted:
    get:
      operationId: get_board_deleted_attachments
      summary: Get the soft-deleted attachments of a board
      description: 'Deleting an attachment from a card is a soft delete: the file

        is kept, the card hides it, and the card history can restore it. This lists

        the attachments of a board that are currently deleted, with who deleted each

        and when, so a script can find one to restore. The live attachments are at

        `GET /api/boards/:boardId/attachments`. Requires board access.'
      tags:
      - Attachments
      parameters:
      - name: board
        in: path
        description: 'the board ID

          '
        required: true
        schema:
          type: string
      security:
      - UserSecurity: []
      responses:
        '200':
          description: 200 response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    attachmentId:
                      type: string
                    attachmentName:
                      type: string
                    attachmentType:
                      type: string
                    boardId:
                      type: string
                    swimlaneId:
                      type: string
                    listId:
                      type: string
                    cardId:
                      type: string
                    deletedAt:
                      type: string
                    deletedBy:
                      type: string
                    deleteBatchId:
                      type: string
components:
  securitySchemes:
    UserSecurity:
      type: apiKey
      in: header
      name: Authorization
x-refined-from:
- wekan-meteor3-openapi.yml
- wekan-openapi.yml