---
title: "HTTP API reference"
description: "The public entrypoint for HTTP/oRPC operations, input schemas, output status, and error recovery guidance."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.appaloft.com/llms.txt
> Use this file to discover all available pages before exploring further.

# HTTP API reference

<a id="api-openapi-reference" />

## 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) |

```bash
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:

```bash
curl https://appaloft.example/api/deployments/dep_123
```

## Errors and recovery

Error responses carry a stable `code`, `category`, whether it's `retryable`, and links to related troubleshooting pages — see [Error Codes And Statuses](/docs/en/reference/errors-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.

## Related tasks

- [Error Codes And Statuses](/docs/en/reference/errors-statuses/)
- [TypeScript SDK](/docs/en/reference/typescript-sdk/)
- [OpenAPI](/docs/en/reference/openapi/)

Source: https://docs.appaloft.com/en/reference/http-api/index.mdx