---
title: "Account API"
description: "Use when you read or change your settings, turn Trove off for one coding agent, report which agents a machine has, read notifications, or send a bug report over HTTP."
url: https://docs.heytrove.ai/reference/api/account
updated: 2026-10-01
---

# Account API

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

## For agents

- 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](https://docs.heytrove.ai/reference/cli/config.md#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](https://docs.heytrove.ai/reference/cli/config.md#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](https://docs.heytrove.ai/reference/cli/setup.md#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](https://docs.heytrove.ai/reference/cli/report.md).