> For the complete documentation index, see [llms.txt](https://docs.customer-alliance.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.customer-alliance.com/insights.md).

# Insights

AI recommendations, mentions and topics.

## List AI recommendations for the account (newest first)

> Requires \`insights:read\`. Recommendations draw on every property's feedback, so only a key bound to the account's only live root receives them; any other key receives an empty list.

```json
{"openapi":"3.1.0","info":{"title":"Customer Alliance API","version":"4.3.0"},"tags":[{"name":"Insights","description":"AI recommendations, mentions and topics."}],"servers":[{"url":"https://app.customer-alliance.com/api/v4","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"An API key created in Settings → API (`ca_live_…`)."}},"parameters":{"cursor":{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque pagination cursor from a prior response's next_cursor."},"limit":{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}},"schemas":{"Recommendation":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"body":{"type":"string"},"priority":{"type":"string"},"impact":{"type":["string","null"]},"canonical_label_id":{"type":["string","null"],"format":"uuid"},"created_at":{"type":"string","format":"date-time"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The key lacks the required scope, the account's plan does not include it, or the key's owner no longer has the access it needs. The last is checked on every call: a key works only while the user who created it is active in the account and holds `api_keys.manage` where the key is bound, plus the permission behind each write scope it carries. Every call with such a key gets the same `403`, whatever its scope, until the owner's access is restored or an administrator creates a new key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/insights/recommendations":{"get":{"summary":"List AI recommendations for the account (newest first)","description":"Requires `insights:read`. Recommendations draw on every property's feedback, so only a key bound to the account's only live root receives them; any other key receives an empty list.","operationId":"listRecommendations","tags":["Insights"],"parameters":[{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/limit"}],"responses":{"200":{"description":"A page of recommendations.","content":{"application/json":{"schema":{"type":"object","required":["data","next_cursor","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Recommendation"}},"next_cursor":{"type":["string","null"],"description":"Pass as `?cursor=` to fetch the next page; null on the last page."},"has_more":{"type":"boolean"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}}}}
```

## List topic mentions extracted from reviews in the key's subtree (newest first)

> Requires \`insights:read\`. Returns mentions from every review on your account's subtree by default — a mention is a snippet of a review you can already read, so the scope matches \`GET /reviews\`. If you are rendering mentions to the public, pass \`?display=public\`.\
> \
> \*\*Mentions from responses to your Customer Alliance surveys are never returned here\*\*, with or without \`display=public\`, for the same reason as \`GET /reviews\`: the response is already served by \`GET /surveys/{id}/responses\`.

```json
{"openapi":"3.1.0","info":{"title":"Customer Alliance API","version":"4.3.0"},"tags":[{"name":"Insights","description":"AI recommendations, mentions and topics."}],"servers":[{"url":"https://app.customer-alliance.com/api/v4","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"An API key created in Settings → API (`ca_live_…`)."}},"parameters":{"cursor":{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque pagination cursor from a prior response's next_cursor."},"limit":{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},"display":{"name":"display","in":"query","schema":{"type":"string","enum":["public"]},"description":"Pass `public` when the response will be shown to the public — a custom widget, an embed, anything a site visitor reads. It excludes two groups of reviews:\n\n- **Portals whose content may not be republished.** Some review portals license redisplay of their content as a paid product, or have terms that have not been cleared for it. Those reviews are yours to read, analyse and act on, but not to republish.\n- **Sources whose authorship was never verified** — reviews entered by hand (`manual`) and imported ones (`upload`: CSV uploads, and everything pushed through `POST /reviews` or `POST /survey-responses`). Legitimate internal signal, but nobody confirmed a guest wrote them.\n\nOnly the exact value `public` opts in. Any other value is ignored and you get the default, unfiltered behaviour — a typo must not silently withhold data.\n\nOmit it — the default — to read everything on your account. Responses to your Customer Alliance surveys are never served by these endpoints either way; see `GET /surveys/{id}/responses`."}},"schemas":{"Mention":{"type":"object","description":"A topic mention extracted from a review. `is_hidden` mirrors the source review's flag.","properties":{"id":{"type":"string","format":"uuid"},"review_id":{"type":"string","format":"uuid"},"source_field":{"type":"string"},"text":{"type":"string"},"sentiment":{"type":["string","null"]},"canonical_label_id":{"type":"string","format":"uuid"},"custom_category_id":{"type":["string","null"],"format":"uuid"},"confidence":{"type":["number","null"]},"is_hidden":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The key lacks the required scope, the account's plan does not include it, or the key's owner no longer has the access it needs. The last is checked on every call: a key works only while the user who created it is active in the account and holds `api_keys.manage` where the key is bound, plus the permission behind each write scope it carries. Every call with such a key gets the same `403`, whatever its scope, until the owner's access is restored or an administrator creates a new key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/insights/mentions":{"get":{"summary":"List topic mentions extracted from reviews in the key's subtree (newest first)","description":"Requires `insights:read`. Returns mentions from every review on your account's subtree by default — a mention is a snippet of a review you can already read, so the scope matches `GET /reviews`. If you are rendering mentions to the public, pass `?display=public`.\n\n**Mentions from responses to your Customer Alliance surveys are never returned here**, with or without `display=public`, for the same reason as `GET /reviews`: the response is already served by `GET /surveys/{id}/responses`.","operationId":"listMentions","tags":["Insights"],"parameters":[{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/display"}],"responses":{"200":{"description":"A page of mentions.","content":{"application/json":{"schema":{"type":"object","required":["data","next_cursor","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Mention"}},"next_cursor":{"type":["string","null"],"description":"Pass as `?cursor=` to fetch the next page; null on the last page."},"has_more":{"type":"boolean"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}}}}
```

## List the canonical topic labels readable by the account

> Requires \`insights:read\`.

```json
{"openapi":"3.1.0","info":{"title":"Customer Alliance API","version":"4.3.0"},"tags":[{"name":"Insights","description":"AI recommendations, mentions and topics."}],"servers":[{"url":"https://app.customer-alliance.com/api/v4","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"An API key created in Settings → API (`ca_live_…`)."}},"schemas":{"Topic":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"language":{"type":["string","null"]},"parent_label_id":{"type":["string","null"],"format":"uuid"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The key lacks the required scope, the account's plan does not include it, or the key's owner no longer has the access it needs. The last is checked on every call: a key works only while the user who created it is active in the account and holds `api_keys.manage` where the key is bound, plus the permission behind each write scope it carries. Every call with such a key gets the same `403`, whatever its scope, until the owner's access is restored or an administrator creates a new key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/insights/topics":{"get":{"summary":"List the canonical topic labels readable by the account","description":"Requires `insights:read`.","operationId":"listTopics","tags":["Insights"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Topic"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}}}}
```
