# External API

The supported external integration contract is the canonical [OpenAPI 3.1 document](/openapi.yaml). Routes that exist in the application but are absent from that document are internal and have no external compatibility guarantee.

## Authentication and scope

Use an F05 Automation Token as a Bearer token. Tokens are bound to one Workspace and exactly one Project or App scope, and have fixed **read + upload** permissions. The API re-checks token expiry/revocation, Workspace membership, current RBAC and Project/App scope on every request.

Public operations declare their required `x-appbarn-scope` in OpenAPI:

- `upload` — reserve and finalise a Build upload.
- `read` — list/read Builds and issue a short-lived artifact download URL.

`X-AppBarn-Workspace-Id` is optional for Automation Tokens because the Workspace is token-bound. If supplied, it must match the token Workspace exactly.

Create and revoke Automation Tokens in the authenticated application. Raw token values are shown once and must be stored as secrets. See [Automation tokens](/reference/automation-tokens) and [CLI configuration](/cli/configure).

## Minimal request

This synthetic example lists Builds for an App. Replace the placeholders locally; never put a real token in source, logs or documentation.

```sh
curl --fail-with-body \
  -H 'Authorization: Bearer ab_REPLACE_WITH_AUTOMATION_TOKEN' \
  'https://staging.api.app-barn.com/apps/00000000-0000-4000-8000-000000000001/builds'
```

## Supported operations

| Scope | Operation | Endpoint |
| --- | --- | --- |
| upload | Reserve upload | `POST /builds` |
| upload | Finalise upload | `POST /builds/{id}/finalise` |
| read | List Builds | `GET /apps/{id}/builds` |
| read | Get Build | `GET /builds/{id}` |
| read | Create download URL | `POST /builds/{id}/download-url` |

Share Links, install tickets, browser-session routes, token administration, Workspace administration, operator routes and provider callbacks are not part of the external API contract.

## Errors, request IDs and pagination

AppBarn uses one F15 error envelope and returns `X-Request-Id` for correlation. Build listing uses an opaque `cursor`; pass `next_cursor` unchanged to the next request and do not decode or construct it. See [API errors and pagination](/reference/api-errors-pagination).

Artifact size and capacity behavior is documented under [Artifacts and limits](/reference/artifacts-limits). Externally relevant platform/installability semantics remain in [Installability](/reference/installability).

## Compatibility

`apps/api/openapi.yaml` is the reviewed source of truth for supported external operations. Adding a public operation requires implementation, OpenAPI and documentation in the same change. Removing or incompatibly changing a published operation requires an explicit compatibility/versioning decision; AppBarn does not introduce a URL version namespace for MSP.

Undocumented internal routes may change without external compatibility guarantees. Capability URLs returned by upload/download operations are short-lived secrets and are not stable API identifiers.
