Introduction to the FluidCloud API

FluidCloud is a storage and raw-file-link backend you can build your own service on. You upload files straight to cloud storage, organize them however you like, and mint public or expiring links that serve the raw bytes over a fast, cookieless domain. Your app never has to run its own object store, presigning, virus scanning, or CDN edge.

This page introduces the API and its mental model. When you're ready to make your first call, jump to the quickstart.

What you can do with an API key

A partner API key gives your service everything it needs to use FluidCloud as a file backend:

• Store and organize files — create top-level buckets (spaces), arrange an optional folder tree inside them, and move or rename items.
• Upload direct-to-storage — start an upload and receive a presigned URL. Your bytes go straight from your client to storage; the API never proxies your file data. Files are scanned on upload before they can be served.
• Mint raw links — turn a clean file into a permanent public hotlink or a short-lived expiring link that serves the bytes from https://files.fluidadmin.com.
• Check usage — read your current storage consumption, share-link count, and plan limits.
• Delete data — permanently remove files, folders, and spaces you no longer need.

You can also tag any upload with your own logical key (client_key, e.g. results/job-7/out.png) and later fetch that file back by the same key — no need to persist FluidCloud's file id on your side. See Uploading.

The mental model

FluidCloud's resources nest in a fixed order. Read this top-to-bottom and the rest of the docs will click into place.

1. Tenant — your account / workspace. Your subscription and your API keys belong to the tenant. Every request your key makes is automatically scoped to your tenant, so you only ever see your own data. (Ids that aren't yours return 404, never another tenant's data — see Errors.)
2. Space — a top-level bucket inside your tenant. A space is the root container you put files and folders in. See Spaces.
3. Folder — an optional tree inside a space for organizing files. You can put files directly in a space and skip folders entirely, or nest folders as deep as you like. See Folders.
4. File — an uploaded object. Every file carries a scan_status; a file must be scanned clean (scan_status is clean) before it can be shared or served. Sharing or serving a not-yet-clean file returns 409 — we call this quarantine-until-clean. See Files.
5. Share / raw link — a link that serves a clean file's raw bytes from https://files.fluidadmin.com/s/<token>. A link is either a permanent public hotlink or a short-lived expiring link. See Raw links and Shares.
6. API key — the credential your service authenticates with. A key looks like fck_live_... (or fck_test_...). You create keys in the FluidCloud dashboard under Settings → Developer → API keys (an active subscription is required). Keys are not created via the API. See Authentication.

Tenant (your account)
└── Space (bucket)
    ├── File  → Share / raw link  → https://files.fluidadmin.com/s/<token>
    └── Folder (optional)
        └── File → Share / raw link

Base URLs

What	URL
API base	https://api-cloud.fluidvip.com/api/v1
Raw-link / file-serving domain	https://files.fluidadmin.com (links look like https://files.fluidadmin.com/s/<token>)
Dashboard (get an API key)	https://cloud.fluidvip.com

Every public route lives under the /api/v1 prefix, so the full base for any call is:

https://api-cloud.fluidvip.com/api/v1

Versioning. The /v1 in the path is a contract. The server can evolve without breaking your integration: new fields and endpoints may be added under /api/v1, but existing behavior won't change underneath you. A future major version would ship as a new prefix (/api/v2) while /api/v1 stays frozen. Pin /api/v1 in your client (both SDKs do this for you). See Versioning.

How authentication works (in one line)

Send your key in the X-API-Key header (you may also send it as Authorization: Bearer <key>). The Python and TypeScript SDKs add the header for you.

curl https://api-cloud.fluidvip.com/api/v1/spaces \
  -H "X-API-Key: fck_live_your_key_here"

Your key carries a fixed set of scopes that authorize exactly the read/write actions described in these docs across spaces, folders, files, shares, and quota. A request needs every scope its endpoint requires; if a scope is missing you get a 403 with error: insufficient_scope. Full details, including the exact scope list, are in Authentication.

What's included with your plan

API access is part of your FluidCloud subscription. Your plan comes with a generous storage pool and a cap on the number of live share links. Read your current usage and limits at any time from the quota endpoint — a limit value of -1 means unlimited. See Quota and usage. If you exceed a storage or share-link cap, a request returns 402 with detail equal to quota_exceeded.

Requests are rate limited per key (a default of 600 requests/minute, plus tighter per-action caps). Over a limit returns 429 with a Retry-After header. See Rate limits.

A note on what the API does not do

The partner API is for using FluidCloud as a storage + raw-link backend. Account-level operations — creating, listing, or rotating API keys, and managing your subscription or team — live in the dashboard, not the API.

Next steps

• Quickstart — install an SDK and run your first upload-and-share in a few minutes.
• Authentication — get a key, send it correctly, and understand scopes.
• Raw links guide — mint public and expiring links to your files.
• Core concepts — a deeper tour of spaces, folders, files, scanning, and shares.
• API reference — every endpoint, parameter, and field.