> For the complete documentation index, see [llms.txt](https://refkit.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://refkit.gitbook.io/docs/reference/rest-api.md).

# REST API

The REST API is the RefKit product contract. This page lists the core endpoints. `GET /v1` returns the full current index.

Use the [integration guides](/docs/integrate-refkit.md) for request examples.

## Apps and credentials

| Method         | Endpoint                    | Purpose                           |
| -------------- | --------------------------- | --------------------------------- |
| `GET`, `POST`  | `/v1/organizations`         | List or create organizations      |
| `GET`, `POST`  | `/v1/api-keys`              | List or create API keys           |
| `DELETE`       | `/v1/api-keys/:id`          | Revoke an API key                 |
| `GET`, `POST`  | `/v1/apps`                  | List or create Apps               |
| `GET`, `PATCH` | `/v1/apps/:id`              | Read or update an App             |
| `GET`          | `/v1/apps/:id/setup-status` | Read Test and Live setup status   |
| `GET`          | `/v1/apps/:id/overview`     | Read App metrics                  |
| `GET`, `PATCH` | `/v1/apps/:id/agreement`    | Read or publish the App agreement |

App logo upload and removal use `POST` and `DELETE /v1/apps/:id/logo`.

## Programs and affiliates

| Method         | Endpoint                             | Purpose                         |
| -------------- | ------------------------------------ | ------------------------------- |
| `GET`, `POST`  | `/v1/programs`                       | List or create Programs         |
| `GET`, `PATCH` | `/v1/programs/:id`                   | Read or update Program settings |
| `GET`, `POST`  | `/v1/programs/:id/terms`             | Read or publish Program terms   |
| `POST`         | `/v1/programs/:id/pause`             | Pause a Program                 |
| `POST`         | `/v1/programs/:id/resume`            | Resume a Program                |
| `POST`         | `/v1/programs/:id/disable`           | Disable a Program               |
| `GET`, `POST`  | `/v1/program-affiliates`             | List or invite affiliates       |
| `POST`         | `/v1/program-affiliates/:id/approve` | Approve an Affiliate            |
| `POST`         | `/v1/program-affiliates/:id/disable` | Disable an Affiliate            |
| `POST`         | `/v1/program-affiliates/:id/enable`  | Re-enable an Affiliate          |

## Affiliate links and joining

| Method            | Endpoint                                          | Purpose                                                |
| ----------------- | ------------------------------------------------- | ------------------------------------------------------ |
| `GET`             | `/v1/affiliate/programs/:programId/links`         | List an Affiliate's Program links                      |
| `POST`            | `/v1/affiliate/programs/:programId/links`         | Create a named link                                    |
| `DELETE`          | `/v1/affiliate/programs/:programId/links/:linkId` | Delete a named link                                    |
| `GET`, `POST`     | `/v1/program-affiliates/:id/links`                | List or create links for a Developer-managed Affiliate |
| `PATCH`, `DELETE` | `/v1/program-affiliates/:id/links/:linkId`        | Update or delete a Developer-managed Affiliate link    |
| `GET`             | `/v1/join/:programSlug`                           | Read hosted join-page data                             |
| `POST`            | `/v1/join/:programSlug`                           | Start hosted Affiliate signup                          |
| `POST`            | `/v1/join/:programSlug/confirm`                   | Confirm hosted Affiliate signup                        |

## Tracking and revenue

| Method        | Endpoint                    | Purpose                                   |
| ------------- | --------------------------- | ----------------------------------------- |
| `POST`        | `/v1/capture`               | Record an affiliate click                 |
| `POST`        | `/v1/identify`              | Identify a Customer and create a Referral |
| `GET`         | `/v1/clicks`                | List clicks                               |
| `GET`         | `/v1/referrals`             | List Referrals                            |
| `GET`, `POST` | `/v1/transactions`          | List or report payments                   |
| `POST`        | `/v1/transactions/refunds`  | Report a refund                           |
| `POST`        | `/v1/transactions/disputes` | Report dispute lifecycle changes          |
| `GET`         | `/v1/commissions`           | List commission entries                   |

Developer list endpoints accept `environment=test|live` where activity is mode-specific.

`POST /v1/identify` accepts `click_id` from ordinary App keys. Only managed provider services using managed revenue keys may instead send direct `promotion_code` evidence with `program_id` and `program_affiliate_id` when that Program enables promotion-code fallback. A valid click wins, and direct evidence stores a null click rather than creating one.

## Payouts

| Method        | Endpoint                                          | Purpose                                              |
| ------------- | ------------------------------------------------- | ---------------------------------------------------- |
| `GET`, `PUT`  | `/v1/payout-details`                              | Read or save Affiliate payout details                |
| `GET`         | `/v1/payout-balance`                              | Read payable balance                                 |
| `GET`, `POST` | `/v1/payout-requests`                             | List or create payout requests                       |
| `POST`        | `/v1/payout-requests/:id/decline`                 | Decline a request                                    |
| `GET`         | `/v1/ready-payouts`                               | List Affiliate payouts ready to pay                  |
| `POST`        | `/v1/ready-payouts/csv`                           | Export current payouts                               |
| `POST`        | `/v1/ready-payouts/:programAffiliateId/mark-paid` | Mark one Affiliate paid                              |
| `POST`        | `/v1/payout-batches/:id/dispatch`                 | Send a prepared batch to the App payout system       |
| `GET`         | `/v1/payout-executions/:id`                       | Fetch instructions with an exact App-scoped live key |
| `POST`        | `/v1/payout-executions/:id/succeeded`             | Report success with `Idempotency-Key`                |
| `POST`        | `/v1/payout-executions/:id/failed`                | Report failure with `Idempotency-Key`                |

## Outgoing webhooks

See [Outgoing webhooks](/docs/integrate-refkit/outgoing-webhooks.md) for dashboard configuration, supported events, payloads, headers, and signature verification.

| Method                 | Endpoint                                | Purpose                                            |
| ---------------------- | --------------------------------------- | -------------------------------------------------- |
| `GET`, `PUT`, `DELETE` | `/v1/apps/:appId/webhook`               | Read, configure, or remove the single App endpoint |
| `POST`                 | `/v1/apps/:appId/webhook/rotate-secret` | Rotate the HMAC signing secret                     |
| `POST`                 | `/v1/apps/:appId/webhook/test`          | Send one test attempt                              |
| `GET`                  | `/v1/apps/:appId/webhook/deliveries`    | Read delivery history                              |

Outgoing delivery is best-effort, has a three-second timeout, and is attempted once without automatic retry.

Payout details and balances require a `program_id`. Payouts contain live commissions only.

## Stripe connection

| Method | Endpoint                           | Purpose                             |
| ------ | ---------------------------------- | ----------------------------------- |
| `POST` | `/v1/stripe/connect-link`          | Create a Stripe App install link    |
| `POST` | `/v1/stripe/claim-pending-install` | Claim a completed installation      |
| `POST` | `/v1/stripe/disconnect`            | Disconnect Stripe Test or Live mode |