Projects
Keep your application's Tables, access, storage, and history together in one workspace.
A Project is where your application's data lives in Spiral. Every Table, Location, Enrichment, and Vector Index belongs to exactly one Project, and the Project decides who can use them, which bucket stores them, and keeps the history of every change. Each Project belongs to one Organization.
Most teams start with one Project, then add another when some data needs a
separate set of people or a separate history. The examples in these docs use
a Project with the ID demo, which holds a frames Table of camera frames
from a robot, the nightly-curation workload that writes to it, and the
Workers that maintain it. A team might keep demo open to everyone for
experiments, next to a production Project that only its ingest pipeline can
write.
What a Project holds
| Part | Purpose | Service |
|---|---|---|
| Resources | Named Tables, Locations, Enrichments, and Vector Indexes. | Catalog |
| Access grants | Which people and workloads can use the Project, and how. | Authorization |
| Workloads | Identities for pipelines and services, such as nightly-curation. | Workloads |
| Storage | The bucket that holds the Project's data. | Storage |
| Tasks and Workers | Background operations and the compute that runs them. | Tasks |
| History | A commit for every change, and branches and tags. | Catalog |
Two Projects in the same Organization share none of these. Each has its own
names, grants, storage, and history, so a frames Table can exist in two
Projects without one affecting the other, and a grant in one Project gives
nothing in the other.
Project IDs
A Project ID is the Project's name in every API path and
address, such as demo/frames. Spiral generates
the ID when you create the Project:
- Without a prefix, the ID is a random readable name, such as
brave-otter-123456. - With a prefix, Spiral appends a hyphen and six digits, so the prefix
roboticsgives an ID such asrobotics-482913.
A prefix contains lowercase ASCII letters, digits, and hyphens, and is at most
25 characters long. You cannot rename a Project ID, so put a display name in
the description. In examples, replace demo with your own Project ID.
Who gets access
The person who creates a Project becomes its admin, and Spiral adds default
grants for each Organization role. Organization membership alone gives no
access to a Project; see
Access to a new Project
for the defaults and how to restrict them.
Storage
A new Project uses its Organization's default storage. Spiral records that choice when it creates the Project, so a later change to the Organization default does not move existing Projects. If the Organization has no storage default, you cannot create a Project until an owner configures one. A Project administrator can choose a different Volume for new Tables in the Project's settings. See Storage.
History
Every change to a Project's Tables and other Resources is a commit in the Project's history. Normal reads and writes use the latest state, so you only think about history when you need a fixed or separate state: reading a training set exactly as it was, or trying a change on a branch. See Commits and branches.
Where it runs
Spiral hosts the Project API at https://api.spiraldb.dev/api/projects. It
records Projects and their initial grants; your Table data stays in the
Project's bucket and never passes through it. See
Architecture.
HTTP API versions
Use /api/projects for new HTTP integrations. Requests and responses use
camelCase field names and the shared error format.
List operations return nextPageToken; pass it unchanged with the same page size
and credential until it is absent. Lists reflect current state on each page.
Existing SDKs and the CLI continue to use /v1/projects, which remains
available with its existing field names and responses.