> 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/api-essentials.md).

# API essentials

The RefKit REST API is available at:

```
https://app.refkit.net/v1
```

`GET /v1` returns the current machine-readable endpoint index.

## Authentication

Send API keys as Bearer tokens:

```http
Authorization: Bearer rk_app_...
```

| Credential      | Use                                                |
| --------------- | -------------------------------------------------- |
| Session         | Dashboard, organization, and user actions          |
| `rk_test_app_*` | App-scoped test capture, identify, and API revenue |
| `rk_app_*`      | App-scoped live capture, identify, and API revenue |
| `rk_aff_*`      | Affiliate self-service and links                   |

Keep App and Affiliate keys out of browser code. Public browser capture is the only integration call that does not require a key.

## Test and Live

The API key selects the mode:

* Test keys create isolated, non-payable activity.
* Live keys create activity used by live metrics and payouts.

Do not mix keys or IDs between modes when testing a flow.

## Errors

Errors use one shape:

```json
{
  "error": {
    "code": "click_not_found",
    "message": "Click not found."
  }
}
```

Use `error.code` for program logic. Treat `message` as diagnostic text.

Requests with a JSON body must send `Content-Type: application/json` (or a compatible `+json` media type). Empty, malformed, or non-JSON bodies return the standard `400` error envelope.

## Pagination

List endpoints accept:

* `limit`, from 1 to 100. The default is 25.
* `starting_after`, using the last returned resource ID.

The cursor must belong to the same App, Program, environment, and other filters as the requested list. A cursor from a different scope returns `invalid_starting_after`.

Response:

```json
{
  "data": [],
  "has_more": false
}
```

## Data conventions

* IDs have resource prefixes such as `app_`, `prg_`, `clk_`, and `txn_`.
* Money amounts are integers in minor units and must fit a signed 32-bit database integer.
* Payment amounts may be zero. Refund and dispute amounts must be positive.
* Currencies use lowercase ISO 4217 codes such as `usd`.
* Timestamps use ISO 8601.
* Stable payment, refund, and dispute IDs provide idempotency. Reusing an ID with a different immutable payload returns a conflict.