API Reference — Conventions
This is the reference section for the FluidCloud Partner API. Every endpoint here is something a self-serve partner API key can call to use FluidCloud as a storage and raw-file-link backend for your own app or service.
This page documents the conventions that apply to every endpoint — the base URL, authentication header, content types, id and timestamp formats, list/filter parameters, and the response semantics you can rely on across the API. Read it once; each resource page below assumes it.
If you are new here, start with the Quickstart, then Authentication and Core concepts.
Base URL
All partner endpoints live under a single versioned prefix:
https://api-cloud.fluidvip.com/api/v1The version segment (/v1) is part of the contract. A future /v2 will be introduced side-by-side without changing /v1, so an integration pinned to /api/v1 keeps working. See Versioning for the stability policy.
Two other hosts you will encounter:
| Host | Purpose |
|---|---|
https://api-cloud.fluidvip.com/api/v1 | The API you call. |
https://files.fluidadmin.com | The cookieless raw-link domain where shared file bytes are served. A raw link looks like https://files.fluidadmin.com/s/<token>. See Raw links. |
https://cloud.fluidvip.com | The FluidCloud dashboard, where you create and manage your API keys (Settings → Developer → API keys). An active subscription is required. Keys cannot be created via the API. |
Both SDKs default to the production base URL, so you only supply your API key:
from fluidcloud import FluidCloud
fc = FluidCloud(api_key="fck_live_...")import { FluidCloud } from "fluidcloud";
const fc = new FluidCloud({ apiKey: "fck_live_..." });Authentication
Every request must carry your API key. Send it in the X-API-Key header:
X-API-Key: fck_live_...The key may also be sent as a bearer credential — Authorization: Bearer fck_live_... — and the server treats the two interchangeably. Both SDKs attach the header for you.
Keys look like fck_live_... (production) or fck_test_.... A missing, malformed, or revoked key returns 401. A valid key whose scope set does not authorize the endpoint returns 403 with a structured insufficient_scope body; a key whose subscription does not include API access returns 403 feature_not_in_plan.
Scopes use AND semantics: a request must hold every scope the endpoint requires. Your partner key carries this fixed set:
spaces:read spaces:write
folders:read folders:write
files:read files:write
shares:read shares:write
quota:readEach reference page states the scope(s) its endpoints need. Full details, including how scopes map to error responses, are on the Authentication page.
Requests and responses
Content type
Request bodies are JSON. Send Content-Type: application/json on any call with a body (POST, PATCH, PUT). Responses are JSON unless a 204 No Content is returned (see below). File bytes are never sent through or returned by the API — uploads go directly from your client to storage via presigned URLs, and downloads are served from the raw-link domain. See Uploading.
Identifiers
Every FluidCloud resource id (space, folder, file, share, upload session) is a UUID string, e.g.:
"id": "8f4b0c2a-3d1e-4a9f-9c77-2b6e5a1d0e44"Pass ids exactly as returned. Ids are opaque — do not parse or construct them.
Many file operations also accept your own client_key — a logical key you choose at upload time (for example results/job-7/out.png) — so you can address a file by a name that is meaningful to your system instead of storing FluidCloud's UUID. Resolve one back to a file with GET /files/resolve. See Uploading for how to set it.
Timestamps
All timestamps are ISO-8601 in UTC, with a trailing Z:
"created_at": "2026-06-23T14:05:00Z"List and filter conventions
List endpoints (for example listing folders in a space, or files in a folder) follow a consistent query-parameter shape:
| Parameter | Meaning |
|---|---|
Scope filters (e.g. space_id, folder_id) | Restrict results to a parent. Passed as UUID strings in the query string. |
limit | Maximum number of items to return in one page. |
cursor | Opaque pagination cursor returned by the previous page; pass it back to fetch the next page. |
Always treat the cursor value as opaque and pass it back verbatim — never build or modify one. When a list response omits the next cursor, you have reached the end. Each resource page documents the exact filters it supports; do not assume a filter exists unless it is listed there.
curl "https://api-cloud.fluidvip.com/api/v1/folders?space_id=8f4b0c2a-3d1e-4a9f-9c77-2b6e5a1d0e44&limit=50" \
-H "X-API-Key: fck_live_..."page = fc.folders.list(space_id="8f4b0c2a-3d1e-4a9f-9c77-2b6e5a1d0e44", limit=50)const page = await fc.folders.list({
spaceId: "8f4b0c2a-3d1e-4a9f-9c77-2b6e5a1d0e44",
limit: 50,
});Response semantics
These rules hold across every endpoint. Relying on them keeps your integration correct when you retry, when ids belong to another tenant, and when a file is still being processed.
204 No Content
Successful operations that have no body to return — chiefly deletes and share-link revocations — respond with 204 No Content. There is no JSON payload; the status itself is the result. Treat any 2xx as success and only parse a body when one is present.
Idempotent deletes and revokes
Deletes and revocations are idempotent. Deleting a file (or folder, or space) that is already gone, or revoking a share link that is already revoked, returns the same successful result as the first call rather than an error. This means a retry after a dropped connection is always safe — you never need to special-case "already deleted" as a failure. See Deleting data and the Deletion reference.
Note on revoked permanent links: revocation takes effect immediately, but a previously fetched permanent raw link can still serve from edge cache until its max-age of 3600 seconds lapses. Plan deletions accordingly — see Raw links.
Tenant isolation — 404, never 403
Your key can only see resources in your own tenant. A request for an id that exists but belongs to another tenant returns 404 Not Found — exactly as if the id did not exist. The API never returns 403 to confirm that an id is real but off-limits, so you cannot probe for other tenants' ids. Treat 404 as "not yours or not found" and move on. (A 403 means a scope or plan problem with your key, not a missing resource — see Errors.)
Quarantine-until-clean
Every uploaded file is automatically scanned before it can leave FluidCloud. A file must be scanned clean — scan_status equals clean — before you can create a share link for it or serve its bytes. Attempting to share or serve a file that has not yet cleared the scan returns 409 Conflict ("the file is not ready"). This is the quarantine-until-clean rule. Poll the file's scan_status (see the Files reference) until it reads clean, then create the share. See Uploading for the full upload-to-clean lifecycle.
Errors
Every error is an HTTP status with a JSON body whose top-level key is detail (a string, or a structured object for 402/403). The cases you will see:
| Status | Meaning |
|---|---|
400 | Bad input. |
401 | Missing, invalid, or revoked API key. |
402 | detail is quota_exceeded — over your storage or share-link cap. |
403 | Structured detail: error is insufficient_scope (key lacks a needed scope) or feature_not_in_plan (subscription does not include API access). |
404 | Not found — or not yours (cross-tenant ids return 404, never 403). |
409 | The file is not ready (sharing/serving a not-yet-clean file). |
413 | Payload too large. |
422 | Validation error. |
429 | Rate limited — includes a Retry-After header. |
The SDKs map these to typed errors: AuthError (401), QuotaExceededError (402), PermissionError (403), NotFoundError (404), ConflictError (409), and ApiError for everything else. Full payload shapes and handling patterns are on the Errors page.
Rate limits
Limits are enforced per API key: a default of 600 requests per minute, plus tighter per-action caps (creating share links 120/min, starting uploads 300/min, starting URL imports 30/min). Exceeding a limit returns 429 with a Retry-After header telling you how many seconds to wait before retrying. See Rate limits.
Reference pages
The partner API surface, by resource:
| Page | Scopes | What it covers |
|---|---|---|
| Spaces | spaces:read, spaces:write | Create and manage spaces — the top-level containers for your folders and files. |
| Folders | folders:read, folders:write | Organize files into folders within a space. |
| Files | files:read, files:write | Inspect file metadata, check scan_status, resolve by client_key, and delete files. |
| Uploads | files:write | Start an upload, complete the presigned PUT, and import a file from a URL. |
| Shares | shares:read, shares:write | Create, list, and revoke raw share links served from files.fluidadmin.com. |
| Quota | quota:read | Read your current storage usage, share-link count, and plan limits. |
| Deletion | *:write | Idempotent delete and revoke semantics across spaces, folders, files, and shares. |
For the conceptual model behind these resources (spaces → folders → files → shares), see Core concepts. For the SDK method names that map onto each endpoint, see the Python SDK and TypeScript SDK references.
Creating, listing, and rotating API keys is done in the FluidCloud dashboard (Settings → Developer → API keys), not through the API. Team management, cross-service delegation, and Google Drive import are not available to partner API keys.