How to connect Craft CMS, and what agents can change there
Updated
In the Craft control panel, create a GraphQL token whose schema has Create/save entries on your sections. Paste your Site Domain and GraphQL Token on the Craft CMS row in Connections. Your agents edit titles, URLs, text and asset alt text, add new entries, and fill SEO values kept in plain custom fields.
Before you start#
- You need Craft 5, or Craft 4.8 or later, any edition. Craft 3.5 to 4.7 need the Pro edition for GraphQL.
- Your GraphQL schema needs Create/save entries on the sections SEOmatic should work on. Edit it in GraphQL, Schemas.
Your website must show the fields
On a headless Craft site, SEOmatic fills in fields in your entries. Google only sees an SEO title, canonical or noindex if your website's code reads that field.
Connect Craft CMS#
- In the Craft control panel, go to GraphQL, Tokens, click New token and pick the schema above. Copy the token.
- In SEOmatic, on the Craft CMS row, click Add Connection. Fill in Site Domain and GraphQL Token, then click Connect.
- Right after you connect, SEOmatic asks where agent articles go. Pick the section and entry type for blog posts.
To change the target later, click Change next to Agent articles publish to on the connection card.
What your agents can change on Craft CMS#
| Change | What happens | Notes |
|---|---|---|
| Title and URL | Live | |
| Text in plain text and rich text fields | Live | |
| SEO title, meta description, canonical, noindex | Live | When they are plain custom fields with conventional handles |
| Asset alt text | Live | |
| New entries | Live | In the section you chose |
| Values inside Craft SEO plugins | Paste | Including SEOmatic for Craft, a different product from ours |
| Redirects | Paste | Retour has no write API. Add them in Retour or your server |
Fix connection errors#
| You see | What to do |
|---|---|
| Could not find a Craft GraphQL endpoint on this domain... | Check that GraphQL is on and the token is enabled and not expired. On Apache, ask your host to pass the Authorization header through. |
| The token was accepted but its GraphQL schema cannot save any entries... | Edit the schema in GraphQL, Schemas and turn on Create/save entries for your sections. If you just created the token, copy it again. |
| Could not reach the Craft site: followed by a reason | Check the Site Domain. It must be reachable from the internet. |
- I use SEOmatic for Craft. Is that this product?
- No. SEOmatic for Craft is a separate Craft plugin by another company. Your agents do not write the values it stores, and give you those changes to paste.
Was this article helpful?
Still need help?Email contact@seomatic.ai with your site address and a screenshot. A person replies, usually within one business day.