> ## 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.

# Resumen de la API

> Conceptos básicos de la REST API, incluyendo URL base, autenticación, errores y rate limits.

La API de Faces es una REST API que te permite generar y gestionar de forma programática presentaciones interactivas y explorables. Pitches, portafolios, guías y propuestas. Describe lo que quieres en un prompt y Faces lo construye.

## URL base

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

## Autenticación

Incluye tu API key como un Bearer token:

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

Consulta [Autenticación](/es/authentication) para aprender cómo crear una key.

## Formato de las requests

* Todos los cuerpos de request son JSON (`Content-Type: application/json`)
* Todas las responses son JSON

## Responses de error

Los errores devuelven un cuerpo JSON con un campo `error` y, opcionalmente, un `hint`:

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

| Status | Significado                                        |
| ------ | -------------------------------------------------- |
| `400`  | Cuerpo o parámetros de request inválidos           |
| `401`  | API key ausente o inválida                         |
| `402`  | Créditos insuficientes para iniciar una generación |
| `403`  | La acción requiere un plan de pago                 |
| `404`  | Recurso no encontrado                              |
| `409`  | Conflicto (URL, subdominio o dominio ya en uso)    |
| `429`  | Rate limit excedido (50 req/min)                   |
| `500`  | Error interno del servidor                         |
| `502`  | No se pudo despachar la generación                 |

## Rate limits

Todos los endpoints comparten un límite de **50 requests por minuto** por usuario. Cuando se excede:

* Status de la response: `429`
* Headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`

## Paginación

Los endpoints de listado usan paginación basada en cursores:

```bash theme={null}
# Primera página
GET /projects?limit=10

# Siguiente página (usa nextCursor de la response anterior)
GET /projects?limit=10&cursor=cm1abc123...
```