List AI suggestion rows

Settings module

GET/ai-suggestionsaiSuggestions.list

A change an Aurora feature proposes, waiting for the confirmation of the person who asked. The summary says exactly what will change; nothing is written until they confirm. Returns a cursor page of AI suggestion rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.

Requires the capability home.dashboard.read.
OAuth scopes: home.
Cursor-paginated: limit, cursor, fields, sort and filter apply.
Error statuses: 400, 401, 429. Errors are RFC 9457 problem details.

Path and query parameters

aiSuggestions.list: Path and query parameters
Field	Type	Required	Description
limit	Limit	No	Page size. Default 50, maximum 200.Constraints: range 1 to 200
cursor	Cursor	No	Opaque cursor from `next_cursor` of the previous page.Constraints: length 1 to any
fields	Fields	No	Sparse fieldset: a comma-separated list of top-level fields to return. `id` is always returned.Constraints: pattern ^[a-z_][a-z0-9_](,[a-z_][a-z0-9_])*$
sort	Sort	No	Sort keys, comma-separated; a leading `-` sorts descending. Without `sort`, the documented default order applies (coded lists sort in numeric code order).Constraints: pattern ^-?[a-z_][a-z0-9_](,-?[a-z_][a-z0-9_])*$
filter	Filter	No	Filter grammar `filter[field][op]=value`. Operators: eq, ne, lt, lte, gt, gte, in (comma-separated values), is_null (true or false) and contains. Conditions combine with AND.

Response 200: a page of AiSuggestion

aiSuggestions.list: AiSuggestion
Field	Type	Required	Description
id	string (uuid)	Yes	Identifier of the ai suggestion.
org_id	string (uuid)	Yes	Identifier of the owning organization, derived from the parent row and never accepted from the caller.
created_at	string (date-time)	Yes	When the row was created.
created_by	string (uuid) \| null	Yes	Identifier of the person who created the row.
updated_at	string (date-time)	Yes	When the row was last updated.
updated_by	string (uuid) \| null	Yes	Identifier of the person who last updated the row.
request_id	string (uuid)	Yes	Identifier of the AI request that proposed the change.
operation_id	string	Yes	Public API operation that performs the change.Constraints: length 1 to 100
target_id	string (uuid) \| null	Yes	Identifier of the record the change updates; null when it creates one.
summary	string	Yes	What will change, shown on the confirmation step.Constraints: length 1 to 1000
suggestion_state	AiSuggestionState	Yes	Proposed and waiting for the person who asked, Confirmed by them, Applied once the public API accepted the write, Rejected, or Expired unanswered.Constraints: one of "Proposed", "Confirmed", "Applied", "Rejected", "Expired"
expires_at	string (date-time)	Yes	After this time the suggestion can no longer be confirmed.
applied_id	string (uuid) \| null	Yes	Identifier of the record the public API wrote, once Applied.
proposed_fields	array of AiSuggestionField	Yes	Proposed fields in confirmation order.

{
  "data": [
    {
      "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
      "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
      "created_at": "2026-10-08T14:30:00Z",
      "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
      "updated_at": "2026-10-08T14:30:00Z",
      "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
      "request_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
      "operation_id": "insuranceCertificates.create",
      "target_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
      "summary": "Add the Atlantic Mutual general liability certificate.",
      "suggestion_state": "Proposed",
      "expires_at": "2026-10-08T14:30:00Z",
      "applied_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
      "proposed_fields": [
        {
          "field_path": "expires_on",
          "proposed_value": "2027-03-31",
          "confidence": 0.91,
          "refusal": null,
          "missing": null,
          "source_excerpt": "Policy expiration 03/31/2027",
          "provenance": "agent"
        }
      ]
    }
  ],
  "next_cursor": null
}

Code samples

curl -X GET "$XOS_BASE_URL/ai-suggestions" \
  -H "Authorization: Bearer $XOS_API_KEY"

for await (const row of xos.aiSuggestions.listAll()) {
  console.log(row);
}

for row in xos.ai_suggestions.list_all():
    print(row)

xos ai-suggestions list --all