Contentful

Contentful is the leading headless CMS with a structured content model that agents can interact with via three distinct APIs. The Content Delivery API (CDA) provides CDN-cached, read-only access to published content — fast and cacheable. The Content Management API (CMA) handles content creation, updates, publishing, and content type management — the full editorial workflow. The Content Preview API gives access to draft/unpublished content for preview environments. For agents managing content — creating blog posts, updating product descriptions, managing localized content — the CMA provides comprehensive programmatic control. The structured content model means every piece of content has a defined schema (content type) with typed fields, making API responses predictable. Multi-environment support enables staging content changes before publishing. Localization is built into the content model.

Three REST APIs plus GraphQL. CDA at cdn.contentful.com/spaces/{space_id}/environments/{env}/entries — read-only, CDN-cached. CMA at api.contentful.com with full CRUD for entries, content types, assets, environments, and spaces. Entries follow content type schemas with typed fields (text, number, date, reference, rich text, location). The GraphQL Content API auto-generates a typed schema from content types — agents get strongly-typed queries matching their content model. Content versioning tracks every change. Publishing workflow: draft → changed → published with explicit publish/unpublish operations. Rich text fields use a structured JSON format (Contentful Rich Text) rather than HTML. Asset management handles file upload and image transformations. The API design is mature and well-structured — one of the strongest in the CMS category.

API errors return JSON with sys.type: 'Error', sys.id (error code), message, and details. CDA rate limits: 78 requests per second. CMA rate limits: 10 requests per second (more restrictive — writes are more expensive). 429 responses include X-Contentful-RateLimit-Reset header. The CDA's CDN caching means many reads never hit rate limits. Content type validation errors return field-specific details when entries don't match their content type schema. Publishing errors (e.g., required field missing) return actionable messages. Webhook delivery for content events retries on failure. The main consideration for agents: the CMA rate limit of 10 req/s means bulk content operations need throttling. Content versioning with optimistic concurrency (sys.version) prevents lost updates.

CDA uses delivery API tokens (read-only, safe for client-side). CMA uses personal access tokens or OAuth tokens with management permissions. Content Preview API uses preview API tokens. This three-token model provides clean separation: read-only content access doesn't require management credentials. Personal access tokens are created per-user with full management access. OAuth 2.0 is available for app marketplace integrations. Space-level access controls which spaces a user/token can access. Role-based permissions within spaces provide fine-grained editorial access control. For agents, using CDA tokens for content reads and CMA tokens for content writes provides appropriate least-privilege access. The token model is one of the most thoughtful among CMS platforms.

Developer documentation at contentful.com/developers is comprehensive — tutorials, API reference, SDK documentation, and content modeling guides. The API reference covers CDA, CMA, Images API, and GraphQL with examples. SDKs for JavaScript, Python, Ruby, PHP, Java, .NET, Swift, and Android are official and maintained. The content modeling documentation helps agents understand how to structure content types and relationships. The App Framework enables building custom integrations. Community resources include a developer forum and conference talks. The documentation's strength: it covers both technical API mechanics and content strategy concepts, helping agents make good content modeling decisions. For agents, the CMA quick start and content type documentation are essential.