Skip to content
CM Box Documentation

REST API

CM Box exposes a REST API for everything you can do in the product UI: managing content items, content types, assets and renditions, users and permissions, sites, packages, and workflow. The API is described by an OpenAPI 3.1 specification, and this site renders that specification as a browsable reference — see the REST API Reference group in the sidebar.

This page gives you the orientation you need before diving into individual endpoints.

Base URL

Section titled “Base URL”

The API is served directly from your CM Box instance. All endpoint paths in the reference are relative to your instance’s root URL:

https://<your-cmbox-host>/api/...

Almost every endpoint lives under /api/. The one exception is the token endpoint, which follows the OAuth2 convention and lives at /oauth2/token.

Authentication

Section titled “Authentication”

Every API request (other than the token endpoint and published-asset endpoints) carries a JWT bearer token in the Authorization header:

Authorization: Bearer <access_token>

You obtain a token from POST /oauth2/token using the OAuth2 client_credentials grant with a service account’s credentials, sent as a form-encoded body (client_id, client_secret, grant_type). The response contains an access_token (JWT), expires_in (validity in seconds), and token_type (Bearer).

See Authentication for the full flow, including how to create a service account.

Content types

Section titled “Content types”
  • Requests — JSON (Content-Type: application/json) for almost all endpoints. The token endpoint takes application/x-www-form-urlencoded. Resumable file uploads use the TUS protocol via POST /api/items/upload.
  • Responses — JSON for API operations. Asset retrieval endpoints (/api/assets/...) return the binary file content of the requested rendition; adding a download query parameter forces a Content-Disposition attachment header.

How the API is organized

Section titled “How the API is organized”

The reference groups endpoints by tag. The groups are:

Group What it covers
Authentication OAuth2 authentication and token management
Items Content item operations — create, read by ID or slug, update, delete, versions, copies, resumable uploads
Content Management Content types, taxonomies, categories, folders, repositories, and update packages
Assets Asset and rendition retrieval (binary), including zip downloads
Published Assets Public access to published assets
Security Users, groups, roles, service accounts, and permission bundles
Queue Job queue management
Admin Administrative operations — repository configurations, webhooks, search indexes, system settings
Sites Site management and publishing
Activity Content item activity and version history
Dependencies Content item dependency tracking
References Content item references and relationships
Renditions Asset rendition management
Queries GraphQL query generation for content types
User User authentication token and preferences
Workflow Workflow engine integration — events, status callbacks, package workflow state
Workflow Admin Workflow connections and workflow definitions
AI AI service proxy and image operations
GraphQL GraphQL proxy endpoints
Integration Third-party integration passthrough

Repository-scoped endpoints take the repository as a path parameter — usually named configId or repo. See the Architecture overview for how repositories work.

Response conventions

Section titled “Response conventions”

List envelopes. List endpoints consistently return a count plus an items array:

{
  "count": 12,
  "items": [ ... ]
}

Errors. Error responses (400, 401, 403, 404, 409, 500) share one shape:

{
  "error": true,
  "message": "Item not found"
}

The token endpoint is the exception: its error responses carry an OAuth2-style string code, for example { "error": "invalid_client" }.

Versioned retrieval. Asset retrieval endpoints accept a version query parameter (latest, latestpublished, or a specific version number) and a format parameter to convert the output (for example webp). This mirrors the draft/published distinction described in the Architecture overview.

Permissions

Section titled “Permissions”

Your token’s service account (or user) carries permissions, and the API enforces them per operation. Where an endpoint requires a specific permission key, the endpoint’s description in the reference states it — for example, locking a content type “Requires the admin.types.lock permission.”

To see what your current token can do, call GET /api/security/me/permissions, which returns your effective permissions.

Worked example

Section titled “Worked example”

List the content types defined in your CM Box instance. You can optionally filter by name with a name query parameter.

Terminal window
curl -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://<your-cmbox-host>/api/content/management/types"

A 200 response returns the standard list envelope, where each item is a content type definition:

{
  "count": 2,
  "items": [
    {
      "id": "article",
      "name": "article",
      "displayName": "Article",
      "apiName": "Article",
      "description": "Long-form editorial content",
      "isLocked": false,
      "settings": { ... },
      "fields": [ ... ]
    }
  ]
}

Exploring the API

Section titled “Exploring the API”
  • Generated reference — the REST API Reference group in this site’s sidebar documents every endpoint, parameter, and schema from the OpenAPI specification.
  • Interactive Swagger UI — your CM Box instance serves the same specification interactively at /api-docs, where you can try requests against your own instance.
Section titled “Related”