---
title: "Manuscripts API"
description: "Use when you list, create, update, pause or archive manuscripts over HTTP. A manuscript is a book an agent keeps up to date from research sessions."
url: https://docs.heytrove.ai/reference/api/manuscripts
updated: 2026-10-01
---

# Manuscripts API

> Load this page when: you need to manage manuscripts over HTTP

## For agents

- Filter the list with the status query: ACTIVE, PAUSED or ARCHIVED.
- Pause with PUT and status PAUSED to free a plan slot. Archive with DELETE.
- On MANUSCRIPT_LIMIT_EXCEEDED, relay the message to the user. It names the manuscripts using the slots.

A manuscript uses one of your plan's manuscript slots while it is active. See [Manuscripts](https://docs.heytrove.ai/concepts/manuscripts.md).

## List manuscripts

`GET https://heytrove.ai/api/v1/manuscripts`

Lists your manuscripts and the team manuscripts you can read. Each carries a `locked` flag.

**Parameters**

| Name | In | Type | Required | Constraints | Meaning |
| --- | --- | --- | --- | --- | --- |
| `status` | query | string | no | `ACTIVE`, `PAUSED` or `ARCHIVED` | Show only manuscripts in this state. |

**Request**

```bash
curl "https://heytrove.ai/api/v1/manuscripts?status=ACTIVE" \
  -H "Authorization: Bearer trove_your_key"
```

**Response**

```json
{
  "manuscripts": [
    {
      "id": "cmms123",
      "title": "Team runbook",
      "description": null,
      "audience": null,
      "topics": ["deploys", "rollbacks"],
      "criteria": [],
      "trigger": null,
      "instructions": null,
      "autoUpdate": true,
      "isSystem": false,
      "team": false,
      "locked": false,
      "status": "ACTIVE",
      "itemId": "cmrun456",
      "createdAt": "2026-10-01T09:00:00.000Z",
      "updatedAt": "2026-10-01T09:00:00.000Z"
    }
  ]
}
```

**Errors**

| Status | Message | Code | Fix |
| --- | --- | --- | --- |
| 400 | `Invalid status. Must be one of: ACTIVE, PAUSED, ARCHIVED` | `INVALID_INPUT` | Use one of the three. |

**CLI equivalent**: [trove ms list](https://docs.heytrove.ai/reference/cli/ms.md#trove-ms-list).

## Create a manuscript

`POST https://heytrove.ai/api/v1/manuscripts`

Creates a manuscript, with a new book or attached to a book you already have.

**Parameters**

| Name | In | Type | Required | Constraints | Meaning |
| --- | --- | --- | --- | --- | --- |
| `title` | body | string | yes | 1 to 200 characters | Title. |
| `description` | body | string | no | up to 4,000 characters | Description. |
| `audience` | body | string | no | up to 500 characters | Target audience. |
| `topics` | body | string array | no | up to 50 items of up to 200 characters | Topics. |
| `criteria` | body | string array | no | up to 50 items of up to 500 characters | Acceptance criteria. |
| `trigger` | body | string | no | up to 80 characters | One line that says when to log to this manuscript. |
| `instructions` | body | string | no | up to 16,000 characters | How the agent maintains the book. |
| `autoUpdate` | body | boolean | no | none | Update after each session without asking. |
| `itemId` | body | string | no | letters and digits, up to 64 | Attach to an existing book. |
| `teamId` | body | string | no | letters and digits, up to 64 | Share with a team you belong to. |
| `structure` | body | object | no | up to 16,000 bytes of JSON | Structure hints. |

**Request**

```bash
curl https://heytrove.ai/api/v1/manuscripts \
  -H "Authorization: Bearer trove_your_key" \
  -H "Content-Type: application/json" \
  -d '{"title":"Team runbook","topics":["deploys","rollbacks"],"autoUpdate":true}'
```

**Response**

Status 201. The body is `{ "manuscript": { ... } }` with the fields shown above.

**Errors**

| Status | Message | Code | Fix |
| --- | --- | --- | --- |
| 400 | A message that names the field that failed | `INVALID_INPUT` | Fix the field. |
| 403 | A message that names the manuscripts using your slots | `MANUSCRIPT_LIMIT_EXCEEDED` | Pause one, or upgrade. The body adds `upgradeUrl`, `limit`, `used` and `occupants`. |
| 403 | `Your library is full. Upgrade to add more items.` | `PLAN_LIMIT_EXCEEDED` | A new manuscript also creates a book. |
| 403 | `You are not a member of team {id}.` | `NOT_TEAM_MEMBER` | Use a team you belong to. |
| 404 | `Item {id} not found or does not belong to your account.` | `ITEM_NOT_FOUND` | Check `itemId`. |
| 409 | `Item {id} already has an active manuscript. Archive it first with: trove ms archive {manuscriptId}` | `MANUSCRIPT_ITEM_CONFLICT` | Archive the other one. The body adds `existingManuscriptId`. |
| 429 | `Too many requests` | `RATE_LIMITED` | Wait a minute. |

**CLI equivalent**: [trove ms create](https://docs.heytrove.ai/reference/cli/ms.md#trove-ms-create).

## Update a manuscript

`PUT https://heytrove.ai/api/v1/manuscripts/{id}`

Changes fields or the status. Send only the fields you want to change. A field that allows it can be set to `null` to clear it.

**Parameters**

| Name | In | Type | Required | Constraints | Meaning |
| --- | --- | --- | --- | --- | --- |
| `id` | path | string | yes | none | Manuscript to change. |
| `title` | body | string | no | 1 to 200 characters | New title. |
| `description` | body | string or null | no | up to 4,000 characters | Description. |
| `audience` | body | string or null | no | up to 500 characters | Audience. |
| `topics` | body | string array | no | up to 50 items | Topics. |
| `criteria` | body | string array | no | up to 50 items | Criteria. |
| `trigger` | body | string or null | no | up to 80 characters | Trigger line. |
| `instructions` | body | string or null | no | up to 16,000 characters | Instructions. |
| `autoUpdate` | body | boolean | no | none | Auto-update on or off. |
| `status` | body | string | no | `ACTIVE`, `PAUSED` or `ARCHIVED` | `PAUSED` stops updates and frees the slot. `ACTIVE` uses a slot. |
| `structure` | body | object or null | no | up to 16,000 bytes of JSON | Structure hints. |

**Request**

```bash
curl -X PUT https://heytrove.ai/api/v1/manuscripts/cmms123 \
  -H "Authorization: Bearer trove_your_key" \
  -H "Content-Type: application/json" \
  -d '{"status":"PAUSED"}'
```

**Response**

```json
{ "manuscript": { "id": "cmms123", "title": "Team runbook", "status": "PAUSED" } }
```

The `manuscript` object has every field shown in the list response.

**Errors**

| Status | Message | Code | Fix |
| --- | --- | --- | --- |
| 400 | `Invalid request body` | none | Send a JSON object. |
| 404 | `Manuscript not found` | `NOT_FOUND` | Check the id. |
| 403 | `Only the author or a team owner/admin can update this team manuscript.` | `FORBIDDEN` | Ask the author or a team admin. |
| 403 | A message that names the manuscripts using your slots | `MANUSCRIPT_LIMIT_EXCEEDED` | Pause another one first. |

**CLI equivalent**: [trove ms update](https://docs.heytrove.ai/reference/cli/ms.md#trove-ms-update).

## Archive a manuscript

`DELETE https://heytrove.ai/api/v1/manuscripts/{id}`

Archives a manuscript you wrote. Nothing is deleted. The book stays, and updates stop.

**Request**

```bash
curl -X DELETE https://heytrove.ai/api/v1/manuscripts/cmms123 \
  -H "Authorization: Bearer trove_your_key"
```

**Response**

```json
{ "success": true }
```

**Errors**

| Status | Message | Code | Fix |
| --- | --- | --- | --- |
| 404 | `Manuscript not found` | `NOT_FOUND` | Only the author can archive. Check the id. |

**CLI equivalent**: [trove ms archive](https://docs.heytrove.ai/reference/cli/ms.md#trove-ms-archive).