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

# API Reference

> Complete reference for all Stover API endpoints

## Base URL

All API requests should be made to:

```
https://api.stover.app
```

## API Versioning

The API uses URL versioning. The current version is `v1`:

```
https://api.stover.app/v1/contacts
https://api.stover.app/v1/posts/{platform}
https://api.stover.app/v1/webhooks/receive/{webhook_key}
```

## Authentication

Most endpoints require authentication via API key. See the [Authentication](/authentication) guide for details.

```bash theme={null}
Authorization: Bearer stover_pk_your_api_key
```

## Request Format

All request bodies should be JSON with the `Content-Type` header:

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

## Response Format

All responses are JSON. Successful responses follow this structure:

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

## Error Handling

Error responses include an error message and optional details:

```json theme={null}
{
  "status": 400,
  "error": "Validation failed",
  "message": "first_name is required",
  "details": {}
}
```

### HTTP Status Codes

| Code | Description                               |
| ---- | ----------------------------------------- |
| 200  | Success                                   |
| 201  | Created                                   |
| 400  | Bad Request - Validation error            |
| 401  | Unauthorized - Missing or invalid API key |
| 403  | Forbidden - Insufficient permissions      |
| 404  | Not Found                                 |
| 405  | Method Not Allowed                        |
| 413  | Payload Too Large                         |
| 429  | Too Many Requests - Rate limit exceeded   |
| 500  | Internal Server Error                     |

## Rate Limiting

| Mode                   | Limit                     |
| ---------------------- | ------------------------- |
| Authenticated          | 100 requests/minute       |
| Public (Contacts only) | 20 requests/minute per IP |

When rate limited, you'll receive a `429` response:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Please try again later."
}
```

## Pagination

List endpoints support pagination with `page` and `limit` query parameters:

```bash theme={null}
GET /v1/contacts?page=1&limit=20
```

Paginated responses include metadata:

```json theme={null}
{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}
```

## Available Endpoints

<CardGroup cols={2}>
  <Card title="Create Contact" icon="address-book" href="/api-reference/contacts/create">
    `POST /v1/contacts`
  </Card>

  <Card title="Create Post" icon="share-nodes" href="/api-reference/posts/overview">
    `POST /v1/posts/{platform}`
  </Card>

  <Card title="Receive Webhook" icon="webhook" href="/api-reference/webhooks/overview">
    `POST /v1/webhooks/receive/{key}`
  </Card>
</CardGroup>