# Deployments

| Method | Path | Purpose |
|---|---|---|
| POST | `/check` | Validate a file bundle and return a manifest and diff |
| PATCH | `/push` | Deploy the validated manifest to preview |
| POST | `/publish` | Promote preview to live with its knowledge changes, once its tests allow it |
| POST | `/rollback` | Restore previous live |
| GET | `/status` | Deployment pointers |
| GET | `/manifest?environment=preview` | A deployed manifest |
| GET | `/env` | Both environments, with the branch preview was pushed from and its unpublished knowledge changes |
| GET | `/env/:name` | `preview` or `live`: token, share URL, knowledge changes and conflicts, its own secret names |

First call `POST /check` with the workspace files:

```json
{
  "environment": "preview",
  "files": [
    {
      "path": "vatio.yml",
      "encoding": "utf-8",
      "content": "workspace: acme\nagent:\n  instructions: Help visitors learn about Acme.\n"
    }
  ]
}
```

Each file has a relative `path`, `content`, and `encoding` (`utf-8` or `base64`).
The response contains `ok`, `manifest`, `errors`, `warnings`, and `diff`.
Diagnostics contain `message` and `path`. Validation failure is HTTP 200 with
`ok: false`; an unreadable or oversized bundle is 422.

When `ok` is true, send the returned `manifest` unchanged to
`PATCH /push` with optional `git_sha`, `git_branch` and `force`. Do not
construct the normalized manifest yourself. The response includes
`deployment_id`, `environment`, `share_url`, and `preview_url`; `share_url` is
the inbox's **Test** page for preview, open to the workspace's owner and
developers.
Once the workspace is published, a push from a different `git_branch` than
preview's unpublished version came from answers 422 with
`error_key: "preview_has_unpublished_push"`, unless `"force": true`
([Working with others](https://vatio.ai/docs/deployments#working-with-others)).

Publish promotes preview's current version. Its knowledge changes go live with
it, listed in `knowledge`; when live changed one of those entries meanwhile,
publish answers 409 with `error_key: "knowledge_conflict"` and nothing moves.
`notices` carries anything to show the developer, such as a deprecation, or
that preview was already live's version: then nothing moves but its knowledge
changes, and the answer describes live as it already was.
Once the workspace is published, publish answers 422 when preview's tests say
no ([Publishing](https://vatio.ai/docs/deployments#publishing)):

| `error_key` | When |
|---|---|
| `evals_missing` | Preview's version has not been tested: run `vatio eval`, then publish |
| `evals_running` | Its tests are still running |
| `evals_regressed` | A flag that passes on live fails on it. The body also has `regressions: [{ "id": "F-7K2QX", "title": "…" }]` |

`{ "force": true }` publishes anyway. Rollback needs no body. Neither
operation uploads your local files.