Utiliser l’API de site / CMS
Authentifiez, modifiez et publiez du contenu avec API v1 sur la plateforme ou un CMS indépendant.
Utiliser l’API de site / CMS
API v1 relie les intégrations externes aux données du site et du CMS. Consultez le contrat du déploiement, créez une clé aux droits limités, puis enregistrez un brouillon protégé par une version.
Choisir le service et le déploiement
Définissez QOKIT_API_URL sur l’origine du service API (en local, http://localhost:7777) ou de l’installation indépendante. QOKIT_PROJECT_ID est l’identifiant du projet ; l’export le stocke dans data/seed.json sous project.id. Les lectures publiques utilisent le slug du projet.
| Déploiement | Fonctions |
|---|---|
| Plateforme | Gestion CMS, exports et publication sur la plateforme |
cms-managed | Gestion CMS locale et rendu du site |
cms-only | Gestion CMS locale et lectures publiques headless ; aucun rendu de site |
site-only | Pages HTML et ressources statiques ; aucune API d’exécution |
Découvrir le contrat
Chaque service annonce seulement les opérations prises en charge. Les autres renvoient 404. API 1.0 conserve la compatibilité des routes existantes sans version.
| Chemin | Usage |
|---|---|
GET /v1/openapi.json | OpenAPI 3.1 : corps, réponses, droits et préconditions |
GET /v1/capabilities | Version API, type de déploiement et opérations disponibles |
GET /v1/sdk/client.mjs | Client JavaScript sans dépendances |
GET /v1/sdk/client.d.mts | Déclarations TypeScript correspondantes |
Créer une clé API
Utilisez l’accessToken obtenu après une connexion complète à la plateforme comme SESSION_TOKEN. Le compte doit pouvoir gérer les paramètres du site. Terminez toute authentification requise avant de créer la clé.
curl --fail-with-body "$QOKIT_API_URL/v1/projects/$QOKIT_PROJECT_ID/api-keys" \
-H "Authorization: Bearer $SESSION_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"name":"Server integration","scopes":["content:read","content:write"],"expiresInDays":90}'Pour un CMS indépendant, connectez-vous avec l’e-mail et le mot de passe du propriétaire du déploiement, conservez le Cookie de session, puis créez la clé :
curl --fail-with-body -c cookies.txt "$QOKIT_API_URL/api/auth/login" \
-H 'Content-Type: application/json' \
-d '{"email":"owner@example.com","password":"your-deployment-password"}'
curl --fail-with-body -b cookies.txt "$QOKIT_API_URL/v1/projects/$QOKIT_PROJECT_ID/api-keys" \
-H 'Content-Type: application/json' \
-d '{"name":"Server integration","scopes":["content:read","content:write"],"expiresInDays":90}'La création renvoie token une seule fois. Enregistrez-le dans la variable serveur QOKIT_SITE_API_KEY ; les appels utilisent des jetons Bearer commençant par qk_site_. Durée par défaut : 90 jours, réglable de 1 à 365, avec 50 clés actives au maximum par projet. Avec une session autorisée à gérer les paramètres, listez via GET /v1/projects/{id}/api-keys et révoquez via DELETE /v1/projects/{id}/api-keys/{keyId}.
Choisissez seulement les droits nécessaires. L’accès et les permissions du créateur sont revérifiés à chaque appel. Expiration, révocation et changements de rôle affectent les appels suivants. Les clés API ne gèrent pas les autres clés.
| Scope | Usage |
|---|---|
content:read / content:write | Lire / modifier les collections et entrées |
content:publish | Publication explicite et écritures publiant des entrées |
pages:read / pages:write | Lire le runtime / modifier contenu, structure, SEO et formulaires |
media:read / media:write | Lire / gérer les médias et dossiers |
settings:read / settings:write | Lire / modifier les paramètres du site |
users:read / users:write | Lire / gérer les utilisateurs CMS |
leads:read / leads:write / analytics:read | Lire / mettre à jour les prospects et lire le tableau de bord CMS |
marketing:read / marketing:write | Lire / générer le contenu marketing |
deployments:read / deployments:write | Tâches d’export et de publication de la plateforme |
sync:write / updates:read / updates:write | Synchronisation et mises à jour signées des installations indépendantes |
Enregistrer un brouillon avec le SDK
Le paquet du workspace est @qokit/site-api ; il n’est pas encore publié sur npm. Pour un projet externe, téléchargez les deux fichiers client dans sdk. Les nouveaux exports les incluent déjà.
mkdir -p sdk
curl --fail-with-body "$QOKIT_API_URL/v1/sdk/client.mjs" -o sdk/client.mjs
curl --fail-with-body "$QOKIT_API_URL/v1/sdk/client.d.mts" -o sdk/client.d.mtsCet exemple nécessite content:read et content:write. Remplacez en par une langue activée. Il crée une collection d’exemple ; aux exécutions suivantes, réutilisez un identifiant de collection existante.
import { createSiteApiClient } from './sdk/client.mjs';
const api = createSiteApiClient({
baseUrl: process.env.QOKIT_API_URL,
projectId: process.env.QOKIT_PROJECT_ID,
token: process.env.QOKIT_SITE_API_KEY
});
const collection = await api.collections.create({
key: 'integration_example', name: 'Integration example', kind: 'generic', fields: []
});
const draft = await api.entries.create(collection._id, {
title: 'Integration draft', locale: 'en', status: 'draft', fields: {}
});
const saved = await api.entries.update(draft._id, { title: 'Reviewed copy' }, {
expectedUpdatedAt: draft.updatedAt
});
console.log(saved._id, saved.updatedAt);Enregistrer un brouillon conserve le précédent instantané public d’une entrée publiée. Après vérification, une clé avec content:publish peut publier explicitement la version enregistrée. Les pages de la plateforme restent des brouillons jusqu’à la publication du site.
await api.entries.publish(saved._id, { expectedUpdatedAt: saved.updatedAt });Pour restaurer, consultez api.entries.revisions(id) puis appelez api.entries.restore(id, revisionId, { expectedUpdatedAt }). Les autres opérations documentées utilisent api.request(path, options), avec idempotencyKey. Le client ne relance jamais automatiquement les écritures.
Routes de gestion
Préfixez ces chemins avec /v1/projects/{id}. OpenAPI décrit toutes les opérations, champs et exigences propres au déploiement. DELETE archive les collections, entrées et médias.
| Chemin | Méthode |
|---|---|
/cms/collections | GET, POST |
/cms/collections/{collectionId} | PUT, DELETE |
/cms/collections/{collectionId}/entries | GET, POST |
/cms/entries/{entryId} | GET, PUT, DELETE |
/cms/entries/{entryId}/publish | POST |
/cms/entries/{entryId}/revisions | GET |
/cms/entries/{entryId}/revisions/{revisionId}/restore | POST |
/cms/media, /cms/media/folders | GET, POST |
/cms/media/{assetId}, /cms/media/folders/{folderId} | PUT, DELETE |
/runtime, /content/{locale} | GET; PUT /content/{locale} |
/site/pages, /site/pages/{pageId}, /site/pages/{pageId}/seo, /site/forms | POST, DELETE, PUT, PUT |
/cms/settings | GET, PUT |
/cms/users, /cms/users/{memberId} | GET / POST, PUT / DELETE |
/leads, /leads/{leadId} | GET, PUT |
La plateforme gère l’enregistrement d’URL et les intentions d’envoi ; les envois indépendants utilisent fileName, contentType et contentBase64, avec limite de 10 MB et validation de signature. Les mutations d’utilisateurs plateforme exigent Idempotency-Key ; les utilisateurs locaux un mot de passe de 12–1024 caractères. CSV, écritures groupées et liens de traduction sont des extensions plateforme.
Versions, pagination et erreurs
Les modifications, archivages et restaurations exigent expectedUpdatedAt issu du dernier updatedAt lu. Une version manquante renvoie 428, une version obsolète 409.
Pour la structure, le SEO et les formulaires, lisez GET /v1/projects/{id}/runtime puis envoyez content.updatedAt et siteVersion.updatedAt comme baseContentUpdatedAt et baseSiteVersionUpdatedAt. Les contrôles de révision et de bail d’édition actif de Builder restent applicables.
Les listes utilisent par défaut page=1&pageSize=24, avec 100 éléments au maximum par page. La gestion renvoie items, les listes publiques entries. Révisions et dossiers renvoient des tableaux. Lisez toutes les pages pour exporter le contenu.
{"items":[],"page":1,"pageSize":24,"total":0,"totalPages":1}Les réponses incluent X-Request-Id et X-Qokit-Api-Version. Les erreurs ont un code stable et un identifiant de requête :
{"statusCode":409,"message":"This resource changed.","error":{"code":"CONFLICT","message":"This resource changed.","requestId":"request-id"}}Pour 401, vérifiez la clé ; pour 403, les droits et l’accès du créateur. Pour 409, relisez et comparez les changements ; pour 428, fournissez la version. Pour 429, respectez Retry-After. La limite est de 300 requêtes par minute par clé/adresse, avec des limites IP et écriture supplémentaires sur la plateforme.
Configurer l’installation indépendante
La plateforme utilise CORS_ALLOWED_ORIGINS pour les intégrations navigateur. Les appels indépendants avec clé exigent des origines exactes dans SITE_API_ALLOWED_ORIGINS ; la gestion par Cookie reste de même origine. Les lectures publiques CMS acceptent aussi CMS_ALLOWED_ORIGINS. Configurez CMS_PUBLIC_URL pour les URL de médias CMS-only.
Sauvegardez l’ensemble des données et fichiers envoyés, y compris les fichiers privés data/api-security.json et data/api-revisions.json. Mots de passe et clés restent localement sous forme de hachages. Un seul processus Node écrit dans chaque répertoire de données.
Les anciens exports obtiennent v1 par une mise à jour signée du runtime. Ensuite, téléchargez le contrat et client actuels par HTTP ; les fichiers inclus restent des instantanés de l’export.
Pour les lectures publiques sans identifiants, consultez Appeler l’API publique de contenu.
Dernière mise à jour