Push your docs

Every push is the whole folder, as a gzipped tar archive, sent with a project key.

1. Pack the folder

tar -czf docs.tar.gz -C docs .

2. Send it

curl -sS -X POST "$BASE/docs?branch=main&commit=$GITHUB_SHA" -H "Authorization: Bearer $LATITUDE10_KEY" -H "Content-Type: application/gzip" --data-binary @docs.tar.gz

The answer, with 201, holds the build's id, its kind, its label, its page count, its url and warnings: every broken link, missing image, unknown config key or page left out of the navigation. A push with warnings still builds, so read them in CI.

Parameters

Parameter	What it's for
`branch`	Required. The Git branch the folder came from.
`commit`	The commit SHA, kept with the build.
`version`	A label such as `v1`: the push becomes a versioned copy at `/v/<label>`.
`preview`	`1`: the push becomes a private preview of the branch.

version and preview can't both be sent.

The docs branch

Without version or preview, a push replaces the live site. The first branch you push becomes the project's docs branch, and a production push from any other branch answers 409, so a feature branch can't replace the site by accident. Change the docs branch in the project's Docs panel.

Previews

On Pro and up, preview=1 builds a branch on its own. The answer adds previewUrl, a private address with a random token in it: share it with reviewers, since nobody can guess it. A preview expires after 14 days. Pushing the same branch again replaces its preview.

Delete a preview when its pull request closes:

curl -sS -X DELETE "$BASE/docs/previews/feature%2Fnew-guide" -H "Authorization: Bearer $LATITUDE10_KEY"

It answers 204 whether or not there was a preview. Encode a / in the branch name as %2F.

How many versions and previews a project keeps, and how many pushes it gets a day, depend on the plan: see Plans and limits. A new version or preview past the plan's number is refused until you delete one in the workspace.

Errors

Status	When
`400`	`branch` is missing or malformed, `commit` or `version` is malformed, or both `version` and `preview` were sent.
`403`	The plan has no versions or previews, or already has as many as it keeps.
`409`	A production push from a branch that isn't the docs branch.
`413`	The folder is over the plan's size or page count.
`415`	The body isn't sent as `application/gzip`.
`422`	The archive or its config is refused: see The docs folder.
`429`	The project's docs pushes for today are used.

Where this comes from

app/api/registry/v1/docs/route.ts
app/api/registry/v1/docs/previews/[branch]/route.ts
app/docs/_lib/store.ts
app/docs/_lib/build.ts
openapi/registry-v1.yaml