File Upload API

Clouisle provides endpoints for knowledge-base documents, chat attachments, sandbox artifacts, and file parsing. Requests use multipart/form-data, and responses follow the unified code, data, msg shape.

Endpoint Overview

Supported Formats and Limits

Knowledge-base document uploads support PDF, DOC/DOCX, TXT/Markdown, HTML, CSV, XLS/XLSX, JSON, and PPTX. Images, archives, and video are not knowledge-base document types.

Generic image uploads support JPEG, PNG, GIF, WebP, SVG, and ICO. Generic file uploads also support PDF, TXT, Markdown, HTML, CSV, JSON, DOC/DOCX, XLSX, and PPTX.

Chat's generic upload path has one server-enforced 10 MB per-file limit rather than separate limits by format.

Upload an Image or Generic File

curl -X POST "$API_BASE_URL/api/v1/upload/file" \
  -H "Authorization: Bearer $CLOUISLE_TOKEN" \
  -F "file=@/path/to/report.pdf"

Both /upload/image and /upload/file accept a category query parameter, defaulting to general; other common values are avatar and icon. It selects the storage folder and appears in the returned url:

curl -X POST "$API_BASE_URL/api/v1/upload/image?category=avatar" \
  -H "Authorization: Bearer $CLOUISLE_TOKEN" \
  -F "file=@/path/to/avatar.png"

The response contains a generated storage filename. When submitting a chat attachment, use the returned url, filename, size, and mime_type; do not construct /upload/files/{asset_id} from the asset ID.

{
  "code": 0,
  "data": {
    "asset_id": "550e8400-e29b-41d4-a716-446655440000",
    "url": "/api/v1/upload/files/general/2026/09/7f3a1c9d2b10_a1b2c3d4.pdf",
    "filename": "7f3a1c9d2b10_a1b2c3d4.pdf",
    "original_name": "report.pdf",
    "size": 1048576,
    "content_type": "application/pdf"
  },
  "msg": "success"
}

Pass these fields in the file_urls array of an Agent chat request; the older parsed files field is deprecated. See the Agent Chat API.

Parse Files

curl -X POST "$API_BASE_URL/api/v1/upload/parse?max_content_length=100000&truncate_strategy=end" \
  -H "Authorization: Bearer $CLOUISLE_TOKEN" \
  -F "file=@/path/to/document.pdf"

max_content_length defaults to 100000 and accepts 1000–500000. truncate_strategy accepts end, start, or middle. Batch parsing uses the files field and accepts at most five files; individual failures are returned with the corresponding result instead of failing every item.

Knowledge-Base Documents and Sandbox Artifacts

A successful knowledge-base document upload returns pending. Configure chunk settings and call the knowledge-base process endpoint to start embedding and indexing.

The sandbox artifact endpoint accepts a JWT or clou_ API key. Internal sandbox requests may instead use a signature: the X-Sandbox-Artifact-Timestamp (Unix seconds) and X-Sandbox-Artifact-Signature headers, rejected when the timestamp differs from the current time by more than 300 seconds. Its size limit comes from the SANDBOX_ARTIFACT_MAX_FILE_SIZE_MB site setting.

Access Control and Errors

• Generated images, generated videos, and sandbox artifacts are protected Assets. Viewing or downloading them requires the current user or API key to have access to the related conversation or workflow run.
• Fetch protected media URLs with the active JWT or API key. Clients should surface unauthenticated, unauthorized, unavailable, and too-large preview states instead of falling back to an unauthenticated raw URL.
• An asset_ref is valid only within its conversation or workflow-run scope; do not guess or reuse it across scopes.

When an upload or parse fails, read data.errors and msg; do not infer the cause from the HTTP status alone.