External API

The supported external integration contract is the canonical OpenAPI 3.1 document. 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-quollvault-scope in OpenAPI:

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

X-QuollVault-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 and CLI configuration.

Minimal request

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

curl --fail-with-body \
  -H 'Authorization: Bearer qv_REPLACE_WITH_AUTOMATION_TOKEN' \
  'https://app.quollvault.com/api/apps/00000000-0000-4000-8000-000000000001/builds'

Supported operations

Scope	Operation	Endpoint
upload	Reserve upload	POST /api/builds
upload	Finalise upload	POST /api/builds/{id}/finalise
read	List Builds	GET /api/apps/{id}/builds
read	Get Build	GET /api/builds/{id}
read	Create download URL	POST /api/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

QuollVault 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.

Artifact size and capacity behavior is documented under Artifacts and limits. Externally relevant platform/installability semantics remain in 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; QuollVault 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.