suggestReason

query · in the family Reading your records

What it does

Draft a short reason for the change you are about to save — composed from what actually changed.

Suggest a short change-log reason for the edit you are about to save: the model drafts ONE plain sentence (two at most) from the change summary the office composed — what changed, and where the summary makes it obvious, why. It never invents facts beyond the summary. The answer arrives trimmed and bounded 1..256 like every stored cause reason. type is the record kind word (prompt context only); text is the change summary (<= 500 chars). NOTHING auto-applies — the answer pre-fills the reason input. Refuses INTEGRATION/UNAVAILABLE while the assistant is offline/keyless — write the reason by hand. Requires authentication (user sessions). Every made call is cost-metered (at.ai.call.v1).

What happens

A drafting assist: the suggestion only fills the reason box, and nothing saves until you press Save. It never invents facts beyond your own changes. Each use makes one metered AI call.

Who may call it

Capability area: Reading your records — Looking up and listing the records of your organization.

• Owner
• System Administrator
• Manager
• Associate Manager
• Warehouse Associate
• Sales Associate
• An API key whose scope allows api:suggestReason

Arguments

Returns

SuggestedReason SuggestedReason! — The reason assist's answer: ONE drafted change-log reason, trimmed and bounded like every stored cause reason. It pre-fills the reason input — NOTHING auto-applies.

Example request

query ExampleSuggestReason($type: String!, $text: String!) {
  suggestReason(type: $type, text: $text) {
    suggestion
  }
}

Variables:

{
  "type": "<type>",
  "text": "Restock before the weekend."
}

Example response

{
  "data": {
    "suggestReason": {
      "suggestion": "<suggestion>"
    }
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": null,
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}

Errors this call can answer

• VALIDATION/INVALID — Something in the request is not valid. (VALIDATION)
• AUTHN/REQUIRED — Sign in to do this. (AUTHN)
• AUTHZ/FORBIDDEN — Your role does not allow this action. (AUTHZ)
• RATE_LIMIT/THROTTLED — Too many requests in a short time. (RATE_LIMIT)