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

# API Overview

> REST API basics, including base URL, authentication, errors, and rate limits.

The Faces API is a REST API that lets you programmatically generate and manage interactive, explorable decks. Pitches, portfolios, guides, and proposals. Describe what you want in a prompt, and Faces builds it.

## Base URL

```
https://faces.app/api/v1
```

## Authentication

Include your API key as a Bearer token:

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

See [Authentication](/en/authentication) for how to create a key.

## Request format

* All request bodies are JSON (`Content-Type: application/json`)
* All responses are JSON

## Error responses

Errors return a JSON body with an `error` field and optionally a `hint`:

```json theme={null}
{
  "error": "prompt is required",
  "hint": "POST /api/v1/projects/generate {\"prompt\": \"<text>\"}"
}
```

| Status | Meaning                                             |
| ------ | --------------------------------------------------- |
| `400`  | Invalid request body or parameters                  |
| `401`  | Missing or invalid API key                          |
| `402`  | Insufficient credits to start a generation          |
| `403`  | Action requires a paid plan                         |
| `404`  | Resource not found                                  |
| `409`  | Conflict (URL, subdomain, or domain already in use) |
| `429`  | Rate limit exceeded (50 req/min)                    |
| `500`  | Internal server error                               |
| `502`  | Generation could not be dispatched                  |

## Rate limits

All endpoints share a **50 requests per minute** limit per user. When exceeded:

* Response status: `429`
* Headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`

## Pagination

List endpoints use cursor-based pagination:

```bash theme={null}
# First page
GET /projects?limit=10

# Next page (use nextCursor from previous response)
GET /projects?limit=10&cursor=cm1abc123...
```