> ## Documentation Index
> Fetch the complete documentation index at: https://docs.projectecho.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Draft changelogs with an agent

> Set up API or MCP permissions and use copy-paste prompts so an agent can draft weekly changelogs from completed requests.

Agents can create **draft** changelog entries, link completed requests, and leave publishing to you in the Project Echo web app. This keeps accidental public posts from shipping automatically.

For a reusable Cursor/agent install, see [Install the Project Echo agent skill](/api-mcp-and-embed/agent-skill).

## 1. Create an API key

1. Sign in at [app.projectecho.io](https://app.projectecho.io).
2. Open **API & MCP** in the workspace nav.
3. Create a key (label e.g. “Changelog agent”). Prefer the **Contributor** preset, or pick individual permissions below.
4. Copy the **token** (`pe_api_…`) and **Key ID** — the token is shown once.

### Recommended permissions

| Permission                 | Why                                                             |
| -------------------------- | --------------------------------------------------------------- |
| `changelogs:read`          | List and open drafts                                            |
| `changelogs:create`        | Create draft entries                                            |
| `changelogs:update`        | Edit draft title, slug, body, author, date                      |
| `changelogs:link_requests` | Attach completed requests (optional but usual for weekly posts) |
| `requests:read`            | Find completed / unlinked requests                              |
| `statuses:read`            | Resolve the Completed status id                                 |
| `users:read`               | Pick an author teammate if you do not want the default          |

**Full agent** and **Contributor** presets include the changelog create/link permissions. Existing keys do **not** gain new permissions automatically — create a new key if needed.

### Default author

If the agent omits `author_user_id`, Project Echo uses the **billing admin who joined the workspace first**.

## 2. Connect REST or MCP

**REST** — every call needs:

* `Authorization: Bearer pe_api_…`
* `X-PE-API-Key-Id: <key-uuid>`

**MCP** — see [Connect MCP](/api-mcp-and-embed/connect-mcp). Useful tools: `list_statuses`, `list_requests` (with `unlinked=true`), `create_changelog_draft`, `update_changelog_draft`, `set_changelog_requests`, `upload_changelog_image`, `list_changelogs`, `get_changelog`.

## 3. Weekly workflow

1. `list_statuses` → find the id for **Completed** (or any status with changelog eligibility).
2. `list_requests` with that `status_id` and `unlinked=true`.
3. Draft TipTap `content_json` using the [TipTap body guide](/api-mcp-and-embed/changelog-tiptap-body-for-agents).
4. `create_changelog_draft` with title, body, optional `linked_request_ids` and `published_at` (intended publish time — entry stays a draft until you publish).
5. Open **Changelog** in the staff app, review the draft, then turn **Published** on.

API/MCP **cannot** publish. That is intentional.

## 4. Copy-paste prompts

### Prompt A — weekly draft from completed requests

```text theme={null}
You are helping me write a Project Echo changelog draft.

1. Use Project Echo MCP/API tools with my configured key.
2. List statuses and find the Completed (changelog-eligible) status.
3. List requests with that status_id and unlinked=true (limit 50).
4. Summarize what shipped into a customer-friendly changelog (simple language, limited jargon).
5. Build content_json as TipTap JSON only (type: "doc"). Follow the TipTap body guide for paragraphs, headings, lists, images, and YouTube.
6. Create a draft with create_changelog_draft. Title like “Week of <date>”. Link the request ids you used. If linking fails, report the API error details and continue without those ids.
7. Do NOT publish. Reply with the draft id, slug, title, and a short summary for me to review in the Project Echo web app.
```

### Prompt B — revise an existing draft

```text theme={null}
Update Project Echo changelog draft <CHANGELOG_UUID>.

- Fix the TipTap content_json using the TipTap body guide (valid type:doc JSON only).
- Keep status as draft; do not try to publish.
- Optionally refresh linked_request_ids to the completed, unlinked requests we agreed on.
- Reply with what changed and any API validation errors verbatim.
```

## Errors agents should surface

The API returns `{ "error": "...", "code": "...", "details": ... }` when useful. Common codes: `invalid_content_json`, `youtube_missing_src`, `content_too_large`, `link_validation_failed`, `not_draft`, `invalid_author`, `no_default_author`, or `403` for missing permissions.

## Related

* [Install the Project Echo agent skill](/api-mcp-and-embed/agent-skill)
* [Changelog TipTap body format for agents](/api-mcp-and-embed/changelog-tiptap-body-for-agents)
* [Create and manage API keys](/api-mcp-and-embed/create-manage-api-keys)
* [Connect MCP](/api-mcp-and-embed/connect-mcp)
* [Create and publish changelog entries](/roadmap-and-changelog/create-publish-changelog)