API Delivery Formats

Content can be queried by REST or GraphQL to serve different purposes and use cases. While you can use the GraphQL API for highly specialized queries with fewer requests and lower network traffic, REST APIs are usually more scalable, faster, and more efficient.

As with most technology, the best approach depends on what exactly you want to build, but we recommend starting with the REST API for simplicity and using the GraphQL API for more specialized requests or highly network-sensitive applications like mobile apps.

If you are using the REST API and TypeScript, you can use our auto-generated clients that provide a fully typed development experience that’s customized to your content model for features like auto-complete and type safety that also simplify AI-assisted development.

The Content Management API is only available as a GraphQL API.

Services

Content Cloud comes with a couple of different service APIs that serve different purposes and have different permission requirements.

APIs are accessed through different subdomains. Each environment receives a dedicated subdomain per service. You can view the domains of your environment in the Content Sync app.

Content Management

Content Management API

Access: Strictly private

Stale content: Never

This API is used by Content Sync to manage all data in the Content Cloud. You can use this API to create your own types or add your own content.

Please note that changes to content are not propagated to Drupal right now. We are working on a way to synchronize changes back to Drupal sites, though. If you are interested in using this feature, please contact us.

Satellite APIs

Content APIs

Live API

Access: Public or Private, Private recommended

Stale content: Replication lag only

Permissions: -

The live API delivers content uncached to provide changes as fast as possible to the requesting user. If you are using cross-region replication, consider adding a region=source parameter to your requests to enforce receiving the latest content.

This API will not provide stale content and will display errors instead if there’s any issue with the API.

CDN API

Access: Public or Private

Stale content: Yes

Permissions: -

The CDN API delivers content cached to minimize latency and optimize for scalability and redundancy.

This API will provide stale content for up to 24 hours if there’s a technical issue with the API or custom upstream integrations.

By default, the CDN API will cache responses statically for 1 day, but will invalidate the cache earlier when content or related configuration changes based on cache tags.

Preview API

Access: Strictly private

Stale content: Replication lag only

Permissions: permission:preview

The preview API behaves like the live API but requires authorization with the permission:preview permission.

Dev API

Access: Strictly private

Stale content: Replication lag only

Permissions: permission:dev

The dev API behaves like the live API but requires authorization with the permission:dev permission. This API will bypass type caching to deliver the most up-to-date version of both content and typing information for minimal delays during development. This API provides inspection, allowing developers to use, e.g., Apollo to create GraphQL queries with autocomplete.

Asset APIs

Assets API

Access: Public or Private

Stale content: Yes, in error scenarios

Permissions: permission:asset:read:file

The regular asset API serves assets that are in a published state. If an asset exists both in a published and unpublished state, this API will serve the published version (regardless of preview permissions of the requester).

This API will cache all responses based on the hash of the file content.

Assets Preview API

Access: Strictly private

Stale content: Never

Permissions: permission:asset:read:file and permission:preview

The preview asset API will serve the latest version of an asset, whether it’s in a published state or not.