Draft & publish

Publish the staged draft to the live site

Promotes the draft to the live site and refreshes the serving index. Everything is optional in the body: send {} (or nothing) to publish everything that is staged, or keys / routes to publish only part of it.

Before it goes live the publish checks that the site has a real purpose in its brief (first publish), that no <dotsy-collection> card template would render empty, that redirects do not loop, that the site's Rules pass (for agents, a blocking Rule answers 422; a person gets ruleWarnings on the 200), and that no import or adapt job is still running. A blocked publish answers an error and changes nothing.

feedback and handoff are optional. Agents send them so Dotsy learns from the session and the next session inherits the decisions made in this one.

post/api/v1/sites/{slug}/publish

Request

  • Base URL: https://api.dotsy.ai
  • URL: https://api.dotsy.ai/api/v1/sites/{slug}/publish
  • Auth: HTTP bearer

Path parameters

slugstring required
Example:acme-studio

Site slug or site id (UUID). An old slug answers 301/308 and a site id 307 to the canonical slug path.

Request body

handoffstring

Optional one-line hand-off note (decisions, preferences, open threads) appended to the site brief's hand-off log before the publish. Routine no-information notes such as "Routine dashboard publish." are not appended.

keysstring[]

Selective publish: content keys to promote. Everything else stays staged. Unknown keys are ignored. Omit keys and routes (or send both empty) to publish everything.

routesstring[]

Selective publish: route paths to promote (see keys). Unknown paths are ignored.

autoboolean

Set by the dashboard's live mode, where every save publishes. Leave it out.

Example request

{
  "handoff": "Switched the hero to the new photo; pricing copy still needs review.",
  "keys": [
    "blog/launch.html"
  ],
  "routes": [
    "/blog/launch"
  ]
}

Response

Published. The site is live.

okboolean required
status'published' required
publishedAtnumber required

Publish time, Unix ms.

pagesnumber required

Keys in the published manifest.

feedbackStoredboolean required

False when the request carried no feedback (or the feedback sink is not configured). The publish succeeds either way.

feedbackQueuedboolean

True when feedback was queued to the outbox because PostgREST was unreachable (0.74 M4).

integrationsPendinginteger

Count of unresolved clone integrations (non-blocking; 0.27.1 M3.2).

publicUrlstring required
liveUrlstring required
liveReadytrue required
collectionDataPendingstring[]

Collections whose data file did not finish building (partial build). The publish is live; republish to retry.

collectionSqlPendingstring[]

Collections whose SQL index did not finish building. The publish is live; republish to retry.

collectionDiscoveryPendinginteger

Pages not yet indexed for the collections they place. The publish is live and every collection built before keeps serving its last data (marked pending); republish shortly to finish. Absent when discovery was complete.

deprecationWarningsstring[]

Non-blocking notices about deprecated markup the publish found.

fragmentWarningsstring[]

Pages that went live with a <dotsy-fragment> that has no fragments/<name>.html, so visitors see the raw tag. One line each, starting fragment_not_found:, with the pages and a likely name when one is close. Create the fragment or fix the name, then publish again.

seoFileWarningsstring[]

The site's own robots.txt or sitemap.xml that this publish did not use: a robots.txt that blocks the whole site (Disallow: / for every crawler) or any static sitemap.xml needs the ownSeoFiles site setting; the generated file keeps serving. Also a robots.txt that is used but names a Sitemap: on another host (served as written), and each _headers line this publish refused (_headers line N: …: a header outside the allowlist, a control character, a Cache-Control over max-age 3600 or with immutable), or the file over its 4 KB / 30-rule caps.

materializedDraftJobsnumber

Pending import/bulk draft fragments folded into this publish.

templateScanPartialtrue

The empty-collection template gate hit its key cap — listing pages beyond the first 1,000 scanned keys were not checked.

postCommitWarningsstring[]

Post-commit enrichment steps that failed. The publish is live; republish to retry them.

Example response

{
  "publicUrl": "https://acme-studio.dotsy.site/"
}

Changes

No recorded changes to this operation across all 1 revision of this API.