Stable identifier
Appaloft’s HTTP API is built on oRPC, and its input/output directly reuse the same business operation schema as the CLI, Web, and SDK — the documentation describes what the fields mean, not a separately invented set of HTTP-only business semantics.
Interactive documentation entrypoints
The backend serves machine-readable and interactive documentation at these addresses by default:
| Address | Description |
|---|---|
/api/openapi.json | The OpenAPI 3.1 spec document |
/api/reference | A Scalar-based interactive API reference where you can try calls directly in the browser |
/docs/reference/openapi/ | The OpenAPI reference entrypoint generated by the public documentation site, with each operation expanded into its own page |
OpenAPI operations are tagged by Appaloft business domain, so Scalar and the generated docs don’t degrade into one flat route list. These entrypoints are registered by a built-in OpenAPI reference system plugin; to embed the same documentation into another Bun/Elysia service, import @appaloft/openapi and mount the response handler it exports.
Authentication
| Scenario | Credential type |
|---|---|
| Interactive product operations (Web session) | Product session cookie |
| Machine automation / CI / agent | Deploy token (Bearer) |
curl https://appaloft.example/api/projects \
-H "Authorization: Bearer $APPALOFT_TOKEN"Never write a deploy token into a repository config file; inject it in CI through a trusted secret or environment variable.
Lifecycle status
The status of asynchronous operations like deployments, resources, and certificates should be observed through public query operations or read models — not by inspecting the database or internal runtime objects:
curl https://appaloft.example/api/deployments/dep_123Errors and recovery
Error responses carry a stable code, category, whether it’s retryable, and links to related troubleshooting pages — see Error Codes And Statuses for the full field description.
Documentation link convention
OpenAPI, oRPC, and any future tool descriptions should all point to stable anchors on the public documentation site, rather than internal spec file paths — this way, whether navigating from Scalar, the CLI’s --help, or an external bookmark, you always land on the same readable page.