> Source: https://wexa.ai/docs/governance/request-approval

# request-approval

Ask a person in this project to approve something your app is about to do. It appears in the Approvals Inbox as an **App request**, and a project admin decides it, or someone above them in the organization. Needs no grant. It returns at once with the approval's id.

**Ask for an approval**

**Wexa MCP server**

```bash
curl -sS -X POST https://fabric.wexa.ai/mcp/$FABRIC_PROJECT_ID \
  -H "authorization: Bearer $FABRIC_API_KEY" \
  -H "Mcp-Session-Id: $MCP_SESSION_ID" \
  -H "content-type: application/json" -H "accept: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"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}}}}'
```

```json
{
  "content": [
    {
      "type": "text",
      "text": "{\"lifecycle_id\":\"qlc_000043\",\"result\":{\"id\":\"ar_6abbaaa3fb130d22ba652a6c\",\"status\":\"pending\",\"risk\":\"high\",\"reference\":\"refund-1042\",\"expires_at\":\"2026-09-30T12:10:11.253931788Z\"}}"
    }
  ],
  "isError": false
}
```

**REST API**

```bash
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}}'
```

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

**TypeScript SDK**

```ts
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 }
})
```

```ts
// result is the payload itself, with no `.result` to read
{
  id: 'ar_6abbaaa3fb130d22ba652a6c',
  status: 'pending',
  risk: 'high',
  reference: 'refund-1042',
  expires_at: '2026-09-30T12:10:11.253931788Z'
}
```

**Python SDK**

```python
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},
)
```

```python
# out is the result, already unwrapped
{
    "id": "ar_6abbaaa3fb130d22ba652a6c",
    "status": "pending",
    "risk": "high",
    "reference": "refund-1042",
    "expires_at": "2026-09-30T12:10:11.253931788Z"
}
```

## Parameters

| Parameter | Type | Required | Notes |
| --- | --- | --- | --- |
| `choices` | array | Optional | Options the approver picks from, at most 10, none an empty string, each at most 64 characters. The pick comes back from `get-approval` as `choice`. |
| `payload` | object | Optional | Details shown to the approver with the request. An object, at most 64 KiB as JSON. |
| `reason` | string | Optional | Why your app needs it, at most 4000 characters. Shown to the approver. |
| `reference` | string | Required | Your app's own id for this request, at most 200 characters. The same reference while the approval is open returns that approval. Non-empty. While the open approval for it is being decided, the call is refused (409): call again once the decision lands. |
| `risk` | string | Optional | `low`, `medium` or `high`. Default `medium`. Sets the approver's deadline. Any other value is refused. |
| `title` | string | Required | What the approver is asked to allow, in one line, at most 200 characters. Non-empty. |

**Errors**

- `ApprovalError`: only when an SDK waits for the decision and the approval was rejected, expired or went overdue, or no decision arrived in time.

**Show full response**

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

**Result of request-approval**

**REST API**

```json
{
  "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"
  }
}
```

**Wexa MCP server**

```json
{
  "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
}
```

**TypeScript SDK**

```ts
// 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'
```

**Python SDK**

```python
# 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
```

**More details**

Read the decision with [`get-approval`](/docs/governance/get-approval), or let an SDK wait for it. For how approvals are decided and resumed, see [policy and approvals](/docs/governance/policy-and-approvals).

`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 in another project is a separate approval there.

- `high`: deadline (`expires_at`) 24 hours, expires (`hard_expires_at`) 48 hours.
- `medium` (default): deadline (`expires_at`) 48 hours, expires (`hard_expires_at`) 96 hours.
- `low`: deadline (`expires_at`) 72 hours, expires (`hard_expires_at`) 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.

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.

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.

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

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.

**Wait for the decision**

**TypeScript SDK**

```ts
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)
}
```

**Python SDK**

```python
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)
```

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.

Every tool call works the same way: [How every tool call works](/docs/sdks-and-apis/how-every-tool-call-works).