Elastic Path Files API

openapi: 3.1.0
info:
  version: 25.1126.6886238
  x-version-timestamp: 2025-11-26 19:10:23+00:00
  title: Addresses Introduction Account Addresses Files API
  description: 'The Addresses API allows you to organize account addresses. Addresses are a sub-resource of `account` resources, an account can have multiple addresses, such as home, work, and neighbour.


    You can use an account address with either [client_credentials access token](/docs/api/authentication/create-an-access-token) or a combination of [implicit access token](/docs/api/authentication/create-an-access-token) and [Account Management authentication](/docs/api/accounts/post-v-2-account-members-tokens) token.

    '
  contact:
    name: Elastic Path
    url: https://www.elasticpath.com
    email: support@elasticpath.com
  license:
    url: https://elasticpath.dev
    name: MIT
servers:
- url: https://useast.api.elasticpath.com
  description: US East
- url: https://euwest.api.elasticpath.com
  description: EU West
security:
- BearerToken: []
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 |

        |:----------------------|:----------|:--------------------------|:-------------|

        | `id`                  | `string`  | `in`                      | `in(id,file-id-1,file-id-2,file-id-3)` |

        | `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)` |


        #### Bulk File Retrieval


        To retrieve multiple files by their IDs in a single request, use the `in` operator with a comma-separated list of file IDs:


        ```

        GET /v2/files?filter=in(id,06b881bd-f152-4c36-8658-7132a8fab49c,ec73567b-04e8-4000-a11a-7e1407cc2f21)

        ```


        This is more efficient than making separate requests for each file and is recommended for bulk operations.


        **Note on invalid IDs**: If any IDs in the filter are missing, malformed, or do not exist in the store, they will be silently ignored. The response will only include files that were successfully found. For example, if you request 5 IDs but only 3 exist, the response will contain 3 files with `total: 3` in the metadata.

        '
      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
                bulk_retrieval:
                  summary: Bulk file retrieval using in() filter
                  description: 'Retrieve multiple files by their IDs in a single request. This is useful for operations like fetching product images for all items in a shopping cart.


                    Example request: GET /v2/files?filter=in(id,f8cf26b3-6d38-4275-937a-624a83994702,a1b2c3d4-5678-90ab-cdef-1234567890ab)

                    '
                  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: product-image-1.png
                      mime_type: image/png
                      file_size: 110041
                      public: true
                      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
                    - type: file
                      id: a1b2c3d4-5678-90ab-cdef-1234567890ab
                      link:
                        href: https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/a1b2c3d4-5678-90ab-cdef-1234567890ab.png
                      file_name: product-image-2.png
                      mime_type: image/png
                      file_size: 95234
                      public: true
                      meta:
                        dimensions:
                          width: 800
                          height: 800
                        timestamps:
                          created_at: '2018-03-14T10:22:15.892Z'
                      links:
                        self: https://useast.api.elasticpath.com/v2/files/a1b2c3d4-5678-90ab-cdef-1234567890ab
                    links:
                      self: https://useast.api.elasticpath.com/v2/files?page[offset]=0&page[limit]=100&filter=in(id,f8cf26b3-6d38-4275-937a-624a83994702,a1b2c3d4-5678-90ab-cdef-1234567890ab)
                      first: https://useast.api.elasticpath.com/v2/files?page[offset]=0&page[limit]=100&filter=in(id,f8cf26b3-6d38-4275-937a-624a83994702,a1b2c3d4-5678-90ab-cdef-1234567890ab)
                      last: null
                    meta:
                      page:
                        limit: 100
                        offset: 0
                        current: 1
                        total: 1
                      results:
                        total: 2
        '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:
  schemas:
    UUID:
      type: string
      format: uuid
      example: 00000000-0000-0000-0000-000000000000
    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
    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
    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
    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
    ErrorResponse:
      required:
      - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
    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
    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
  responses:
    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
    NotFoundError:
      description: Forbidden. The operation is forbidden on this entity.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            file-not-found:
              value:
                errors:
                - title: Resource Not Found
                  status: 404
                  detail: The resource you are requesting does not exist
    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
    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
  parameters:
    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'
    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'
    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)
  securitySchemes:
    BearerToken:
      type: http
      scheme: bearer