> ## Documentation Index
> Fetch the complete documentation index at: https://docs.receiptor.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Execute Capability

> Execute a capability by slug using API key authentication.

## Endpoint

`POST /v1/capabilities/:slug`

Authentication: API key required.

## Example: `documents.search`

```bash theme={null}
curl -s -X POST https://developer.api.receiptor.ai/v1/capabilities/documents.search \
  -H "Authorization: Bearer $RECEIPTOR_API_KEY" \
  -H "X-Receiptor-Org-Id: $RECEIPTOR_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "airbnb",
    "limit": 5,
    "docType": "receipt",
    "outputMode": "compact"
  }'
```

## Example: `documents.bulk-edit` dry run

```bash theme={null}
curl -s -X POST https://developer.api.receiptor.ai/v1/capabilities/documents.bulk-edit \
  -H "Authorization: Bearer $RECEIPTOR_API_KEY" \
  -H "X-Receiptor-Org-Id: $RECEIPTOR_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant": "Uber",
    "changes": { "category": "Transport" },
    "dryRun": true
  }'
```

`documents.bulk-edit` defaults to preview mode (`dryRun: true`). Set `dryRun: false` to apply changes.

## Approval-required execution

If you call a gated capability in execute mode, the API returns an approval payload instead of running it immediately.

Example cases:

* `documents.bulk-edit` with `dryRun: false`
* `documents.resolve-duplicates` with `dryRun: false`
* `integrations.send-to-integration` with `dryRun: false`
* `integrations.unlink-document` with `dryRun: false`
* `entities.cleanup` with `dryRun: false`
* `rules.execute` with `dryRun: false`

```json theme={null}
{
  "status": "approval_required",
  "approvalRequestId": "01J...",
  "capability": {
    "name": "bulkEditDocuments",
    "slug": "documents.bulk-edit"
  },
  "title": "Apply bulk edit",
  "description": "Bulk editing updates multiple documents and requires approval before execution."
}
```

Approve or reject through the approval capabilities documented in [Capability Approvals](/api/capabilities/approvals).

## Common errors

* `401` missing/invalid API key
* `401` missing org context (`Organization context required`)
* `403` API key restricted to a different workspace
* `404` unknown capability slug
* `400` input validation errors