API overview

Base URL

All API requests go to https://api.capreolus.app. Anything you can do from the dashboard is available here, plus a few endpoints that exist only over the API (bulk import, agent runs).

Versioning

Public endpoints live under /v1/. We bump the version when we make breaking changes. Old versions stay supported for at least 12 months after the next one ships, with deprecation notices in the response headers.

JSON envelope

Every JSON response is wrapped in a discriminated union. Successful responses have success: true and a data field. Errors have success: false and an error field with a stable code.

{
  "success": true,
  "data": {
    "id": "app_8af2",
    "slug": "acme-mobile",
    "platforms": ["ios", "android"]
  }
}

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "App not found",
    "requestId": "req_01H7..."
  }
}

Standard error codes

• UNAUTHENTICATED — missing or expired token.
• FORBIDDEN — token valid but lacks scope.
• NOT_FOUND — resource does not exist for this caller.
• VALIDATION_FAILED — payload schema violation.
• RATE_LIMITED — backoff and retry.
• INTERNAL — anything we did not anticipate. Includes a requestId we can use to debug.

Pagination

List endpoints accept limit (max 100) and cursor. The response includes a nextCursorwhen there are more results; omit it when there aren't.