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. The control exists only when the response contains a structured pending confirmation; assistant prose cannot create one. For reports, integration requests, and asks, Murph uses this staged control as the filing offer, and no team-visible record exists until the approved replay succeeds. On Murph UI-control surfaces, an ordinary-language reply that clearly approves the action—such as “yes”, “yep”, “sounds good”, or an equivalent in the user’s language—is also accepted for the exact pending action. Murph interprets the reply semantically; ambiguous, conditional, or conflicting replies do not execute. Phrase-token API/MCP flows still require the exact confirmation phrase. Filing an ask offers the control before anything reaches the Scope3 team, and it always does so when the same conversation has already read content Murph did not author — an uploaded document, a search result, or a response from another agent. Text from those sources can contain an instruction, and your approval is what stops such an instruction from putting a request in the Scope3 queue that looks like you sent it. Murph also looks into a problem before offering to file it, so on a broken-or-blocked ask the approval offer arrives after that check rather than instead of it.

​
Confirmation lifecycle

  1. Send a normal Murph chat request.
  2. If the response includes pendingConfirmations (or pendingConfirmation), show the proposed action and an approve/cancel control for each entry.
  3. POST each user 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.
Prefer pendingConfirmations (plural). Murph can propose multiple gated writes in a single turn (e.g. queue N delete_campaign calls). Older clients that only read pendingConfirmation (singular) render just the first widget and silently drop the rest. New clients should iterate pendingConfirmations and render one approve/cancel control per entry; each entry has its own confirmationUid and is decided independently.
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 fields

POST /api/v2/murph/chat and POST /api/v2/murph/chat/stream can return two related fields on a turn where one or more protected writes were proposed but did not run:
  • pendingConfirmations (array, new) — every pending confirmation issued this turn, in tool-call order. Render one approve/cancel control per entry. Empty (or omitted) when nothing gated this turn. New callers should prefer this field.
  • pendingConfirmation (object, retained) — the first entry from pendingConfirmations, or null. Kept for back-compat with clients that render at most one confirmation per turn (Slack, older SDKs). A client that reads only this field will silently drop the remaining N-1 controls when Murph gates multiple writes in one turn.
Each entry (in either field) uses this shape:

​
Confirm or cancel

POST /api/v2/murph/confirmations/{confirmationUid}/decision

​
Request body

​
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. If the approved tool returns an error, Murph distinguishes outcomes only when the tool can prove the failure happened before any durable write could take effect. In that case Murph says that nothing was written and can offer a fresh approval after the cause is corrected. For timeouts, transport failures, server errors, and tools that provide no proof, Murph reports the outcome as unknown and asks you to verify the current state before retrying. This conservative default prevents an already-applied write from being repeated after its response was lost.

​
Cancel response

When decision is cancel, no write runs and the response only records the cancelled confirmation.

​
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 account.
  • 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.