Routes with policies
Five routes per resource, each with the policy you wrote: public, authenticated, owner, admin, or a mix like owner | admin. calm routes lists them with the file they came from.
At a glance
- version
- 2.0 beta
- licence
- MIT
- runs on
- Node.js 22, Express 5, MongoDB
- runtime dependencies
- express and mongoose
- framework in your repo
- About 8,600 lines
- framework tests
- 443, on real MongoDB
- official blocks
- 35, added as source
- tools for coding agents
- 29, over MCP
Why it copies itself into your project
Most frameworks live in node_modules, and you meet their internals for the first time when something breaks late at night. CalmAPI goes the other way. npm create calmapi puts the framework in a calm/ folder in your repository: commented JavaScript you can read, step through in a debugger and change.
Owning the code usually means giving up upgrades. CalmAPI keeps a calm.lock file with a hash of every framework file, so calm upgrade replaces the files you never touched and three-way merges the ones you did. Conflicts get ordinary conflict markers, like any other merge.
What one resource file gives you
Fields and access rules live in one file. CalmAPI turns them into the Mongoose schema and everything around it. Business logic goes in a service, custom endpoints in a routes file, and both are optional.
Validation before your code runs
Unknown, read-only and hidden fields are rejected with a 422. Query operators are allowlisted, so x[$ne]=1 is a 400, and page size is capped.
Responses filtered per caller
A field marked visibleTo('owner | admin') never reaches anyone else, and owner-scoped lists only return the caller's own records.
OpenAPI from the same file
The OpenAPI 3.1 document is generated from the resource itself, so the docs cannot drift from the code. calm client turns it into a typed client for your web or mobile app.
Accounts done properly
Opaque sessions stored as SHA-256 hashes, scrypt passwords, lockout after 5 failed logins in 15 minutes, and two-factor login through the totp block.
Features as source code
Blocks like oauth, payments-stripe, jobs, webhooks and push-fcm are copied into app/blocks/ with notes for AI agents next to the code. Most need no extra dependencies.
Devtools inside your own app
Run npm run dev and open /_calm. There is no extra service and no browser extension. Devtools only run in development and only answer on localhost, and they cannot be switched on in production.
Made for working with coding agents
We use AI agents on real code, so CalmAPI is designed for them. An agent connects through calm mcp and gets 29 tools for the project: scaffold a resource, call the API as any user, run the tests, run the audit. New projects ship with AGENTS.md and CLAUDE.md, so the agent knows the conventions before it writes a line.
Everything the agent does lands in one activity log that devtools streams live, with diffs and the requests it sent. calm review shows what changed since a person last signed off, and calm review --sign refuses to run in an agent's shell. That is how we work anyway: AI writes the draft, a named engineer signs it.
Start in a minute
You need Node.js 22.12 or newer and a MongoDB to talk to.
Create a project
Pick the api template for sign-up, users and posts, or minimal for an empty app.
npm create calmapi@latest my-api
Run it
The API answers on localhost:5001/api and devtools on localhost:5001/_calm.
cd my-api && npm run dev
Check it
Tests, then the authorization audit. Both run against a throwaway database.
npm test && npx calm audit
Questions about CalmAPI
Is CalmAPI 2 ready for production?
It is in beta. The framework has 443 tests that run against a real MongoDB, but details can still change before 2.0 is final. On a 1.x project, run npx calmapi@next doctor first and follow the migration guide.
Does it work with PostgreSQL?
No. CalmAPI is built on Express 5 and Mongoose, so it needs MongoDB.
Do I have to use an AI agent with it?
No. The agent tools are there if you want them. Resources, the audit and devtools work the same without one.
Can I use it in a commercial project?
Yes. It is MIT licensed, and the framework code in your repository is yours.
Will you build my project on CalmAPI?
When it fits. It is our default for Node.js APIs on MongoDB. If your project needs something else, we use something else.