File upload, directory organisation and asset retrieval for use in campaigns, templates and chatbot flows.
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