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

# Partner API reference

> Technical reference for the Contro Partner API

## Base URL

All Partner API requests use the following base URL:

```
https://api.contro.me/v1
```

## Authentication

Include your API key in the `x-contro-api-key` header:

```
x-contro-api-key: sk_live_...
```

| Environment | Key prefix | Base URL |
| - | - | - |
| Sandbox | `sk_test_*` | `https://api.contro.me/v1` |
| Production | `sk_live_*` | `https://api.contro.me/v1` |

<Warning>
  Never expose your API keys in client-side code or public repositories.
</Warning>

## Request format

* All request bodies must be JSON with `Content-Type: application/json`
* Path parameters are denoted by `{id}` in endpoint paths
* Query parameters are used for filtering and pagination

## Response format

Successful responses return the requested resource or a success indicator:

```json theme={null}
{
  "id": "ch_abc123",
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane@example.com",
  "status": "active"
}
```

List endpoints return paginated results:

```json theme={null}
{
  "data": [...],
  "page": 1,
  "limit": 20,
  "total": 137
}
```

## Pagination

List endpoints support page-based pagination with two query parameters:

| Parameter | Type | Default | Description |
| - | - | - | - |
| `page` | integer | 1 | Page number (1-indexed) |
| `limit` | integer | 20 | Items per page (1–100) |

Increment `page` to walk through results. You have reached the end when `page * limit >= total`.

## Rate limiting

The Partner API allows **1,000 requests per minute** per API key. When exceeded:

* Response status: `429 Too Many Requests`
* The `Retry-After` header indicates seconds to wait before retrying

## Errors

All errors return a consistent format:

```json theme={null}
{
  "success": false,
  "error": "Human-readable error message"
}
```

| Status | Meaning |
| - | - |
| 400 | Bad request — invalid parameters |
| 401 | Unauthorized — missing or invalid API key |
| 404 | Not found — resource does not exist |
| 429 | Rate limited — too many requests |
| 500 | Internal server error |

See the [errors guide](/partner/errors) for troubleshooting details.

## Resources

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/partner/authentication">
    API key setup and security best practices
  </Card>

  <Card title="Quickstart" icon="rocket" href="/partner/quickstart">
    Issue your first card in 5 steps
  </Card>

  <Card title="Webhooks" icon="bell" href="/partner/webhooks">
    Real-time event notifications
  </Card>

  <Card title="Errors" icon="circle-exclamation" href="/partner/errors">
    Error codes and troubleshooting
  </Card>
</CardGroup>