Skip to main content

​
Error envelope

Validation, authentication, permission, conflict, not-found, and provider errors raised by Almanac use one JSON shape: 
{
  "error": "not_found",
  "message": "wiki was not found",
  "request_id": "req_..."
}
Use error for program control, show message to a developer, and include request_id when reporting a failure. Framework-level unknown routes and unsupported methods can instead return a detail response. Integrations should still handle an unexpected non-JSON or non-Almanac error body defensively.

​
Pagination

Job lists, page lists, page search, source lists, and source search use limit and offset query parameters: 
curl --get "$ALMANAC_API_URL/v1/wikis/$WIKI_ID/pages" \
  -H "Authorization: Bearer $ALMANAC_TOKEN" \
  --data-urlencode "limit=50" \
  --data-urlencode "offset=0"
limit defaults to 50 and accepts 1 through 500; offset starts at 0. Increase the offset by the number of records returned. Stop when a response contains fewer records than the requested limit. Responses are plain arrays and do not include a total or next cursor.

​
Common failure boundaries

  • 401: the bearer token is missing, expired, or invalid.
  • 403: the key is valid but lacks the required workspace permission.
  • 404: the resource or page path does not exist.
  • 403: the caller lacks permission, including access to the requested wiki.
  • 400: an identifier, query, or request body failed validation.
  • 409: the requested write conflicts with existing state.
  • 503: a required provider is temporarily unavailable.
See Troubleshooting for CLI symptoms and the generated endpoint reference for exact schemas.