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

# API overview

> REST + OpenAPI. One surface for everything an integrator needs.

The Caratuva API is a single REST surface served from `api.caratuva.com/v1`. It is designed for ERPs, marketplaces, and trade-finance platforms that want to add cross-border collection without building their own treasury, FX, or compliance stack.

* **Base URL** — `https://api.caratuva.com/v1`
* **Format** — JSON. Request bodies and responses are UTF-8 JSON.
* **Spec** — OpenAPI 3.x, served by the API host at `/docs-json`, with a browsable Swagger UI at `/docs`. These are reachable once the API host (`api.caratuva.com`) is publicly available. In the meantime, `pnpm dev` in the docs repo generates a local spec snapshot from a running API.

## Versioning

The current major version is `v1`, baked into the URL path. Breaking changes will land on `v2` rather than mutating `v1`. Non-breaking additions land on `v1` continuously.

## Capabilities

| Surface                   | What it does                                                                                                                         |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **API keys**              | Issue, list, and revoke server-to-server credentials per organization.                                                               |
| **Payment intents**       | Create payment requests with hosted payment links. The integrator-facing primary surface.                                            |
| **Invoices**              | Read invoice state for both API-created and dashboard-created invoices.                                                              |
| **Payments**              | Read the canonical payment view (collection, FX, settlement).                                                                        |
| **Webhook subscriptions** | Register and inspect outbound webhook endpoints; rotate signing secrets.                                                             |
| **Connected accounts**    | Onboard your own end clients (sellers/buyers) to KYB/KYC server-to-server and register a seller end client's PIX payout destination. |
| **Health**                | `/healthz` and `/readyz` probes (no auth).                                                                                           |

The flows that do not have a public API surface — your own organization's KYB submission and PIX destination, buyer KYC on the hosted payment page, and team management — live in the dashboard. They are too document-heavy and too security-sensitive to be useful through programmatic access.

## What's NOT in the API

We've deliberately kept some things out of the v1 API:

* **No buyer KYC on the hosted payment page via API.** Buyer KYC happens on the hosted payment page, where document capture, the verification selfie, and consent flows are first-class. You cannot upload a buyer's passport for the hosted flow via the API. (Onboarding your *own* end clients to KYB/KYC is available via [Connected accounts](/api-reference/connected-accounts).)
* **No configuration of your own organization's PIX destination.** Your org's PIX payout key is dashboard-only and gated by ownership. (A seller end client's PIX destination is set via connected-accounts `payout-config`.)
* **No buyer authentication.** Buyer sign-in lives on the hosted payment page.
* **No "skip KYC" flag.** Every buyer goes through identity verification on first payment, regardless of how the invoice was created.

## Auth schemes

| Scheme     | Header                               | Used by                                      |
| ---------- | ------------------------------------ | -------------------------------------------- |
| API key    | `X-API-Key: pk_<mode>_<id>.<secret>` | Server-to-server clients on the seller side. |
| Bearer JWT | `Authorization: Bearer <jwt>`        | Dashboard sessions.                          |

See [Authentication](/api-reference/authentication) for details, including idempotency and tenancy.

## Rate limits

Per-API-key rate limits apply on specific high-cost routes (e.g. payment-intent and invoice creation), not on every endpoint. There are no `X-RateLimit-*` response headers. When you exceed a limit, the API returns `429 RateLimitExceeded` with a `retryAfter` field (seconds) in the JSON body:

```json theme={null}
{
  "statusCode": 429,
  "error": "RateLimitExceeded",
  "message": "Rate limit exceeded. Retry after 30s.",
  "retryAfter": 30
}
```

Wait `retryAfter` seconds, then retry. Don't hammer.

## Idempotency

Resource-creating endpoints (`POST /v1/invoices`, `POST /v1/payment-intents`) accept an `Idempotency-Key` header (any UUID-like string). A replay with the same key returns the existing resource (re-serialized from storage, reflecting its current state) without re-executing side effects — there is no expiry. Always set one on retries. See [Authentication → Idempotency](/api-reference/authentication#idempotency).

## Where to next

* [Authentication](/api-reference/authentication) — credentials and tenancy.
* [B2B integration quickstart](/api-reference/b2b-quickstart) — your first paid intent in five steps.
* [Errors](/api-reference/errors) — error envelope and the codes you'll actually see.