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

# Vue d'ensemble de l'API

> Les bases de l'API REST, notamment l'URL de base, l'authentification, les erreurs et les rate limits.

L'API Faces est une API REST qui vous permet de générer et de gérer de manière programmatique des decks interactifs et explorables. Pitches, portfolios, guides et propositions. Décrivez ce que vous voulez dans un prompt, et Faces le construit.

## URL de base

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

## Authentification

Incluez votre clé API en tant que Bearer token :

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

Consultez [Authentification](/fr/authentication) pour savoir comment créer une clé.

## Format des requests

* Tous les corps de request sont en JSON (`Content-Type: application/json`)
* Toutes les responses sont en JSON

## Responses d'erreur

Les erreurs renvoient un corps JSON avec un champ `error` et, en option, un champ `hint` :

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

| Status | Signification                                       |
| ------ | --------------------------------------------------- |
| `400`  | Corps ou paramètres de request invalides            |
| `401`  | Clé API manquante ou invalide                       |
| `402`  | Crédits insuffisants pour lancer une génération     |
| `403`  | Action nécessitant un forfait payant                |
| `404`  | Ressource introuvable                               |
| `409`  | Conflit (URL, sous-domaine ou domaine déjà utilisé) |
| `429`  | Rate limit dépassé (50 req/min)                     |
| `500`  | Erreur interne du serveur                           |
| `502`  | La génération n'a pas pu être lancée                |

## Rate limits

Tous les endpoints partagent une limite de **50 requests par minute** par utilisateur. En cas de dépassement :

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

## Pagination

Les endpoints de liste utilisent une pagination basée sur cursor :

```bash theme={null}
# Première page
GET /projects?limit=10

# Page suivante (utilisez nextCursor de la response précédente)
GET /projects?limit=10&cursor=cm1abc123...
```