Confirm an AI suggestion
Settings module
POST/ai-suggestions/{id}/confirmaiSuggestions.confirm
Records the confirmation of the person who asked, then performs the named public operation as the caller with the proposed values and any `values` the caller changed or added. On success the suggestion is Applied with the record written. When the operation refuses, the suggestion returns to Proposed and the answer is that 422 refusal. Refused after expiry. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.
- Requires the capability home.dashboard.read.
- OAuth scopes: home.
- Send an Idempotency-Key header. A replay with the same key returns the original response.
- Error statuses: 400, 401, 404, 409, 422, 429. Errors are RFC 9457 problem details.
Path and query parameters
| Field | Type | Required | Description |
|---|---|---|---|
| id | string (uuid) | Yes | Identifier of the ai suggestion. |
Request body: AiSuggestionConfirmRequest
| Field | Type | Required | Description |
|---|---|---|---|
| reason | string | Yes | Why, recorded in the suggestion ledger.Constraints: length 1 to 500 |
| values | object | No | Field values to send instead of, or in addition to, the proposed ones: corrections the person made and context ids such as `document_id`. |
{
"reason": "Checked against the certificate.",
"values": {
"document_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"
}
}Response 200: 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. |
{
"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"
}
]
}Code samples
curl -X POST "$XOS_BASE_URL/ai-suggestions/0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/confirm" \
-H "Authorization: Bearer $XOS_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"reason":"Checked against the certificate.","values":{"document_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"}}'const { data } = await xos.aiSuggestions.confirm("0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", {
"reason": "Checked against the certificate.",
"values": {
"document_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"
}
});response = xos.ai_suggestions.confirm("0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", {"reason": "Checked against the certificate.", "values": {"document_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"}})xos ai-suggestions confirm 0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f --data '{"reason":"Checked against the certificate.","values":{"document_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"}}'