Use the Site / CMS API
Authenticate, edit and publish content through API v1 on the platform or an independent CMS.
Use the Site / CMS API
API v1 connects external integrations to site and CMS data. Start with the contract served by your deployment, create a scoped key, then save a draft with version protection.
Choose the service and deployment
Set QOKIT_API_URL to the API service origin (locally http://localhost:7777) or the independent installation origin. Set QOKIT_PROJECT_ID to the project ID; an export stores it in data/seed.json as project.id. Public reads use the project slug instead.
| Deployment | Capabilities |
|---|---|
| Platform | CMS management, exports and platform publishing |
cms-managed | Local CMS management and website rendering |
cms-only | Local CMS management and public headless reads; no website rendering |
site-only | Static HTML pages and assets; no runtime API |
Discover the contract
Each service advertises only its supported operations. Unsupported operations return 404. API version 1.0 keeps existing unversioned routes compatible.
| Path | Purpose |
|---|---|
GET /v1/openapi.json | OpenAPI 3.1: bodies, responses, scopes and preconditions |
GET /v1/capabilities | API version, deployment type and supported operations |
GET /v1/sdk/client.mjs | Dependency-free JavaScript client |
GET /v1/sdk/client.d.mts | Matching TypeScript declarations |
Create an API key
Use the accessToken from a completed platform login as SESSION_TOKEN. The account needs site settings management permission. Complete any required authentication before issuing a key.
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}'For an independent CMS, log in with the deployment owner email and password, save the session Cookie, then create the key:
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}'Creation returns token once. Store it as server environment variable QOKIT_SITE_API_KEY; requests use Bearer tokens starting with qk_site_. Keys default to 90 days, allow 1–365 days, and have a limit of 50 active keys per project. List with GET /v1/projects/{id}/api-keys and revoke with DELETE /v1/projects/{id}/api-keys/{keyId} using a settings administrator login session.
Choose only the scopes your integration needs. Creator access and permissions are rechecked on every request. Expiry, revocation and role changes take effect on subsequent requests. API keys cannot manage other keys.
| Scope | Purpose |
|---|---|
content:read / content:write | Read / edit collections and entries |
content:publish | Explicit publication and writes that publish entries |
pages:read / pages:write | Read runtime / edit page content, structure, SEO and forms |
media:read / media:write | Read / manage media and folders |
settings:read / settings:write | Read / edit site settings |
users:read / users:write | Read / manage CMS users |
leads:read / leads:write / analytics:read | Read / update leads and read the CMS dashboard |
marketing:read / marketing:write | Read / generate marketing content |
deployments:read / deployments:write | Platform export and publish jobs |
sync:write / updates:read / updates:write | Independent installation sync and signed updates |
Save a draft with the SDK
The workspace package is @qokit/site-api; it has not been published to npm. For an external project, download both client files into sdk. New exports already include them.
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.mtsThis example needs content:read and content:write. Replace en with an enabled project locale. It creates a new example collection; on later runs, reuse an existing collection ID instead of creating it again.
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);Saving a draft preserves the previous public snapshot of a published entry. After review, a key with content:publish can explicitly publish the saved version. Platform page edits remain drafts until the site publishing workflow completes.
await api.entries.publish(saved._id, { expectedUpdatedAt: saved.updatedAt });For recovery, read api.entries.revisions(id) and call api.entries.restore(id, revisionId, { expectedUpdatedAt }). Use api.request(path, options) for other documented operations, including idempotencyKey. The client never retries writes automatically.
Management routes
Prefix these paths with /v1/projects/{id}. OpenAPI lists all operations, request fields and host-specific requirements. DELETE archives collections, entries and media.
| Path | Method |
|---|---|
/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 |
Platform media supports URL registration and upload intents; independent uploads use fileName, contentType and contentBase64 with a 10 MB file limit and signature checks. Platform user mutations require Idempotency-Key; local user creation needs a 12–1024 character password. CSV, bulk writes and translation links are platform extensions.
Versions, pagination and errors
Resource updates, archives and revision restores require expectedUpdatedAt from the last read of updatedAt. A missing version returns 428; a stale version returns 409.
For page structure, SEO and forms, read GET /v1/projects/{id}/runtime and submit content.updatedAt and siteVersion.updatedAt as baseContentUpdatedAt and baseSiteVersionUpdatedAt. Platform Builder revision and active edit lease checks still apply.
Paged lists default to page=1&pageSize=24, with at most 100 items per page. Management lists return items; public lists return entries. Revisions and folders return arrays. Read every page when exporting content.
{"items":[],"page":1,"pageSize":24,"total":0,"totalPages":1}Responses include X-Request-Id and X-Qokit-Api-Version. Errors have a stable code and request ID:
{"statusCode":409,"message":"This resource changed.","error":{"code":"CONFLICT","message":"This resource changed.","requestId":"request-id"}}For 401, check key validity; for 403, check scopes and creator access. For 409, reread and compare changes; for 428, supply the missing version. For 429, respect Retry-After. The rate limit is 300 requests per minute per key/address, with additional platform IP and write limits.
Independent installation configuration
Platform browser integrations use CORS_ALLOWED_ORIGINS. Independent API-key browser calls need exact origins in SITE_API_ALLOWED_ORIGINS; Cookie management remains same-origin. Public CMS reads can also allow CMS_ALLOWED_ORIGINS. For CMS-only media URLs, configure CMS_PUBLIC_URL.
Back up the entire data directory and uploads, including private data/api-security.json and data/api-revisions.json. Passwords and API keys are hashed and stay local. One Node process writes each data directory.
Older exports acquire v1 through a signed runtime update. After upgrading, download the current contract and client over HTTP; bundled files are snapshots from export time.
For public reads without credentials, follow Call the public content API.
Last updated on