> For the complete documentation index, see [llms.txt](https://ovion-studio.gitbook.io/keryo-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ovion-studio.gitbook.io/keryo-docs/keryo-docs-fr/developpeurs/api-reference.md). # Référence de l'API Les endpoints de l'API REST Keryo par ressource, avec scopes et exemples de requêtes. Cette référence liste les endpoints de l'API REST Keryo, organisés par ressource. Chaque tableau indique la méthode HTTP, le chemin, le scope requis (le cas échéant) et une courte description. Tous les chemins sont relatifs à l'URL de base — `https://api.keryo.io` en production, `http://localhost:3001` en développement. {% hint style="info" %} Les corps de requête et de réponse sont donnés **à titre indicatif**, sauf lorsqu'une forme précise est documentée (par exemple `{name, scopes}` lors de la création d'une clé API). Considérez les noms de champs des exemples comme des indications, non comme un contrat. {% endhint %} ## Authentification Envoyez une clé API (ou un jeton d'accès OAuth 2.1) sous forme de jeton Bearer : ```http Authorization: Bearer ``` Les scopes sont vérifiés par endpoint, et le **gating par offre s'applique toujours** en plus des scopes. Voir [Authentification](/keryo-docs/keryo-docs-fr/developpeurs/authentication.md). ## Groupes d'endpoints (préfixes de montage) Le backend monte les routes sous ces préfixes : | Préfixe | Accès | | ---------------------------------------------------------------------------------------------- | ------------------------------------------- | | `/auth`, `/feedback`, `/oauth`, `/.well-known/oauth-authorization-server` | Public | | `/users`, `/admin`, `/stripe` | Protégé (JWT), sans abonnement actif requis | | `/clients`, `/posts`, `/templates`, `/report-templates`, `/github`, `/statistics`, `/api-keys` | Protégé + abonnement actif requis | ## Clients Les espaces clients. **Tous les endpoints `/clients` requièrent le scope `accounts:read`.** | Méthode | Chemin | Scope | Description | | -------- | ----------------- | --------------- | --------------------------- | | `GET` | `/clients` | `accounts:read` | Lister les espaces clients. | | `POST` | `/clients` | `accounts:read` | Créer un espace client. | | `GET` | `/clients/:id` | `accounts:read` | Récupérer un client. | | `PUT` | `/clients/:id` | `accounts:read` | Modifier un client. | | `DELETE` | `/clients/:id` | `accounts:read` | Supprimer un client. | | `POST` | `/clients/select` | `accounts:read` | Définir l'espace actif. | ## Posts Création de posts, médias, planification et publication. | Méthode | Chemin | Scope / prérequis | Description | | ------- | ----------------------------------- | ----------------- | --------------------------------------------------------- | | `GET` | `/posts` | `posts:read` | Lister les posts. | | `POST` | `/posts` | `posts:write` | Créer un brouillon (multipart ; images prises en charge). | | `POST` | `/posts/import` | Freelance+ | Importer des posts existants. | | `PUT` | `/posts/:id` | — | Modifier le contenu d'un post. | | `POST` | `/posts/send/:id` | `posts:publish` | Publier immédiatement (irréversible). | | `PUT` | `/posts/schedule/:id` | `posts:publish` | Planifier ou replanifier à une date ISO-8601 future. | | `POST` | `/posts/refactor` | — | L'IA réadapte / réécrit le contenu. | | `POST` | `/posts/retry/:id` | — | Relancer une publication échouée. | | `POST` | `/posts/youtube/video/init/:id` | — | Démarrer une session d'upload YouTube reprenable. | | `POST` | `/posts/youtube/video/complete/:id` | — | Finaliser un upload YouTube reprenable. | Des sous-routes média permettent de joindre des fichiers **image**, **vidéo** et **PDF** à un post. {% hint style="info" %} **Les uploads YouTube vont directement vers YouTube.** Les vidéos YouTube volumineuses (jusqu'à \~15 Go) sont envoyées directement du navigateur vers YouTube via une **session reprenable**, sans jamais être stockées côté Keryo. YouTube est **bientôt disponible** — LinkedIn et X sont les réseaux actifs à ce jour. {% endhint %} ### Exemple — créer un brouillon Les brouillons sont créés en multipart (pour joindre des médias dans la même requête) : ```bash curl -X POST https://api.keryo.io/posts \ -H "Authorization: Bearer " \ -F 'content=Bonjour depuis l'\''API Keryo' \ -F 'image=@./cover.png' ``` ```json { "id": "post_123", "status": "draft" } ``` > *Les champs de réponse ci-dessus sont donnés à titre indicatif.* ### Exemple — publier immédiatement ```bash curl -X POST https://api.keryo.io/posts/send/post_123 \ -H "Authorization: Bearer " ``` {% hint style="warning" %} La publication est **irréversible** et **limitée en débit**. Pour publier plus tard, utilisez plutôt `PUT /posts/schedule/:id` avec une date-heure ISO-8601 future. Voir [Limites de débit & erreurs](/keryo-docs/keryo-docs-fr/developpeurs/rate-limits-and-errors.md). {% endhint %} ## Statistiques Statistiques par plateforme. **Requièrent le scope `stats:read` et une offre Studio (ou supérieure).** | Méthode | Chemin | Scope / prérequis | Description | | ------- | -------------------------------- | --------------------- | --------------------------------- | | `GET` | `/statistics/linkedin` | `stats:read` + Studio | Statistiques LinkedIn actuelles. | | `GET` | `/statistics/x` | `stats:read` + Studio | Statistiques X actuelles. | | `GET` | `/statistics/snapshots/linkedin` | `stats:read` + Studio | Instantanés historiques LinkedIn. | | `GET` | `/statistics/snapshots/x` | `stats:read` + Studio | Instantanés historiques X. | {% hint style="info" %} **Réseaux actifs :** LinkedIn et X. Les autres réseaux sont répertoriés mais **en attente** — leurs statistiques ne sont pas disponibles à ce jour. {% endhint %} ## Modèles & modèles de rapport | Préfixe | Description | | ------------------- | ------------------------------------ | | `/templates` | Modèles de posts réutilisables. | | `/report-templates` | Modèles de rapports de statistiques. | Les deux sont protégés et requièrent un abonnement actif. Leurs endpoints suivent les mêmes conventions (lister, créer, lire, modifier, supprimer). ## Clés API Gérées via `/api-keys` (uniquement depuis l'application web / une session). Voir [Authentification](/keryo-docs/keryo-docs-fr/developpeurs/authentication.md) pour le détail complet — une clé API ne peut pas gérer les clés. ## Stripe Les endpoints de facturation sont montés sous `/stripe` (Stripe Checkout pour s'abonner, Stripe Billing Portal pour gérer / résilier). Ce groupe est protégé (JWT) mais ne requiert **pas** d'abonnement actif, afin que les utilisateurs puissent s'abonner depuis celui-ci. Les clés Stripe ne touchent jamais le client. ## Auth Endpoints d'authentification publics sous `/auth` : | Méthode | Chemin | Description | | ------- | ------------------------- | ----------------------------------------------------- | | `POST` | `/auth/magic-link` | Demander un e-mail de lien magique sans mot de passe. | | `POST` | `/auth/magic-link/verify` | Vérifier le lien magique et ouvrir une session. | La connexion sociale via GitHub est également disponible. Les sessions reposent sur cookie/JWT et disposent d'un accès complet sans aucun scope. ## Pages associées * [Authentification](/keryo-docs/keryo-docs-fr/developpeurs/authentication.md) — clés API, scopes et en-têtes. * [Connecteur MCP](/keryo-docs/keryo-docs-fr/developpeurs/mcp-connector.md) — les mêmes actions exposées aux clients IA. * [Limites de débit & erreurs](/keryo-docs/keryo-docs-fr/developpeurs/rate-limits-and-errors.md) — sémantique des erreurs et du débit.