> For the complete documentation index, see [llms.txt](https://docs.wandreferrals.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.wandreferrals.com/integrations-and-api-production-rollout-gate-pending/public-api.md).

# Public REST API overview

> **Production status:** The public API rollout is not approved. The repository does not yet enforce a universal production kill switch for every API route, so deployment configuration alone must not be treated as a safety boundary. This guide documents the implemented preview surface for authorized validation only. Production use requires a server-side gate, verified denial evidence, review, and a separate rollout approval.

## What it does

Wand Referrals has a public REST API (`/api/v1/*`) so you or your developer can read and manage your affiliate data programmatically — affiliates, programs, commissions, payouts, coupons, analytics, click journeys, outbound webhooks, and server-side conversions.

## Plan requirement

API access is a **Professional-plan** feature. See [Billing plans](https://github.com/wand-referrals-app/wand-referrals/tree/codex/gitbook-docs-foundation/docs/manual/account/billing-plans/README.md).

> **Read and write access.** A Professional API key supports the full documented read/write API. Grandfathered Enterprise shops retain the same access with their existing higher rate limit for compatibility; Enterprise is not an upgrade target.

## Get your key

Mint and manage scoped API keys on the **Developer** page — see [Developer — API keys, events & webhooks](https://github.com/wand-referrals-app/wand-referrals/tree/codex/gitbook-docs-foundation/docs/manual/integrations/developer-api-keys/README.md). Send the key as a Bearer token:

```
Authorization: Bearer <api_key>
```

Your shop (tenant) is resolved from the key server-side, and the key is stored hashed at rest. Treat it like a password.

## For developers

* **Full REST reference (endpoints, params, examples):** [`docs/api/reference.md`](/integrations-and-api-production-rollout-gate-pending/reference.md)
* **Machine-readable spec:** [`docs/api/openapi.yaml`](https://github.com/wand-referrals-app/wand-referrals/tree/codex/gitbook-docs-foundation/docs/api/openapi.yaml)
* **Legacy quick-start HTML (no auth, partial):** `https://wandreferrals.com/api/v1/docs` — it omits the Events and Journey endpoints; use the reference and OpenAPI file above for the complete contract.
* **Outbound webhooks + HMAC:** [`docs/api/webhooks.md`](/integrations-and-api-production-rollout-gate-pending/webhooks.md)

## Related

* [Integrations overview](https://github.com/wand-referrals-app/wand-referrals/tree/codex/gitbook-docs-foundation/docs/manual/integrations/overview/README.md)
* [Outbound webhooks](https://github.com/wand-referrals-app/wand-referrals/tree/codex/gitbook-docs-foundation/docs/manual/integrations/outbound-webhooks/README.md)
* [Billing plans](https://github.com/wand-referrals-app/wand-referrals/tree/codex/gitbook-docs-foundation/docs/manual/account/billing-plans/README.md)