# Push your docs

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

### 1. Pack the folder

```sh
tar -czf docs.tar.gz -C docs .
```

### 2. Send it

```sh
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:

```sh
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](../get-started/plans-and-limits#docs). 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](bundle). |
| `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`