QuollVault Docs

Appearance

API errors and pagination ​

QuollVault resource endpoints under /api/* use UTF-8 JSON. The one deliberate media-type exception is GET /api/install/:ticket/manifest.plist, which is the F08 Apple OTA plist response (application/xml; charset=utf-8). Errors, including errors from that route, use the normal JSON envelope.

Errors ​

json
{
  "error": {
    "code": "stable_code",
    "message": "safe message",
    "fields": { "field": "optional validation detail" }
  },
  "request_id": "server-generated-request-id"
}

fields is optional and bounded. X-Request-Id carries the same server-generated request ID. Client-provided request IDs are never authoritative. Keep the request ID when reporting an unexpected failure; never include bearer tokens, request bodies or signed URLs.

Common statuses: 400, 401, 403, 404, 409, 413, 415, 426, 429, and 5xx.

JSON mutations ​

  • Content-Type: application/json is required before feature logic runs.
  • request bodies must be valid UTF-8;
  • common maximum body size is 64 KiB; a feature may declare a smaller limit;
  • unknown and prototype-like object keys are rejected;
  • feature handlers consume validated typed schema output only.

Workspace context ​

Human requests operating in a Workspace send exact lowercase UUIDv4 X-QuollVault-Workspace-Id. The server reloads current membership; the header selects context and never grants access. Automation Tokens pin one Workspace; a supplied Workspace header must match that credential exactly.

Pagination ​

Lists use bounded pages: default 50, never above 100. next_cursor is an opaque, query-shape-bound value. Do not decode, edit or reuse it with different filters. New F15 cursors use a versioned UTF-8-safe encoding; the server temporarily accepts the immediately preceding cursor format for rollout compatibility.

CLI exit categories ​

The CLI preserves API code/request ID and maps failures to stable non-zero categories: 2 input/protocol, 3 authentication, 4 authorization/not-visible, 5 conflict, 6 quota/rate, 7 server/provider, 1 local/unknown.