# Building Integrations

> Source: https://agilitycms.com/docs/developers/building-integrations

No single platform does everything well. Your commerce platform is great at carts, your CRM at leads, your search engine at relevance. Agility is great at content: modeling it, editing it, approving it and delivering it fast. A **composable architecture** lets each system do its job and connects them through APIs, so you can swap one piece without rebuilding the rest.

This page explains where Agility plugs into that architecture, which pattern fits which job, and how AI agents can help you design, build and run the whole thing.

## At a glance

- **Agility is the content service** in your stack. Everything it holds is available through APIs, and it tells other systems when content changes.
- **An integration connects in one of five places:** your front end, webhooks, the Management API, an app inside Agility, or an AI agent through the MCP Server.
- **One rule keeps it healthy:** every piece of data has one owner. Agility stores references (product IDs, document links, secure file references), not copies of other systems' data.
- **AI helps at every stage:** agents can propose the architecture, write the integration code, build Agility apps, migrate content and work with content through the MCP Server, with people approving what goes live.

## What composable means with Agility

In a composable stack, each capability comes from a service that's best at it, and your front end puts them together.

| Capability | Typically owned by | How it meets Agility content |
| --- | --- | --- |
| Pages, navigation, articles, campaigns | **Agility** | Your front end reads them from the Fetch or GraphQL API |
| Products, prices, cart, checkout | Commerce platform | Agility stores product IDs; the front end looks up the rest |
| Search | Search service | Agility webhooks keep the index current |
| Leads, contacts, forms | CRM or form provider | The front end sends submissions straight to the CRM |
| Images, video, brand assets | Agility media, or a DAM | A picker app stores the asset reference |
| Private files (member downloads, gated PDFs) | Your own Azure Blob Storage or AWS S3 | A Secure Files app stores the file reference; your front end gives allowed readers a short-lived signed URL |
| Documents managed in Microsoft 365 | SharePoint | Agility stores a link |
| Sign-in and audiences | Identity provider | Your front end decides what each reader sees |
| Analytics and experiments | Analytics platform | The front end reports; apps show results to editors |

Good patterns to follow:

- **One owner per piece of data.** Store IDs, not copies, so prices, stock or documents are never out of date. See [Reference Architecture: Headless Commerce](/docs/developers/reference-architecture-headless-commerce).
- **Structure content so any channel can use it.** See [Structured Content Explained](/docs/developers/structured-content-explained) and [Beyond the Website](/docs/developers/beyond-the-website).
- **Design for a slow or missing service.** A page should still render when one system is down. See [Handle Rate Limits and Outages Gracefully](/docs/developers/handle-rate-limits-and-outages).
- **Keep keys on the server.** Only the Fetch key, which reads published content, is safe in a browser.
- **Keep private files private.** Files in the Agility media library are served from a public CDN URL. Files that need access control belong in your own storage, behind signed URLs.

[How Agility Works: A 10-Minute Architecture Tour](/docs/overview/how-agility-works) and [Reference Architectures](/docs/developers/reference-architectures) show complete designs.

## The five places an integration plugs in

Most integrations use one or two of these.

| Where | Direction | Use it for | Start here |
| --- | --- | --- | --- |
| **1. Your front end or app** | Agility → your code | Combining Agility content with other services at render time | [Content Fetch API](/docs/developers/content-fetch-api), [GraphQL API](/docs/developers/graphql-api) |
| **2. Webhooks** | Agility → other systems | Reacting when content is published, unpublished or changes workflow state | [Webhooks](/docs/developers/webhooks) |
| **3. Management API** | Other systems → Agility | Importing, syncing or updating content from a system of record | [Content Management API](/docs/developers/content-management-api) |
| **4. Apps inside Agility** | Inside the editor | Custom fields, pickers and sidebars that bring other systems into the editing experience | [Apps SDK](/docs/apps/apps-sdk) |
| **5. AI agents (MCP)** | Both ways | Letting AI assistants read, create and manage content with your permissions | [Agility CMS MCP Server](/docs/developers/agility-cms-mcp-server) |

### 1. Your front end or app

This is where composition usually happens. Your site reads pages and content from Agility and calls other services for the rest: product data from commerce, results from search, personalization from your audience data.

- Use the [Content Fetch API](/docs/developers/content-fetch-api) or the SDKs for pages and components, and the [GraphQL API](/docs/developers/graphql-api) for typed, field-level reads of content lists.
- For large or offline copies, use [Content Sync](/docs/developers/content-sync-explained).
- Not on a JavaScript framework? Any platform that can make an HTTP request can read Agility, including [Microsoft Power Pages](/docs/developers/microsoft-power-pages) and [SharePoint](/docs/developers/sharepoint). See also [Integrating Agility into a Traditional Website](/docs/overview/integration-agility-cms-into-a-traditional-website).

### 2. Webhooks

Webhooks tell other systems the moment content changes, so nothing has to poll. They clear caches, update search indexes, trigger builds and post to social channels.

- [Webhooks](/docs/developers/webhooks) and the [Webhook Events and Payload Reference](/docs/developers/webhook-events-and-payloads) describe what Agility sends.
- Always check the signature: [Verifying Signed Webhooks](/docs/developers/verifying-signed-webhooks).
- Re-fetch the content in your handler rather than trusting the payload alone, and make handlers safe to run twice.

### 3. Management API

The Management API writes to Agility: create and update content, upload media, manage pages and run workflow. Use it to import content, keep a list in sync with a system of record, or automate publishing.

- [Content Management API](/docs/developers/content-management-api), with SDKs for JavaScript and .NET.
- Use a [Personal Access Token](/docs/developers/personal-access-tokens) for long-running jobs.
- Saves land in Staging. Publishing is a separate step. When you publish pages through the API, publish their components too: publishing a page doesn't publish the content in its zones.
- Make syncs idempotent: store the other system's ID on each item, update instead of duplicating, and only write the fields that system owns.

### 4. Apps inside Agility

Apps bring other systems into the editor, so editors don't copy and paste IDs between browser tabs. A product picker, a DAM browser, a secure file field, a translation button or an analytics sidebar are all apps.

- [App Types In Agility](/docs/apps/apps-in-agility), [Creating Apps for Agility](/docs/apps/creating-apps-for-agility) and the [Apps SDK](/docs/apps/apps-sdk).
- [Picker Fields](/docs/apps/picker-fields) for choosing items from another system.
- [Extending the Rich Text Editor with an App](/docs/apps/extending-the-rich-text-editor).

### 5. AI agents through the MCP Server

The [Agility CMS MCP Server](/docs/developers/agility-cms-mcp-server) lets AI assistants such as Claude, ChatGPT or Microsoft 365 Copilot work with your instance: read content, create models, draft items and move them through workflow, always with the signed-in user's permissions. See [Connect the Agility MCP Server to Microsoft 365 Copilot](/docs/developers/connect-agility-mcp-server-to-microsoft-365-copilot).

## Patterns by use case

| You want to | Pattern | Guides |
| --- | --- | --- |
| Add site search | Webhooks keep an index current; the front end queries it | [Indexing Agility Content for Search](/docs/developers/indexing-content-for-search), [Algolia](/docs/developers/algolia), [Coveo](/docs/developers/coveo), [Elastic](/docs/developers/elastic), [Azure AI Search](/docs/developers/azure-ai-search) |
| Sell products | Commerce owns the catalog; Agility stores product IDs; a picker app helps editors | [Reference Architecture: Headless Commerce](/docs/developers/reference-architecture-headless-commerce), [BigCommerce](/docs/apps/bigcommerce), [Commercetools](/docs/apps/commercetools) |
| Capture leads | The front end posts forms to your CRM or form provider | [HubSpot](/docs/apps/hubspot), [Salesforce Sales Cloud](/docs/developers/salesforce-sales-cloud), [Formstack](/docs/apps/formstack), [TypeForm](/docs/apps/typeform) |
| Manage images and video | Use Agility media, or a DAM through a picker app | [Cloudinary](/docs/apps/cloudinary), [Bynder](/docs/apps/bynder), [Vimeo](/docs/apps/vimeo), [YouTube](/docs/apps/youtube) |
| Protect files and downloads | Files stay in your private cloud storage; editors attach them with a secure file field; the front end checks the reader and hands out a short-lived signed URL | [Secure Files - Azure](/docs/apps/secure-files-azure), [Secure Files - AWS](/docs/apps/secure-files-aws), [Reference Architecture: Member Portal and Intranet](/docs/developers/reference-architecture-member-portal) |
| Translate content | A translation app or automation writes to other locales | [DeepL](/docs/apps/deepl), [Google Translate](/docs/apps/google-translate), [Zapier Translate](/docs/developers/zapier-translate) |
| Run an intranet | A Microsoft front end reads Agility; documents stay in SharePoint | [Microsoft Power Pages](/docs/developers/microsoft-power-pages), [SharePoint](/docs/developers/sharepoint), [Reference Architecture: Member Portal and Intranet](/docs/developers/reference-architecture-member-portal) |
| Measure and experiment | The front end reports; an app shows results to editors | [PostHog](/docs/apps/posthog), [Google Analytics](/docs/apps/google-analytics) |
| Publish to social channels | Webhooks trigger posts when content goes live | [Publishing to Social Channels](/docs/developers/publishing-to-social-channels) |
| Deploy and rebuild | Webhooks trigger builds or cache clears on your host | [Vercel](/docs/developers/vercel), [Netlify](/docs/developers/netlify) |
| Serve many channels | One content hub, many front ends | [Building a Content Hub](/docs/overview/building-a-content-hub), [Reference Architecture: Multi-Channel Delivery](/docs/developers/reference-architecture-multi-channel) |

> [!NOTE]
> A **Secure Assets** app for the Agility marketplace is on the [roadmap](https://roadmap.agilitycms.com/c/fl-1099-secure-assets). Until it ships, use the Secure Files apps for Azure or AWS.

## How AI helps you do it all

AI agents are good at exactly the work integrations need: reading APIs, writing glue code, mapping fields and checking results. Use them at every stage, and keep people in charge of what goes live.

| Stage | What an agent does | Guides |
| --- | --- | --- |
| **Evaluate and design** | Connects to your instance, explains what's there, proposes content models and an integration plan | [Evaluate Agility with an AI Agent in 30 Minutes](/docs/overview/evaluate-agility-with-an-ai-agent), [Make Your Content Model Agent-Friendly](/docs/developers/agent-friendly-content-models) |
| **Build the integration** | Writes front-end code, webhook handlers and sync scripts against Agility and the other system's API | [Building an Agility Site with AI Coding Tools](/docs/developers/building-sites-with-ai-coding-tools), [Agility Skills for Your Coding Agent](/docs/developers/agility-skills-for-coding-agents), [Writing an AGENTS.md for Agility Projects](/docs/developers/agents-md-for-agility) |
| **Build apps for editors** | Scaffolds and builds Agility apps with the Apps SDK | [Building Apps with AI Coding Tools](/docs/apps/building-apps-with-ai-coding-tools), [How We Built the Google Analytics Page Sidebar with Claude](/docs/apps/building-the-google-analytics-page-sidebar-with-claude) |
| **Move content in** | Inventories the old system, maps fields and imports a reviewable sample, then writes the bulk import script | [Migrating Content into Agility with an AI Agent](/docs/developers/migrating-content-with-an-ai-agent), [Migrating to Agility](/docs/developers/migrating-to-agility) |
| **Test and ship** | Checks the integration end to end, in the browser and in CI | [Letting Agents Drive the Browser](/docs/developers/letting-agents-drive-the-browser), [Test Your Agility Integration in CI](/docs/developers/test-agility-integration-in-ci), [From Proof of Concept to Production](/docs/developers/vibe-coding-to-production) |
| **Run day to day** | Drafts and updates content through the MCP Server, for editors to review and publish | [Agility CMS MCP Server](/docs/developers/agility-cms-mcp-server), [MCP and Agility Gotchas to Know Before You Build](/docs/developers/vibe-coding-gotchas) |
| **Serve AI readers** | Makes your content easy for AI assistants and search to use | [Search for People and for AI Agents](/docs/developers/search-for-people-and-ai-agents), [Build an MCP Server over Your Agility Content](/docs/developers/build-an-mcp-server-for-your-content), [Making Your Agility-Powered Site Readable by AI](/docs/developers/making-your-site-readable-by-ai) |

Guardrails that keep this safe:

- **Agents act with the user's permissions.** Give the account an agent uses only the role it needs.
- **Work lands in Staging.** Review agent-created content and code before anything is published or deployed.
- **Move volume to scripts.** Let the agent write and test a script for bulk work, rather than making thousands of individual calls.
- **Verify, don't trust.** Check results with the Fetch API and in preview, not just the API's success response.

[Managing a Team of Coding Agents](/docs/developers/managing-a-team-of-coding-agents) and [Training Your Team to Build with Agents](/docs/developers/training-your-team-to-build-with-agents) cover running this as a team.

## Need a hand?

Working on an integration and want a second opinion on the approach? [Contact us](mailto:support@agilitycms.com) and we'll help.

## Related

- [Reference Architectures](/docs/developers/reference-architectures)
- [Headless, Hybrid or Traditional: Choose Your Delivery Model](/docs/overview/choose-your-delivery-model)
- [Content Security Policy and Network Allowlist](/docs/developers/content-security-policy-and-network-allowlist)
- [Webhooks](/docs/developers/webhooks)
- [Apps SDK](/docs/apps/apps-sdk)

---

## Related pages

- [Zapier Translate](https://agilitycms.com/docs/developers/zapier-translate.md)
- [Vercel](https://agilitycms.com/docs/developers/vercel.md)
- [Ahrefs](https://agilitycms.com/docs/developers/ahrefs.md)
- [Netlify](https://agilitycms.com/docs/developers/netlify.md)
- [Salesforce Sales Cloud](https://agilitycms.com/docs/developers/salesforce-sales-cloud.md)
- [Auth](https://agilitycms.com/docs/developers/auth0.md)
- [User Generated Content (UGC)](https://agilitycms.com/docs/developers/user-generated-content-ugc.md)
- [Microsoft Power Pages](https://agilitycms.com/docs/developers/microsoft-power-pages.md)
- [SharePoint](https://agilitycms.com/docs/developers/sharepoint.md)

Index of every docs page: https://agilitycms.com/docs/llms.txt