# API de votre espace kortex

Cette page décrit l'API de **votre site** (par exemple
`https://acheter-fute.kortex.center`) : remplir le référentiel, régler les
prompts, alimenter le stock d'idées, piloter les actions et décisions des
agents, par script ou depuis une IA.

Elle est publique et lisible sans compte : elle ne décrit que la forme de
l'API, jamais vos données. La même table est disponible en JSON sur
`/api/aide/routes`.

**Avant d'écrire quoi que ce soit, lisez le
[guide de l'espace](https://kortex.center/modules/guide-espace/)** : il
explique ce que chaque route touche et pourquoi.

- [Le référentiel](https://kortex.center/modules/guide-espace/#le-referentiel) :
  la seule source que les agents ont le droit d'utiliser, ses
  [types de lignes](https://kortex.center/modules/guide-espace/#les-types-de-lignes)
  et [ce que le modèle lit](https://kortex.center/modules/guide-espace/#ce-que-le-modele-lit).
- [Les prompts des agents](https://kortex.center/modules/guide-espace/#les-prompts-des-agents).
- [Le stock d'idées et le dépilement](https://kortex.center/modules/guide-espace/#le-stock-d-idees).
- [Les articles et les décisions](https://kortex.center/modules/guide-espace/#les-articles-et-les-decisions).
- [Le suivi des actions](https://kortex.center/modules/guide-espace/#le-suivi-des-actions).
- [Prompt pour un agent IA](#prompt-pour-un-agent-ia) : à donner tel quel
  à une IA, il lui dit quoi lire, dans quel ordre et pourquoi.
- [Activer l'API d'un espace](https://kortex.center/modules/guide-espace/#activer-l-api-d-un-espace) :
  allumer l'option, créer la clé dans l'espace, la vérifier.
- [Pour une IA qui pilote un espace](https://kortex.center/modules/guide-espace/#pour-une-ia-qui-pilote-un-espace) :
  l'ordre de travail recommandé.

## En bref

```sh
export KORTEX_SITE=https://votre-site.kortex.center
export KORTEX_API_KEY=kx_...        # créée dans Réglages › Clés API

curl -sS -H "Authorization: Bearer $KORTEX_API_KEY" "$KORTEX_SITE/api/me"
```

La réponse dit au nom de quel compte la clé agit, avec quelle portée et
jusqu'à quand.

## Obtenir une clé

1. L'API doit être **activée pour votre site** par kortex (module « API »).
   Tant qu'elle ne l'est pas, ces routes répondent `404 module_inactif`.
   La marche à suivre complète, y compris par script :
   [Activer l'API d'un espace](https://kortex.center/modules/guide-espace/#activer-l-api-d-un-espace).
2. Un **administrateur du site** ouvre `Réglages › Clés API`, choisit un nom,
   une portée et une durée (30, 90 ou 365 jours), et crée la clé.
3. La clé n'est **montrée qu'une fois**. Rangez-la dans le gestionnaire de
   secrets de votre script. kortex n'en garde qu'une empreinte : une clé
   perdue se remplace, elle ne se retrouve pas.

Une clé agit **au nom de l'administrateur qui l'a créée**. Si ce compte est
désactivé ou perd le rôle administrateur, toutes ses clés cessent de
fonctionner immédiatement.

## Portées

| portée | ce qu'elle permet |
|---|---|
| `lecture` | lire le référentiel, les prompts, les idées, les contenus, le registre des actions et les décisions |
| `pilotage` | `lecture`, plus remplir et corriger le référentiel, régler les prompts, alimenter le stock d'idées, demander et corriger des contenus, piloter les actions et décisions des agents |
| `destructif` | `pilotage`, plus supprimer, publier ou dépublier un contenu, cacher un contenu, abandonner une action |

Choisissez la plus petite portée qui suffit : un script qui importe un
référentiel n'a pas besoin de publier.

**Aucune clé, quelle que soit sa portée, n'ouvre** : les ventes et
Shippingbo, la gestion des utilisateurs, les sauvegardes, les identifiants
des agents, ni la gestion des clés elles-mêmes. Ces gestes demandent une
connexion à l'espace.

## Routes ouvertes aux clés

Cette table est générée à partir du code de votre site : elle ne peut pas
annoncer une route que la clé ne passerait pas.

`POST /api/seo/decisions/:verb` demande `pilotage`, sauf les verbes `publish`
et `depublier`, qui demandent `destructif`.

### Portée `lecture`

lire le référentiel, les prompts, les idées, les contenus, le registre des actions et les décisions.

| méthode | chemin | à lire |
|---|---|---|
| GET | `/api/seo/content` | [Articles](https://kortex.center/modules/guide-espace/#les-articles-et-les-decisions) |
| GET | `/api/seo/content/:id` | [Articles](https://kortex.center/modules/guide-espace/#les-articles-et-les-decisions) |
| GET | `/api/seo/correcteur/reformulation/:id` | [Articles](https://kortex.center/modules/guide-espace/#les-articles-et-les-decisions) |
| GET | `/api/seo/decisions` | [Décisions](https://kortex.center/modules/guide-espace/#les-articles-et-les-decisions) |
| GET | `/api/seo/decisions/:id` | [Décisions](https://kortex.center/modules/guide-espace/#les-articles-et-les-decisions) |
| GET | `/api/seo/decisions/stagnantes` | [Décisions](https://kortex.center/modules/guide-espace/#les-articles-et-les-decisions) |
| GET | `/api/seo/faits-manquants` | [Faits manquants](https://kortex.center/modules/guide-espace/#ce-que-le-modele-lit) |
| GET | `/api/seo/health` | [L'espace en bref](https://kortex.center/modules/guide-espace/#l-espace-en-bref) |
| GET | `/api/seo/idees` | [Stock d'idées](https://kortex.center/modules/guide-espace/#le-stock-d-idees) |
| GET | `/api/seo/media` | [Articles](https://kortex.center/modules/guide-espace/#les-articles-et-les-decisions) |
| GET | `/api/seo/overview` | [L'espace en bref](https://kortex.center/modules/guide-espace/#l-espace-en-bref) |
| GET | `/api/seo/planning-depilement` | [Stock d'idées](https://kortex.center/modules/guide-espace/#le-stock-d-idees) |
| GET | `/api/seo/prompts` | [Prompts](https://kortex.center/modules/guide-espace/#les-prompts-des-agents) |
| GET | `/api/seo/prompts/:verbe/:type_contenu` | [Prompts](https://kortex.center/modules/guide-espace/#les-prompts-des-agents) |
| GET | `/api/seo/prompts/:verbe/:type_contenu/versions` | [Prompts](https://kortex.center/modules/guide-espace/#les-prompts-des-agents) |
| GET | `/api/seo/prompts/:verbe/:type_contenu/versions/:v` | [Prompts](https://kortex.center/modules/guide-espace/#les-prompts-des-agents) |
| GET | `/api/seo/references` | [Documents historiques](https://kortex.center/modules/guide-espace/#documents-historiques) |
| GET | `/api/seo/references-v2` | [Le référentiel](https://kortex.center/modules/guide-espace/#remplir-le-referentiel) |
| GET | `/api/seo/references-v2/lignes` | [Le référentiel](https://kortex.center/modules/guide-espace/#remplir-le-referentiel) |
| GET | `/api/seo/references-v2/rendu` | [Le référentiel](https://kortex.center/modules/guide-espace/#remplir-le-referentiel) |
| GET | `/api/seo/references/:nom` | [Documents historiques](https://kortex.center/modules/guide-espace/#documents-historiques) |
| GET | `/api/seo/references/:nom/historique` | [Documents historiques](https://kortex.center/modules/guide-espace/#documents-historiques) |
| GET | `/api/seo/registre` | [Suivi des actions](https://kortex.center/modules/guide-espace/#le-suivi-des-actions) |
| GET | `/api/seo/registre/:action_id/avis-propositions` | [Suivi des actions](https://kortex.center/modules/guide-espace/#le-suivi-des-actions) |
| GET | `/api/seo/registre/:action_id/avis-propositions/sans-motif` | [Suivi des actions](https://kortex.center/modules/guide-espace/#le-suivi-des-actions) |
| GET | `/api/seo/registre/:action_id/questions-fil` | [Suivi des actions](https://kortex.center/modules/guide-espace/#le-suivi-des-actions) |
| GET | `/api/seo/registre/abandons` | [Suivi des actions](https://kortex.center/modules/guide-espace/#le-suivi-des-actions) |
| GET | `/api/seo/registre/arbitrages` | [Suivi des actions](https://kortex.center/modules/guide-espace/#le-suivi-des-actions) |
| GET | `/api/seo/registre/corrections` | [Suivi des actions](https://kortex.center/modules/guide-espace/#le-suivi-des-actions) |
| GET | `/api/seo/registre/flux` | [Suivi des actions](https://kortex.center/modules/guide-espace/#le-suivi-des-actions) |
| GET | `/api/seo/registre/observations` | [Suivi des actions](https://kortex.center/modules/guide-espace/#le-suivi-des-actions) |
| GET | `/api/seo/registre/quarantine` | [Suivi des actions](https://kortex.center/modules/guide-espace/#le-suivi-des-actions) |
| GET | `/api/seo/registre/rapport/:id/contenu` | [Suivi des actions](https://kortex.center/modules/guide-espace/#le-suivi-des-actions) |
| GET | `/api/seo/registre/rapports` | [Suivi des actions](https://kortex.center/modules/guide-espace/#le-suivi-des-actions) |
| GET | `/api/seo/registre/transitions` | [Suivi des actions](https://kortex.center/modules/guide-espace/#le-suivi-des-actions) |
| GET | `/api/seo/search` | [L'espace en bref](https://kortex.center/modules/guide-espace/#l-espace-en-bref) |

### Portée `pilotage`

lecture, plus remplir et corriger les référentiels, régler les prompts, alimenter le stock d'idées, demander et corriger des contenus, piloter les actions et décisions des agents.

| méthode | chemin | à lire |
|---|---|---|
| POST | `/api/seo/content/:id/blocking/:index/statuer` | [Articles](https://kortex.center/modules/guide-espace/#les-articles-et-les-decisions) |
| POST | `/api/seo/content/:id/corps` | [Articles](https://kortex.center/modules/guide-espace/#les-articles-et-les-decisions) |
| POST | `/api/seo/content/:id/entete` | [Articles](https://kortex.center/modules/guide-espace/#les-articles-et-les-decisions) |
| POST | `/api/seo/content/:id/image` | [Articles](https://kortex.center/modules/guide-espace/#les-articles-et-les-decisions) |
| POST | `/api/seo/content/:id/relancer-redaction` | [Articles](https://kortex.center/modules/guide-espace/#les-articles-et-les-decisions) |
| POST | `/api/seo/content/brief` | [Articles](https://kortex.center/modules/guide-espace/#les-articles-et-les-decisions) |
| POST | `/api/seo/correcteur/reformulation/verdict` | [Articles](https://kortex.center/modules/guide-espace/#les-articles-et-les-decisions) |
| POST | `/api/seo/correcteur/reformuler-fragment` | [Articles](https://kortex.center/modules/guide-espace/#les-articles-et-les-decisions) |
| POST | `/api/seo/decisions/:id/cancel` | [Décisions](https://kortex.center/modules/guide-espace/#les-articles-et-les-decisions) |
| POST | `/api/seo/decisions/:id/nouveau-brief` | [Décisions](https://kortex.center/modules/guide-espace/#les-articles-et-les-decisions) |
| POST | `/api/seo/decisions/:id/relancer` | [Décisions](https://kortex.center/modules/guide-espace/#les-articles-et-les-decisions) |
| POST | `/api/seo/decisions/:id/renvoyer` | [Décisions](https://kortex.center/modules/guide-espace/#les-articles-et-les-decisions) |
| POST | `/api/seo/decisions/:verb` | [Décisions](https://kortex.center/modules/guide-espace/#les-articles-et-les-decisions) |
| POST | `/api/seo/idees` | [Stock d'idées](https://kortex.center/modules/guide-espace/#le-stock-d-idees) |
| PUT | `/api/seo/idees/:id` | [Stock d'idées](https://kortex.center/modules/guide-espace/#le-stock-d-idees) |
| POST | `/api/seo/idees/:id/depiler` | [Stock d'idées](https://kortex.center/modules/guide-espace/#le-stock-d-idees) |
| PUT | `/api/seo/idees/:id/priorite` | [Stock d'idées](https://kortex.center/modules/guide-espace/#le-stock-d-idees) |
| POST | `/api/seo/idees/charger-lot-initial` | [Stock d'idées](https://kortex.center/modules/guide-espace/#le-stock-d-idees) |
| POST | `/api/seo/idees/depiler-maintenant` | [Stock d'idées](https://kortex.center/modules/guide-espace/#le-stock-d-idees) |
| POST | `/api/seo/idees/lot-tsv` | [Stock d'idées](https://kortex.center/modules/guide-espace/#le-stock-d-idees) |
| PUT | `/api/seo/planning-depilement` | [Stock d'idées](https://kortex.center/modules/guide-espace/#le-stock-d-idees) |
| PUT | `/api/seo/prompts/:verbe/:type_contenu` | [Prompts](https://kortex.center/modules/guide-espace/#les-prompts-des-agents) |
| POST | `/api/seo/prompts/:verbe/:type_contenu/versions/:v/activer` | [Prompts](https://kortex.center/modules/guide-espace/#les-prompts-des-agents) |
| POST | `/api/seo/references-v2/apercu` | [Le référentiel](https://kortex.center/modules/guide-espace/#remplir-le-referentiel) |
| POST | `/api/seo/references-v2/importer` | [Le référentiel](https://kortex.center/modules/guide-espace/#remplir-le-referentiel) |
| POST | `/api/seo/references-v2/ligne` | [Le référentiel](https://kortex.center/modules/guide-espace/#remplir-le-referentiel) |
| PUT | `/api/seo/references-v2/lignes/:id` | [Le référentiel](https://kortex.center/modules/guide-espace/#remplir-le-referentiel) |
| POST | `/api/seo/references-v2/lignes/lot` | [Le référentiel](https://kortex.center/modules/guide-espace/#remplir-le-referentiel) |
| PATCH | `/api/seo/references/:nom` | [Documents historiques](https://kortex.center/modules/guide-espace/#documents-historiques) |
| PUT | `/api/seo/references/:nom` | [Documents historiques](https://kortex.center/modules/guide-espace/#documents-historiques) |
| POST | `/api/seo/registre/:action_id/avis-propositions/:id/motif` | [Suivi des actions](https://kortex.center/modules/guide-espace/#le-suivi-des-actions) |
| POST | `/api/seo/registre/:action_id/avis-propositions/:id/refuser` | [Suivi des actions](https://kortex.center/modules/guide-espace/#le-suivi-des-actions) |
| POST | `/api/seo/registre/:action_id/corriger` | [Suivi des actions](https://kortex.center/modules/guide-espace/#le-suivi-des-actions) |
| POST | `/api/seo/registre/:action_id/questions-fil` | [Suivi des actions](https://kortex.center/modules/guide-espace/#le-suivi-des-actions) |
| POST | `/api/seo/registre/:action_id/questions/:qid/lu` | [Suivi des actions](https://kortex.center/modules/guide-espace/#le-suivi-des-actions) |
| POST | `/api/seo/registre/:action_id/questions/:qid/plan/refuser` | [Suivi des actions](https://kortex.center/modules/guide-espace/#le-suivi-des-actions) |
| POST | `/api/seo/registre/:action_id/verifier` | [Suivi des actions](https://kortex.center/modules/guide-espace/#le-suivi-des-actions) |
| POST | `/api/seo/registre/abandons/:id/retablir` | [Suivi des actions](https://kortex.center/modules/guide-espace/#le-suivi-des-actions) |
| POST | `/api/seo/registre/actions` | [Suivi des actions](https://kortex.center/modules/guide-espace/#le-suivi-des-actions) |
| POST | `/api/seo/registre/arbitrages` | [Suivi des actions](https://kortex.center/modules/guide-espace/#le-suivi-des-actions) |
| POST | `/api/seo/registre/avis-propositions/:id/geste` | [Suivi des actions](https://kortex.center/modules/guide-espace/#le-suivi-des-actions) |
| POST | `/api/seo/registre/ingest` | [Suivi des actions](https://kortex.center/modules/guide-espace/#le-suivi-des-actions) |
| POST | `/api/seo/registre/quarantine/:id/resolve` | [Suivi des actions](https://kortex.center/modules/guide-espace/#le-suivi-des-actions) |
| POST | `/api/seo/registre/questions/:id/repondre` | [Suivi des actions](https://kortex.center/modules/guide-espace/#le-suivi-des-actions) |
| POST | `/api/seo/registre/rapport` | [Suivi des actions](https://kortex.center/modules/guide-espace/#le-suivi-des-actions) |
| POST | `/api/seo/registre/rapport/:id/heartbeat` | [Suivi des actions](https://kortex.center/modules/guide-espace/#le-suivi-des-actions) |
| POST | `/api/seo/registre/rapport/:id/relancer` | [Suivi des actions](https://kortex.center/modules/guide-espace/#le-suivi-des-actions) |
| POST | `/api/seo/registre/recalcul` | [Suivi des actions](https://kortex.center/modules/guide-espace/#le-suivi-des-actions) |

### Portée `destructif`

pilotage, plus supprimer, publier ou dépublier un contenu, cacher un contenu, abandonner une action.

| méthode | chemin | à lire |
|---|---|---|
| POST | `/api/seo/content/:id/cacher` | [Articles](https://kortex.center/modules/guide-espace/#les-articles-et-les-decisions) |
| DELETE | `/api/seo/idees/:id` | [Stock d'idées](https://kortex.center/modules/guide-espace/#le-stock-d-idees) |
| DELETE | `/api/seo/references-v2/lignes/:id` | [Le référentiel](https://kortex.center/modules/guide-espace/#remplir-le-referentiel) |
| POST | `/api/seo/registre/:action_id/abandonner` | [Suivi des actions](https://kortex.center/modules/guide-espace/#le-suivi-des-actions) |
| DELETE | `/api/seo/registre/action/:id` | [Suivi des actions](https://kortex.center/modules/guide-espace/#le-suivi-des-actions) |


## Exemples

Lire le référentiel :

```sh
curl -sS -H "Authorization: Bearer $KORTEX_API_KEY" "$KORTEX_SITE/api/seo/references"
```

Lire une table du référentiel :

```sh
curl -sS -H "Authorization: Bearer $KORTEX_API_KEY" "$KORTEX_SITE/api/seo/references/<nom>"
```

Les corps attendus par chaque route d'écriture sont ceux qu'utilise l'espace
lui-même ; une requête mal formée répond `400` sans rien modifier.

## Erreurs

| code | `error` | signification |
|---|---|---|
| 400 | `cle_dans_url` | la clé était dans l'URL : elle passe dans l'en-tête `Authorization`, jamais ailleurs |
| 400 | `auth_ambigue` | la requête portait à la fois une session et une clé |
| 401 | `unauthenticated` | clé absente, fausse, expirée, révoquée, ou API désactivée pour le site (même réponse pour toutes ces causes) |
| 403 | `session_requise` | cette route n'est pas ouverte aux clés |
| 403 | `portee_insuffisante` | la portée de la clé ne suffit pas pour ce geste |
| 404 | `module_inactif` | l'API n'est pas activée pour ce site |
| 429 | `trop_de_requetes` | plus de 120 requêtes par minute avec cette clé |
| 429 | `trop_de_tentatives` | trop de clés refusées depuis votre adresse ; attendez 15 minutes |

## Bonnes pratiques

- Une clé par script ou par usage, avec un nom qui le dit : vous saurez
  laquelle révoquer.
- Jamais de clé dans une URL, un dépôt git, un ticket ou un message.
- Chaque écriture faite par une clé est inscrite au journal du site, avec le
  début de la clé (`kx_<préfixe>`) et le compte au nom duquel elle agit.

## En cas de fuite

1. `Réglages › Clés API` : révoquez la clé (ou **Tout révoquer**). L'effet
   est immédiat.
2. Relisez le journal du site pour voir ce que la clé a fait.
3. Si besoin, demandez à kortex de désactiver l'API du site : toutes les clés
   s'arrêtent à la requête suivante.

## Prompt pour un agent IA

À donner tel quel à un agent IA qui doit piloter un espace : il lui dit quoi
lire, dans quel ordre et pourquoi, et ce qu'il ne doit jamais faire.
Remplacez `<SITE>` par le nom de l'espace (`acheter-fute` pour
`acheter-fute.kortex.center`). Les clés passent par l'environnement, jamais
dans le prompt.

```text
Tu pilotes l'espace Kortex du site <SITE> (https://<SITE>.kortex.center).
Kortex met en service, pour chaque site client, un espace fait de deux
composants : un dashboard (référentiel, articles, suivi des actions) et un
superviseur (agents IA qui rédigent, vérifient et corrigent). Kortex ne
touche jamais au site du client lui-même. Toi, tu agis par l'API, au nom
d'un administrateur, dans la limite de la portée de ta clé.

Tes clés sont dans l'environnement ; ne les écris jamais ailleurs (ni URL,
ni fichier, ni message) :
- KORTEX_SITE_KEY : clé de l'espace (https://<SITE>.kortex.center)
- KORTEX_API_KEY  : clé de kortex.center, si on t'en a donné une (facultatif)
Toujours en en-tête : Authorization: Bearer <clé>.

LIS D'ABORD, DANS CET ORDRE, ET COMPRENDS POURQUOI :

1. https://kortex.center/modules/guide-espace.md
   Pourquoi : le fonctionnement de l'espace. Ce qu'est le référentiel
   (chaque type de ligne et son rôle), ce que le modèle lit vraiment, les
   prompts, le stock d'idées et le dépilement, la vie d'un article et ses
   décisions, le suivi des actions. Sans lui, tu sais appeler les routes
   sans savoir ce qu'elles changent.

2. https://kortex.center/modules/dashboard-api.md
   Pourquoi : la forme exacte de l'API de l'espace (routes, portées,
   erreurs). La colonne « à lire » de chaque route renvoie à la section du
   guide qui l'explique : suis-la avant toute écriture.

3. https://kortex.center/aide/api.md (seulement si KORTEX_API_KEY existe)
   Pourquoi : l'API de la plateforme, qui sert surtout ici à activer l'API
   d'un espace (section « Activer l'API d'un espace » du guide).

4. GET https://<SITE>.kortex.center/api/me avec KORTEX_SITE_KEY
   Pourquoi : savoir au nom de qui tu agis, ta portée (lecture, pilotage,
   destructif) et la date d'expiration de ta clé. Ne tente jamais un geste
   au-delà de ta portée.

5. GET https://<SITE>.kortex.center/api/seo/references-v2/rendu
   Pourquoi : c'est EXACTEMENT ce que lisent les agents rédacteurs ; la
   seule source de vérité sur la marque et les produits.

SI L'ESPACE RÉPOND 404 module_inactif OU SI TU N'AS PAS DE CLÉ D'ESPACE :
suis la section « Activer l'API d'un espace » du guide. Avec KORTEX_API_KEY
(portée pilotage), tu peux allumer l'option : lire les modules du site, les
renvoyer TOUS avec api = {actif: true}. Tu ne peux PAS créer la clé de
l'espace : demande-la à un administrateur du site, qui la crée dans
Réglages › Clés API.

RÈGLES NON NÉGOCIABLES :
- N'affirme rien qui ne figure pas dans le référentiel. Ce qui manque se
  signale (GET /api/seo/faits-manquants), ne s'invente pas.
- Toute ligne FAIT que tu ajoutes porte une preuve (URL ou source). Une
  ligne = une affirmation. Ce qui ne se prouve pas reste vide : l'absence
  est une garde.
- Ne publie, ne dépublie et ne supprime rien sans l'accord explicite de
  l'équipe du site, même si ta portée le permet.
- Lis avant d'écrire, écris le minimum, relis après. Préfère « aperçu » à
  « importer » pour un collage de tableur.
- Chaque écriture est inscrite au journal du site avec le préfixe de ta clé
  et le compte au nom duquel tu agis. Agis comme si on te relisait.
- En cas de 401, n'insiste pas : clé fausse, expirée, révoquée, ou API
  éteinte. Signale-le.

ORDRE DE TRAVAIL :
1. Vérifier la clé (/api/me).
2. Lire le rendu du référentiel et les faits manquants.
3. Proposer, puis ajouter les faits manquants, avec leurs preuves.
4. Alimenter le stock d'idées avec des briefs complets (sujet, slug,
   requête cible, intention, cocon, plan en questions).
5. Relire les articles proposés ; décider (approve, regenerate avec
   consignes) ; laisser publish à l'équipe.
6. Suivre les actions par leurs états ; arbitrer avec un motif clair.

À LA FIN, rends compte : ce que tu as lu, ce que tu as écrit (route, objet,
avant/après), ce que tu n'as pas pu faire et pourquoi, et ce que tu
recommandes à l'équipe.
```