Plansmith for developers
The three developer surfaces, how they authenticate, and which one to reach for.
Everything your team does in Plansmith is available outside the browser.
CLI
Read and push plans from your terminal or from CI.
MCP server
Give a coding agent the plan it is meant to build from.
API
A versioned JSON API at api.plansmith.co/v1.
Which one
Reach for the CLI for anything a person or a script runs: pulling a plan into a repo, pushing from CI, checking what is Ready.
Reach for the MCP server when a coding agent should read the plan while it works. That is the difference between an agent that guesses at requirements and one that builds from Specs with acceptance criteria.
Reach for the API when you are building something of your own.
One permission model
Whichever surface you use, your credential acts as you. It reaches exactly the plans you can reach, and a private plan nobody shared with you is invisible to your scripts and your agents too.
Nothing here can widen your access. A write-scoped key held by someone with view-only access to a plan still cannot change that plan.
Authenticating
Two credential kinds work everywhere, on the same Authorization: Bearer header:
| Credential | Get one | Use it for |
|---|---|---|
Personal API key (psk_…) | Settings → API keys, or plansmith keys create | CI, scripts, anything non-interactive. |
| OAuth access token | plansmith auth, or your MCP client's consent screen | A person at a terminal, or an agent acting for them. |
A key is scoped read or write. Scope is a ceiling on top of your own permissions, never a
widening of them.
curl -H "Authorization: Bearer psk_read_…" https://api.plansmith.co/v1/meHow things are addressed
Projects have a slug, plans are PLAN-n within their project, and Specs are SPEC-n within their
plan. They are the same handles you see in the web app, so a URL you read in the console is a path
you can call.
/v1/projects/recipe-box
/v1/projects/recipe-box/plans/PLAN-12
/v1/projects/recipe-box/plans/PLAN-12/specs/SPEC-3