Skip to main content
Murph can propose durable writes while helping operate a storefront, such as filing a report, updating operating instructions, publishing storefront setup state, or changing other persistent configuration. For protected writes, Murph returns a structured confirmation request instead of executing the write immediately. Clients should render the confirmation as an explicit approve/cancel control. A plain chat reply like “yes” is not enough for these writes.

​
Confirmation lifecycle

  1. Send a normal Murph chat request.
  2. If the response includes pendingConfirmation, show the proposed action and an approve/cancel control.
  3. POST the user’s decision to the confirmation decision endpoint.
  4. If the user confirms, the response is a normal Murph chat response for the turn that executed the approved write.
  5. If the user cancels, the response only records the cancelled confirmation.
confirmationUid is short-lived, single-use, and bound to the authenticated actor, conversation, tool, and resolved parameters. Do not persist it as a long-term approval record.

​
Chat response field

POST /api/v2/murph/chat and POST /api/v2/murph/chat/stream can return pendingConfirmation on a turn where a protected write was proposed but did not run. 
{
  "data": {
    "conversationUid": "6e60d909-721e-41ca-85b8-4e5a72bbf792",
    "answer": "This action needs approval before it runs.",
    "toolsUsed": [],
    "escalated": false,
    "escalation": null,
    "customerSwitch": null,
    "pendingConfirmation": {
      "confirmationUid": "50669fad-52e1-43c8-9334-77bf14ba72eb",
      "toolName": "report_issue",
      "toolKey": "report_issue",
      "summary": "Run `report_issue`.",
      "policy": "always",
      "resolvedParams": {
        "title": "Checkout page error",
        "severity": "low"
      },
      "writeExecuted": false,
      "plainAffirmativeAccepted": false,
      "expiresAt": "2026-06-13T19:45:00.000Z"
    }
  }
}
FieldTypeNotes
confirmationUidUUIDPass this to the decision endpoint.
toolNamestringInternal Murph tool that requested the write.
toolKeystringStable key for the gated action.
summarystringHuman-readable action summary for the confirmation UI.
policy"always" or "tainted"Why the confirmation gate applied.
resolvedParamsobjectParameters the user is approving.
writeExecutedfalseThe write did not run on this turn.
plainAffirmativeAcceptedfalseThe user must use the confirmation control.
expiresAtdatetimeConfirmation expiry time.

​
Confirm or cancel

POST /api/v2/murph/confirmations/{confirmationUid}/decision 
curl -X POST "https://api.interchange.io/api/v2/murph/confirmations/50669fad-52e1-43c8-9334-77bf14ba72eb/decision" \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "decision": "confirm" }'

​
Request body

FieldTypeRequiredNotes
decision"confirm" or "cancel"YesConfirms or cancels the pending write.

​
Confirm response

When decision is confirm, the endpoint returns the same shape as a Murph chat response. The approved write may appear in toolsUsed, and fields such as escalated or customerSwitch reflect the write that actually ran. 
{
  "data": {
    "conversationUid": "6e60d909-721e-41ca-85b8-4e5a72bbf792",
    "answer": "Filed the report.",
    "toolsUsed": [
      {
        "name": "report_issue",
        "input": {
          "title": "Checkout page error",
          "severity": "low"
        },
        "output": "{ \"status\": \"filed\" }",
        "isError": false
      }
    ],
    "escalated": true,
    "escalation": null,
    "customerSwitch": null,
    "pendingConfirmation": null
  }
}

​
Cancel response

When decision is cancel, no write runs and the response only records the cancelled confirmation. 
{
  "data": {
    "confirmationUid": "50669fad-52e1-43c8-9334-77bf14ba72eb",
    "status": "cancelled"
  }
}

​
Errors

  • 400 VALIDATION_ERROR - the path or request body is malformed.
  • 404 NOT_FOUND - the confirmation is unknown, expired, cancelled, or already used.
  • 403 FORBIDDEN - the confirmation belongs to another actor or customer.
  • 503 SERVICE_UNAVAILABLE - Murph is not available to process a confirmed write.
See Errors for the full error contract.

Ask Murph

Use Murph to operate and troubleshoot your storefront.

Authentication

Authenticate Murph API requests.