Reference

Manuscripts API

Updated 1 Oct 2026

View as Markdown Open in Claude (opens in a new tab)Open in ChatGPT (opens in a new tab)

On this page

List manuscripts
Create a manuscript
Update a manuscript
Archive a manuscript

For agents

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

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.

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.

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.

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.

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.

Manuscripts API

For agents

List manuscripts#

Create a manuscript#

Update a manuscript#

Archive a manuscript#

List manuscripts

Create a manuscript

Update a manuscript

Archive a manuscript