# Plansmith API

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



## Start here, with no 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.

```bash
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 [#authentication]

```bash
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 [#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 [#errors]

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

<Callout>
  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.
</Callout>

## How things are addressed [#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.

```text
/v1/projects/recipe-box
/v1/projects/recipe-box/plans/PLAN-12
/v1/projects/recipe-box/plans/PLAN-12/specs/SPEC-3
```

## The full reference [#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.

```bash
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.