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
referrals
This user’s referral link, code, and rewards summary
Attribute the current user as referred by a code (first-touch, one-time, best-effort)
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)
Detect select↔relation drift for a parent record (MN-286): child records whose select-field label matches the parent’s title but aren’t linked here
Bulk-link every currently-drifted child record to the parent (MN-286)
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
Download the whole workspace as a .zip (schema, records, relations, attachments)
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 (90-day retention, MN-264)
Dry-run a rule against one record
Rotate a webhook_received rule's token + secret — the old URL 404s immediately
The most recent payload a webhook_received rule received (for token mapping)
hooks
Inbound webhook receiver for a webhook_received automation rule
approvals
List approvals for this workspace, optionally filtered by status
Approve a pending approval — enqueues the gated action from its frozen snapshot (human-only)
Reject a pending approval — the gated action never runs (human-only)
integrations
Integrations directory — registry metadata + per-integration connected status
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
Disconnect GitHub — clears token, App installation and watched repos
Reviews sidebar: PRs in one bucket (needs_review/authored/participating)
PR detail: metadata, changed files (with patch), checks
Cached inline review comments for this PR
Post a new inline (file/line-anchored) review comment
Reply within an existing comment thread
React to a review comment
Poll GitHub for review comments and refresh the local cache
Approve / Request changes / Comment — submits a GitHub PR review
Code & reviews settings (defaulted)
Save Code & reviews settings
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
Disconnect Linear — clears the stored API key and team-key filter
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
Disconnect Slack — clears the stored bot token, webhook and default channel
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
MN-264: manually close the circuit breaker before its cool-down elapses
Begin an OAuth2 connect (redirects to the provider)
OAuth2 callback — verifies state, exchanges the code, seals the tokens
Resend bounce/complaint webhook for one connection — signature-verified, unauthenticated by design
google-calendar
List writable calendars for a Calendar connection
List database-to-calendar sync bindings
Bind a database and date fields to a Google Calendar
Push all current dated records to Google Calendar now
Remove a calendar binding (existing Google events remain)
runs
Monthly automation-run usage vs the plan allowance, with a pace projection
Every automation run in the workspace, newest first — rule runs today (source syncs pending #239)
Run detail: trigger context, per-action attempts/artifacts, approval linkage
Re-run one failed action from this run with its original frozen inputs
sources
List the sources syncing into this database
Configure a new source: provider + connection + field mapping + schedule
The source provider catalog — what can be synced, and its config shape
#341: list the YouTube channels a Google connection owns, for the channel picker
MN-262: preview a provider's field keys before creating a source (point-and-click mapping)
Stop syncing — leaves every record the source created intact
Reconfigure a source
Run one sync cycle immediately, ignoring the schedule gate
Recent sync runs for one source (fetched/created/updated/errors)
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
Delegate a record to an agent — it runs with the record as context and posts progress back as a comment
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
skills
List skills visible to the caller: their own, plus every shared one
Create a skill — personal by default; pass visibility: "shared" to publish it to the workspace
Starter scaffolds for the "new skill" flow (AC #2, not-from-scratch)
Read one skill
Delete a skill — owner-only
Edit a skill — owner-only, even if it's shared
Export a skill as portable instructions (Markdown / Claude Skill SKILL.md / ChatGPT)
Run a skill manually; returns its step log (no model invoked yet)
templates
Available starter templates
Install a template (packs create a space; database templates take space_id and may be renamed)
Remove exactly the sample records templates created
packs
Export a workspace slice as a pack manifest; creates nothing
Install a pack manifest; idempotent
Preview what installing a manifest would do; creates nothing
List tracked pack installs in this workspace
Uninstall a tracked pack install
List this workspace's marketplace submissions
Submit a pack manifest to the marketplace for review
The built-in Business Pack gallery
One built-in pack, manifest included
Browse published Community Marketplace packs
One published pack — manifest, changelog, versions
public
The built-in Business Pack gallery — public, pre-signup
One built-in pack — public, pre-signup preview
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
favorites
Current user's favorites in this workspace (resolved titles)
Star a record or database
Unstar
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.
#300/MN-216c — agent runs across every workspace: workspace, agent, status, run_class, trigger, started/finished. Read-only.
#300/MN-216c — kill switch: cancel a queued/running/waiting-approval run in any workspace. A status flip to Canceled only — no other side effects.
MN-220 — pack marketplace submissions awaiting (or having had) review
MN-220 — approve or reject a pending pack submission
#304 — set a workspace plan (comp/Enterprise grant); requires a reason; never touches live Stripe
#304 — set entitlement overrides (e.g. maxWorkspaces) for a workspace; requires a reason
#304 — clear a workspace's entitlement overrides; requires a reason
#304 — current plan + overrides + audit trail for a workspace
GitHub
Select theme
Dark
Light
Auto
Disconnect Linear — clears the stored API key and team-key filter
POST
/api/v1/workspaces/{ws}/integrations/linear/disconnect
Responses
Section titled “Responses”
201
Section titled “201”
