---
title: "Change where a shared section shows"
method: POST
path: "/api/v1/sites/{slug}/shared-sections/{name}/placement"
tags: ["Content"]
---

# Change where a shared section shows

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

## Request

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

Move it between the pages where it appears and every page (one slot in the layout), or hide it on some pages of an every-page section and show it there again. The hide marker lives in each page's `<dotsy-config>`, so it moves with the page. All pages of a call change together or none do. Over the per-call cap, move to every page in slices with `keys`: the first call also places it in the layout and takes the inline copy of every page it doesn't hide, a page not moved yet keeps its own reference (and shows it once). Pages kept out are hidden with the first move, or before it (`hide` without `scope`, in as many calls as needed). Staged as a draft; `dryRun` reports without writing.

## Path parameters

- `slug` string, required
- `name` string, required

## Request body

- SharedSectionPlacementRequest
  - `scope` 'where_found' | 'every_page': Move the section between where_found and every_page, in one all-or-nothing change.
  - `keys` string[]: every_page in slices, for a move over the per-call cap: the pages that place it whose own tag this call removes (default all of them). The first call also puts it in the layout; pages not moved yet keep their tag and still show it once. Call again with the next slice until every page is moved.
  - `hide` string[]: Pages that should stop showing this every-page section (a marker in each page's <dotsy-config>). Moving to every page, pages kept out (they keep their own copy) go with the first move or ahead of it (hide without scope, before any move).
  - `show` string[]: Pages that should show it again (removes their marker).
  - `dryRun` boolean: Report what would change; write nothing.

## Response `200`

Placed (staged as a draft), or what would change on a dry run.

- SharedSectionPlacementResult
  - `name` string, required
  - `key` string, required
  - `scope` 'where_found' | 'every_page', required
  - `pages` integer, required
  - `hidden` integer, required
  - `skipped` object[]: Pages left alone. `ambiguous_similar`: none or several similar copies on the page; on every page such a page hides the section (it keeps its own copies, and counts in `hidden`). `not_a_match` (`selectors` only): the index listed the page but its stored HTML doesn't hold the same run of elements, so it keeps what it has.
    - `key` string, required
    - `reason` 'ambiguous_similar' | 'not_a_match', required
  - `written` string[], required: Every content key this call staged (or, on a dry run, would stage): the section file, pages, the layout. Staged as a draft; in live publishing mode the dashboard then publishes exactly these keys.
  - `dryRun` boolean, required
  - `alreadyApplied` boolean, required
  - `eventId` string, nullable, required: The activity event of this change — undo with POST …/activity/{eventId}/revert. Null on a dry run, when nothing was written, or when the audit insert failed.

## Other responses

- `400`: The body is not valid, or the change needs more pages than one call can change (`too_many_pages`, with `max`).
- `401`: Missing or invalid credentials.
- `403`: The key or token cannot edit this site (viewer role, or AI access set to read only).
- `404`: No such site, or no such section (`section_not_found`).
- `409`: A page changed (`shared_section_conflict`, nothing written), or a later every-page slice hid a page whose own copy the first move already took (`hide_after_move`). `index_warming`: the index is not ready yet — 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)