Jetons personnels
L’API est incluse dans l’offre Agence. Le propriétaire ou un admin de l’organisation crée un jeton depuis l’application (menu du compte, « API et jetons ») : un nom, des droits (lecture, ou lecture et brouillons), les projets accessibles (tous, ou une liste) et une durée de validité de 30 jours à 1 an. Le jeton n’est affiché qu’une fois ; Nelvi n’en garde qu’une empreinte. Il se révoque à tout moment, avec effet immédiat, et cesse de fonctionner si son créateur quitte l’organisation ou n’en est plus admin.
Authentification
Chaque requête porte le jeton dans l’en-tête Authorization. Les cookies de session ne sont jamais acceptés sur l’API, et un jeton n’ouvre jamais l’application ni le back-office.
curl https://nelvi.ai/api/v1/public/projects \
-H "Authorization: Bearer nlv_…"
Routes
Base : https://nelvi.ai/api/v1/public. Réponses en JSON, dates ISO 8601 en UTC (à afficher à l’heure de Paris), pagination des cartes par curseur (nextCursor).
| Méthode | Route | Rôle | Droits |
|---|
| GET | /projects | Lister les projets du jeton | Lecture |
| GET | /projects/{projectId} | Lire un projet | Lecture |
| GET | /projects/{projectId}/cards | Lister les cartes | Lecture |
| POST | /projects/{projectId}/cards | Déposer un brouillon | Lecture et brouillons |
| GET | /projects/{projectId}/cards/{cardId} | Lire une carte | Lecture |
| POST | /projects/{projectId}/cards/{cardId}/actions | Marquer une carte comme faite, l’archiver ou la désarchiver | Lecture et brouillons |
| GET | /projects/{projectId}/reports | Lister les rapports | Lecture |
| GET | /projects/{projectId}/analytics | Lire le trafic et la santé SEO | Lecture |
curl -X POST https://nelvi.ai/api/v1/public/projects/{projectId}/cards \
-H "Authorization: Bearer nlv_…" -H "Content-Type: application/json" \
-d '{"agentKey":"linkedin","type":"post","title":"Annonce","body":"…"}'
Limites de débit
60 requêtes par minute et par jeton, sur une fenêtre glissante. Chaque réponse donne RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset et RateLimit-Policy ; au-delà, la réponse 429 indique le délai dans Retry-After (en secondes).
Erreurs
Format unique : {"error": {"code": "…", "message": "…"}}, code stable en anglais, message en français.
| Statut | Cas |
|---|
| 400 | Corps ou paramètres invalides (`invalid_body`, `invalid_query`, `invalid_cursor`). |
| 401 | Jeton absent, inconnu, expiré ou révoqué (`unauthorized`, `invalid_token`). |
| 403 | Jeton en lecture seule pour une écriture (`insufficient_scope`). |
| 404 | Projet ou carte hors de portée du jeton (`not_found`). |
| 409 | Carte programmée ou en cours de publication (`conflict`). |
| 429 | Limite atteinte : attends le nombre de secondes de `Retry-After` (`rate_limited`). |
Sécurité et publication
- Un jeton ne voit que les projets de son organisation (et de sa liste, s’il en a une) : les données de tes autres clients et des autres comptes restent inaccessibles, y compris en cas d’erreur de route.
- Un brouillon déposé par l’API reste un brouillon : la relecture, la programmation et la publication se font dans Nelvi, par une personne, et sont journalisées.
- Chaque écriture est inscrite au journal des actions du projet, au nom du créateur du jeton, avec la mention « via l’API ».
- Les données sont hébergées dans l’Union européenne.
Nelvi