API reference

Tip

The full interactive API reference with request builder is available via Swagger UI →

Base URL

https://api.vauchflow.com

Authentication

Include your secret API key in every request:

Authorization: Bearer vf_sk_YOUR_KEY

Agent keys (vf_ak_*) authenticate via the same Authorization: Bearer header for REST endpoints. The MCP endpoint conventionally uses the X-API-Key: header instead — see AI agents for details.

Request headers

Header	Description
Idempotency-Key	Supply a unique string per write request to safely retry on network failures without double-creating resources.
Vauchflow-Dry-Run: true	Preview an action without persisting it. The response is identical to the real response but includes "dry_run": true and "id": null. Supported on POST /v1/campaigns, PATCH /v1/campaigns/{id}, POST /v1/vouchers, POST /v1/customers, POST /v1/webhooks. Explicitly rejected (400) for POST /v1/vouchers/{code}/redeem, POST /v1/vouchers/bulk, and all DELETE endpoints.
Vauchflow-Agent-Context	Voluntary fingerprint header for AI agents. Format: agent=<id>;client=<name@version>;prompt_fp=<8hex>;conv=<id>. Maximum 512 bytes. See AI agents for allowed agent values and audit trail behaviour.

Vouchers

Method	Path	Description
POST	/v1/vouchers	Create a single voucher
POST	/v1/vouchers/bulk	Generate up to 50,000 codes (async)
GET	/v1/vouchers/{code}	Look up a voucher
POST	/v1/vouchers/{code}/validate	Check eligibility — no redemption consumed
POST	/v1/vouchers/{code}/redeem	Atomically redeem
POST	/v1/vouchers/{code}/rollback	Reverse a redemption within 30 minutes
PATCH	/v1/vouchers/{code}	Update metadata or expiry
GET	/v1/vouchers	Paginated list with filters

Campaigns

Method	Path	Description
POST	/v1/campaigns	Create a campaign with rules
GET	/v1/campaigns	List campaigns
GET	/v1/campaigns/{id}	Campaign detail + pool stats
PATCH	/v1/campaigns/{id}	Update name, end date, budget cap
POST	/v1/campaigns/{id}/pause	Pause or resume

Customers

Method	Path	Description
POST	/v1/customers	Register a customer reference (no PII required)
GET	/v1/customers/{id}/redemptions	Full redemption history
DELETE	/v1/customers/{id}	GDPR right to erasure
GET	/v1/customers/{id}/export	GDPR data portability (JSON or CSV)

Analytics

Method	Path	Description
GET	/v1/analytics/overview	Tenant-level summary
GET	/v1/analytics/campaigns/{id}	Per-campaign metrics + time series
GET	/v1/analytics/fraud	Velocity anomalies and fraud alerts
GET	/v1/reports/redemptions	Export full redemption log as CSV

API keys

Method	Path	Description
POST	/v1/api-keys	Create a secret or publishable key
POST	/v1/api-keys/agent	Create an agent key (vf_ak_*) — requires a secret key
GET	/v1/api-keys	List active keys
POST	/v1/api-keys/{id}/rotate	Rotate a secret key (agent keys not supported — revoke and recreate)
DELETE	/v1/api-keys/{id}	Revoke

MCP

Method	Path	Description
POST	/v1/mcp	Model Context Protocol JSON-RPC 2.0 endpoint — see MCP server

Agent approvals

‘Operator’ means a vf_sk_* secret key or a dashboard JWT with OWNER, ADMIN, or DEVELOPER role (for read endpoints) or OWNER/ADMIN only (for approve/reject). Agent keys (vf_ak_*) are limited to fetching their own queued entries by id.

Method	Path	Description	Caller
GET	/v1/agent-approvals	List pending agent actions	Operator only (SECRET_KEY or JWT OWNER/ADMIN/DEVELOPER)
GET	/v1/agent-approvals/{id}	Approval entry detail	Operator or originating agent key
POST	/v1/agent-approvals/{id}/approve	Approve and replay	Operator only (SECRET_KEY or JWT OWNER/ADMIN)
POST	/v1/agent-approvals/{id}/reject	Reject (final)	Operator only (SECRET_KEY or JWT OWNER/ADMIN)

Response codes

Code	Meaning
200	Success
201	Created
202	Accepted (async job started)
204	No content
400	Invalid request
401	Authentication failed
404	Resource not found
409	Already redeemed / duplicate
422	Validation failed, idempotency-key mismatch, or unsupported operation (e.g. rotating an agent key)
429	Rate limit exceeded — check Retry-After header