components:
  responses:
    '404':
      description: Record not found
      content:
        application/json:
          schema:
            properties:
              data:
                properties:
                  code:
                    type: integer
                  message:
                    type: string
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >
        Static API Key authentication.  A long-lived token generated manually in
        the SendPulse account settings.
      x-ai-description: >
        Permanent authentication token. Ideal for simple integrations without
        token refresh logic.
    outh2:
      type: oauth2
      description: OAuth 2.0 Client Credentials flow for temporary access tokens.
      flows:
        clientCredentials:
          tokenUrl: https://api.sendpulse.com/oauth/access_token
          scopes: {}
      x-ai-description: >
        Standard OAuth 2.0 flow using Client ID and Client Secret.  Provides
        temporary tokens (valid for 1 hour) for enhanced security.
info:
  description: >-
    Using the API for the FileManager service, you can integrate your system
    with FileManager from SendPulse
  title: SendPulse FileManager Public API
  version: 1.0.0
openapi: 3.1.2
paths:
  /file:
    post:
      tags:
        - File
      summary: Upload file to storage
      description: Uploads one or multiple files to the specified directory
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - content[]
                - pathToStore
              properties:
                content[]:
                  type: array
                  items:
                    type: string
                    format: binary
                  description: File(s) to upload
                pathToStore:
                  type: string
                  example: /test
                  description: Path to the directory where the file will be stored
                height:
                  type: integer
                  description: Optional height parameter for video files
                  example: 1080
                width:
                  type: integer
                  description: Optional width parameter for video files
                  example: 1920
      responses:
        '200':
          description: File successfully uploaded
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
      operationId: uploadFile
      x-ai-role: file_storage_manager
      x-ai-description: >-
        Uploads one or more files to the SendPulse file storage at a specified
        directory path. This endpoint serves as the entry point for all asset
        management — images, documents, or video content used across campaigns,
        landing pages, or chatbot flows. The path structure is persistent and
        shared across the account, so naming and organization at upload time
        directly affects long-term asset discoverability.
      x-ai-reasoning-instructions:
        - >-
          Confirm the target directory path exists or will be auto-created
          before uploading.
        - >-
          Warn the user if uploading multiple files simultaneously — ensure each
          file in content[] is within allowed size limits.
        - >-
          For video files, prompt the user to provide width and height to avoid
          server-side defaults that may degrade quality.
        - >-
          Avoid overwriting existing files with identical names in the same path
          — ask the user to rename or use versioned subdirectories.
        - >-
          Validate that pathToStore starts with a forward slash (e.g.,
          /images/2024) and does not contain unsafe characters.
      x-ai-responding-instructions:
        - >-
          Confirm successful upload and echo back the path where the file was
          stored.
        - >-
          If multiple files were uploaded, summarize the count of successfully
          stored assets.
        - >-
          Suggest using the stored file URL in relevant campaign or chatbot
          configuration as the immediate next step.
        - >-
          If the upload fails, distinguish between path errors, file format
          issues, and size limit violations in your explanation.
      x-ai-suggestions:
        - /images/campaigns
        - /documents/legal
        - /videos/onboarding
        - /assets/newsletters/2024
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
            - FileUpload
            - ResourceStateUpdate
    delete:
      tags:
        - File
      summary: Delete file from storage
      description: Delete specific file from storage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                path:
                  type: string
                  description: Path to file in storage
                  example: /directory/file_name.txt
      responses:
        '204':
          description: File delete successfully
        '404':
          description: File not found
      operationId: deleteFile
      x-ai-role: storage_manager
      x-ai-description: >-
        Permanently removes a file from the storage by its full path. This is a
        destructive, irreversible operation — the file cannot be recovered after
        deletion. Use this to clean up obsolete assets, free storage quota, or
        enforce data retention policies.
      x-ai-reasoning-instructions:
        - >-
          Before deleting, confirm with the user that the correct file path is
          specified — especially if the path was provided dynamically.
        - >-
          Warn if the file might be referenced by other resources (e.g., active
          campaigns, landing pages, or email templates).
        - >-
          Ensure the path includes the full directory structure, not just the
          filename.
        - >-
          Do not proceed without explicit user confirmation when operating on
          files in critical or shared directories.
      x-ai-responding-instructions:
        - >-
          Confirm successful deletion by echoing the deleted file path back to
          the user.
        - >-
          If a 404 is returned, clarify that the file does not exist at the
          specified path and suggest verifying the path via a file listing
          operation.
        - >-
          Remind the user that this action is irreversible and the file cannot
          be restored.
      x-ai-suggestions:
        - /uploads/images/banner_old.png
        - /exports/report_2024_q1.csv
        - /tmp/import_draft.xlsx
      x-ai-capabilities:
        confirmation:
          type: Required
          message: This will permanently delete the file. This action cannot be undone.
        security_info:
          data_handling:
            - IrreversibleDelete
  /file/exist:
    post:
      tags:
        - File
      summary: Check if file exists
      description: Checks whether a file exists at the specified path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - path
              properties:
                path:
                  type: string
                  example: /test/file.txt
                  description: Path to the file to check
      responses:
        '200':
          description: Check completed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: boolean
                    description: Whether the file exists
      operationId: checkFileExist
      x-ai-role: file_system_manager
      x-ai-description: >-
        Validates the physical presence of a file at a given path before
        performing dependent operations such as download, delete, or update. Use
        this as a pre-check guard to avoid 404 errors or unnecessary API calls
        in file management workflows.
      x-ai-reasoning-instructions:
        - >-
          Use this check before any destructive or read operation to avoid
          acting on a non-existent file.
        - >-
          Ensure the path is absolute and uses forward slashes — relative paths
          may produce misleading results.
        - >-
          If the result is false, suggest verifying the path spelling or listing
          the parent directory contents.
      x-ai-responding-instructions:
        - >-
          Clearly state whether the file exists or not — do not leave the user
          guessing from a raw boolean.
        - >-
          If the file does not exist, suggest next steps: check the path, list
          the directory, or upload the file.
        - >-
          If the file exists, suggest the likely follow-up action (download,
          delete, get metadata).
      x-ai-suggestions:
        - /uploads/images/logo.png
        - /documents/reports/q1-2024.pdf
        - /test/file.txt
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
            - ReadOnly
  /directory:
    post:
      tags:
        - Directory
      summary: Create directory
      description: Creates a new directory at the specified path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - pathToStore
                - name
              properties:
                pathToStore:
                  type: string
                  example: /test
                  description: Path where the directory will be created
                name:
                  type: string
                  example: my-folder
                  description: Name of the directory to create
      responses:
        '200':
          description: Directory successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
      operationId: createDirectory
      x-ai-role: file_system_manager
      x-ai-description: >-
        Initializes a new directory node within the file storage hierarchy. A
        directory in SendPulse File Manager acts as a logical container for
        organizing uploaded assets. Creating a well-structured directory tree
        upfront simplifies future file retrieval, sharing, and cleanup
        operations.
      x-ai-reasoning-instructions:
        - >-
          Before creating, verify whether a directory with the same name already
          exists at the specified path to avoid silent duplicates.
        - >-
          Validate that `pathToStore` starts with `/` and does not contain
          illegal characters.
        - >-
          Advise the user to use lowercase, hyphen-separated names (e.g.,
          `campaign-assets-2024`) for cross-platform compatibility.
        - >-
          If the parent path does not exist, clarify whether the API creates
          intermediate directories or returns an error.
      x-ai-responding-instructions:
        - >-
          Confirm successful creation by echoing the full resulting path
          (pathToStore + name).
        - >-
          Suggest uploading files into the new directory as the immediate next
          step.
        - >-
          If creation fails, check whether the path is valid and the account has
          sufficient storage quota.
      x-ai-suggestions:
        - campaign-assets
        - user-uploads-2024
        - product-images
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
            - ResourceStateUpdate
    get:
      tags:
        - Directory
      summary: Get directory tree
      description: Returns tree structure of directories
      responses:
        '200':
          description: Directory tree retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  tree:
                    type: object
                    description: Tree structure of directories
      operationId: getDirectory
      x-ai-role: file_system_navigator
      x-ai-description: >-
        Retrieves the full hierarchical tree of directories in the account's
        file storage. Use this as the entry point for any file management
        workflow — it reveals the folder structure before uploading, moving, or
        organizing files.
      x-ai-reasoning-instructions:
        - >-
          Call this endpoint first when the user asks to upload or organize
          files — you need the tree to determine the correct target directory.
        - >-
          If the tree is empty, inform the user that no directories have been
          created yet and suggest creating one before proceeding.
        - >-
          Use the returned structure to resolve human-readable folder names to
          their IDs for subsequent API calls.
      x-ai-responding-instructions:
        - >-
          Present the directory tree in a readable hierarchical format, not as
          raw JSON.
        - >-
          If the user is looking for a specific folder, highlight it in the
          response.
        - >-
          Suggest a next step such as uploading a file or creating a
          subdirectory based on the user's context.
      x-ai-suggestions:
        - Use the returned directory IDs with file upload or move endpoints.
        - >-
          If you need to create a new folder, use the directory creation
          endpoint with the parent ID from this tree.
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
            - ReadOnly
  /directory/size:
    get:
      tags:
        - Directory
      summary: Get storage statistics
      description: Returns storage usage statistics
      responses:
        '200':
          description: Storage statistics retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  fileCount:
                    type: integer
                    description: Number of files
                    example: 150
                  directoryCount:
                    type: integer
                    description: Number of directories
                    example: 25
                  usedSpace:
                    type: number
                    format: float
                    description: Used space in MB
                    example: 245.7
                  tariffStorageSpace:
                    type: number
                    format: float
                    description: Available storage space by tariff in MB
                    example: 1024
                  availableSpace:
                    type: number
                    format: float
                    description: Available free space in MB
                    example: 778.3
      operationId: getDirectorySize
      x-ai-role: storage_resource_manager
      x-ai-description: >-
        Provides a snapshot of the account's file storage state: how many files
        and directories exist, how much space is consumed, and how much remains
        under the current tariff. Use this before upload operations to prevent
        quota overflows, or to surface storage health to the user without
        navigating the UI.
      x-ai-reasoning-instructions:
        - >-
          Check this endpoint before bulk upload operations to confirm
          sufficient free space (availableSpace) is available.
        - >-
          If usedSpace is close to tariffStorageSpace, proactively warn the user
          about the risk of hitting the quota.
        - >-
          Use fileCount and directoryCount to give the user a meaningful
          structural overview, not just raw numbers.
        - >-
          Do not infer directory depth or hierarchy from this endpoint — it
          returns aggregate totals only.
      x-ai-responding-instructions:
        - >-
          Present usedSpace and availableSpace as human-readable values (e.g.,
          '245.7 MB used of 1024 MB').
        - >-
          If availableSpace is below 10% of tariffStorageSpace, flag it as a
          warning and suggest cleaning up unused files.
        - >-
          Mention fileCount and directoryCount as context, not as primary data —
          the quota numbers are what matter most.
        - >-
          If the user asks whether they can upload a specific file size, compare
          it against availableSpace and give a direct yes/no.
      x-ai-suggestions:
        - Run before any bulk file import to verify quota headroom.
        - >-
          Use alongside `listDirectory` to correlate storage usage with specific
          folders.
        - >-
          Combine with a tariff upgrade suggestion if availableSpace is
          critically low.
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
            - ReadOnly
  /directory/{path}:
    get:
      tags:
        - Directory
      summary: Get directory contents
      description: Returns data for a specific directory
      parameters:
        - in: path
          name: path
          schema:
            type: string
          required: true
          description: Directory path
          example: /test/subfolder
      responses:
        '200':
          description: Directory contents retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    path:
                      type: string
                      example: /test/subfolder/file.txt
                    name:
                      type: string
                      example: file.txt
                    isFolder:
                      type: boolean
                      example: false
                    size:
                      type: number
                      format: float
                      example: 12.5
                    filesCount:
                      type: integer
                      example: 0
      operationId: getDirectoryContents
      x-ai-role: file_system_navigator
      x-ai-description: >-
        Retrieves the contents of a specific directory in the SendPulse file
        storage. Use this to explore the file tree before performing operations
        — it reveals both files (with size) and nested folders (with file
        count), enabling informed decisions about uploads, deletions, or
        reorganization without blindly guessing paths.
      x-ai-reasoning-instructions:
        - >-
          Ensure the path starts with '/' and uses forward slashes; normalize
          user-provided paths before calling.
        - >-
          If the user mentions a folder name without a full path, check parent
          directories first to resolve the correct absolute path.
        - >-
          Distinguish between files (isFolder: false) and subdirectories
          (isFolder: true) in the response to guide follow-up actions.
        - >-
          An empty array response means the directory exists but is empty — do
          not assume the path is invalid.
        - >-
          If the path does not exist, surface the error clearly rather than
          retrying with guessed alternatives.
      x-ai-responding-instructions:
        - >-
          Present the contents as a structured list separating folders from
          files for readability.
        - >-
          For files, include name and size (in KB if > 1024 bytes); for folders,
          include name and filesCount.
        - >-
          If the directory is empty, explicitly tell the user rather than
          showing a blank result.
        - >-
          Suggest logical next steps based on what was found — e.g., upload a
          file, navigate into a subfolder, or delete an item.
      x-ai-suggestions:
        - /
        - /images
        - /uploads/2024
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
            - ReadOnly
  /directory/find:
    get:
      tags:
        - Directory
      summary: Search files
      description: Search for files in the specified directory
      parameters:
        - in: query
          name: search
          schema:
            type: string
          required: true
          description: Keyword for search
          example: document
        - in: query
          name: path
          schema:
            type: string
            default: /
          required: true
          description: Directory for recursive search
          example: /test
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          example: /test/document.pdf
                        name:
                          type: string
                          example: document.pdf
                        size:
                          type: string
                          example: 2.5
                        date:
                          type: string
                          example: 2025-10-15T12:00:00.000Z
                        extension:
                          type: string
                          example: pdf
                        thumb:
                          type: string
                          example: /thumb/document.jpg
      operationId: findDirectoryFiles
      x-ai-role: file_system_navigator
      x-ai-description: >-
        Performs a recursive keyword search across all files within a specified
        directory tree. This is the primary discovery tool for locating assets
        by name fragment — useful before operations like move, delete, or share
        when the exact path is unknown. Search is case-insensitive and matches
        partial filenames.
      x-ai-reasoning-instructions:
        - >-
          If the user does not specify a path, default to '/' to search the
          entire storage.
        - >-
          Prefer narrow `path` scopes when the user mentions a folder context —
          it reduces noise in results.
        - >-
          If the result set is large, suggest narrowing the search keyword or
          restricting the path.
        - >-
          Use this endpoint before file operations (delete, move, download) when
          the user only knows the filename or extension, not the full path.
      x-ai-responding-instructions:
        - >-
          Present results as a list with name, path, size, and date — highlight
          the full path for direct use in follow-up operations.
        - >-
          If no results are returned, suggest broadening the keyword or checking
          the path scope.
        - >-
          If multiple files share the same name in different directories, list
          all matches and ask the user to confirm which one to act on.
      x-ai-suggestions:
        - >-
          Search by extension fragment (e.g., '.pdf') to list all files of a
          type.
        - >-
          Use a parent folder path like '/projects' to scope the search to a
          subtree.
        - >-
          Combine results with `deleteFile` or `moveFile` for post-discovery
          operations.
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
            - ReadOnly
  /file/filter:
    post:
      tags:
        - File
      summary: Filter files
      description: Filters files in the specified directory by date range and sorting
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - path
              properties:
                path:
                  type: string
                  example: /test
                  description: Directory path to filter files
                fromDate:
                  type:
                    - string
                    - 'null'
                  format: date
                  example: 2025-01-01 00:01
                  description: >-
                    Filter files from this date (search: '>='). Supported
                    formats: Y-m-d H:i. Timezone: UTC
                toDate:
                  type:
                    - string
                    - 'null'
                  format: date
                  example: 2025-12-31 23:59
                  description: >-
                    Filter files to this date (search: '<='). Supported formats:
                    Y-m-d H:i. Timezone: UTC
                sort:
                  type:
                    - string
                    - 'null'
                  enum:
                    - asc
                    - desc
                  example: desc
                  description: Sort order for files
      responses:
        '200':
          description: Files filtered successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    path:
                      type: string
                      example: /test/test_1.txt
                      description: Full path to the file
                    lastModified:
                      type: string
                      format: date-time
                      example: 2025-10-17T14:12:09.000Z
                      description: Last modification timestamp
      operationId: filterFiles
      x-ai-role: file_system_manager
      x-ai-description: >-
        Дозволяє звузити перелік файлів у директорії за часовим діапазоном та
        порядком сортування. Корисний при аудиті завантажень, пошуку нещодавно
        змінених файлів або побудові інтерфейсів перегляду медіатеки. Часовий
        діапазон інтерпретується у UTC — важливо враховувати часовий пояс
        клієнта перед передачею дат.
      x-ai-reasoning-instructions:
        - >-
          Перед викликом переконайся, що path — це директорія, а не шлях до
          конкретного файлу.
        - >-
          Якщо вказано лише fromDate або лише toDate — це допустимо: один з
          параметрів є відкритим кінцем діапазону.
        - >-
          Всі дати передаються у UTC. Якщо користувач вказав локальний час —
          конвертуй перед викликом.
        - >-
          Якщо sort не вказано — порядок не гарантований; для стабільних
          результатів рекомендуй явно передавати 'desc' для отримання найновіших
          файлів першими.
        - >-
          Якщо результат порожній — не роби повторний виклик; поясни, що файли у
          вказаному діапазоні відсутні.
      x-ai-responding-instructions:
        - Відобрази кількість знайдених файлів і їхні шляхи у зручному вигляді.
        - >-
          Якщо масив порожній — повідом, що файли за вказаними критеріями не
          знайдено, і запропонуй розширити діапазон дат.
        - >-
          Якщо повернуто багато файлів — запропонуй уточнити фільтр або
          завантажити конкретний файл через відповідний endpoint.
        - >-
          Зверни увагу на поле lastModified — воно в ISO 8601 UTC і може
          відрізнятися від локального часу користувача.
      x-ai-suggestions:
        - >-
          Отримати файли за останній тиждень: fromDate=7 днів тому,
          toDate=сьогодні, sort=desc
        - >-
          Переглянути всі файли у директорії без фільтрації по даті: передати
          лише path
        - 'Знайти найстаріші файли: sort=asc без обмеження дат'
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
            - ReadOnly
security:
  - apiKey: []
  - oauth2: []
servers:
  - description: Production server
    url: https://api.sendpulse.com/fm/public/v1
tags:
  - description: file entity
    name: File
  - description: directory entity
    name: Directory
