# HTTP API

The HTTP API is how `goff` talks to `geoffrey-server`. OpenAPI 3.1 has been generated from the server and served by it since version 0.12.0.

`openapi.json` at the repository root is that document. A running server serves it, unauthenticated, at `GET /openapi.json`, with `servers` set to `public_url`. `GET /docs` on the server is an unauthenticated Scalar page that loads `/openapi.json`. The page loads its renderer from a CDN. That Scalar page is the API reference. This documentation site is separate.

On the production file host those routes are `https://files.strand3.com/openapi.json` and `https://files.strand3.com/docs`.

Owner routes use the header `X-API-KEY`. Uploads use `Authorization: Bearer` with the rental's `upload_token`. A missing or unknown key is 401. Another client's key on an owner route for a rental it does not own is 404. A wrong upload token is 403.

| Method | Path | Auth |
|---|---|---|
| `POST` | `/api/rentals` | API key. Body `duration_seconds`, optional `locked`. |
| `GET` | `/api/rentals` | API key. `{ "rentals": [ … ] }` for this key only. |
| `GET` | `/api/rentals/{rental_id}` | API key. |
| `DELETE` | `/api/rentals/{rental_id}` | API key. 204 when an unlocked `inactive` or `expired` rental is removed. |
| `POST` | `/api/rentals/{rental_id}/enable` | API key. |
| `POST` | `/api/rentals/{rental_id}/enable/{token}` | Token in the path. Empty 200. |
| `POST` | `/api/rentals/{rental_id}/disable` | API key. |
| `POST` | `/api/rentals/{rental_id}/revive` | API key. Body `extend_seconds`. |
| `POST` | `/api/rentals/{rental_id}/lock` | API key. |
| `POST` | `/api/rentals/{rental_id}/unlock` | API key. |
| `GET` | `/api/storage` | API key. Allowance, used bytes, host totals, and `available_bytes`. |
| `PUT` | `/api/rentals/{rental_id}/files/{path}` | Bearer upload token. |
| `GET` | `/files/{rental_dir}` and `/files/{rental_dir}/{path}` | None. |
| `GET` | `/health` | None. |
| `GET` | `/openapi.json` and `/docs` | None. |

`POST /api/rentals` returns `rental_id`, `upload_url`, `upload_token`, `enable_url`, `base_file_url`, `expires_at`, and `locked`. `upload_token` is the same secret as the enable-path token. `GET /api/storage` sets `available_bytes` to the smaller of the client remainder and the host remainder. Storage accounting has been per uploaded byte since version 0.9.0.

After changing an annotation in the server, regenerate the committed file:

```bash
UPDATE_OPENAPI=1 cargo test -p geoffrey-server openapi_json_is_current
```

Behavior of each operation is on the [rentals](/features/rentals/) and [public files](/features/files/) pages. The [changelog](/changelog/) 0.12.0 entry is the OpenAPI addition.