Choosing a Headless CMS: A Capability Checklist and Questions to Ask Any Vendor

This checklist works for any headless CMS, including Agility. It lists the capabilities that usually decide whether a project goes well, why each one matters, and the questions that get past a sales demo to a real answer. At the end, a table points to where Agility's own documentation answers each area, so you can check our answers the same way you check anyone else's.

How to use it

1. Weight the areas for your project first. A single-site marketing team and a multi-brand enterprise will care about different rows. Decide what matters before you see any demo.
2. Ask to see it, not hear about it. For each must-have, ask the vendor to show it working, ideally on your content in a trial or proof of concept.
3. Check the documentation. If a capability matters, it should be documented. Undocumented features are hard to rely on and hard to hand over.
4. Write down the answers. Record who said what and when, and attach links to the documentation they gave you.

1. Content modeling

Capability	Why it matters	Ask
Structured fields and validation	Clean, reusable content instead of formatted blobs.	Which field types exist? Can we add validation rules and help text?
References between content	Reuse one item in many places and keep it in sync.	How do we link content? Can a field reference a list, a single item or several items?
Reusable page building blocks	Editors assemble pages from components your developers maintain.	How are components defined, and how do they map to front-end code?
Changing models after launch	Models evolve. Changing them shouldn't break content.	What happens to existing content when we add, rename or remove a field?

2. Pages and the editor experience

Capability	Why it matters	Ask
Page management	Editors create pages and arrange components without a developer.	Can an editor create a new page, choose its layout and reorder components on their own?
Preview	Editors check work before it goes live.	How does preview work with our front end? What do we have to build?
Visual or in-context editing	Editors find and change content on the page they're looking at.	Does in-context editing work on our real site, and what code changes does it need?
SEO controls	Marketers own titles, descriptions and URLs.	Which SEO fields are per page? How are redirects managed and applied?

3. Workflow and governance

Capability	Why it matters	Ask
Roles and permissions	Least privilege, especially for agencies and regional teams.	Can we create custom roles? Can we restrict access to a section, a list or a single item?
Approvals	Regulated or brand-sensitive content needs review.	Can we require approval before publishing? Who is notified?
Scheduling and coordinated releases	Launches happen at a set time, across many items.	Can we schedule publish and unpublish? Can we group items into one release?
Version history	Mistakes need undoing.	Is every version kept? Can editors compare and restore?
Audit trail	Security and compliance teams need to know who did what.	What is logged, for how long, and can we export it to our own tools?

4. Localization

Capability	Why it matters	Ask
Locales	Language and regional versions of content and pages.	How are locales structured? Can pages differ by locale, or only their content?
Translation workflow	Translation is often the slowest step.	How do we send content for translation and bring it back? Are there machine translation integrations?

5. Content delivery

Capability	Why it matters	Ask
APIs	Your front end and other channels read content through them.	REST, GraphQL or both? How do filtering, sorting and paging work?
Caching and invalidation	Speed, and fresh content right after publishing.	Is the API served from a CDN? How quickly does a publish reach it?
Change notifications	Your site, search and other systems need to react to changes.	Which events send webhooks? Are deliveries signed and retried? Is there a delivery history?
Copying content locally	Offline apps, search indexes and high read volume.	Is there a sync API that returns only what changed?
Usage limits	Limits shape your architecture and your bill.	What is metered? What counts as an API call? What happens when we reach a limit?

6. Assets

Capability	Why it matters	Ask
Media library and CDN	Images and files served fast, everywhere.	Where are assets stored and served from? Can we use our own domain?
Image transformation	One upload, many sizes and formats.	Can we resize, crop and convert formats by URL? Is there a focal point?

7. Developer experience and extensibility

Capability	Why it matters	Ask
Framework support	Your team's skills and your hosting choices.	Which frameworks have maintained SDKs and starters?
Management API and SDKs	Migrations, automation and integrations.	Can everything in the UI also be done through an API? Which SDKs are maintained?
Environments and CLI	Moving models and content between development, test and production.	How do we promote models and content between environments? Is there a CLI for CI/CD?
UI extensions	Custom fields and integrations inside the editing UI.	Can we add custom fields, panels or apps? How are they built and hosted?

8. AI and agents

Capability	Why it matters	Ask
Agent access	AI assistants can model, migrate and edit content.	Is there an MCP server or similar? How does it authenticate?
Permissions and confirmation	AI should never exceed a user's rights.	Does an agent act with the user's own permissions? Are publish and delete confirmed? Do agent saves go live immediately?
Data handling	Buyers and security teams ask this first.	What data leaves the platform when an AI tool is used, and where does it go?

9. Security, compliance and operations

Capability	Why it matters	Ask
Sign-in and identity	Central control of who can sign in.	Which single sign-on standards are supported? Can we enforce MFA?
Certifications and reviews	Required by most security reviews.	Which certifications do you hold? Can we see the reports?
Data residency	Legal or policy requirements on where data lives.	Which regions are available? What leaves the region, and when?
Availability and recovery	The CMS is part of your publishing chain.	What is the uptime commitment? How are backups and recovery handled? What happens to our live site if the CMS is down?
Shared responsibility	Clear ownership avoids gaps.	Which security tasks are yours and which are ours? Is that documented?

10. Portability and exit

Capability	Why it matters	Ask
Full export	You should be able to leave with your content.	How do we export all content, models, pages and assets? In what format?
History and relationships	Exports that lose references or history are hard to reuse.	Do exports keep links between items? Can we export version history?

Red flags

• A capability that "is on the roadmap" for a must-have requirement.
• Answers that exist only in a slide deck and not in the documentation.
• Limits or pricing that can't be explained in terms of your own expected traffic and team size.
• No clear answer to "how would we get all our content out?"
• A demo that only ever runs on the vendor's sample content.

How Agility answers these

Use the same test on us. Each area links to the Agility documentation that answers it.

Area	Agility documentation
Content modeling	Content Models, Component Models, Fields, Linked Content Field Types
Pages and the editor experience	Page Management, Setting Up Preview, Getting Started With Web Studio, URL Redirections
Workflow and governance	Approvals and Workflows, Custom Roles, Item-level Permissions, Scheduling Overview, Version History, Audit Trail, Logging & SIEM Integration
Localization	Locales, Copying and Translating Content Across Locales
Content delivery	Content Fetch API, GraphQL API, Webhooks, Content Sync API, Content Delivery & CDN Architecture
Assets	Introduction to Assets, Transforming Images with Query Strings, Custom Asset Domains
Developer experience	Developing with Agility, AgilityCLI, Extending the CMS
AI and agents	Agility CMS MCP Server, Governing AI Access to Agility CMS
Security and operations	Hosting, Security & Compliance, Enterprise Single Sign-On, Data Residency & Data Regions, SLA & Uptime, Disaster Recovery & Business Continuity
Portability	Getting Your Content Out: Data Portability and Exit

Related

• Run a Two-Week Proof of Concept
• Is Agility Right for Your Project?