Skip to content
StoryOS Docs
Search
Ctrl
K
Cancel
GitHub
Select theme
Dark
Light
Auto
Getting Started
What is StoryOS
Quickstart
Core concepts
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
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)
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
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 — body.confirm must equal the database 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
relations
Create a relation — needs creator on BOTH databases
Delete a relation, both its fields, and all links (confirm: true)
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
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)
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 }
Serve an uploaded editor image by id (capability URL)
users
Set my avatar (multipart field "file", png/jpeg/webp ≤1MB)
Remove my avatar (falls back to initials)
Serve a user avatar (session required)
search
Search records by title + databases/spaces by name (grant-scoped)
Records across databases where any person field contains me (MN-049)
Records the caller touched most recently (from activity)
notifications
My notifications, newest first
Unread badge count
Mark one notification read
Mark everything read
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)
Save GitHub token and/or repo list
Import/refresh Issues + PRs; auto-links PRs to issues by #N / branch refs
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
templates
Available starter templates
Install a template (packs create a space; database templates take space_id)
Remove exactly the sample records templates created
access
List access grants (optionally for one user)
Grant a role on a space or database (upserts per scope)
Revoke a grant
favorites
Current user's favorites in this workspace (resolved titles)
Star a record or database
Unstar
GitHub
Select theme
Dark
Light
Auto
Current user's favorites in this workspace (resolved titles)
GET
/api/v1/workspaces/{ws}/favorites
Responses
Section titled “Responses”
200
Section titled “200”
