Vendure Assets API

openapi: 3.1.0
info:
  title: Vendure Admin Assets API
  version: '3.6'
  description: 'The Vendure Admin API is the privileged GraphQL endpoint used by the

    Vendure Dashboard and back-office tooling. It governs catalogue (products,

    variants, options, collections, facets), orders and fulfillment,

    customers and customer groups, channels and sellers, promotions, tax

    categories and rates, zones and countries, payment and shipping methods,

    administrators and roles, API keys, jobs and scheduled tasks, stock

    locations, assets, and global settings.


    This OpenAPI document models the single GraphQL endpoint

    (`POST /admin-api`); per-operation contracts are defined by the GraphQL

    schema. See the reference documentation for query and mutation lists.

    '
  contact:
    name: Vendure
    url: https://docs.vendure.io/reference/graphql-api/admin/queries/
  license:
    name: GPL-3.0
    url: https://github.com/vendurehq/vendure/blob/master/LICENSE
servers:
- url: http://localhost:3000/admin-api
  description: Default development server
- url: https://{host}/admin-api
  description: Self-hosted production server
  variables:
    host:
      default: admin.example.com
security:
- BearerAuth: []
  ChannelToken: []
- CookieAuth: []
  ChannelToken: []
tags:
- name: Assets
paths:
  /assets/{assetPath}:
    get:
      summary: Retrieve Asset
      operationId: getAsset
      description: 'Serves the stored binary for the asset at `assetPath`. Supports

        image transforms via query parameters when the asset is an image.

        Responses include `Content-Type`, `Content-Length`, `ETag`, and

        cache headers; ranged requests are supported for large files.

        '
      parameters:
      - $ref: '#/components/parameters/AssetPath'
      - $ref: '#/components/parameters/PresetQuery'
      - $ref: '#/components/parameters/WidthQuery'
      - $ref: '#/components/parameters/HeightQuery'
      - $ref: '#/components/parameters/ModeQuery'
      - $ref: '#/components/parameters/FormatQuery'
      - $ref: '#/components/parameters/QualityQuery'
      responses:
        '200':
          description: Asset bytes.
          content:
            image/jpeg:
              schema:
                type: string
                format: binary
            image/png:
              schema:
                type: string
                format: binary
            image/webp:
              schema:
                type: string
                format: binary
            image/avif:
              schema:
                type: string
                format: binary
            application/octet-stream:
              schema:
                type: string
                format: binary
        '404':
          description: Asset not found.
      tags:
      - Assets
  /assets/preview/{assetPath}:
    get:
      summary: Preview Asset Transform
      operationId: previewAsset
      description: 'Returns a transformed preview of an image asset. Identical to the

        `/assets` route but explicitly routed to the preview pipeline; used

        by the Dashboard for thumbnail rendering.

        '
      parameters:
      - $ref: '#/components/parameters/AssetPath'
      - $ref: '#/components/parameters/PresetQuery'
      - $ref: '#/components/parameters/WidthQuery'
      - $ref: '#/components/parameters/HeightQuery'
      - $ref: '#/components/parameters/ModeQuery'
      - $ref: '#/components/parameters/FormatQuery'
      - $ref: '#/components/parameters/QualityQuery'
      responses:
        '200':
          description: Transformed image bytes.
          content:
            image/jpeg:
              schema:
                type: string
                format: binary
            image/png:
              schema:
                type: string
                format: binary
            image/webp:
              schema:
                type: string
                format: binary
        '404':
          description: Asset not found.
      tags:
      - Assets
components:
  parameters:
    QualityQuery:
      name: q
      in: query
      required: false
      description: Output quality (1-100) for lossy formats.
      schema:
        type: integer
        minimum: 1
        maximum: 100
    AssetPath:
      name: assetPath
      in: path
      required: true
      description: The stored asset path (filename and any storage prefix).
      schema:
        type: string
      example: source/91/demo-product.jpg
    WidthQuery:
      name: w
      in: query
      required: false
      description: Target width in pixels.
      schema:
        type: integer
        minimum: 1
        maximum: 8192
    PresetQuery:
      name: preset
      in: query
      required: false
      description: Named preset configured on the AssetServerPlugin (`tiny`, `thumb`, `small`, `medium`, `large`, or custom).
      schema:
        type: string
        enum:
        - tiny
        - thumb
        - small
        - medium
        - large
    FormatQuery:
      name: format
      in: query
      required: false
      description: Output format override.
      schema:
        type: string
        enum:
        - jpg
        - jpeg
        - png
        - webp
        - avif
    ModeQuery:
      name: mode
      in: query
      required: false
      description: Fit mode for resizing.
      schema:
        type: string
        enum:
        - crop
        - resize
    HeightQuery:
      name: h
      in: query
      required: false
      description: Target height in pixels.
      schema:
        type: integer
        minimum: 1
        maximum: 8192
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    CookieAuth:
      type: apiKey
      in: cookie
      name: session
    ChannelToken:
      type: apiKey
      in: header
      name: vendure-token