openproject/docs/api/apiv3/paths/work_package_file_links.yml

# /api/v3/work_packages/{id}/file_links/
---
post:
  summary: Creates file links.
  operationId: Work_Package_Create_File_Links
  tags:
    - Work Packages
    - File links
  description: |-
    Creates file links on a work package.

    The request body must contain the generated storage token, and not the storage id. In addition, the request must
    send the origin file id and the stored meta data.
    
    If there is already a link on the given work package with the same file id from the same storage, the previous
    data is not overwritten.
    
    As it is possible to link folders from a storage to a work package, the _mimeType_ of this entity can be empty.    
  parameters:
    - name: id
      description: Work package id
      in: path
      required: true
      schema:
        type: integer
      example: 1337
  requestBody:
    content:
      application/json:
        schema:
          type: object
          required:
            - _type
            - _embedded
          properties:
            _type:
              type: string
              enum:
                - Collection
            _embedded:
              type: object
              required:
                - elements
              properties:
                elements:
                  type: array
                  items:
                    allOf:
                      - $ref: '#/components/schemas/File_LinkModel'
                      - type: object
                        required:
                          - storageUrl
                        properties:
                          storageUrl:
                            type: string
                            format: uri
        example:
          _type: Collection
          _embedded:
            elements:
              - originData:
                  id: 5503
                  name: logo.png
                  mimeType: image/png
                  createdAt: '2021-12-19T09:42:10.170Z'
                  lastModifiedAt: '2021-12-20T14:00:13.987Z'
                  createdByName: Luke Skywalker
                  lastModifiedByName: Anakin Skywalker
                _links:
                  storageUrl:
                    href: https://nextcloud.deathstar.rocks/
                    title: Link to storage
          
  responses:
    '201':
      description: Created
      content:
        application/hal+json:
          schema:
            type: object
            required:
              - _type
              - count
              - total
              - _embedded
            properties:
              _type:
                type: string
                enum:
                  - Collection
              count:
                type: integer
                minimum: 0
              total:
                type: integer
                minimum: 0
              _embedded:
                type: object
                required:
                  - elements
                properties:
                  elements:
                    type: array
                    items:
                      $ref: '#/components/schemas/File_LinkModel'
    '400':
      content:
        application/hal+json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            _type: Error
            errorIdentifier: urn:openproject-org:api:v3:errors:InvalidRequestBody
            message: The request body was invalid.
      description: Occurs when the client did not send a valid JSON object in the request body.
    '403':
      content:
        application/hal+json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            _type: Error
            errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
            message: You are not authorized to access this resource.
      description: |-
        Returned if the client does not have sufficient permissions.

        **Required permission:** manage file links

        *Note that you will only receive this error, if you are at least allowed to see the corresponding work package.*        
    '404':
      content:
        application/hal+json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            _type: Error
            errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
            message: The requested resource could not be found.
      description: |-
        Returned if the work package does not exist or the client does not have sufficient permissions to see it.

        **Required permission:** view work package, view file links        
get:
  summary: Gets all file links of a work package
  operationId: Work_Package_Get_File_Links
  tags:
    - Work Packages
    - File links
  description: |-
    Gets all file links of a work package.

    The request can be filtered for the storage types and ids.    
  parameters:
    - name: id
      description: Work package id
      in: path
      required: true
      schema:
        type: integer
      example: 1337
  responses:
    '200':
      description: OK
      content:
        application/hal+json:
          schema:
            type: object
            required:
              - _type
              - count
              - total
              - _embedded
            properties:
              _type:
                type: string
                enum:
                  - Collection
              count:
                type: integer
                minimum: 0
              total:
                type: integer
                minimum: 0
              _embedded:
                type: object
                required:
                  - elements
                properties:
                  elements:
                    type: array
                    items:
                      $ref: '#/components/schemas/File_LinkModel'
    '403':
      content:
        application/hal+json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            _type: Error
            errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
            message: You are not authorized to access this resource.
      description: |-
        Returned if the client does not have sufficient permissions.
        
        **Required permission:** view file links
        
        *Note that you will only receive this error, if you are at least allowed to see the corresponding work package.*        
    '404':
      content:
        application/hal+json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            _type: Error
            errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
            message: The requested resource could not be found.
      description: |-
        Returned if the work package does not exist or the client does not have sufficient permissions to see it.

        **Required permission:** view work package