spaces

name: spaces
description: create and manage spaces, configure access control, set up custom domains, and understand the identity model

a space is the top-level container in sublimated. every space has a unique slug, an owner, and contains items (files and folders) organized as an ltree hierarchy.

creating a space

POST https://api.sublimated.com/v1/spaces
{ "slug": "my-project" }

or via git — pushing to a new slug auto-creates the space.

space types

personal — default, owned by a user
org — organization space (shared ownership)

visibility

private — only authenticated users with access rules can read
public — anyone can clone/read, writes still require auth

set via API or .sbl/access.yml.

access control

access is configured per-space via .sbl/access.yml, pushed through git:

rules:
  - identifier: alice
    role: editor
  - identifier: "*@company.com"
    role: viewer
  - identifier: "*"
    role: viewer
    paths: ["docs"]

roles (highest to lowest privilege): owner, admin, editor, commenter, viewer.

rules support:

username: alice
email: bob@example.com
domain wildcard: *@company.com
public wildcard: * (anonymous access)
path scoping: restrict access to specific folders

access config is parsed, merged hierarchically (deeper folders override parents), and cached in KV for fast lookups.

scoped tokens

create tokens with restricted permissions:

POST https://api.sublimated.com/v1/spaces/{slug}/tokens
{
  "label": "CI deploy",
  "permissions": ["read", "write"],
  "pathScope": ["src"],
  "branchPatterns": ["refs/heads/main"],
  "expiresIn": "30d"
}

token prefix: sk_. use as Bearer token or git password.

identity model (progressive trust)

level 0: anonymous — auto-created on first interaction, gets personal space + scoped token
level 1: email verified
level 2: identity linked (GitHub, etc.)
level 3: full account
level 4: system only (internal service account)

anonymous users can push to their own space immediately — no signup friction.

item hierarchy

items are organized as paths: slug/folder/subfolder/file.md

every folder is independently clonable as a git repo
items track: name, type, path, contentHash, sizeBytes, currentVersion
folders are implicit from paths but also stored as items (for metadata, permissions)

space configuration

.sbl/config.yml in the space root configures:

build settings (which branches trigger Docker builds)
custom domain mappings
default visibility
feature flags

pushed via git, parsed on push, takes effect immediately.