request-approval

Ask a person in this project to approve something your app is about to do. The request appears in the Wexa Approvals Inbox as an App request, beside every other approval in the project, and the same approver rules apply: a project admin of the project decides it, or someone above them in the organization.

The call returns at once with the approval's id. Read the decision with get-approval, or let an SDK wait for it.

One reference, one open approval

reference is your app's own id for the thing being approved: an order number, a refund id, a campaign id. Calling again with the same reference while the approval is still open returns that same approval rather than opening a second one, so a retry or a second worker never puts the same request in front of an approver twice. Once the approval is decided, the same reference opens a new approval.

A reference belongs to your project. The same reference used in another project is a separate approval there.

Deadlines

risk sets how long the approver has.

Risk	Deadline (`expires_at`)	Expires (`hard_expires_at`)
`high`	24 hours	48 hours
`medium` (default)	48 hours	96 hours
`low`	72 hours	144 hours

Past expires_at the approval is overdue: it stays in the Inbox and can still be decided. At hard_expires_at it is expired and can no longer be decided.

Choices

With choices, the Inbox shows one button per choice in place of Approve and Reject. Picking one approves the request with that choice, so the status is approved whichever was picked: read choice to act on it, and include an option such as hold when the approver needs a way to say no.

What it is called on each surface

The wire name is request-approval everywhere: it is what the Wexa MCP server advertises, the REST path is POST /v1/request-approval, and each SDK exposes it under its own language's naming convention.

Surface	Name
Wexa MCP server	`request-approval`
REST API	`POST /v1/request-approval`
TypeScript SDK	`fabric.requestApproval()`
Python SDK	`fabric.request_approval()`

Arguments

2 of the 6 arguments are required. Omitting a required one is refused before the tool runs, at the validation stage, so it costs nothing and changes nothing.

Argument	Type	Required	Notes
`choices`	array	Optional	Options the approver picks from, at most 10. The pick comes back from `get-approval` as `choice`.
`payload`	object	Optional	Details shown to the approver with the request. At most 64 KiB as JSON.
`reason`	string	Optional	Why your app needs it. Shown to the approver.
`reference`	string	Required	Your app's own id for this request, at most 200 characters.
`risk`	string	Optional	`low`, `medium` or `high`. Default `medium`.
`title`	string	Required	What the approver is asked to allow, in one line, at most 200 characters.

The organization, the project and the requester are not arguments you pass. They come from the credential you authenticated with: an API key requests as the admin who created it, and an SDK session requests as the user who signed in. org_id, organization_id, project_id, projectID, requested_by, requester and user_id are refused if you send them — see server-bound arguments.

What it returns

The three surfaces wrap this differently, and code written against one will not read another correctly — see return shape.

Field	Type	Notes
`id`	string	The approval id, `ar_...`. Pass it to `get-approval`.
`status`	string	`pending` for a new request. A repeat call returns the open approval's current status.
`risk`	string	`low`, `medium` or `high`.
`expires_at`	string	The deadline. After it the approval is `overdue`.
`hard_expires_at`	string	When the approval expires.
`reference`	string	The reference you passed.

A real response, captured from a live call to request-approval:

{
  "content": [
    {
      "type": "text",
      "text": "{\"lifecycle_id\":\"qlc_000046\",\"result\":{\"expires_at\":\"2026-10-02T12:10:43.940639977Z\",\"hard_expires_at\":\"2026-10-05T12:10:43.940639977Z\",\"id\":\"ar_6abbaac3fb130d22ba652a6f\",\"reference\":\"mcp-order-77\",\"risk\":\"low\",\"status\":\"pending\"}}"
    }
  ],
  "isError": false
}

{
  "lifecycle_id": "qlc_000043",
  "result": {
    "expires_at": "2026-09-30T12:10:11.253931788Z",
    "hard_expires_at": "2026-10-01T12:10:11.253931788Z",
    "id": "ar_6abbaaa3fb130d22ba652a6c",
    "reference": "refund-1042",
    "risk": "high",
    "status": "pending"
  }
}

// the object you get back IS the result — there is no `.result` to read
{
  expires_at: '2026-09-30T12:11:05.873226724Z',
  hard_expires_at: '2026-10-01T12:11:05.873226724Z',
  id: 'ar_6abbaad9fb130d22ba652a78',
  reference: 'campaign-c12',
  risk: 'high',
  status: 'pending'
}

// The TS SDK names these camelCase — lifecycleId, traceId — where Python uses
// lifecycle_id and trace_id. Both are non-enumerable: readable, but omitted by
// Object.keys() and JSON.stringify(). `result.lifecycleId` here is undefined.
result.lifecycleId // 'qlc_000055'

# a dict subclass; `result` is already unwrapped
{
 "expires_at": "2026-10-01T12:10:55.938521644Z",
 "hard_expires_at": "2026-10-03T12:10:55.938521644Z",
 "id": "ar_6abbaacffb130d22ba652a72",
 "reference": "inv-9",
 "risk": "medium",
 "status": "pending"
}

out.lifecycle_id  # 'qlc_000049' — an attribute, not a key

Keeping the lifecycle_id is what lets you ask later why a call was allowed, refused or held.

Calling it

The same call on all four surfaces. Pick a tab once and every code block in the documentation follows it.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "request-approval",
    "arguments": {
      "title": "Refund order 1042",
      "reference": "refund-1042",
      "reason": "Customer was charged twice",
      "risk": "high",
      "payload": { "order": "1042", "amount": 129 }
    }
  }
}

curl -sS https://fabric.wexa.ai/v1/request-approval \
  -H "authorization: Bearer $FABRIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"title":"Refund order 1042","reference":"refund-1042","reason":"Customer was charged twice","risk":"high","payload":{"order":"1042","amount":129}}'

import { Fabric } from '@wexa-fabric/sdk'

const fabric = new Fabric()
const result = await fabric.requestApproval({
  title: "Refund order 1042",
  reference: "refund-1042",
  reason: "Customer was charged twice",
  risk: "high",
  payload: { order: "1042", amount: 129 }
})

from wexa import Fabric

fabric = Fabric()
out = fabric.request_approval(
    title="Refund order 1042",
    reference="refund-1042",
    reason="Customer was charged twice",
    risk="high",
    payload={"order": "1042", "amount": 129},
)

Waiting for the decision

Both SDKs can wait for you. With wait set they poll get-approval until the approval reaches a final status. approved returns the approval as get-approval shows it. rejected, expired and overdue raise ApprovalError with the status in the message (approval rejected) and the approval in raw. If nothing final arrives within timeout seconds (default 600, checked every poll seconds, default 5), ApprovalError is raised too, and the approval stays open for you to read later.

import { ApprovalError, Fabric } from '@wexa-fabric/sdk'

const fabric = new Fabric()
try {
  const approval = await fabric.requestApproval({
    title: "Refund order 1042",
    reference: "refund-1042",
    wait: true,
    timeout: 3600,
    poll: 10
  })
  console.log(approval.decided_by, approval.decision_reason)
} catch (e) {
  if (!(e instanceof ApprovalError)) throw e
  console.log(e.message)
}

from wexa import ApprovalError, Fabric

fabric = Fabric()
try:
    approval = fabric.request_approval(
        title="Refund order 1042",
        reference="refund-1042",
        wait=True,
        timeout=3600,
        poll=10,
    )
    print(approval["decided_by"], approval.get("decision_reason"))
except ApprovalError as e:
    print(e)

Errors

Both SDKs raise the same typed errors, chosen from the gateway's own error string first and its HTTP status second. request-approval needs no grant, and reaches the classes every tool reaches — listed under the common set. These are the ones specific to it:

Error	Status	Raised when
`ValidationError`	422	`title` or `reference` is missing, `risk` is not `low`, `medium` or `high`, `payload` is not an object or is over 64 KiB, `choices` holds an empty string, or a server-bound argument was sent.
`ConflictError`	409	The open approval for this reference is being decided at this moment. Call again once the decision lands.
`ApprovalError`	—	Only when an SDK waits: the approval was rejected, expired or went overdue, or no decision arrived in time.
`ConfigurationError`	5xx	`request-approval` is not available to you. Retrying will not help.

Governance

Every call to request-approval runs through the same ten-stage lifecycle as every other Wexa tool: the credential is resolved to a scope, quota is drawn down, the arguments are validated, policy rules are evaluated, the call is executed, the result is shaped and redacted, and an audit record is written. The lifecycle_id in the response is the handle to that record.

request-approval is not marked consequential: asking for an approval is never itself held for approval, whatever the project's setting for consequential writes. The request is recorded in the approval audit trail when it is created and again when it is decided.