# HTTP API

The interface between client and Manage server, protocol v1. Anyone using
the bundled client doesn't need this chapter — it's for custom clients, for
debugging, and for troubleshooting with `curl`.

Base URL of this installation: `{{BASE_URL}}/api/v1`

## The four endpoints

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/manifest.php` | which release should be installed |
| `GET` | `/package.php?version=vX.Y.Z` | the release ZIP |
| `POST` | `/backup.php` | upload a backup archive (`multipart/form-data`) |
| `POST` | `/heartbeat.php` | report status, receive update information |

Every request carries two headers:

```http
X-Manage-Instance: myproject-prod
X-Manage-Token:    e4032c4dc51e9100…
```

There is no session, no cookie and no shared password. The server stores
only the SHA-256 hash of the token and compares it in constant time.

## Where to find what

- **Description with example calls**, error cases, and the rules a custom
  client must follow: [08_PROTOCOL.md](08_PROTOCOL.md).
- **Machine-readable**, as OpenAPI 3.1: <{{SELF_URL}}/openapi.php>.
  Contains schemas for every response, the error codes, and the patterns
  for version, filename and checksum.
- **To browse and try out** in the browser:
  [Swagger UI]({{SELF_URL}}/api.php). "Try it out" talks to this
  installation and needs a valid instance plus token.
- **As a reference implementation**: `manage-client/lib/client.php` builds
  the requests; `lib/updater.php` and `lib/backup.php` use them.