Skip to Content
Developer documentation

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.

DeploymentCapabilities
PlatformCMS management, exports and platform publishing
cms-managedLocal CMS management and website rendering
cms-onlyLocal CMS management and public headless reads; no website rendering
site-onlyStatic 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.

PathPurpose
GET /v1/openapi.jsonOpenAPI 3.1: bodies, responses, scopes and preconditions
GET /v1/capabilitiesAPI version, deployment type and supported operations
GET /v1/sdk/client.mjsDependency-free JavaScript client
GET /v1/sdk/client.d.mtsMatching 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.

ScopePurpose
content:read / content:writeRead / edit collections and entries
content:publishExplicit publication and writes that publish entries
pages:read / pages:writeRead runtime / edit page content, structure, SEO and forms
media:read / media:writeRead / manage media and folders
settings:read / settings:writeRead / edit site settings
users:read / users:writeRead / manage CMS users
leads:read / leads:write / analytics:readRead / update leads and read the CMS dashboard
marketing:read / marketing:writeRead / generate marketing content
deployments:read / deployments:writePlatform export and publish jobs
sync:write / updates:read / updates:writeIndependent 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.mts

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

PathMethod
/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

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.

Was this guide helpful?

Last updated on

On this page