Skip to content
StoryOS Docs
Search
Ctrl
K
Cancel
GitHub
Select theme
Dark
Light
Auto
Getting Started
What is StoryOS
Quickstart
Core concepts
Guides
Share a portal with a client
Self-hosting
Overview
Configuration
Attachments (S3/MinIO)
Backup & upgrade
Concepts
Databases & fields
Relations
Lookups & rollups
Formulas
Views
Automations & buttons
Access & roles
Data model reference
Use with AI (MCP)
Overview
Tools
Connect (Claude Code & Desktop)
Hosted MCP (HTTP + PAT)
OAuth connector
API
Overview
Authentication
Querying records
Conventions
Build an MCP server
API Reference
Overview
App
AppController_health
system
Liveness + database connectivity check
auth
Current authenticated user
Enabled auth providers (google appears only when configured)
workspaces
List workspaces I belong to
Create a workspace (creator becomes admin)
Workspace details
Update workspace (admin)
List spaces (guests: scoped spaces only)
Create a space
Delete a space (creator on this space, or admin)
Rename/reorder a space
List active members
Remove a member (admin)
Change a member role / guest scoping (admin)
List pending invites (admin)
Invite by email; guests require space_ids (admin)
Revoke a pending invite (admin)
Accept an invite by token (must match your email)
Live Getting-Started state, derived from what actually exists (MN-213)
spaces
Folders in a space (MN-096)
Create a folder in a space
Delete a folder (its items fall back to the space root)
Rename / re-icon / reorder a folder
billing
Plan, status, usage vs limits, and whether billing is configured
Create a Stripe Checkout session for a plan; returns a redirect URL
Create a Stripe Customer Portal session; returns a redirect URL
Start the 30-day Pro trial (no card, no Stripe subscription yet)
Stripe webhook receiver — signature-verified, unauthenticated by design
Current AI credit balance, auto-reload config, and card-on-file status
Create a one-time Checkout session to add credits; returns a redirect URL
Configure (or disable) auto-reload
access
List access grants (optionally for one user)
Grant a role on a space or database (upserts per scope)
Revoke a grant
databases
List databases (guests: scoped spaces only)
Create a database (auto: title field, system fields, default view)
Database with live fields and views (schema introspection)
Hard delete (creator on this database, or admin) — body.confirm must equal the name
Rename / re-icon (creator); moving between spaces stays member+
fields
Add a field (select types accept initial options)
Soft-delete a field (returns records_with_value)
Rename / reconfigure / reorder a field
How many live records carry a value for this field
Convert field type within the compatibility matrix (dry_run supported)
Add a select option
Delete an option — 409 with usage count unless confirm: true
Rename / recolor / reorder an option (O(1), ids are stable)
records
List records (manual order, optional q= title search, cursor)
Create a record ({values} keyed by field api_name)
Query records: filter AST + sorts + q + keyset cursor (the workhorse)
Create up to 100 records atomically
Apply one values patch to up to 200 records (partial failures reported)
Soft-delete up to 200 records
Restore up to 200 records from trash
Soft-deleted records (30-day retention)
Resolve a record by its public per-database number (MN-087)
Single record, values keyed by api_name
Soft delete (restorable for 30 days)
Merge-update values (null clears a field)
Duplicate: clone values + description + single/m2m links (not owned collections)
Atomic move: fractional reposition + optional value patch (kanban drop)
Restore from trash
mentions
Records whose document mentions this one ("Mentioned in") — MN-205
notifications
My notifications, newest first (filter by type; archived view)
Unread badge count
Mark one notification read
Mark everything read
Archive one notification (MN-073)
Restore an archived notification to the inbox
relations
Create a relation — needs creator on BOTH databases
Relation config + comparable fields for the auto-link editor
Delete a relation, both its fields, and all links (confirm: true)
Set or clear a relation’s auto-link rules (MN-085)
Run auto-link now across existing records — returns a summary (MN-085)
Linked records for a relation field ({id, title} chips)
Replace all links for this record on this field
Add links (409 when one-to-many already linked)
Remove specific links
views
Create a saved view (config validated against live fields)
Delete a view (409 on the last one)
Rename / reconfigure / reorder a view
Duplicate a view with its full config, placed next to the original
Set this view as the database's default (one default per database)
My personal filter override for this view (cleaned of dead field refs)
Set (or replace) my personal filter override for this view
Clear my personal filter override for this view
users
Set my avatar (multipart field "file", png/jpeg/webp ≤1MB)
Remove my avatar (falls back to initials)
Serve a user avatar (session required)
My preferences (defaults applied)
Update my preferences (deep-merged)
export
Download the database (or a view) as CSV
webhooks
List webhooks (secrets are never returned)
Create a webhook — the signing secret is returned once, here only
Delete a webhook
Update a webhook (url / events / enabled)
Recent delivery attempts — status, code, error, retries
documents
Record description (BlockNote JSON; version 0 = never written)
Write the description — 409 with current version on conflict
Standalone documents in a space (MN-095)
Create a standalone document in a space
A standalone document (BlockNote content + version)
Delete a standalone document
Update title/icon/content — 409 on version conflict
tokens
My personal access tokens (prefix only — plaintext is never stored)
Create a PAT — the token is shown ONCE in this response
Revoke a token (immediate)
comments
Comments, newest first
Comment (guests included); mentions extracted server-side
Delete own comment (admins: any)
Edit own comment
activity
Record activity trail, newest first (cursor)
record-versions
Record version history, newest first (cursor)
Restore the record to a previously captured version
attachments
Attachments on a record
Upload a file (multipart field "file"; size-capped)
Download the file (authz-checked, streamed)
Image thumbnail (404 for non-images)
Delete an attachment (object removed best-effort)
files
Upload an image for the editor (multipart "file"); returns { id, url }
Mint a signed, expiring download URL for a file (#201)
Revoke a file — kills its capability URL and any signed download URLs (#201)
Serve an uploaded editor image by id (capability URL, or access-checked under private-attachments mode)
Download a file via a signed, expiring URL (#201)
search
Search records by title + databases/spaces by name (grant-scoped)
Records across databases assigned to me or created by me (MN-049, #36)
Records the caller touched most recently (from activity)
import
Import CSV: fields "file", "mapping" (JSON), "dry_run" ("true"/"false")
buttons
Press a button field (editor+); actions run as the presser
automations
List rules
Create a rule (trigger + condition + actions)
Delete a rule
Update / enable / disable a rule
Run history (30-day retention)
Dry-run a rule against one record
integrations
GitHub config (token presence + repos + App connect state)
Save GitHub token, repos, webhook secret and/or state automation
Begin GitHub App OAuth connect (redirects to GitHub)
List the connected installation's repositories
Import/refresh Issues + PRs; auto-links PRs to issues by #N / branch refs
GitHub webhook receiver — HMAC-verified, unauthenticated by design
GitHub App OAuth callback — verifies state, captures installation id
Linear config (key presence + team keys)
Save Linear API key and/or team-key filter
Preview import counts per team — writes nothing
Import teams → spaces (Issues/Sprints/Projects), idempotent by Linear ID
Slack config (token/webhook presence + default channel)
Save Slack bot token, webhook URL and/or default channel
Send a test message using the saved Slack config, to verify the connection
connections
List connections (auth material is never returned)
Connect an api_key/smtp provider — runs a live health check before saving
The provider catalog — what can be connected, and how
Disconnect — hard-deletes the row, no tombstone
Re-run the provider health check against the stored credential
Begin an OAuth2 connect (redirects to the provider)
OAuth2 callback — verifies state, exchanges the code, seals the tokens
agents
Agents database summary, or { exists: false } if not provisioned
Provision the Agentic OS space + Agents/Runs/Agent Triggers databases (idempotent)
Bind an agent to a state on a database; returns the binding record
Run an agent manually; returns the Run record
Approve a run waiting for approval: apply the staged action
Reject a run waiting for approval: apply nothing, cancel it
Propose a plan from a plain-language goal; creates nothing
Build an approved plan through the ordinary CRUD services
templates
Available starter templates
Install a template (packs create a space; database templates take space_id)
Remove exactly the sample records templates created
packs
Export a workspace slice as a pack manifest; creates nothing
Install a pack manifest; idempotent
favorites
Current user's favorites in this workspace (resolved titles)
Star a record or database
Unstar
public
Public form definition (link/public access only)
Submit a public form → creates a record (anonymous)
Search candidate records for a public form relation field
Create a new linked record from a public form relation field
gdpr
Export everything held about this member (machine-readable JSON)
Erase/anonymize this member: wipe identity to a tombstone, destroy credentials, and remove workspace access. Comments and history are kept.
admin
Instance-wide counts: workspaces, users, records, plan mix, estimated MRR.
Every workspace on the instance: plan, seats, record count.
MN-194 — per-workspace cost and margin from real usage (hosted calls, storage, email; AI cost estimated pending MN-214r), plus blended margin per plan and the margin-floor flags.
GitHub
Select theme
Dark
Light
Auto
Provision the Agentic OS space + Agents/Runs/Agent Triggers databases (idempotent)
POST
/api/v1/workspaces/{ws}/agents/ensure
Responses
Section titled “Responses”
201
Section titled “201”
