# GENERATED FILE - DO NOT EDIT 
openapi: 3.1.0
info:
  description: |
    Products are the items or services that you might want to sell in your store. In Product Experience Manager, products can also have associated rich media assets, such as product images or a file containing additional product details. You can do this using the Files API.

     Once you have created your files, you associate the files with your products using the [Create Product-File Relationships API](/docs/api/pxm/products/create-product-file-relationships).
  title: Files Introduction
  version: '1.0'
servers:
  - url: https://https://euwest.api.elasticpath.com
    description: EU West Production Server
  - url: https://useast.api.elasticpath.com
    description: US East Production Server
security:
  - bearerAuth: []
tags:
  - name: Files
    description: |
      You can upload image files or URLs by using `multipart/form-data` as the content type header. For example, `"Content-Type: multipart/form-data" \`. Commerce supports the following file types.

      | File Extension | Description |
      | --- | --- |
      | .gif | Graphics Interchange Format (GIF) |
      | .jpg/jpeg | Joint Photographic Experts Group (JPEG) format |
      | .png | Portable graphics format  |
      | .webp | Web picture format |
      | .mp4 | Moving Picture Experts Group (MPEG) format |
      | .mov | QuickTime Movie format |
      | .pdf | Portable Document Format |
      | .usdz | Universal Scene Description Format |
      | .glb | Global File format |
      | .jp2 | Compressed bitmap image saved in Joint Photographic Experts Group (JPEG) format |
      | .jxr | Extended range for Joint Photographic Experts Group (JPEG) format |
      | .aac | Advanced Audio Coding (AAC) format |
      | .vrml | Virtual Reality Modelling Language (VRML) format  |
      | .doc(x)  | Microsoft Word Open XML format |
      | .ppt(x) | Microsoft PowerPoint Open XML format |
      | .xls(x) | Microsoft Excel Open XML format |

      By default, the maximum file size is 8MB. If you need to support larger file sizes, contact your Elastic Path representative. Alternatively, store files somewhere else and reference them.
paths:
  /v2/files:
    get:
      tags:
        - Files
      summary: Get all Files
      description: |
        Retrieves all files. 

        ### Filtering
         
        For general filtering syntax, see [Filtering](/guides/Getting-Started/filtering).
         
        The following operators and attributes are available when filtering on this endpoint.
         
        | Attribute             | Type      | Operators           | Example |
        |:----------------------|:----------|:--------------------------|:-------------|
        | `file_name`           | `string`  | `eq` / `like`             | `eq(file_name, my_image.jpg)` |
        | `width`               | `integer` | `gt` / `ge` / `lt` / `le` | `gt(width,200)` |
        | `height`              | `integer` | `gt` / `ge` / `lt` / `le` | `lt(height,500)` |
        | `file_size`           | `integer` | `gt` / `ge` / `lt` / `le` | `le(file_size,20953)` |
      operationId: getAllFiles
      parameters:
        - $ref: '#/components/parameters/filter'
        - $ref: '#/components/parameters/page-limit'
        - $ref: '#/components/parameters/page-offset'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/File'
                  meta:
                    $ref: '#/components/schemas/ResultsMeta'
                  links:
                    $ref: '#/components/schemas/ResultsLinks'
              examples:
                default:
                  value:
                    data:
                      - type: file
                        id: f8cf26b3-6d38-4275-937a-624a83994702
                        link:
                          href: https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png
                        file_name: f6669358-85db-4367-9cde-1deb77acb5f4.png
                        mime_type: image/png
                        file_size: 110041
                        meta:
                          dimensions:
                            width: 1000
                            height: 1000
                          timestamps:
                            created_at: '2018-03-13T13:45:21.673Z'
                        links:
                          self: https://useast.api.elasticpath.com/v2/files/f8cf26b3-6d38-4275-937a-624a83994702
                    links:
                      self: https://useast.api.elasticpath.com/v2/files?page[offset]=0&page[limit]=100&filter=
                      first: https://useast.api.elasticpath.com/v2/files?page[offset]=0&page[limit]=100&filter=
                      last: null
                    meta:
                      page:
                        limit: 100
                        offset: 0
                        current: 1
                        total: 1
                      results:
                        total: 1
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      tags:
        - Files
      summary: Create a File
      description: Create a File
      operationId: createAFile
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  description: Indicates the file you want to upload.
                  type: string
                  format: binary
                  example: UploadFile
                file_location:
                  description: Use this parameter to reference a file stored at a specific location. This must be the URL that points to an image file.
                  type: string
                  example: '@/path/to/file.jpg'
            examples:
              image_url:
                summary: Image URL
                value:
                  file_location: https://my.example.com/images/abc.png
              upload_image:
                summary: Upload Image
                value:
                  file: '@path/to/file'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/File'
              examples:
                default:
                  value:
                    data:
                      type: file
                      id: f8cf26b3-6d38-4275-937a-624a83994702
                      link:
                        href: https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png
                      file_name: f6669358-85db-4367-9cde-1deb77acb5f4.png
                      mime_type: image/png
                      file_size: 110041
                      meta:
                        dimensions:
                          width: 1000
                          height: 1000
                        timestamps:
                          created_at: '2018-03-13T13:45:21.673Z'
                      links:
                        self: https://useast.api.elasticpath.com/v2/files/f8cf26b3-6d38-4275-937a-624a83994702
        '400':
          $ref: '#/components/responses/ValidationError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v2/files/{fileID}:
    get:
      tags:
        - Files
      summary: Get a File
      description: Get a File
      operationId: getAFile
      parameters:
        - name: fileID
          description: The unique identifier for a file.
          in: path
          required: true
          style: simple
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/File'
              examples:
                default:
                  value:
                    data:
                      type: file
                      id: f8cf26b3-6d38-4275-937a-624a83994702
                      link:
                        href: https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png
                      file_name: f6669358-85db-4367-9cde-1deb77acb5f4.png
                      mime_type: image/png
                      file_size: 110041
                      meta:
                        dimensions:
                          width: 1000
                          height: 1000
                        timestamps:
                          created_at: '2018-03-13T13:45:21.673Z'
                      links:
                        self: https://useast.api.elasticpath.com/v2/files/f8cf26b3-6d38-4275-937a-624a83994702
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
        - Files
      summary: Delete a File
      description: Delete a File
      operationId: deleteAFile
      parameters:
        - name: fileID
          description: The unique identifier of the file you want to delete.
          in: path
          required: true
          style: simple
          schema:
            type: string
      responses:
        '204':
          description: No Content
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  parameters:
    filter:
      description: |

        Filtering is available for this endpoint. See [Filtering](/docs/api/pxm/files/get-all-files#filtering).
      name: filter
      in: query
      required: false
      schema:
        type: string
        format: string
        example: eq(file_name,00000000-0000-0000-0000-000000000000.png)
    page-offset:
      name: page[offset]
      in: query
      description: The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [**page length**](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.
      style: form
      explode: true
      schema:
        type: string
        minimum: 0
        maximum: 10000
        format: int64
        examples:
          - '0'
    page-limit:
      description: The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the the [**page length**](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.
      name: page[limit]
      in: query
      style: form
      explode: true
      schema:
        type: string
        minimum: 0
        maximum: 10000
        format: int64
        examples:
          - '10'
  schemas:
    ErrorResponse:
      required:
        - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
    File:
      properties:
        id:
          description: The unique identifier for this file.
          $ref: '#/components/schemas/UUID'
        type:
          description: The type represents the object being returned.
          type: string
          example: file
        file_name:
          description: The name of the file.
          type: string
          example: file_name.jpg
        mime_type:
          description: The mime type of the file.
          type: string
          example: image/jpeg
        file_size:
          description: The size of the file. Required when uploading files.
          type: integer
          example: 36000
        public:
          description: DEPRECATED Whether the file public or not. Required when uploading files.
          type: boolean
          example: true
        meta:
          $ref: '#/components/schemas/FileMeta'
        links:
          $ref: '#/components/schemas/Links'
        link:
          $ref: '#/components/schemas/FileLink'
    FileMeta:
      properties:
        timestamps:
          type: object
          description: The date and time the file was created.
          properties:
            created_at:
              description: The date and time the file was created.
              type: string
              example: '2023-10-11T13:02:25.293Z'
        dimensions:
          description: The file dimensions.
          type: object
          properties:
            width:
              description: The width of the file.
              type: integer
              example: 1800
            height:
              description: The height of the file.
              type: integer
              example: 1000
    ResultsMeta:
      properties:
        page:
          type: object
          description: Contains the results for the entire collection.
          properties:
            limit:
              description: The maximum number of records for all pages.
              type: integer
              example: 100
            offset:
              description: The current offset by number of pages.
              type: integer
              example: 0
            current:
              description: The current number of pages.
              type: integer
              example: 1
            total:
              description: The total number of records for the entire collection.
              type: integer
              example: 1
        results:
          type: object
          description: Contains the results for the entire collection.
          properties:
            total:
              description: The total number of records for the entire collection.
              type: integer
              example: 1
    Links:
      description: Links are used to allow you to move between requests.
      type: object
      properties:
        self:
          description: Single entities use a self parameter with a link to that specific resource.
          type: string
          example: https://https://euwest.api.elasticpath.com//v2/files/ddc28c74-a7df-46be-b262-8fa69a6e7d52
    ResultsLinks:
      type: object
      description: Links are used to allow you to move between requests.
      properties:
        self:
          description: Single entities use a self parameter with a link to that specific resource.
          type:
            - string
            - 'null'
          example: https://useast.api.elasticpath.com/v2/files?page[offset]=0&page[limit]=100
        first:
          description: Always the first page.
          type:
            - string
            - 'null'
          example: https://useast.api.elasticpath.com/v2/files?page[offset]=0&page[limit]=100
        last:
          description: This is `null` if there is only one page.
          type:
            - string
            - 'null'
          example: https://useast.api.elasticpath.com/v2/files?page[offset]=10&page[limit]=100
    FileLink:
      type: object
      description: The publicly available URL for this file.
      properties:
        href:
          description: The publicly available URL for this file.
          type: string
          example: https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png
    UUID:
      type: string
      format: uuid
      example: 00000000-0000-0000-0000-000000000000
    Error:
      required:
        - status
        - title
      properties:
        status:
          type: integer
          format: int
          description: The HTTP response code of the error.
          example: 500
        title:
          type: string
          description: A brief summary of the error.
          example: Internal server error
        detail:
          type: string
          description: Optional additional detail about the error.
          example: An internal error has occurred.
        request_id:
          type: string
          description: Internal request ID.
          example: 00000000-0000-0000-0000-000000000000
        meta:
          type: object
          description: Additional supporting meta data for the error.
          example:
            missing_ids:
              - e7d50bd5-1833-43c0-9848-f9d325b08be8
  responses:
    InternalServerError:
      description: Internal server error. There was a system failure in the platform.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internal-server-error:
              value:
                errors:
                  - status: 500
                    title: Internal Server Error
                    detail: There was an internal server error, you can report with your request id.
                    request_id: 635da56d-75a1-43cd-b696-7ab119756b3a
    NotFoundError:
      description: Forbidden. The operation is forbidden on this entity.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          file-not-found:
            value:
              title: Resource Not Found
              status: 404
              detail: The resource you are requesting does not exist
    ForbiddenError:
      description: Bad request. The request failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            file-location-invalid:
              value:
                errors:
                  - title: Permission denied
                    status: 403
                    detail: You are trying to remove a file outside of the tenancy
    ValidationError:
      description: Bad request. The request failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            file-location-invalid:
              value:
                errors:
                  - title: file_location invalid
                    status: 422
                    detail: '@/path/to/file.jpg is not a valid URL'
            file-not-uploaded:
              value:
                errors:
                  - title: Validation Failed
                    status: 400
                    detail: You have not supplied a file to store