Zesty Files API

openapi: 3.2.0
info:
  title: Zesty Media Files API
  description: 'The Zesty.io Media API is a collection of services for managing media files in the Zesty.io platform. It consists of four services: Media Manager (database communication and primary endpoints), Media Storage (communicates with storage provider), Media Modify (image manipulation), and Media Resolver (returns CDN paths for media file ZUIDs). The Media Manager service is the most commonly used and handles bins, groups (folders), and file management.'
  version: 1.0.0
  contact:
    name: Zesty.io
    url: https://www.zesty.io/
  license:
    name: Proprietary
    url: https://www.zesty.io/
servers:
- url: https://media-manager.api.zesty.io
  description: Zesty Media Manager Service
- url: https://media-storage.api.zesty.io
  description: Zesty Media Storage Service
- url: https://media-modify.api.zesty.io
  description: Zesty Media Modify Service
- url: https://media-resolver.api.zesty.io
  description: Zesty Media Resolver Service
tags:
- name: Files
  description: Manage and upload media files.
paths:
  /files:
    get:
      operationId: getFiles
      summary: Zesty List all media files
      description: Returns a list of media files, optionally filtered by bin or group.
      tags:
      - Files
      security:
      - sessionToken: []
      parameters:
      - name: binZUID
        in: query
        schema:
          type: string
        description: Filter files by bin ZUID.
      - name: groupZUID
        in: query
        schema:
          type: string
        description: Filter files by group ZUID.
      - name: limit
        in: query
        schema:
          type: integer
        description: Maximum number of files to return.
      - name: page
        in: query
        schema:
          type: integer
        description: Page number for pagination.
      responses:
        '200':
          description: A list of media files.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/File'
        '401':
          description: Unauthorized.
  /files/{fileZUID}:
    get:
      operationId: getFile
      summary: Zesty Get a media file
      description: Returns details for a specific media file.
      tags:
      - Files
      security:
      - sessionToken: []
      parameters:
      - name: fileZUID
        in: path
        required: true
        schema:
          type: string
        description: The ZUID of the file.
      responses:
        '200':
          description: File details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                  data:
                    $ref: '#/components/schemas/File'
        '401':
          description: Unauthorized.
        '404':
          description: File not found.
    put:
      operationId: updateFile
      summary: Zesty Update a media file
      description: Updates the metadata of a specific media file.
      tags:
      - Files
      security:
      - sessionToken: []
      parameters:
      - name: fileZUID
        in: path
        required: true
        schema:
          type: string
        description: The ZUID of the file.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  description: The file title.
                fileName:
                  type: string
                  description: The file name.
                groupZUID:
                  type: string
                  description: Move to a different group.
      responses:
        '200':
          description: File updated successfully.
        '401':
          description: Unauthorized.
        '404':
          description: File not found.
    delete:
      operationId: deleteFile
      summary: Zesty Delete a media file
      description: Deletes a specific media file.
      tags:
      - Files
      security:
      - sessionToken: []
      parameters:
      - name: fileZUID
        in: path
        required: true
        schema:
          type: string
        description: The ZUID of the file.
      responses:
        '200':
          description: File deleted successfully.
        '401':
          description: Unauthorized.
        '404':
          description: File not found.
  /upload/{binZUID}/{groupZUID}:
    post:
      operationId: uploadFile
      summary: Zesty Upload a media file
      description: Uploads a new media file to the specified bin and group. Supports images, documents, and other file types.
      tags:
      - Files
      security:
      - sessionToken: []
      parameters:
      - name: binZUID
        in: path
        required: true
        schema:
          type: string
        description: The ZUID of the bin to upload to.
      - name: groupZUID
        in: path
        required: true
        schema:
          type: string
        description: The ZUID of the group (folder) to upload to.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - file
              properties:
                file:
                  type: string
                  format: binary
                  description: The file to upload.
                title:
                  type: string
                  description: The file title.
                fileName:
                  type: string
                  description: The desired file name.
      responses:
        '201':
          description: File uploaded successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                  data:
                    $ref: '#/components/schemas/File'
        '400':
          description: Invalid request or unsupported file type.
        '401':
          description: Unauthorized.
components:
  schemas:
    File:
      type: object
      properties:
        ZUID:
          type: string
          description: The Zesty Universal Identifier for the file.
        binZUID:
          type: string
          description: The bin this file belongs to.
        groupZUID:
          type: string
          description: The group this file belongs to.
        fileName:
          type: string
          description: The file name.
        title:
          type: string
          description: The file title.
        url:
          type: string
          format: uri
          description: The CDN URL for the file.
        type:
          type: string
          description: The MIME type of the file.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
  securitySchemes:
    sessionToken:
      type: apiKey
      in: header
      name: Authorization
      description: A session token or access token obtained from the Auth API.
externalDocs:
  description: Zesty Media API Documentation
  url: https://docs.zesty.io/docs/media