Build with Substrio.
Everything you need to build, connect, and deploy apps with Substrio. Use HTTP, the CLI, or MCP.
Your first app
Get a key, create an app, push a function, try it in a sandbox, and take it live.
Start BuildingStart with HTTP, CLI, or MCP
Create an app key, deploy a function, and call it using HTTP, the CLI, or MCP.
Open the QuickstartConnect your AI agent
Your agent builds and deploys your app over MCP or plain HTTP, with the same results.
Connect Your AgentBring an existing project
Move an existing backend, including its data, sign-in, routes, jobs, mail, files, secrets, and tests.
Bring Your ProjectMake your first API call.
Get an app key, connect to your app, and make your first request. Your key is at /keys. Set SUBSTRIO_URL and SUBSTRIO_KEY before making the request. Operations are available over HTTP, MCP, and the CLI.
curl -s "$SUBSTRIO_URL/v1/_whoami" \
-H "Authorization: Bearer $SUBSTRIO_KEY"Getting started walks from nothing to a deployed function. MCP connects an agent.
Getting started
- Getting startedSign in, create an app, and push a function. You can test it in a sandbox before making it live.
- QuickstartUse HTTP, the CLI, or MCP to create and query data, then deploy and call a function.
- InstallInstall the CLI, SDK, and client packages from npm.
- Project filesDeclare functions, collections, roles, and auth providers as files so the sandbox and production build from the same source.
- Bring your projectMove an existing backend to substrio in order: data, sign-in, routes, jobs, mail, files, secrets, tests, deploy.
Concepts
- Accounts and appsEverything you deploy belongs to an app, and every app belongs to an account.
- VersioningAn app's versions share one history. You can push a commit, move a branch or tag, merge, compare changes, and collect unused objects with Git-like commands.
- Test hosts and root domainsBind a sandbox to a host, test a version there, and promote it from that host to live.
- Plans and limitsLimits apply to function calls, apps, and keys. An account's plan sets app limits, and you can add rate-limit rules.
- GlossaryThis glossary defines terms used throughout the documentation and links to further details.
Best practices
- Data modelingPick collections and ids, declare schemas and unique fields, index for the queries you run, and choose KV, SQL, the ledger or files when a collection is the wrong shape.
- KeysPick the right kind of key for the caller, rotate it without downtime, and never let one reach function source.
- Versions and test hostsPush a version, test it in a sandbox or on a test host, and promote it. If a change goes wrong, you can roll it back.
- Plan limitsRead your limits and usage before you reach a limit, and learn what each error means.
- Errors and retriesBranch on the typed error code, retry only what the envelope says is safe, and keep a retried write from running twice.
- Security and permissionsGate collections with security rules, gate function routes by sign-in, require a verified email or 2FA where it matters, and keep secrets and outbound calls scoped.
MCP and agents
- MCPConnect Claude Code, Claude Desktop, Cursor, or another MCP client to an app's tools without writing an MCP server.
- Agents over plain HTTPSEvery MCP tool is also available through HTTPS under the same name, with the same credential and response.
- Let your users' agents use your appYour users can connect AI agents to your app's MCP endpoint using their credentials. Each agent calls your tools with the permissions of the user who connected it.
- Agent sessionsAn agent session lets an AI agent act for a person in one account.
- Building on substrioBuild and ship an app on substrio as an AI agent, over MCP or plain HTTP with the same results.
- Agent workflowAn AI agent with an app key can discover the platform, write and test a function in dev, promote it, and roll it back.
- Agent shellRun shell commands over your app's files, with pipes and heredocs.
- Agent function toolingUse the typed HTTP endpoints to read, search, check, and edit a deployed function's source and environment in small, bounded calls.
Capabilities
- Schemas, namespaces and viewsDeclare a collection, set its schema, inspect its namespaces, and build materialized or live views over its data.
- Query languageFilter, sort, page, and aggregate a collection's documents with a JSON query.
- Chain queries over the APIRun the filter, sort, join, and aggregate plan of a JavaScript chain as one typed JSON request.
- SQL over the APIRun parameterized SQL over HTTP or MCP against an app's data, with batched transactions and schema introspection.
- SQL dialectSubstrio supports the SQLite and MySQL SQL dialects.
- Key-value storesStore and read bytes by key from a function. The API also supports typed numeric counters, prefix scans, and a byte cursor.
- FilesStore, list, download, change, move, and delete files by path over HTTP or from a function. Public files can be served without a key.
- RealtimeOpen a WebSocket to a collection or one of its fields and receive an event the instant a write commits.
- Queues and background jobsSend a message from a function to a named queue and have another function consume it in the background.
- SchedulesRun a deployed function on a cron schedule, with retries, catch-up and a run history.
- Reliable deliveryWebhooks, document triggers, and cron runs are stored before the first delivery attempt.
- SecretsWrite, list and delete the named values your app's functions read as environment variables.
- App archivesDownload your app as an archive. You can restore the archive as a backup or read it as an export.
- Users and authSign users up, sign them in with a token, and gate routes and records by role, permission, or ownership.
- PermissionsSubstrio uses three permission layers for requests from your app's users and public callers.
- EmailSend email from a function over SMTP, and configure the function that sends your app's sign-in, verification, and invite emails.
- LedgerPost signed entries in minor units against a kind, party, and currency. Read balances maintained as entries change.
- Multi-document transactionsRun insert, update and delete operations across collections in one call, all committed or all rolled back.
- Vectors, geo and RAG searchIndex a collection's vector, geo, or sparse fields, then query them with k-nearest, bounding-box, and RAG search operators.
- App dashboardsAn app can declare an admin dashboard for members of its account and customers of a featured app.
- Graph storage and analyticsStore directed edges between integer node ids under a label. You can read neighbors and degrees and run graph analytics over them.
- Calls and reads between appsCall a function or read a query that another app offers, with no HTTP and no shared code.
- Featured appsA featured app, or jet, is a Substrio app available to apps in every account.
- Custom domainsAttach, list, and detach custom domains for your app. The app remains available on its default subdomain as well.
- Static sitesDeploy a directory as a release and serve it with clean URLs, a real 404 page, and cache headers.
JavaScript runtime
- Function runtimeJavaScript functions have database, platform service, environment, and fetch globals in scope.
- Rust functionsA function can be written in Rust. This guide covers when to use Rust, the available calls, and how to deploy and test a function.
- Wasm functions (Rust)A function can be written in Rust and deployed from source.
- Writing records from RustA Rust function writes documents through the same calls a JavaScript function uses.
- The ledger and files in RustA Rust function can use the same ledger and file operations as a JavaScript function.
- Services and gates in RustA Rust function can use the same platform services, database guards, and gates as a JavaScript function.
- Rust: objects, fetch, timers, crypto and the clockA Rust function can call a durable object, fetch a URL, set timers, read random bytes, and read the clock.
- JavaScript, Lua and cloud functionsDeploy JavaScript functions that run next to your app's data, and run Lua scripts over its Redis-compatible keys.
- Cloud functionsDeploy server-side JavaScript functions that run next to your data, with direct access to collections, SQL, and key-value stores.
- Runtime API referenceFind the globals, types, modules, and signatures available to a function in the declarations served by the server.
- ServicesCall your app's API and other functions directly, and access files, KV, graph data, and authentication.
- Collections and chainsRead, filter, sort, join, and write JSON documents with synchronous calls on a collection.
- Chain referenceLook up chain method signatures, arguments, return values, errors, and runnable examples on one page.
- Records and query resultsRead a row from a collection as a live record, assign its fields, and write them back with one call.
- SQLRun synchronous SQL with typed parameters, prepared statements, and transactions.
- Durable objectsExport a class as a durable object. Each id has one live instance, calls to that instance are serialized, and its state is stored in the app's database.
- Concurrency and async callsRun asynchronous work inside a function call and understand which state concurrent calls share.
- Errors and logsRead recorded errors and function console output, and set up log drains and alerts.
- Function errorsWhen a function throws, Substrio records a typed error with parsed stack frames. You can read it by request, function, or revision.
HTTP API
- HTTP APICall operations over HTTP. Select an app by host or header, send a bearer key, and receive typed JSON.
- API contractsCall an operation over HTTP, MCP, or the CLI with the same arguments and receive the same result and errors.
- Functions operationsWrite, check, run, and inspect app functions, their source, history, and environment variables; invoke and evaluate code.
- Deploy operationsPush a version, check it, try it in a sandbox, make it live, or roll it back.
- Data operationsManage collections, records, key-value pairs, graph edges, and views; import and export data.
- Query operationsRead data with SQL, typed chain queries, counts, and aggregates.
- Schema operationsManage collection schemas, SQL indexes and their state, namespaces, and security rules.
- Schedule operationsManage cron schedules and their history, collection triggers, webhooks, and background jobs.
- Files operationsManage static site releases, uploaded files, and installed tools.
- Config operationsManage secrets, tenant settings, function environment variables, and the MCP tool manifest.
- Access operationsManage end users, roles, authentication providers, rate limits, and agent tokens.
- Realtime operationsPublish live events, stream them to clients, and read their counters.
- Observability operationsRead function logs, thrown errors, usage, and limits.
- Backup operationsCreate and restore backups, clone into another app, and export an app.
- AI operationsUse search, retrieval, and threads, and configure the app's AI.
- Account operationsManage an account's members, keys, and apps.
- Platform operationsRead health, documentation, and the app overview; manage keys, limits, and domains.
- ErrorsA failed call returns a JSON envelope with a stable code, an HTTP status, and a hint for the next step.