Spaces

Most novem resources are built around one kind of content: a plot holds data, a repo holds git history. A space holds files: any type, any folder structure, up to your plan's quota. Think of it as a cloud folder that lives next to your repos and jobs under the code surface.

Spaces are designed to be the storage layer for the rest of the platform. Mountable folders for job containers and sync clients are on the roadmap, but today they are a clean HTTP file API: upload, download, list, move, delete, share.

Structure

Like every novem resource, a space is a small folder hierarchy:

project_data              => Space name
├── content               => Your files and folders live here
│   └── ...               => Arbitrary nesting, up to 64 levels deep
├── changes               => Change journal (for sync clients)
├── config
│   └── access
│       ├── ssh           => Reserved for upcoming access protocols
│       └── web           => Reserved for upcoming access protocols
├── description           => Description (meta)
├── name                  => Display name (meta)
├── summary               => Short summary (meta)
├── shortname             => Auto-generated short id
├── url                   => The space's URL
├── shared                => Who can see / edit the space
└── tags                  => Tags

Everything outside content/ works exactly like the equivalent files on repos and jobs. The interesting part is content/, a real file tree with its own set of verbs, documented in full in the spaces API reference.

Creating a space

A space is created with an HTTP PUT to https://api.novem.io/v1/code/spaces/SPACE_NAME:

novem --put /code/spaces/project_data

DELETE on the same path removes the space, and PATCH renames it: the standard novem resource verbs.

Working with files

Files live under content/. The verbs follow the novem convention: PUT creates a container (a folder), POST writes content (a file's bytes):

# make a folder
novem --put /code/spaces/project_data/content/reports

# upload a (text) file; parent folders are created automatically
novem --post /code/spaces/project_data/content/reports/q1.csv "$(cat q1.csv)"

# read it back
novem --get /code/spaces/project_data/content/reports/q1.csv

A GET on a folder (or on content itself) returns a JSON listing in the same shape as every other novem directory. PATCH renames or moves a file or a whole folder tree; moves are instant regardless of size, since blobs are stored by id, not by path. DELETE removes a file; deleting a non-empty folder requires an explicit ?recursive=true.

Every file carries an ETag that changes on every write, and the write verbs honor If-Match / If-None-Match preconditions, so concurrent editors and scripts can detect conflicts instead of silently overwriting each other. The full verb-by-verb behavior, including status codes and conditional headers, is in the spaces API reference.

File names

The store is case-preserving but case-insensitive: Report.csv keeps its casing, but you cannot create report.csv next to it. Names may use spaces, unicode and mixed case; a small set of characters that cannot exist on every platform (< > : " / \ | ? *, control characters, Windows reserved names like CON, trailing dots or spaces) is rejected at write time. Paths can nest up to 64 levels and 1024 bytes.

Tracking changes

Every mutation in a space (create, update, move, delete) is recorded in an append-only journal with a per-space sequence number. GET .../changes?since=N returns everything that happened after cursor N, including delete tombstones and both sides of moves. This is what future sync clients will be built on, and it's available to your own tooling today:

novem --get "/code/spaces/project_data/changes?since=0"

Sharing

A space is shared like any other novem resource, by creating entries under shared/. The grantee's group role determines what they can do:

• read access — list and download everything under content/, and read the changes journal.
• write access — full control of content/: create, modify, move and delete. Files written by a collaborator count against the owner's quota.

Spaces cannot be made public yet; content is only ever visible to the owner and explicit shares.

Quotas

Space storage is tied to your subscription plan:

Writes that would exceed a limit are rejected with 413. A space can hold at most 1,000,000 files and folders.

Next steps

• Spaces API reference — every endpoint, verb and status code on the spaces surface.
• Jobs and Repos — the neighbours under the code surface.