Tools: publishing

These tools control what goes live. Publishing always needs the user's explicit approval.

set_publish_state

Marks pages as draft, ready or deleted. New pages start as ready, so you only need this when the user asks.

When to use it: When the user asks to make a page a draft, mark it ready, or delete it. Deleted pages disappear from the live site at the next publish and can be restored until then.

Needs an open turn: Yes. Call start_turn first.

Input	Type	Required	Meaning
targets	array	Yes	The pages to change. Each is {"kind": "page", "ref": "/pricing"}. Only pages have a publish status; CMS items are published in the CMS view.
status	string: draft, ready or deleted	Yes	The status to set on every target.

Example call

{
  "siteId": "0APMiuxGY2yB4xJm5BilJ",
  "targets": [
    {
      "kind": "page",
      "ref": "/pricing"
    }
  ],
  "status": "draft"
}

Example result

{
  "success": true,
  "updated": 1,
  "status": "draft",
  "results": [
    {
      "key": "page:/pricing",
      "status": "draft"
    }
  ]
}

See Draft, ready and live pages.

Errors

You see	What it means	What to do
confirmation_required	deleted needs the user's approval.	Ask the user. If they agree, call again with _confirmed: true added.
"page ref must start with "/""	The page address is missing its leading /.	Use the address as list_pages shows it.
"no valid targets"	None of the targets could be changed. errors explains each.	Fix the targets and retry.
not_lock_holder	Your agent has no open turn on this site, or its turn lapsed.	Call start_turn, then retry.
lock_lost	Someone took the site back (for example with Take back control) or the turn expired and was reopened.	Call start_turn to begin a new turn, then retry.
site_publishing	The site is publishing. Editing is paused until it finishes.	Wait for the publish to finish, then retry.

publish

Builds the site and puts it live at its Starjay address and any connected domains. It returns as soon as the publish starts.

When to use it: Only after the user approves this publish, and after they've saved or rejected the AI session in the editor.

Needs an open turn: No. Publishing is refused while an AI session is waiting for Save or Reject, so end your turn and ask the user to review first.

Input	Type	Required	Meaning
_confirmed	boolean	Yes, in practice	Set to true only after the user approves publishing this site in the current conversation. Without it, the call is refused with confirmation_required.

Example call

{
  "siteId": "0APMiuxGY2yB4xJm5BilJ",
  "_confirmed": true
}

Example result

{
  "accepted": true,
  "jobId": "pub_…"
}

While a site publishes, editing is paused for everyone. See Publish your site.

Errors

You see	What it means	What to do
confirmation_required	The call didn't carry the user's approval.	Ask the user. Call again with _confirmed: true only after a clear yes.
accepted: false: "Accept or reject current AI changes before publishing."	There's an AI session waiting for review.	Ask the user to click Save or Reject in the editor, then publish.
accepted: false: "The site is already publishing."	A publish is running.	Follow it with get_publish_status.
accepted: false: "CMS items are still publishing. Publish the site when they finish."	A CMS publish is running.	Wait a few seconds, then retry.
accepted: false with site_archived	The site is archived.	The user restores it from the dashboard first.

get_publish_status

Shows the site's most recent publish: whether it's still running, its status and stage, the live address, and any error.

When to use it: After publish, every few seconds until active is false. Then report the result and address to the user.

Needs an open turn: No.

No inputs besides siteId.

Example call

{
  "siteId": "0APMiuxGY2yB4xJm5BilJ"
}

Example result

{
  "active": false,
  "status": "done",
  "phase": "…",
  "siteId": "0APMiuxGY2yB4xJm5BilJ",
  "jobId": "pub_…",
  "startedAt": "2026-10-17T22:05:00.000Z",
  "url": "https://bakery.starjay.app",
  "error": null
}

status is queued, running, done, failed or cancelled. A site that has never been published returns {"active": false}. If the status is failed, tell the user what error says; they can retry from the editor's Publish panel.

Related

• Publish your site
• Permissions and safety