The base URL, how to authenticate, and the one error rule worth knowing before you start.

The Plansmith API is a versioned JSON API. Every page in this section is generated from the same OpenAPI document the server publishes at /v1/openapi.json, so what you read here is what the API actually accepts and returns.

Base URL

https://api.plansmith.co/v1

Pointing a local client at a dev server needs the /api segment: http://localhost:3000/api/v1/me. The api.plansmith.co host rewrites /v1 onto it for you, and nothing else does.

Authentication

Every request carries a bearer credential:

curl -H "Authorization: Bearer psk_read_…" https://api.plansmith.co/v1/me

Two kinds work on the same header: a personal API key (psk_…) minted in Settings → API keys or with plansmith keys create, and an OAuth access token (plan_at_…) obtained by the CLI or an MCP client.

Both act as the human they belong to. A credential reaches exactly the plans that person can reach, and scope (read or write) is a ceiling on top of that, never a widening of it.

Errors

Errors come back in one envelope, on every endpoint:

{
  "error": {
    "code": "not_found",
    "message": "No such plan."
  }
}

A plan you cannot read answers 404, exactly like a plan that does not exist. That is deliberate: a 403 next to a 404 would tell you which private plans are real. The only 403 you will see on plan content is when you can read a plan but not edit it.

Shapes worth knowing up front

Collections are named, not wrapped in a generic envelope: GET /v1/api-keys answers { "keys": [ … ] }, GET /v1/projects answers { "projects": [ … ] }.

Deletes answer 200 with a small acknowledgement, not 204: { "deleted": true }, { "removed": true }, or a count.

Plans and Specs are addressed by their handles (PLAN-12, SPEC-3) wherever a URL takes one, and needsFirst comes back as handles too, so you can render "needs SPEC-3 first" without building your own id map.

Versioning

The path carries the version. /v1 will not change shape underneath you: fields are added, never removed or repurposed, and a breaking change would arrive as /v2.

Trying a request

Every endpoint page has a playground. Fill in a key and send a real request; without one you get a real 401, which is the fastest way to confirm you are reaching the right host.

Open in Claude View as Markdown

Getting started with the Plansmith API