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

# Public API

> Automate proxy management, monitor traffic, and query geo data with the Catproxy REST API.

The Catproxy Public API gives you programmatic access to everything you can do in the dashboard: create and configure proxies, track usage, manage your balance, and look up geo data - all over HTTPS with JSON.

<CardGroup cols={2}>
  <Card title="Interactive Swagger UI" icon="code" href="https://api.catproxy.io/swagger/index.html">
    Explore and test every endpoint directly in your browser.
  </Card>

  <Card title="Postman Collection" icon="circle-down" href="/downloads/catproxy-public-api.postman_collection.json" download>
    Import the ready-made collection and start making requests in minutes.
  </Card>
</CardGroup>

***

## Base URL

All API requests go to:

```
https://api.catproxy.io
```

***

## Authentication

The API uses **API keys** passed in a request header. Every request must include:

```http theme={null}
X-API-Key: cat_YOUR_API_KEY
```

**Getting an API key:**

1. Open the [Dashboard](https://catproxy.io/app) and go to **API Keys** in the sidebar.
2. Click **Create API Key** and select the permissions you need.
3. Copy the key - it is shown only once.

<Warning>
  API keys are secrets. Do not commit them to version control or expose them in client-side code. Rotate a key immediately if it is ever leaked.
</Warning>

### Scopes

Each API key carries one or more scopes that gate access to endpoint groups. Request only the scopes your integration needs.

| Scope           | Grants access to                     |
| :-------------- | :----------------------------------- |
| `proxies:read`  | List and retrieve proxy details      |
| `proxies:write` | Create, update, and delete proxies   |
| `stats:read`    | Traffic statistics and usage export  |
| `balance:read`  | Account balance and balance history  |
| `geo:read`      | Country, state, city, and ZIP lookup |

`proxies:write` does **not** include `proxies:read` - the scopes are independent.

***

## Request Format

For endpoints that accept a body (`POST`, `PUT`), send JSON and set the `Content-Type` header:

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

***

## Response Format

All responses are JSON wrapped in a standard envelope:

```json theme={null}
{
  "result": true,
  "data": { ... },
  "error": "",
  "error_type": "",
  "meta": {}
}
```

| Field        | Type           | Description                                     |
| :----------- | :------------- | :---------------------------------------------- |
| `result`     | boolean        | `true` on success, `false` on error             |
| `data`       | object / array | The response payload                            |
| `error`      | string         | Human-readable error message (empty on success) |
| `error_type` | string         | Machine-readable error code (empty on success)  |
| `meta`       | object         | Pagination or other metadata where applicable   |

***

## Error Handling

Error responses use standard HTTP status codes alongside the envelope:

```json theme={null}
{
  "result": false,
  "error": "API key not found or expired",
  "error_type": "unauthorized"
}
```

| HTTP Status        | Meaning                                                    |
| :----------------- | :--------------------------------------------------------- |
| `400 Bad Request`  | Invalid input - check the request body or query parameters |
| `401 Unauthorized` | Missing or invalid API key                                 |
| `403 Forbidden`    | Valid key, but insufficient scope for this endpoint        |
| `404 Not Found`    | The requested resource does not exist                      |

***

## Quick Example

Retrieve all your proxies with a single `curl` call:

```bash theme={null}
curl https://api.catproxy.io/v1/proxy \
  -H "X-API-Key: cat_YOUR_API_KEY"
```

See the [Swagger UI](https://api.catproxy.io/swagger/index.html) for a full interactive reference of every endpoint, including request schemas and live response examples.