Skip to Content
Documentation développeur

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éploiementFonctions
PlateformeGestion CMS, exports et publication sur la plateforme
cms-managedGestion CMS locale et rendu du site
cms-onlyGestion CMS locale et lectures publiques headless ; aucun rendu de site
site-onlyPages 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.

CheminUsage
GET /v1/openapi.jsonOpenAPI 3.1 : corps, réponses, droits et préconditions
GET /v1/capabilitiesVersion API, type de déploiement et opérations disponibles
GET /v1/sdk/client.mjsClient JavaScript sans dépendances
GET /v1/sdk/client.d.mtsDé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.

ScopeUsage
content:read / content:writeLire / modifier les collections et entrées
content:publishPublication explicite et écritures publiant des entrées
pages:read / pages:writeLire le runtime / modifier contenu, structure, SEO et formulaires
media:read / media:writeLire / gérer les médias et dossiers
settings:read / settings:writeLire / modifier les paramètres du site
users:read / users:writeLire / gérer les utilisateurs CMS
leads:read / leads:write / analytics:readLire / mettre à jour les prospects et lire le tableau de bord CMS
marketing:read / marketing:writeLire / générer le contenu marketing
deployments:read / deployments:writeTâches d’export et de publication de la plateforme
sync:write / updates:read / updates:writeSynchronisation 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.mts

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

CheminMéthode
/cms/collectionsGET, POST
/cms/collections/{collectionId}PUT, DELETE
/cms/collections/{collectionId}/entriesGET, POST
/cms/entries/{entryId}GET, PUT, DELETE
/cms/entries/{entryId}/publishPOST
/cms/entries/{entryId}/revisionsGET
/cms/entries/{entryId}/revisions/{revisionId}/restorePOST
/cms/media, /cms/media/foldersGET, 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/formsPOST, DELETE, PUT, PUT
/cms/settingsGET, 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.

Ce guide vous a-t-il été utile ?

Dernière mise à jour

Sur cette page