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

# 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`](/docs/tools/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](/docs/get-started/scope-and-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](/docs/tools/overview#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`:

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

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.

**Call request-approval**

**Wexa MCP server**

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

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

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

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

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

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

## 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](/docs/tools/errors#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.

## See also

[`get-approval`](/docs/tools/get-approval) to read the decision,
[the tool index](/docs/tools/overview), [errors](/docs/tools/errors),
and [which identifier goes where](/docs/tools/identifiers).