Reference

Account 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

Get your settings
Change your settings
Change which agents are turned off
Report a machine
List machines
List notifications
Mark notifications read
Send a report

For agents

Load this page when: you need to manage account settings, connected agents, notifications or reports over HTTP

Settings and agent routes need a CLI API key. OAuth connector tokens are refused on the agent routes.
Change settings with PATCH /user/config. Only planMode and citationBlock exist.
Agent changes are idempotent. Repeating one returns changed false.

These endpoints serve the settings the CLI keeps in sync across your machines.

Get your settings

GET https://heytrove.ai/api/v1/user/config

Returns your stored settings and a version number that goes up on every change. A setting you never changed is left out. The CLI fills in defaults.

Request

bash

curl https://heytrove.ai/api/v1/user/config \
  -H "Authorization: Bearer trove_your_key"

Response

json

{
  "config": { "skill": { "planMode": "smart" } },
  "configVersion": 3
}

CLI equivalent: trove config show.

Change your settings

PATCH https://heytrove.ai/api/v1/user/config

Changes settings in the skill group. Send only the keys you want to change. Unknown keys are refused.

Parameters

Name	In	Type	Required	Constraints	Meaning
`planMode`	body	string	no	`always`, `smart`, `ask` or `off`	When the agent consults your library while it plans.
`citationBlock`	body	string	no	`on` or `off`	Whether answers carry a citation block.

Request

bash

curl -X PATCH https://heytrove.ai/api/v1/user/config \
  -H "Authorization: Bearer trove_your_key" \
  -H "Content-Type: application/json" \
  -d '{"planMode":"smart"}'

Response

json

{ "configVersion": 4 }

Errors

Status	Message	Code	Fix
400	`Invalid JSON body`	none	Send valid JSON.
400	A message that starts with the field name, such as `planMode: …`	none	Use an allowed value.

CLI equivalent: trove config set.

Change which agents are turned off

PATCH https://heytrove.ai/api/v1/user/config/agents

Turns Trove off or on for one coding agent. The change applies to every machine you use. It needs a CLI API key.

Parameters

Name	In	Type	Required	Constraints	Meaning
`op`	body	string	yes	`disable` or `enable`	What to do.
`agent`	body	string	yes	`claude-code`, `cursor`, `github-copilot`, `gemini-cli`, `codex` or `grok`	Agent to change.

Request

bash

curl -X PATCH https://heytrove.ai/api/v1/user/config/agents \
  -H "Authorization: Bearer trove_your_key" \
  -H "Content-Type: application/json" \
  -d '{"op":"disable","agent":"cursor"}'

Response

json

{ "disabled": ["cursor"], "configVersion": 5, "changed": true }

Repeating the call returns changed: false.

Errors

Status	Message	Code	Fix
403	`This token cannot manage agent installs. Use a CLI API key (trove auth login) — OAuth connector tokens are limited to library and marketplace access.`	`INSUFFICIENT_SCOPE`	Use an API key.
400	`agent: unknown agent. Supported agents: …`	`UNKNOWN_AGENT`	Use a listed agent.
413	`Request body too large`	none	Send a smaller body.
429	`Too many changes — wait a minute and retry.`	`RATE_LIMITED`	Wait a minute.

CLI equivalent: trove setup.

Report a machine

PUT https://heytrove.ai/api/v1/user/agents

Reports which agents the CLI found on one machine. The report replaces the earlier rows for that machine. Repeating it is harmless. It needs a CLI API key.

Parameters

Name	In	Type	Required	Constraints	Meaning
`machineId`	body	string	yes	8 to 64 characters	A stable id for the machine.
`hostname`	body	string or null	no	up to 255 characters	Kept only while client telemetry is on.
`os`	body	string or null	no	`macos`, `linux` or `windows`	Kept only while client telemetry is on.
`cliVersion`	body	string or null	no	up to 40 characters	CLI version.
`agents`	body	array	yes	up to 14 entries	One entry per agent.
`agents[].name`	body	string	yes	1 to 40 characters	Agent name. Unknown names are ignored.
`agents[].detected`	body	boolean	yes	none	The agent was found.
`agents[].installed`	body	boolean	yes	none	Trove is installed in it.
`agents[].installType`	body	string or null	no	`skill`, `plugin+skill` or `codex bundle`	How it is installed.

Trove keeps at most 20 machines per account. The machines seen longest ago are dropped first.

Response

json

{ "ok": true, "machineId": "machine-0001", "agentCount": 2, "ignoredAgents": [] }

Errors

Status	Message	Code	Fix
400	A message that starts with the field name	none	Fix the field.
403	The `INSUFFICIENT_SCOPE` message	`INSUFFICIENT_SCOPE`	Use an API key.
429	`Too many agent reports — wait a minute and retry.`	`RATE_LIMITED`	Wait a minute.

List machines

GET https://heytrove.ai/api/v1/user/agents

Lists the retained machines, most recently seen first. It needs a CLI API key.

Response

json

{
  "machines": [
    {
      "machineId": "machine-0001",
      "hostname": null,
      "os": "macos",
      "cliVersion": "1.0.0",
      "lastSeenAt": "2026-10-01T09:00:00.000Z",
      "agents": [{ "name": "claude-code", "detected": true, "installed": true, "installType": "plugin+skill" }]
    }
  ]
}

List notifications

GET https://heytrove.ai/api/v1/user/notifications

Lists up to 50 notifications, newest first. The CLI uses it to tell you when a book you asked for is ready.

Parameters

Name	In	Type	Required	Constraints	Meaning
`unread`	query	boolean	no	`true`	Only notifications you have not marked read.
`type`	query	string	no	a notification type, such as `gap_fulfilled`	Only this type.

Request

bash

curl "https://heytrove.ai/api/v1/user/notifications?unread=true&type=gap_fulfilled" \
  -H "Authorization: Bearer trove_your_key"

Response

json

{
  "notifications": [
    { "id": "cmnote1", "type": "gap_fulfilled", "title": "…", "body": "…", "metadata": {}, "createdAt": "2026-10-01T09:00:00.000Z" }
  ]
}

Mark notifications read

POST https://heytrove.ai/api/v1/user/notifications/mark-read

Marks your own notifications as read. Ids that are not yours are ignored.

Parameters

Name	In	Type	Required	Constraints	Meaning
`ids`	body	string array	yes	the first 200 are used	Notifications to mark.

Request

bash

curl https://heytrove.ai/api/v1/user/notifications/mark-read \
  -H "Authorization: Bearer trove_your_key" \
  -H "Content-Type: application/json" \
  -d '{"ids":["cmnote1"]}'

Response

json

{ "ok": true, "updated": 1 }

Send a report

POST https://heytrove.ai/api/v1/report

Posts a bug report, feature request or idea to your support inbox.

Parameters

Name	In	Type	Required	Constraints	Meaning
`title`	body	string	yes	1 to 200 characters	Title.
`body`	body	string	yes	1 to 100,000 characters	Report text.
`type`	body	string	no	`bug`, `feature`, `idea` or `other`	Report type. Default `other`.

Request

bash

curl https://heytrove.ai/api/v1/report \
  -H "Authorization: Bearer trove_your_key" \
  -H "Content-Type: application/json" \
  -d '{"title":"toc fails on a large book","type":"bug","body":"Steps and output."}'

Response

json

{ "id": "cmrep123", "url": "https://heytrove.ai/support/cmrep123" }

Errors

Status	Message	Code	Fix
400	`title is required`	none	Send a title.
400	`body is required`	none	Send a body.
400	`title exceeds 200 characters`	none	Shorten it.
429	`Too many reports in a short window — wait a minute and retry.`	`RATE_LIMITED`	Wait a minute.

CLI equivalent: trove report.

Account API

For agents

Get your settings#

Change your settings#

Change which agents are turned off#

Report a machine#

List machines#

List notifications#

Mark notifications read#

Send a report#

Get your settings

Change your settings

Change which agents are turned off

Report a machine

List machines

List notifications

Mark notifications read

Send a report