---
title: "Find where an element repeats before sharing it"
method: POST
path: "/api/v1/sites/{slug}/shared-sections/analyze"
tags: ["Content"]
---

# Find where an element repeats before sharing it

`POST /api/v1/sites/{slug}/shared-sections/analyze`

## Request

- Base URL: `https://api.dotsy.ai`
- URL: `https://api.dotsy.ai/api/v1/sites/{slug}/shared-sections/analyze`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Reads the element from the page's stored HTML and looks it up in the site's section index: the pages with an exact copy, the pages with a similar copy (same structure, different words), whether it can go on every page, and a free name. With `selectors`, the same for a run of elements next to each other (no similar copies). Writes nothing. One stored-page read; the counts come from the index.

## Path parameters

- `slug` string, required

## Request body

- AnalyzeSharedSectionRequest
  - `sourceKey` string, required: Content key of the page the element is on, e.g. 'about.html'.
  - `selector` string: CSS selector of the element in the page's stored HTML (the editor's selector, or one checked with get_content?selector=). It must match exactly one element.
  - `ifMatch` string: The page's content hash (analyze's sourceEtag). If the page changed since, nothing is written.
  - `selectors` string[]: A run of elements that sit next to each other in one parent (only whitespace or comments between), in page order — instead of `selector`. Each must match exactly one element. The section is the run inside one wrapper (`wrapTag`); the pages that hold the same run (the same elements, in the same order, next to each other) take it.
  - `wrapTag` 'div' | 'section' | 'footer' | 'header' | 'article' | 'aside': With `selectors`: the wrapper element. Default `footer` when the run is the last of the page content, else `section`.
  - `keepLayout` boolean: With `selectors`: give the wrapper style="display:contents" so a flex or grid parent still lays out the run's elements as before. Default true.

## Response `200`

Where it repeats.

- AnalyzeSharedSectionResult
  - `sourceKey` string, required
  - `sourceEtag` string, required: The page's content hash. Send it back as `ifMatch` to share.
  - `block` object, required
    - `exact` string, required: Hash of the element's normalised HTML (text and classes kept). For `selectors`: the run's id (as in suggestions).
    - `tag` string, required: The element's tag; for `selectors`, the wrapper the section gets.
    - `text` string, required: Its first 120 characters of text, for a label.
    - `bytes` integer, required
  - `proposedName` string, required: A free section name made from its heading or text.
  - `matches` object, required
    - `pages` integer, required: Distinct pages, counted in full.
    - `keys` object[], required: Pages with an exact copy, the source page first, at most 200. For `selectors`: pages with the same run.
      - `key` string, required
      - `count` integer, required: Copies on that page (all are replaced).
    - `more` boolean, required: True when there are more pages than `keys` lists.
  - `similar` object, required
    - `pages` integer, required: Distinct pages, counted in full.
    - `keys` object[], required: Pages with the same structure but different words, closest first, at most 200. Not shared unless sent in `similar`. Always empty for `selectors` (a run is only shared where it repeats exactly).
      - `key` string, required
      - `score` number, required: 0–1; higher is closer.
    - `more` boolean, required: True when there are more pages than `keys` lists.
  - `placement` object, required
    - `everyPageAllowed` boolean, required
    - `reason` 'inside_section' | 'spans_template' | 'not_a_block' | 'too_large' | 'collection_page' | 'no_layout' | 'several_layouts' | 'not_at_edge' | 'layout_owned' | 'nested' | 'not_on_page' | 'page_config_invalid' | 'too_deep' | 'has_code', nullable, required: Why `every_page` is not offered.
    - `layout` string, nullable, required
    - `edge` 'top' | 'bottom', nullable, required: Where the layout slot goes, around the page content.
    - `layoutPages` integer, required: Pages that use that layout.
    - `gaining` object, required
      - `pages` integer, required: Distinct pages, counted in full.
      - `keys` string[], required: Pages on the layout without a copy today. With `every_page` they show it too, unless you list them in `hide`.
      - `more` boolean, required: True when there are more pages than `keys` lists.
  - `indexWarming` boolean, required: The index is still being built: counts may be low, and sharing is refused until it is done.
  - `warnings` object[], required
    - `code` string, required
    - `hint` string, required

## Other responses

- `400`: The body or selector is not valid.
- `401`: Missing or invalid credentials.
- `404`: No such site, or the page (`content_not_found`).
- `409`: The page changed since `ifMatch` (`shared_section_conflict`), or `index_warming`: on a site whose route list isn't cached, reading it now would not leave room for the rest of the call — retry in a minute.
- `422`: The element or page can't take part (`not_eligible`, with `reason`), the selector matched 0 or 2+ elements (`unexpected_match_count`), or `selectors` don't sit next to each other in one parent, in page order (`not_siblings`).

---

[API](https://skmtc.dev/dotsy/apis/dotsy-api.md) · [All operations](https://skmtc.dev/dotsy/apis/dotsy-api/llms.txt) · [OpenAPI document](https://skmtc.dev/dotsy/apis/dotsy-api/revisions/4272ed3b85d7?raw)