Agents

An agent is a first-class user: it has a name, its own permissions and its own token. You invite it with a one-time link (see Invite your agent).

Read the invite

GET /join/:token

No key needed. Returns markdown with what Pluma is, which site it is, what you'll be able to do, and the exact command to redeem it.

curl https://pluma.so/join/$PLUMA_INVITE

Redeem

POST /join/:token/redeem

curl -X POST https://pluma.so/join/$PLUMA_INVITE/redeem

{
  "token": "pluma_agt_…",
  "agent": { "name": "María's Claude", "can": ["read_published", "read_drafts", "write", "publish", "manage_model", "manage_keys", "manage_webhooks"] },
  "space": "acton-estero",
  "next": [ "GET /api/v1/spaces/acton-estero/llms.txt", "…" ]
}

• The token is shown only once. Save it as an environment variable (PLUMA_KEY), never in the repo.
• The link is now used. Opening or redeeming it again gives invite_used; if 24 hours have passed, invite_expired.
• The token works like any key: Authorization: Bearer pluma_agt_….

Your site's docs

GET /api/v1/spaces/:space_id/llms.txt

curl https://pluma.so/api/v1/spaces/acton-estero/llms.txt -H "Authorization: Bearer $PLUMA_KEY"

Markdown generated live: which site it is, its locales, each content type with its fields and validations, and the endpoints ready to copy with the slug filled in. It changes as soon as the model changes. Read it before creating or importing anything: you should never have to guess the model.

Keys for the site

GET /api/v1/spaces/:space_id/api_keys

POST /api/v1/spaces/:space_id/api_keys

curl -X POST https://pluma.so/api/v1/spaces/acton-estero/api_keys \
  -H "Authorization: Bearer $PLUMA_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "Netlify build", "kind": "delivery" }'

{ "token": "pluma_dlv_…", "key": { "id": "3", "name": "Netlify build", "kind": "delivery" } }

• An agent can create delivery and preview keys. A management one gives key_cannot: an agent can't hand out more permissions than its owner has.
• The token is shown once. For the build, save it in the host's environment variables (Netlify, Vercel), not in the code.

An agent's permissions

An agent has its own permissions, capped by the current role of the person who connected it (whoever approved the OAuth or generated the invite link). If that person's role is lowered, the agent loses the same right away; if they're removed from the site, the agent can't do anything. The breakdown by role is in What the agent can do.