Contentful

Contentful

This connector works with one Contentful space and environment. It reads published content through the Content Delivery API (https://cdn.contentful.com, read-only, delivery token) and writes through the Content Management API (https://api.contentful.com, personal access token): content types, entries, assets, locales and tags, plus creating, changing, publishing and unpublishing entries.

Two tokens, by design. Reads go to the delivery API with a delivery token that can only read published content. Writes, drafts, spaces and environments need the management API and a personal access token that acts with the full rights of its user. The management variables are optional: without them every read works, and the management tools answer that CONTENTFUL_MANAGEMENT_URL or CONTENTFUL_MANAGEMENT_TOKEN is missing.

Setup (about 5 minutes)

1. In https://app.contentful.com open the space, then Settings → API keys → Add API key. Tick the environments it may read (master at least) and save.
2. Copy the Space ID into CONTENTFUL_SPACE_ID and the Content Delivery API access token into CONTENTFUL_DELIVERY_TOKEN.
3. Set CONTENTFUL_ENVIRONMENT to the environment id, usually master.
4. Set CONTENTFUL_DELIVERY_URL to https://cdn.contentful.com (or https://cdn.eu.contentful.com for a space in the EU data region). To read drafts too, use https://preview.contentful.com (or https://preview.eu.contentful.com) with the Content Preview API access token of the same key instead.
5. For writes: avatar menu → Account settings → CMA tokens → Create personal access token, pick an expiry, copy the token at once (shown only once) into CONTENTFUL_MANAGEMENT_TOKEN, and set CONTENTFUL_MANAGEMENT_URL to https://api.contentful.com (or https://api.eu.contentful.com). The token acts as you, in every space you can edit.
6. Install and run contentful_get_space.

Publishing changes the live website or app: confirm first. contentful_publish_entry and contentful_unpublish_entry change what visitors see. State the entry and the effect and wait for the user's yes. contentful_delete_entry is installed switched off.

Read before you write

1. contentful_list_content_types gives the content type ids and field ids; contentful_list_locales the locale codes.
2. Field values are keyed by field id and then by locale: {"title": {"en-US": "Hello"}}. Links are {"sys": {"type": "Link", "linkType": "Entry", "id": "..."}} (or "linkType": "Asset").
3. Every write after the first needs the entry's current sys.version: read it with contentful_get_entry_for_editing right before writing. A stale version fails with 409 VersionMismatch; read again and retry.
4. contentful_update_entry replaces all fields (anything left out is deleted). For one or two fields use contentful_patch_entry.
5. A change is live only after contentful_publish_entry with the new version.

Searching: contentful_list_entries takes content_type, full-text query, and further search parameters in filters as a query string (fields.slug=hello or fields.date[gte]=2026-01-01&sys.id[nin]=a,b). Filtering or sorting by a field needs content_type. Linked entries and assets come back in includes (depth via include). Asset URLs start with //: add https:.

Paging: lists return total, skip and limit (up to 1000). Ask for the next page with skip = previous skip + limit.

Common errors

• 401 AccessTokenInvalid: wrong or expired token, or a delivery token used on the preview host (or the other way round).
• 404 NotFound: wrong id, or the space or environment is not covered by the token (Contentful answers 404, not 403).
• 400 BadRequest "A Content Type ID is required": add content_type when filtering by fields.
• 409 VersionMismatch: read the entry again and pass its current sys.version.
• 422 ValidationFailed: a required field is empty or a value breaks a validation; the details name the field.
• 429 RateLimitExceeded: the management API allows about 7 requests a second; wait and retry.

Out of scope here: uploading assets, creating or editing content types, environments, webhooks, roles, apps and GraphQL.

401 OrganizationAccessGrantRequired on the management tools: the organization only accepts personal access tokens it has granted. An organization admin opens Organization settings, finds the token under the access settings for personal access tokens and grants it access, then the write tools work. Read tools on the delivery token are not affected.