Skip to main content

Search listing

How a site is described to search engines: the title and description its pages fall back to, the separator between a page's name and the site's title, and the pattern a page's title is built from. These are the four fields of the console's Setup → SEO base card.

Each page can also have a listing of its own, which wins over the site's — that is on pages. A product's page has its own listing too, on the product.

Scopes: seo:read to read, seo:write to change.

The search listing object​

{
"object": "site_seo",
"site": "host_demo",
"title": "Demo Bakery — bread and pastries in Austin",
"description": "Sourdough, rye and pastries baked fresh every morning. Order online for pickup.",
"separator": "|",
"titlePattern": null,
"image": "https://…/social-card.jpg",
"imageAlt": "A table of fresh loaves"
}
FieldTypeNotes
objectstringAlways "site_seo".
sitestringThe site's id.
titlestring | nullThe title a page with no search title of its own falls back to.
descriptionstring | nullThe description a page with no search description of its own falls back to.
separatorstring | nullThe character between a page's name and the site title, such as |.
titlePatternstring | nullHow a page with no search title of its own is titled, using {{page.name}}, {{site.separator}} and {{site.name}}. null is the default pattern.
imagestring | nullThe social image shown when a page is shared. Read-only here.
imageAltstring | nullWhat the social image shows. Read-only here.

What the API doesn't change​

The rest of Setup → SEO stays in the console: the switch that asks search engines to stay away, the site verification codes, the text for AI agents, the local business fields, and the social image. A write that names any of them is a 400 that names the member.

Endpoints​

Retrieve the search listing​

GET /v1/sites/{siteId}/seo — scope seo:read.

curl "https://app.aglyn.com/api/v1/sites/host_demo/seo" \
-H "Authorization: Bearer aglyn_sk_…"

Update the search listing​

PATCH /v1/sites/{siteId}/seo — scope seo:write.

A member left out keeps its value. Returns the search listing as saved.

curl -X PATCH "https://app.aglyn.com/api/v1/sites/host_demo/seo" \
-H "Authorization: Bearer aglyn_sk_…" \
-H "Content-Type: application/json" \
-d '{
"title": "Demo Bakery — Austin sourdough",
"titlePattern": "{{page.name}} {{site.separator}} {{site.name}}"
}'
MemberNotes
titleAt most 60 characters. Required: it cannot be emptied.
descriptionAt most 155 characters. Required: it cannot be emptied.
separatorAt most 3 characters. Required: it cannot be emptied.
titlePatternAt most 120 characters. The only one that can be cleared: an empty string or null goes back to the default pattern.

Over the API the limits are hard. The console shows the title and description limits as guidance; a program writing a listing is held to what a search result shows.

Changes are live when saved​

The console has no draft for these settings: a change is saved at once, and the live site refreshes right away — search engines and the browser tab see the new title and description the next time they load a page. There's no need to publish after it.

Because there is nothing to review afterwards, an app acting for a person should show the change and get their approval before it sends the write.

Errors​

StatustypeWhen
400bad_requestcode: "validation_failed" — a member that isn't writable, a value over its limit, or title, description or separator emptied. fields names each.
403insufficient_scopeKey lacks seo:read, or seo:write on a PATCH.
403forbiddencode: "site_permission_required" — a connected app whose person can't edit the site's content.
404not_foundUnknown or unowned site.
405method_not_allowedAllow: GET, PATCH.
423—The site is locked.
  • Pages — each page's own search listing.
  • Business details — the name, address and contact details the site shows.
  • SEO Toolkit — the same settings in the console.