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

# REST API overview

> Base URL, the response envelope, pagination, auth, and errors for app.reechee.io/api/v1.

The REST API is served from a single base URL:

```
https://app.reechee.io/api/v1
```

It is the source of truth for the platform - the [MCP server](/mcp/overview) is a thin
wrapper over these same endpoints.

## Authentication

Anonymous endpoints (product search, the pain-points taste, competitors) need nothing.
Everything else needs a paid-team API key, sent as a bearer token:

```bash theme={null}
curl "https://app.reechee.io/api/v1/credit-balance" \
  -H "Authorization: Bearer rch_live_your_key_here"
```

Create and revoke keys in the app under **Settings → API keys**. See the
[Authentication guide](/guides/authentication) for details.

## Response envelope

Every response is a JSON envelope. Success:

```json theme={null}
{
  "success": true,
  "data": { },
  "meta": { }
}
```

Failure:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "Resource not found",
    "details": null
  }
}
```

`data` is the payload (an object or an array). `meta` is optional and carries things
like `pagination` on list endpoints and an `upsell` CTA on anonymous tastes.

## Pagination

List endpoints are page-based (1-indexed). Pass `page` and `page_size` (max `100`,
default `20`). The response's `meta.pagination` tells you whether to keep going:

```json theme={null}
{ "page": 1, "page_size": 20, "has_more": true }
```

## Errors

Errors use a stable machine `code` plus a human `message`. The HTTP status matches the
code:

| Status | `code`             | When                                                |
| ------ | ------------------ | --------------------------------------------------- |
| 400    | `invalid_request`  | Malformed parameters or body.                       |
| 401    | `unauthorized`     | Missing, invalid, revoked, or expired API key.      |
| 402    | `payment_required` | Not enough credits for a credit-spending action.    |
| 403    | `forbidden`        | A limit was reached (e.g. the plan's product cap).  |
| 404    | `not_found`        | Unknown resource id.                                |
| 429    | `rate_limited`     | Rate limit exceeded - see the `Retry-After` header. |
| 500    | `internal_error`   | Something went wrong on our side.                   |

See the [error reference](/guides/errors) and [rate limits](/guides/rate-limits) for the
full story.

## Endpoints

Browse the full endpoint reference in this section - each page has request parameters,
schemas, and a live "Try it" playground.