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

# Retempo REST API — Complete Reference and Overview

> Base URL, request and response format, HTTP status conventions, and a complete summary table of every endpoint in the Retempo REST API.

The Retempo API is a REST API that lets you programmatically manage services, payment plans, checkout sessions, usage events, invoices, and on-chain USDC settlements. All resources are accessible under `https://api.retempo.xyz/api/v1`. Every request and response uses JSON, and your API key is sent with each call.

## Base URL

```
https://api.retempo.xyz
```

All API endpoints are mounted under `/api/v1`. Construct the full URL for any request by appending the endpoint path:

```
https://api.retempo.xyz/api/v1/<endpoint>
```

## Request Format

All `POST` requests must include a `Content-Type: application/json` header and send a valid JSON object as the body. `GET` requests do not require a body.

```bash theme={null}
Content-Type: application/json
```

Example POST request:

```bash theme={null}
curl -X POST https://api.retempo.xyz/api/v1/services \
  -H "Content-Type: application/json" \
  -d '{ "name": "My Service" }'
```

<Note>
  Requests that omit `Content-Type: application/json` on write operations will receive a `400 Bad Request` response with `{ "error": "Request body must be a JSON object." }`.
</Note>

## Response Format

Every response body is JSON. Successful responses return the created or retrieved resource nested under a named key (for example, `service`, `plan`, or `invoice`). Error responses return a single `error` string describing what went wrong.

**Success shape:**

```json theme={null}
{
  "service": { "id": "clz1abc2def3ghi4", "name": "DataStream Pro" }
}
```

**Error shape:**

```json theme={null}
{
  "error": "Service was not found."
}
```

HTTP status codes follow standard REST conventions: `200` for successful reads and idempotent returns, `201` for successful creates, `400` for validation errors, `404` for missing resources, `409` for conflicts, and `500` for unexpected server errors.

## Endpoints Summary

| Method | Endpoint                                       | Description                         |
| ------ | ---------------------------------------------- | ----------------------------------- |
| `POST` | `/api/v1/services`                             | Create a new service                |
| `GET`  | `/api/v1/services`                             | List all services                   |
| `GET`  | `/api/v1/services/:serviceId`                  | Get a single service by ID          |
| `POST` | `/api/v1/services/:serviceId/plans`            | Create a payment plan for a service |
| `GET`  | `/api/v1/services/:serviceId/plans`            | List all plans for a service        |
| `POST` | `/api/v1/checkout-sessions`                    | Create a checkout session           |
| `GET`  | `/api/v1/checkout-sessions/:checkoutSessionId` | Get a checkout session by ID        |
| `POST` | `/api/v1/usage-events`                         | Record a usage event                |
| `POST` | `/api/v1/invoices`                             | Create an invoice                   |
| `GET`  | `/api/v1/invoices/:invoiceId`                  | Get a single invoice by ID          |
| `POST` | `/api/v1/settlements`                          | Submit a USDC settlement            |
| `GET`  | `/api/v1/settlements/:settlementId`            | Get a settlement by ID              |

## Health Check

Verify that the API is reachable at any time by calling the health endpoint. This endpoint requires no authentication and returns basic service information.

```bash theme={null}
curl https://api.retempo.xyz/health
```

```json theme={null}
{
  "ok": true,
  "service": "Retempo",
  "apiRoot": "/api/v1"
}
```

<Tip>
  Use the health check endpoint in your deployment pipelines or monitoring dashboards to confirm API availability before sending live traffic.
</Tip>

## Explore Key Sections

<CardGroup cols={2}>
  <Card title="Create a Service" icon="server" href="/api/services/create">
    Register a new service and assign an owner. Services are the top-level resource that payment plans, checkout sessions, and settlements attach to.
  </Card>

  <Card title="Create a Plan" icon="rectangle-list" href="/api/plans/create">
    Define a payment plan for your service — fixed recurring, usage-based, or one-time — priced in USDC with a configurable billing interval.
  </Card>

  <Card title="Create a Checkout Session" icon="credit-card" href="/api/checkout/create">
    Generate a checkout session that lets a payer subscribe to one of your plans with USDC.
  </Card>

  <Card title="Submit a Settlement" icon="money-bill-transfer" href="/api/settlements/create">
    Submit an on-chain USDC settlement to record confirmed payment and close an invoice.
  </Card>
</CardGroup>