Storage API

The Storage API is the primary interface for reading and writing project content. It persists every first-class artifact of a Diafunc project — entities, links, events, tables, notebooks — and supports structural operations such as branching, forking, merging, and bulk import and export. It is the workhorse behind most programmatic integrations with the platform.

All Storage API endpoints are served under /api/v1/storage.

Read operations on entities, tables, notebooks, and their relationships require the storage:read scope; any mutation of project content requires storage:write. Branch and fork operations additionally honor the caller's project-level permissions.

See Authentication for the shared token and error model.

The Storage API is organized around the following resource groups:

Entities — create, read, update, and delete entities of any kind (functions, tables, notebooks, texts, and other typed entities); look up entities by id, list them as sets, navigate linked entities, and find entities matching structured criteria.

Links and events — connect entities through typed links and record events on entities; traverse the graph of linked entities to navigate related content.

Tables — read tabular data, import rows from uploaded files, and export full tables or filtered slices.

Notebooks — read and update notebooks and their sections as first-class interactive documents.

Branches and forks — create branches of entities or of an entire project, fork a project into a new independent copy, and merge changes back into the source branch.

Import and export — bulk-import content into a project from an archive and export the project state for backup or replication.

Tasks and transactions — group multiple mutations into a transaction and observe long-running background tasks spawned by heavyweight operations.

Project search — search within a single project using lightweight queries tailored to project-local lookups.

Ingesting an external dataset — create a table entity, import the dataset rows from an uploaded file, and link the table to related entities within the project so it is discoverable alongside the rest of the project graph.

Pushing computed entities back into a project — open a transaction, create or update the entities that represent the computation result, commit the transaction, and verify the resulting entity set.

Replicating project state — export a project as an archive, import it into a target environment, and reconcile any environment-specific settings afterwards.

Branching for experimentation — branch the project, make exploratory changes on the branch, and merge back only the changes worth keeping.