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.