How to publish from your pipeline

Goal

Publish a compiled documentation package so it becomes the live version for this workspace.

Conditions

• You already have a docs build that emits files.
• You are a workspace owner or admin.
• You want go-live, not chat indexing. Sync is a different job. *(see How-to: How to connect a source)* *(see Explanation: About Hosted Docs)*

Procedure

1. In the dashboard under Publishing credentials, create a push token. It starts with hdpt_ and is shown once. Store it as HOSTED_DOCS_PUSH_TOKEN.
2. If you want a full package, POST the manifest plus file bytes:
   POST /api/broker/push

   POST https://hosted.devdocs.ai/api/broker/push
   Authorization: Bearer hdpt_your_push_token
   Content-Type: application/json
   
   {
     "manifest": {
       "version": "<any string, for example the git sha>",
       "generator": "<your build tool>",
       "entries": [
         { "path": "index.page.json", "sha256": "<hex sha256 of the bytes>", "size": 1234 }
       ]
     },
     "files": {
       "index.page.json": "<base64 of the file bytes>"
     }
   }

3. If you want a Markdown-only push (no manifest.json, no .page.json), send the .md files. The host compiles missing reader artifacts when the push is under 300 Markdown pages and 8 MiB of Markdown. If compile cannot finish, the version still goes live and shapingNotice says why.
4. Treat a 200 as live. There is no separate activate step.
5. If you need rollback, push a known-good build again.

Verification

A successful push returns 200:

HTTP/1.1 200 OK
{
  "versionId": "...",
  "entries": 42,
  "chunksIndexed": 128,
  "r2Prefix": "...",
  "shapedPages": 0
}

Open the workspace subdomain. You should see this version.

Failures

• sha256 or size mismatch: the whole push is rejected. The live version is untouched.
• Traversal or absolute paths: rejected. Use relative paths such as index.md.
• shapingNotice: version is live, but pages we could not compile will not render. Prefer emitting a full package from your build. *(see Reference: Content and navigation)*