Reference
Gaps API
Updated 1 Oct 2026
On this page
For agents
Load this page when: you need to report a knowledge gap or manage reader requests over HTTP
- 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.
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
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
{ "ok": true }CLI equivalent: 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
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.
[
{
"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. |
CLI equivalent: 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
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
{ "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.
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
{ "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
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
{ "ok": true, "restored": 3 }CLI equivalent: 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
curl https://heytrove.ai/api/v1/author/gaps \
-H "Authorization: Bearer trove_your_key"Response
The response is a bare array.
[
{
"itemId": "cmabc123",
"itemTitle": "Use The Index, Luke",
"openCount": 3,
"topSubcategories": [{ "subcategory": "retry backoff", "reporterCount": 3 }]
}
]CLI equivalent: 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
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
{ "ok": true }