---
title: Agents
status: current
phase: 4
order: 5
---

# 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](../guides/invite-your-agent.md)).

## 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.

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

## Redeem

`POST /join/:token/redeem`

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

```json
{
  "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`](../errors/invite_used.md); if 24 hours have passed, [`invite_expired`](../errors/invite_expired.md).
- The token works like any key: `Authorization: Bearer pluma_agt_…`.

## Your site's docs

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

```sh
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`

```sh
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" }'
```

```json
{ "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`](../errors/key_cannot.md): 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](../mcp/tools.md#what-the-agent-can-do).

| Permission | What it allows |
| --- | --- |
| `read_published` | Read what's published |
| `read_drafts` | Read drafts and versions |
| `write` | Create and edit entries and files |
| `publish` | Publish, archive, unarchive |
| `manage_model` | Create and edit content types and fields |
| `manage_keys` | Create `delivery` and `preview` keys |
| `manage_webhooks` | Create, test and delete deploy hooks |