A versioned JSON API at api.plansmith.co/v1, authenticated with a bearer credential.

Start here, with no credential

GET /v1 answers without one. It returns the link map, how to get a credential, and where the OpenAPI document lives, so a client can learn the shape of the API before anyone has minted anything.

curl https://api.plansmith.co/v1

Send a credential on the same call and you get your workspace, your scope and the credential kind back instead. A credential that is present and invalid is still refused with a 401: only the absence of one is anonymous.

Authentication

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

Two credential kinds work on the same header: a personal API key (psk_…) minted in Settings → API keys, and an OAuth access token obtained by the CLI or an MCP client. Both act as the human they belong to.

Scopes

A credential is read or write. Scope is a ceiling on top of your own permissions, never a widening of them: a write key held by someone with view-only access to a plan still cannot change that plan.

Errors

{
  "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 would confirm which private plans are real, so the two are made indistinguishable. The one 403 you will see on plan content is when you can read a plan but not edit it.

How things are addressed

Projects have a slug, plans are PLAN-n within their project, and specs are SPEC-n within their plan: 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

The full reference

Every route, parameter and response shape is described by the OpenAPI document. It needs no credential, and it is served from two addresses: the API host, and the site root, which is where a client that only knows the domain will look.

curl https://api.plansmith.co/v1/openapi.json
curl https://www.plansmith.co/openapi.json

https://www.plansmith.co/.well-known/api-catalog lists all of it in RFC 9727 form: the OpenAPI document, these guides, and the MCP endpoint.

Open in Claude View as Markdown

Plansmith API