Use this page when a Vary app is intended to serve a public API through Via.

## App manifest

The app manifest records the production-facing contract:

| Manifest field | What to declare |
|---|---|
| App id | Stable app id used by Via deploy records. |
| Required capabilities | Runtime capabilities such as `http`, `sqlite`, `worker`, `config`, `secrets`, `outbound_http`, `route`, and `backup`. |
| Config keys | Runtime config names that must be present before the app serves traffic. |
| Managed SQLite | Binding name, add-on name, schema version, and migration history. |
| Routes | Hostname, path prefix, service target, port, and smoke path. |
| Workers | Worker names, commands, and required/drain status. |
| Health/readiness | HTTP paths and readiness check names used before Via serves traffic. |
| Rollback | Code rollback mode, schema downgrade refusal, and restored metadata checks. |

Declare these fields in `via.app.toml` and validate them before deploy:

```bash
via app manifest validate --file via.app.toml
via app manifest apply --file via.app.toml
via app manifest smoke --file via.app.toml
```

`validate` checks manifest shape and required production metadata. `apply`
creates or reuses declared managed SQLite add-ons, binds them to the app for
the next deployment, and stages declared routes through Via route metadata.
`smoke` prints the health, readiness, route, SQLite, and representative request
checks for the app.

## Capabilities and config keys

Each public route should map to an explicit capability. Config keys and secrets
are not read from public requests. Via serves runtime config through workload
identity; build jobs do not receive runtime config, add-on descriptors, or
SQLite credentials.

## Managed add-ons

Declare and apply managed SQLite before the release that needs it:

```bash
via app manifest apply --file via.app.toml
vary app deploy my-api --target prod
```

The deploy snapshots the binding into the release. App code connects with
`Sql.connect("DATABASE")` or `Sql.connect_managed("DATABASE", schema)`.

## Domain routing

Public traffic is declared in the manifest and staged through Via route
metadata:

```bash
via app manifest apply --file via.app.toml
via route validate --app my-api <route-id>
via load-balancer reload
```

Via checks hostname policy, DNS proof, optional approval, certificate coverage,
route target, port range, and route conflicts before traffic becomes active.

## Backup and restore checks

Before a public API release, verify that `via backup create` includes the
control-plane database and managed add-on storage. Restore checks must prove the
schema version, the `v1 release_baseline` migration record, add-on binding
metadata, and app release records survive the round trip.

Managed SQLite restores require an explicit safety choice such as drain and
restart. The restore operation should produce an audit event and should not
silently change the database under a running app.

For public APIs, Via compares restored SQLite metadata with the manifest before
serving traffic. The restored `schema_version` must match the manifest, the
restored migration history must contain every declared migration, and extra
unknown migrations are treated as an incompatible downgrade/rollback target.

## Rollback behavior

App code rollback reuses a previous signed artifact; it does not rebuild the
target revision. A failed build, failed test run, failed runtime start, or
failed route reload must leave the current serving deploy in place.

Schema rollback is fail-closed. If the selected artifact expects older SQLite
metadata than the restored database records, Via refuses the downgrade before
serving traffic. Restored databases must keep schema version and migration
history metadata so this decision survives backup/restore round trips.

## API artifacts

For public APIs, keep the generated artifacts aligned with the contract:

| Artifact | Purpose |
|---|---|
| OpenAPI spec | Documents the HTTP surface exposed by the app. |
| Route manifest | Records the routes, methods, auth policy, and response shapes Via needs. |
| Generated client | Gives callers a typed entry point for the published API. |
| Manifest smoke output | Names health, readiness, SQLite, route, and representative request checks for the app. |