Publish and rerender

Pages are published as they are written. These endpoints refresh cached responses or regenerate rendered pages; they do not hold changes for later release.

Both require an organization API key. :site accepts a slug or an id.

Publish

POST /v1/sites/:site/publish

Advances the site's cache generation. Requests use the new generation after host metadata refreshes; browser caches may still serve older responses. This is not an atomic content switch.

curl -s -X POST "$DOCSARY_API/v1/sites/acme/publish" \
  -H "authorization: Bearer $DOCSARY_KEY"

Responds 200 with the site's current publish counter — the same value that appears in the x-docsary-epoch header on every served page.

Use this to request fresh server responses without editing content. It does not publish a draft or create an atomic release.

Installed offline readers replace their saved pages when they reconnect and receive the update. Publishing cannot update a disconnected device.

Rerender

POST /v1/sites/:site/rerender

Regenerates rendered content for every page in every version from stored Markdown. It refreshes titles, descriptions, HTML, tables of contents, and search entries without changing the source.

Use rerender when a rendering change must apply to existing pages. Re-pushing identical Markdown leaves the stored render unchanged.

The loop

The endpoint processes a small batch per call and tells you where to resume.

curl -s -X POST "$DOCSARY_API/v1/sites/acme/rerender" \
  -H "authorization: Bearer $DOCSARY_KEY" \
  -H "content-type: application/json" \
  -d '{"offset":0}'

{ "processed": 6, "next_offset": 6 }

Call again with the returned next_offset until it comes back null:

{ "processed": 3, "next_offset": null }

offset=0
while [ "$offset" != "null" ]; do
  offset=$(curl -s -X POST "$DOCSARY_API/v1/sites/acme/rerender" \
    -H "authorization: Bearer $DOCSARY_KEY" \
    -H "content-type: application/json" \
    -d "{\"offset\":$offset}" | sed -n 's/.*"next_offset":\([^,}]*\).*/\1/p')
  echo "at $offset"
done

Keep other page writes paused during the loop so offsets continue to identify the intended pages.

What happens at the end

Rerender updates stored pages in place, one batch at a time. Readers can encounter mixed output before completion. The final batch rebuilds navigation and advances the cache generation. An interrupted run leaves completed changes in place; restart from offset zero.

Rerendering a page that was already rerendered is harmless.