Skip to content

Content Management API

Changes to /content/management/v1. Newest first. How versions work is on Releases and versions.

2026-09-22 — Content Management API: a stale pin is named; content_find pages searches

Section titled “2026-09-22 — Content Management API: a stale pin is named; content_find pages searches”

A PUT /content/management/v1/components/{id} whose document fails validation against the component’s pinned contract version, when that pin is behind the contract’s latest, now says so. The 400 validation_failed keeps its errors and adds pinnedContractVersion, latestContractVersion, validatesAgainstLatest and a message naming repinToLatest: true. A failure against a pin that is already the latest is unchanged.

The offset-paged listings (GET /components, /contracts, /templates) now document that they are not stable while the environment is being written to, and that GET /items is the way to enumerate one. Their behaviour has not changed.

@ebitex/content-mcp: content_find with search or externalId now returns a nextCursor when more results exist. Previously it always returned null, so an agent never saw past the first page of a search.

2026-09-22 — Content Management API: bundles and /items apply the key’s role

Section titled “2026-09-22 — Content Management API: bundles and /items apply the key’s role”

A management key acts as its role, and POST /import, POST /export and GET /items now enforce that as the per-item endpoints always have. Importing or exporting a contract, template, adapter, stream, audience or category needs the role’s manage permission for that kind (403 permission_denied). A component or page needs view to be exported and edit to be imported, both where it is and wherever the bundle files it (403 access_denied or 404). An import checks only the items it selects. GET /items leaves out components, folders and pages the role cannot view.

This can refuse a request that used to succeed. A key bound to a role without these permissions could import and export anything in its environment. If an import is now refused, mint the key against a role that holds the permission the refusal names.

2026-09-21 — Content Management API: imports respect plan limits

Section titled “2026-09-21 — Content Management API: imports respect plan limits”

POST /content/management/v1/import now refuses an import that would take the organization past its plan’s limit on components, pages or categories. Nothing is written, and the job fails with error: "quota_exceeded" and a quotas list naming each exceeded limit with its limit, current count and how many the import was adding. Previously such an import succeeded, and the organization found out later when creating anything by hand was refused.

Only the items an import creates count, so re-applying a model that updates existing content is never refused, even over a limit. POST /import-plan warns ahead of time: warnings gains one line starting quota: per limit the plan’s new items would pass. Nothing else about either endpoint has changed.

2026-09-16 — Content Management API: importing a bundle is now a job

Section titled “2026-09-16 — Content Management API: importing a bundle is now a job”

Breaking. POST /content/management/v1/import answers 202 { id, status } instead of 200 with the per-item results. The import runs as a background job: poll GET /operations/{id} until status is succeeded or failed, and read the same per-item outcomes from the finished run’s result.

The reason is a ceiling rather than a preference. A blocking import was capped by the timeout of whatever proxy sits in front of the API, however fast the server was — a 110-item bundle already failed at roughly 125 seconds with no HTTP status at all, and a full site’s content model is larger than that. Publishing has worked this way since this API launched, so the polling shape is not a new concept, and GET /operations/{id} is the endpoint you already use for it.

What has not changed: every refusal you can act on still comes back immediately, from the same call, with the same status and body — a blocked plan, an unconfirmed overwrite, an omitted new item, a malformed bundle. What has changed is that a bundle carrying an invalid document fails the job rather than the request: the run’s error carries the same list naming every invalid item and its failing fields. Nothing is written either way, since an import is one transaction.

Also in this release, GET /operations/{id} returns error as a JSON object, matching result beside it. It was previously the raw stored text, so it arrived as JSON encoded inside a JSON string.

@ebitex/content-mcp is updated for this in 0.4.97: content_transfer with apply returns the operation to poll rather than a finished result, and says so in its description. If you read its result, update before upgrading — the key is now operation, and the import is not finished when the tool returns.