Confirm an AI suggestion

Módulo Settings

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`.

Requiere la capacidad home.dashboard.read.
Alcances de OAuth: home.
Envía el encabezado Idempotency-Key. Una repetición con la misma clave devuelve la respuesta original.
Estados de error: 400, 401, 404, 409, 422, 429. Los errores son detalles de problema RFC 9457.

Parámetros de ruta y de consulta

aiSuggestions.confirm: Parámetros de ruta y de consulta
Campo	Tipo	Obligatorio	Descripción
id	string (uuid)	Sí	Identifier of the ai suggestion.

Cuerpo de la solicitud: AiSuggestionConfirmRequest

aiSuggestions.confirm: AiSuggestionConfirmRequest
Campo	Tipo	Obligatorio	Descripción
reason	string	Sí	Why, recorded in the suggestion ledger.Restricciones: 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"
  }
}

Respuesta 200: AiSuggestion

aiSuggestions.confirm: AiSuggestion
Campo	Tipo	Obligatorio	Descripción
id	string (uuid)	Sí	Identifier of the ai suggestion.
org_id	string (uuid)	Sí	Identifier of the owning organization, derived from the parent row and never accepted from the caller.
created_at	string (date-time)	Sí	When the row was created.
created_by	string (uuid) \| null	Sí	Identifier of the person who created the row.
updated_at	string (date-time)	Sí	When the row was last updated.
updated_by	string (uuid) \| null	Sí	Identifier of the person who last updated the row.
request_id	string (uuid)	Sí	Identifier of the AI request that proposed the change.
operation_id	string	Sí	Public API operation that performs the change.Restricciones: length 1 to 100
target_id	string (uuid) \| null	Sí	Identifier of the record the change updates; null when it creates one.
summary	string	Sí	What will change, shown on the confirmation step.Restricciones: length 1 to 1000
suggestion_state	AiSuggestionState	Sí	Proposed and waiting for the person who asked, Confirmed by them, Applied once the public API accepted the write, Rejected, or Expired unanswered.Restricciones: one of "Proposed", "Confirmed", "Applied", "Rejected", "Expired"
expires_at	string (date-time)	Sí	After this time the suggestion can no longer be confirmed.
applied_id	string (uuid) \| null	Sí	Identifier of the record the public API wrote, once Applied.
proposed_fields	array of AiSuggestionField	Sí	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"
    }
  ]
}

Ejemplos de código

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"}}'