> ## Documentation Index
> Fetch the complete documentation index at: https://docs.borga.is/llms.txt
> Use this file to discover all available pages before exploring further.

# Borga REST API reference overview

> Full REST API reference for Borga. Base URL https://api.borga.is. Authenticates with API keys. All requests and responses use JSON over HTTPS.

Borga's API is REST over HTTPS. Request and response bodies are JSON. Every request authenticates with an API key passed as a Bearer token. The base URL for all endpoints is `https://api.borga.is`.

## Base URL

```
https://api.borga.is
```

All endpoints are versioned under `/v1/`. A full endpoint path looks like `https://api.borga.is/v1/payments`.

## Authentication

Pass your secret API key in the `Authorization` header as a Bearer token. Most endpoints also require an `X-Merchant-Id` header identifying the merchant account.

```
Authorization: Bearer sk_live_…
X-Merchant-Id: mer_xxx
```

Use `sk_test_…` keys during development — they make no real charges. Switch to `sk_live_…` when you are ready to process real transactions.

<Note>
  The `GET /v1/merchants/current` endpoint does not require `X-Merchant-Id`. Use it to look up your Merchant ID during initial setup.
</Note>

For full details on key types, scopes, and error handling, see [Authentication](/authentication).

## Request format

Set `Content-Type: application/json` and pass parameters as a JSON body on `POST` and `PATCH` requests.

```bash curl theme={null}
curl --request GET \
  --url https://api.borga.is/v1/merchants/current \
  --header "Authorization: Bearer sk_test_YOUR_SECRET_KEY"
```

## Pagination

List endpoints use cursor-based pagination. Pass `starting_after` with the ID of the last object you received to fetch the next page, and use `limit` to control page size.

| Parameter        | Type    | Description                          |
| ---------------- | ------- | ------------------------------------ |
| `starting_after` | string  | Return objects after this object ID. |
| `limit`          | integer | Maximum number of objects to return. |

<Tip>
  Store the `id` of the last item on each page and pass it as `starting_after` on the next request. This approach handles insertions and deletions more reliably than offset-based pagination.
</Tip>

## Idempotency

Network failures can leave you uncertain whether a request was processed. Pass an `Idempotency-Key` header with a unique string on `POST` requests to safely retry without risking duplicate operations. Borga stores the result of the first request and returns the same response for any subsequent request with the same key.

```
Idempotency-Key: a1b2c3d4-e5f6-7890-abcd-ef1234567890
```

A UUID generated per operation works well as an idempotency key. Do not reuse a key for a different operation — Borga deduplicates on the key alone.

## Versioning

All endpoints are under `/v1/`. Breaking changes will be introduced under a new version prefix. The current version will continue to be supported after a new version is released.

## Rate limits

Rate limits apply to all API endpoints. If you exceed the limit, Borga returns `429 Too Many Requests`. Back off and retry after a short delay. See [Errors](/api-reference/errors) for details on the error response format.