Skip to main content

​
Base URL

https://orca-klavest.app/api/v1

​
Authentication

ORCA uses two authentication methods depending on the context:
Dashboard and frontend requests use JWT bearer tokens:
curl -H "Authorization: Bearer eyJ..." \
  https://orca-klavest.app/api/v1/files
Get a token by logging in:
curl -X POST https://orca-klavest.app/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@company.com", "password": "your-password"}'
Response:
{
  "data": {
    "access_token": "eyJ...",
    "refresh_token": "abc...",
    "token_type": "bearer"
  }
}
If 2FA is enabled, the login response includes requires_2fa: true and a temp_token. Complete authentication with:
curl -X POST https://orca-klavest.app/api/v1/auth/totp/complete \
  -H "Content-Type: application/json" \
  -d '{"temp_token": "...", "code": "123456"}'

​
Response format

All endpoints return a consistent envelope: 
{
  "data": { ... },
  "error": null,
  "meta": {}
}
On error: 
{
  "data": null,
  "error": {
    "code": "insufficient_scope",
    "message": "This endpoint requires the 'scan' scope."
  },
  "meta": {}
}

​
Error codes

HTTP statusCodeDescription
400bad_requestInvalid or missing request parameters
401unauthorizedMissing or invalid token / API key
403insufficient_scopeAPI key lacks the required scope
404not_foundResource doesn’t exist or belongs to another org
429rate_limitedToo many requests, retry after cooldown
500internal_errorUnexpected server error

​
Rate limits

Endpoint categoryLimit
AuthenticationStrict per-IP (prevents brute-force)
File uploads / prescan30/min per-user
Job creation / start20/hour
Billing (add credits)10/hour
Chat queriesPer-user limiting
General APIStandard per-user limiting
WebSocket30 connections/min per IP, 10-min timeout
Every response includes rate limit headers:
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1700000060
When rate-limited, you’ll receive a 429 response. Wait and retry with exponential backoff.

​
Pagination

List endpoints support pagination via query parameters: 
GET /api/v1/files?limit=20&offset=0
ParameterDefaultMaxDescription
limit20200Number of items to return
offset0-Number of items to skip

​
Organisation scoping

All data is scoped to your organisation. The org_id is derived from your JWT token — you cannot access resources belonging to other organisations. This is enforced at the database query level on every endpoint.

​
WebSocket

Real-time job progress is available via WebSocket: 
wss://orca-klavest.app/ws/jobs/{job_id}/progress
Requires JWT authentication. Messages include processing stage, percentage, and per-file status updates. Falls back to HTTP polling if WebSocket is unavailable.