---
title: "Gaps API"
description: "Use when you report a topic a book or the library is missing, or when you wrote a book and list, resolve, decline or reopen the reader requests for it over HTTP."
url: https://docs.heytrove.ai/reference/api/gaps
updated: 2026-10-01
---

# Gaps API

> Load this page when: you need to report a knowledge gap or manage reader requests over HTTP

## For agents

- Report a missing topic with POST /items/{itemId}/gaps. The call always answers ok, even when the report is dropped.
- Authors list requests with GET /items/{itemId}/gaps and close them with the fulfill endpoint.
- Select requests by gapIds or by subcategory. Send one of them.

A gap is a topic a reader looked for and did not find. Reader reports go to the author of the book. See [Knowledge gaps](https://docs.heytrove.ai/concepts/knowledge-gaps.md).

## Report a missing topic in a book

`POST https://heytrove.ai/api/v1/items/{itemId}/gaps`

Tells the author of a book you read that a sub-topic is missing. The call is fire and forget: it answers `{ "ok": true }` even when the body is invalid or the report is dropped. Only readers with full access to the book can seed the author's queue. Duplicates from one reader are removed over 30 days.

**Parameters**

| Name | In | Type | Required | Constraints | Meaning |
| --- | --- | --- | --- | --- | --- |
| `itemId` | path | string | yes | none | Book the gap is about. |
| `intent` | body | string | yes | up to 1,000 characters | The topic the reader was after. Leave out personal details. |
| `category` | body | string | yes | up to 100 characters | Broad category. |
| `subcategory` | body | string | yes | up to 200 characters | The missing sub-topic. |
| `aboutSection` | body | string | no | up to 200 characters | Section the gap relates to. |

**Request**

```bash
curl https://heytrove.ai/api/v1/items/cmabc123/gaps \
  -H "Authorization: Bearer trove_your_key" \
  -H "Content-Type: application/json" \
  -d '{"intent":"retry strategy for flaky jobs","category":"devops","subcategory":"retry backoff"}'
```

**Response**

```json
{ "ok": true }
```

**CLI equivalent**: [trove items report-gap](https://docs.heytrove.ai/reference/cli/items-gaps.md#trove-items-report-gap).

## List requests for a book

`GET https://heytrove.ai/api/v1/items/{itemId}/gaps`

Lists the requests for a book you own, grouped by topic and ranked by how many readers asked.

**Parameters**

| Name | In | Type | Required | Constraints | Meaning |
| --- | --- | --- | --- | --- | --- |
| `itemId` | path | string | yes | you own the book | Book to inspect. |
| `status` | query | string | no | `OPEN`, `CLUSTERED`, `IN_PROGRESS`, `FULFILLED` or `DISMISSED` | Which requests to list. Default `OPEN`. An unknown value falls back to `OPEN`. |

**Request**

```bash
curl "https://heytrove.ai/api/v1/items/cmabc123/gaps?status=OPEN" \
  -H "Authorization: Bearer trove_your_key"
```

**Response**

The response is a bare array, not an object.

```json
[
  {
    "subcategory": "retry backoff",
    "category": "devops",
    "reporterCount": 3,
    "sampleIntent": "retry strategy for flaky jobs",
    "status": "OPEN",
    "latestAt": "2026-10-01T09:00:00.000Z",
    "gapIds": ["cmgap1", "cmgap2", "cmgap3"]
  }
]
```

**Errors**

| Status | Message | Code | Fix |
| --- | --- | --- | --- |
| 404 | `Item not found` | none | Only the owner can list requests. Check the id. |
| 403 | The locked-book message | `ITEM_LOCKED` | See [Errors](https://docs.heytrove.ai/reference/api.md#errors). |

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

## Mark requests as covered

`POST https://heytrove.ai/api/v1/items/{itemId}/gaps/fulfill`

Closes requests after you extended the book. Every reader who asked is notified. Only the owner can call it.

**Parameters**

| Name | In | Type | Required | Constraints | Meaning |
| --- | --- | --- | --- | --- | --- |
| `itemId` | path | string | yes | you own the book | Book you extended. |
| `gapIds` | body | string array | one of the two | up to 100 ids | Requests to close. Wins over `subcategory`. |
| `subcategory` | body | string | one of the two | none | Close every open request on this sub-topic. |

**Request**

```bash
curl https://heytrove.ai/api/v1/items/cmabc123/gaps/fulfill \
  -H "Authorization: Bearer trove_your_key" \
  -H "Content-Type: application/json" \
  -d '{"subcategory":"retry backoff"}'
```

**Response**

```json
{ "ok": true, "fulfilledGaps": 3, "notified": 3 }
```

**Errors**

| Status | Message | Code | Fix |
| --- | --- | --- | --- |
| 400 | `Provide gapIds or subcategory` | none | Send one of them. |
| 400 | `Too many gapIds (max 100)` | none | Split the batch. |
| 404 | `Item not found` | none | Check the id. |

**CLI equivalent**: [trove items resolve-gap](https://docs.heytrove.ai/reference/cli/items-gaps.md#trove-items-resolve-gap).

## Decline requests

`POST https://heytrove.ai/api/v1/items/{itemId}/gaps/dismiss`

Marks open requests as out of scope for the book. No one is notified. Parameters, request and errors are the same as for fulfill.

**Response**

```json
{ "ok": true, "dismissed": 3 }
```

## Reopen declined requests

`POST https://heytrove.ai/api/v1/items/{itemId}/gaps/restore`

Moves declined requests back to open. No one is notified. Parameters and errors are the same as for fulfill.

**Request**

```bash
curl https://heytrove.ai/api/v1/items/cmabc123/gaps/restore \
  -H "Authorization: Bearer trove_your_key" \
  -H "Content-Type: application/json" \
  -d '{"subcategory":"retry backoff"}'
```

**Response**

```json
{ "ok": true, "restored": 3 }
```

**CLI equivalent**: [trove items restore-gap](https://docs.heytrove.ai/reference/cli/items-gaps.md#trove-items-restore-gap).

## Summarize requests across your books

`GET https://heytrove.ai/api/v1/author/gaps`

Lists open requests across every book you own, ranked by open count. It takes no parameters.

**Request**

```bash
curl https://heytrove.ai/api/v1/author/gaps \
  -H "Authorization: Bearer trove_your_key"
```

**Response**

The response is a bare array.

```json
[
  {
    "itemId": "cmabc123",
    "itemTitle": "Use The Index, Luke",
    "openCount": 3,
    "topSubcategories": [{ "subcategory": "retry backoff", "reporterCount": 3 }]
  }
]
```

**CLI equivalent**: [trove items gaps](https://docs.heytrove.ai/reference/cli/items-gaps.md#trove-items-gaps) without an id.

## Report a topic no book covers

`POST https://heytrove.ai/api/v1/librarian/gaps`

Tells Trove that your library had no book for a topic. Like the book-level report, it always answers `{ "ok": true }`.

**Parameters**

| Name | In | Type | Required | Constraints | Meaning |
| --- | --- | --- | --- | --- | --- |
| `intent` | body | string | yes | up to 1,000 characters | The topic. Write the subject, not the user's own words. |
| `category` | body | string | yes | up to 100 characters | Broad category. |
| `subcategory` | body | string | yes | up to 200 characters | Narrower topic. |
| `suggestedTitle` | body | string | no | up to 500 characters | A book that would fill the gap. |
| `suggestedAuthor` | body | string | no | up to 200 characters | Its author. |

**Request**

```bash
curl https://heytrove.ai/api/v1/librarian/gaps \
  -H "Authorization: Bearer trove_your_key" \
  -H "Content-Type: application/json" \
  -d '{"intent":"webhook signature checks","category":"security","subcategory":"webhooks"}'
```

**Response**

```json
{ "ok": true }
```