FluidCloud API

Appearance

API Reference — Quota ​

Read your tenant's storage and share-link usage against the limits that come with your subscription. Use this endpoint to render a usage meter, decide whether to start a large upload, or warn before you hit a cap.

There is exactly one quota resource per tenant. It is read-only over the API — limits come from your plan, and the counters move automatically as you upload, delete, and mint share links.

  • Base URL: https://api-cloud.fluidvip.com/api/v1
  • Scope required: quota:read

GET /quota ​

Returns the caller's tenant storage usage, share-link usage, the limits that apply, and a per-product footprint breakdown.

Required scope: quota:read

This endpoint takes no parameters and no request body.

Response — QuotaOut ​

FieldTypeDescription
bytes_usedintegerTotal bytes currently stored across your tenant. This is the authoritative, enforced counter — every upload is checked against bytes_limit.
bytes_limitintegerYour storage allowance in bytes. -1 means unlimited.
links_usedintegerNumber of active share links you currently hold.
links_limitintegerYour share-link allowance. -1 means unlimited.
by_apparray of AppUsagePer-product storage breakdown (reporting only — never enforced). May be empty. See below.

bytes_used / bytes_limit is the single authoritative pool that gates uploads. by_app is a computed breakdown for attribution and sub-meters; it does not affect any limit.

AppUsage ​

FieldTypeDescription
appstringThe product slug that owns these files (for files you upload through this API key, this is typically fluidcloud).
bytesintegerTotal bytes attributed to that product.
filesintegerNumber of files attributed to that product.

Note on by_app and deletes. by_app is computed live from your file records, so it includes files that are soft-deleted but not yet purged (they still occupy storage, matching bytes_used). Once a file is purged its bytes drop out of both bytes_used and by_app. See Deleting data.

Example request ​

bash
curl https://api-cloud.fluidvip.com/api/v1/quota \
  -H "X-API-Key: fck_live_your_key_here"
python
from fluidcloud import FluidCloud

fc = FluidCloud(api_key="fck_live_your_key_here")

quota = fc.quota.get()
print(quota.bytes_used, "/", quota.bytes_limit)
print(quota.links_used, "/", quota.links_limit)

for app in quota.by_app:
    print(app.app, app.bytes, app.files)
typescript
import { FluidCloud } from "fluidcloud";

const fc = new FluidCloud({ apiKey: "fck_live_your_key_here" });

const quota = await fc.quota.get();
console.log(quota.bytes_used, "/", quota.bytes_limit);
console.log(quota.links_used, "/", quota.links_limit);

for (const app of quota.by_app) {
  console.log(app.app, app.bytes, app.files);
}

Example response ​

json
{
  "bytes_used": 4831838208,
  "bytes_limit": -1,
  "links_used": 42,
  "links_limit": 1000,
  "by_app": [
    { "app": "fluidcloud", "bytes": 4831838208, "files": 318 }
  ]
}

In this example, storage is unlimited (bytes_limit: -1), and 42 of 1000 share links are in use.

Reading limits correctly ​

Treat -1 as a sentinel for unlimited, not as a real number. A safe check:

python
def has_room(used: int, limit: int, incoming: int = 0) -> bool:
    if limit < 0:
        return True  # unlimited
    return used + incoming <= limit
typescript
function hasRoom(used: number, limit: number, incoming = 0): boolean {
  if (limit < 0) return true; // unlimited
  return used + incoming <= limit;
}
  • Before a large upload, check bytes_limit. If it is -1, you always have room; otherwise compare bytes_used + size against bytes_limit. The server enforces this regardless — an over-cap upload is refused with 402 quota_exceeded when you try to start it.
  • Before minting a share link, check links_limit the same way. Over the cap returns 402 quota_exceeded from the share-create call.

You never have to pre-create or initialize the quota — it exists for your tenant from first use, and the counters update automatically.

When usage changes ​

These counters move on their own as you use the API; you do not write to them:

  • bytes_used increases when an upload completes and decreases when a file's bytes are released (rollback or purge). See Uploading files.
  • links_used increases when you create a share link and decreases when you revoke one. See Raw links.

Quota and counters are read on every call — there is no caching to wait on. Right after an upload completes, the next GET /quota reflects it.

Limits and your plan. Storage is a generous pool, and a share-link count limit applies; both come with your subscription. If your plan changes, your limits update — read GET /quota to see the current values. The FluidCloud API itself is included with your plan; if it were not, calls would return 403 with feature_not_in_plan (see Errors).

Errors ​

StatusWhendetail
401Missing, invalid, or revoked API key"..."
403Key lacks quota:read{ "error": "insufficient_scope", ... }
403Subscription does not include API access{ "error": "feature_not_in_plan", ... }
429Over the rate limitsent with a Retry-After header

402 quota_exceeded is not returned by this read endpoint — it surfaces only on the actions that consume quota (uploads and share-link creation). See Errors for the full error model and Rate limits for limits and Retry-After handling.

The SDKs map these to typed errors: AuthError (401), PermissionError (403), and ApiError for others.

FluidCloud API — part of the Fluidvip ecosystem.

© Fluidvip