API Reference — Spaces

A Space is a top-level file bucket inside your tenant. Every other resource — folders, files, uploads, and shares — lives inside a Space, so a space_id is the first thing you need before you can store anything. Most partners run with a single default Space, but you can create more to keep separate workloads (for example, one per customer or per pipeline) isolated from one another.

This page documents every Spaces endpoint a partner API key can call. All routes are under the base URL:

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

Send your API key in the X-API-Key header (or Authorization: Bearer). See Authentication for details. Both SDKs add the header automatically.

For an introduction to how Spaces, folders, and files relate, see Concepts.

The `SpaceOut` object

Every Spaces endpoint returns one or more of these objects.

Field	Type	Description
`id`	string (UUID)	The Space identifier. Pass this as `space_id` to the folders, files, uploads, and shares endpoints.
`tenant_id`	string (UUID)	The tenant that owns this Space. Always your own tenant.
`name`	string	A human-readable label for the Space (free text, 1–200 characters). Not used as a path — object keys are derived internally from the tenant and Space UUIDs, not the name.
`app`	string	The originating Fluid product namespace. Native FluidCloud Spaces report the default app namespace; partner-created Spaces use this for per-product grouping (see `app` below).
`created_at`	string (ISO-8601 UTC)	When the Space was created.
`updated_at`	string (ISO-8601 UTC)	When the Space was last modified.

Example

json

{
  "id": "8b1c4f2e-3d9a-4a6b-9c0e-1f2a3b4c5d6e",
  "tenant_id": "bb4da085-1d97-4780-9c0e-707c8b1b0000",
  "name": "My files",
  "app": "fluidcloud",
  "created_at": "2026-06-23T10:15:00Z",
  "updated_at": "2026-06-23T10:15:00Z"
}

List Spaces

GET /spaces

Lists every Space in your tenant, oldest first — so your default "My files" Space leads the list. The response is never empty for a valid key: on a brand-new account, calling this endpoint also provisions your tenant and its default Space, so you always receive a real space_id to work with. A good first call when bootstrapping an integration.

Required scope: spaces:read

Query parameters

Name	In	Type	Required	Description
`app`	query	string	No	Filter to one Fluid product's Spaces (for example, `fluidtalk`). Omit to list all of your Spaces regardless of product namespace. See `app` below.

Returns

A JSON array of SpaceOut objects, ordered by created_at then name.

Status codes

Code	Meaning
`200`	Spaces returned (array may contain one or more entries).
`401`	Missing, invalid, or revoked API key.
`403`	`insufficient_scope` (key lacks `spaces:read`) or `feature_not_in_plan` (subscription does not include API access).
`429`	Rate limited. Retry after the `Retry-After` header.

See Errors for the full error model.

Examples

curl

bash

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

Filter to one product's Spaces:

bash

curl "https://api-cloud.fluidvip.com/api/v1/spaces?app=fluidtalk" \
  -H "X-API-Key: fck_live_..."

Python (pip install fluidcloud)

python

from fluidcloud import FluidCloud

fc = FluidCloud(api_key="fck_live_...")

# All Spaces in your tenant (oldest first)
spaces = fc.spaces.list()
for space in spaces:
    print(space.id, space.name, space.app)

# Filter to one product's Spaces
talk_spaces = fc.spaces.list(app="fluidtalk")

TypeScript (npm install fluidcloud)

import { FluidCloud } from "fluidcloud";

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

// All Spaces in your tenant (oldest first)
const spaces = await fc.spaces.list();
for (const space of spaces) {
  console.log(space.id, space.name, space.app);
}

// Filter to one product's Spaces
const talkSpaces = await fc.spaces.list({ app: "fluidtalk" });

Create a Space

POST /spaces

Creates a new Space within your tenant. Use this when you want to keep separate workloads isolated — most integrations are fine with the default Space and never need to call this.

Required scope: spaces:write

Request body

Field	Type	Required	Description
`name`	string	Yes	Display label for the Space. 1–200 characters; leading/trailing whitespace is trimmed. Free text — it is a label only, not a path.
`app`	string	No	Product namespace to create the Space under. Omit for the native FluidCloud namespace. See `app` below.

Returns

The newly created SpaceOut object.

Status codes

Code	Meaning
`201`	Space created.
`400`	Bad input — for example, an empty `name` or a `name` longer than 200 characters.
`401`	Missing, invalid, or revoked API key.
`403`	`insufficient_scope` (key lacks `spaces:write`) or `feature_not_in_plan` (subscription does not include API access).
`422`	Validation error (malformed body).
`429`	Rate limited. Retry after the `Retry-After` header.

Examples

curl

bash

curl -X POST https://api-cloud.fluidvip.com/api/v1/spaces \
  -H "X-API-Key: fck_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Render outputs"}'

With a product namespace:

bash

curl -X POST https://api-cloud.fluidvip.com/api/v1/spaces \
  -H "X-API-Key: fck_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Render outputs", "app": "fluidtalk"}'

Python

python

from fluidcloud import FluidCloud

fc = FluidCloud(api_key="fck_live_...")

space = fc.spaces.create(name="Render outputs")
print(space.id)  # use this space_id for folders/files/uploads/shares

# Optionally namespace it to a product
space = fc.spaces.create(name="Render outputs", app="fluidtalk")

TypeScript

import { FluidCloud } from "fluidcloud";

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

const space = await fc.spaces.create({ name: "Render outputs" });
console.log(space.id); // use this space_id for folders/files/uploads/shares

// Optionally namespace it to a product
const namespaced = await fc.spaces.create({
  name: "Render outputs",
  app: "fluidtalk",
});

Per-product namespacing: the `app` field

The optional app field on both endpoints lets you group Spaces by an originating Fluid product. It is a convenience for partners who serve multiple products from one tenant:

On create, app tags the Space with a namespace. Omit it and the Space is created in the native FluidCloud namespace.
On list, passing ?app=<name> filters the response to only that namespace's Spaces. Omit it to list all Spaces in your tenant.

The value is normalized (trimmed and lower-cased) server-side, so FluidTalk and fluidtalk resolve to the same namespace. The app field never affects where bytes are stored — object keys are always derived from the tenant and Space UUIDs.

Tenant isolation

Every Spaces query is scoped to your own tenant. You only ever see and create Spaces that belong to you. Space IDs from another tenant are not visible to your key — endpoints that take a space_id (folders, files, uploads, shares) return 404 for an ID outside your tenant, never 403. See Security for the full isolation model.

Not available to API keys: there are no endpoints to rename, delete, or transfer a Space via the partner API. Spaces are managed in the FluidCloud dashboard. The API surface is list and create only.

Next steps

Organizing files — folders and structure within a Space.
Uploading files — put your first object into a Space.
Folders reference — create and list folders inside a Space.
Files reference — work with files, including lookup by your own client_key.
Quota & usage — read your storage pool and share-link limits.
Reference index — all endpoints at a glance.

API Reference — Spaces ​

The SpaceOut object ​

Example ​

List Spaces ​

Query parameters ​

Returns ​

Status codes ​

Examples ​

Create a Space ​

Request body ​

Returns ​

Status codes ​

Examples ​

Per-product namespacing: the app field ​

Tenant isolation ​

Next steps ​

API Reference — Spaces

The `SpaceOut` object

Example

List Spaces

Query parameters

Returns

Status codes

Examples

Create a Space

Request body

Returns

Status codes

Examples

Per-product namespacing: the `app` field

Tenant isolation

Next steps