Publish and rerender

A content change needs neither of these. Pages go live when they are written: there is no build step, no publish gate, and nothing to purge afterwards. These two endpoints exist for the rarer case where you need to act on stored content without changing it.

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

Publish

POST /v1/sites/:site/publish

Refreshes every cached page for the site at once. There is no partially-updated window: one call, and every subsequent request is answered from freshly built output.

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.

That is the whole operation. It publishes nothing that was not already live, so it is not a staging gate: use it when something outside your own writes changed how pages should look, or when you simply want a response rebuilt now rather than served from cache. It is also a safe no-op health check on the write path.

Publishing also retires the stored pages held by installed offline readers, so nobody keeps an obsolete procedure after a correction ships.

Rerender

POST /v1/sites/:site/rerender

Re-runs the render over stored markdown for every page of every version of the site. Titles, descriptions, HTML, tables of contents, and search index entries are all rewritten from the markdown you already pushed. No content changes; only its rendered form.

Reach for it after Docsary itself gains a rendering change you want applied to pages you are not otherwise touching. Re-pushing your folder does the same thing, so this is mainly for the case where the source is not conveniently to hand.

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

Pages are processed in a stable order, so the offset stays meaningful across calls.

What happens at the end

The final call — the one returning next_offset: null — rebuilds the navigation tree for every version and publishes the result.

Nothing is published mid-loop. While a rerender is in progress the site keeps serving what it was already serving, and readers see the new output only once the loop completes. Half-rerendered content never reaches anyone; an abandoned loop leaves the site exactly as it was, which is the safe failure.

An interrupted loop can simply be restarted from offset: 0. Rerendering a page that was already rerendered is harmless.