The RefCampaign API powers the shipped public merchant surface: campaigns, affiliates, applications, commissions, conversion attribution, and dashboard summaries.

Endpoints are versioned under `/api/v1/*` and authenticated with a Bearer token (prefixed `rc_live_` / `rc_test_`) issued from the dashboard. Responses follow a consistent envelope, errors return machine-readable codes, and the spec is published as OpenAPI 3.1.

## Where to start

* **[Getting started](/docs/api/getting-started)** — sign up, generate an API key, send your first request.
* **[Authentication](/docs/api/authentication)** — how API keys work, header format, and rotation.
* **[Integration / SDK](/docs/api/integration/sdk)** — drop the official `@refcampaign/sdk` package into a JS / TS app.
* **[Integration / S2S postback](/docs/api/integration/postback)** — track conversions directly from your backend without the SDK.
* **[Error handling](/docs/api/error-handling)** — error envelope, codes, retries.
* **[API reference](/docs/api/reference)** — auto-generated, every endpoint with try-it-out.

## Stability and versioning

The current public API version is `v1`. The URL prefix is the version contract:
public merchant API endpoints live under `/api/v1/*`, and the OpenAPI
document lists the supported operations. Responses do not currently include a
dedicated `RefCampaign-API-Version` header because the route prefix is the
authoritative version signal.

Deprecations are announced with a `Deprecation` HTTP header at least 90 days
before removal whenever a shipped `v1` operation needs to be retired.

## Public route boundaries

The public integration surface is the documented `/api/v1/*` merchant API plus
the explicitly documented SDK/browser endpoints and merchant webhook delivery
docs. Dashboard, admin, internal, auth, and provider webhook implementation
routes are application routes, not public API promises.

No endpoint is considered public just because it exists in the codebase. To be
public, a route must be intentionally exposed, covered by the OpenAPI registry,
and documented in the API reference.

## Breaking changes

Breaking changes require a new version prefix or an explicit deprecation window.
Examples include:

* Removing or renaming an endpoint.
* Removing a response field or changing its type or meaning.
* Renaming request fields, changing required fields, or rejecting a payload that
  was previously valid.
* Changing authentication, authorization, pagination, idempotency, or status-code
  semantics for an existing operation.

## Non-breaking changes

`v1` can receive compatible additions without a new version prefix. Examples
include:

* Adding a new optional request field.
* Adding a new response field.
* Adding a new endpoint under `/api/v1/*`.
* Adding a new error code for a new validation path while keeping the existing
  error envelope.
* Tightening documentation, examples, rate-limit explanations, or generated
  OpenAPI metadata without changing runtime behavior.

## SDK compatibility

The `@refcampaign/sdk` SDK v1 targets API v1. Any breaking API change requires
an SDK compatibility plan before release: supported SDK versions, migration
notes, and whether old SDK versions continue to work during the deprecation
window.

## Guardrails

The OpenAPI registry is the source of truth for public v1 route documentation,
and spec tests compare the documented operations with the implemented
`/api/v1/*` handlers. Those tests are the guardrail that prevents dashboard,
admin, internal, auth, or provider webhook implementation routes from being
documented as public by accident.

## Need help?

Open an issue on the [SDK repo](https://github.com/RefCampaign/sdk) or contact us through the merchant dashboard.