Skip to content

HTTP API Contract & Error Codes ​

Custom Server Endpoints (/v1/* & Static) ​

MethodPathAuthSuccessError Statuses
GET/v1/healthzNone200 {"status":"ok","version":"..."}—
POST/v1/registerNone (application/json, rate-limited)201 {"email":"...","verified":false,"verification_sent":bool}400, 415, 429, 500
POST/v1/proxy/chat/completionsBearer <auth_token>Upstream 2xx OpenAI completion JSON400, 401, 403, 429, 502, 503
GET/, /registerNoneEmbedded landing & registration HTML (__AIST_SERVER_URL__ injected from Settings.Meta.AppURL)—
GET/run.sh, /uninstall.shNoneBootstrap & uninstall shell scripts—
GET/releases/client/*NoneVersion-matched client archives & checksums.txt404

PocketBase User Auth Endpoints ​

MethodPathAuthPurpose
GET/api/collections/users/auth-methodsNoneDiscover enabled password / OTP / MFA login modes
POST/api/collections/users/auth-with-passwordNonePassword sign-in (returns authResponse, or 401 {"mfaId":"..."} when MFA is required)
POST/api/collections/users/request-otpNoneSend email OTP (200 {"otpId":"..."})
POST/api/collections/users/auth-with-otpNoneExchange otpId + code (and optional mfaId) for authResponse
POST/api/collections/users/auth-refreshBearer <auth_token>Sliding token renewal + fresh meta.config
POST/api/collections/users/request-verificationNoneResend email verification link (204)
POST/api/collections/users/request-password-resetNoneSend password reset email (204)

authResponse Payload & meta.config Projection ​

json
{
  "token": "<jwt>",
  "record": {
    "id": "u1234567890abcd",
    "email": "[email protected]"
  },
  "meta": {
    "config": {
      "schema_version": 1,
      "limits": {
        "context_window": 128000,
        "max_output_tokens": 8192
      },
      "session": {
        "max_sessions": 10,
        "compaction": {
          "keep_tokens": 20000,
          "trigger_ratio": 0.85
        }
      },
      "blacklist": ["rm -rf /"]
    }
  }
}

Structured Proxy Error Envelope ​

Non-2xx responses from POST /v1/proxy/chat/completions use a uniform JSON envelope so the client can surface localized, actionable guidance without blind retries:

json
{
  "error": {
    "code": "quota_exceeded",
    "message": "weekly token quota exceeded",
    "retry_at": "2026-11-23T00:00:00Z"
  }
}
HTTP Statuserror.codeRetryable by Client?Meaning
400invalid_requestNoMalformed payload, context window exceeded, or upstream content/safety rejection
401(PocketBase auth)Refresh token onceInvalid, expired, or revoked user JWT
403no_available_modelNoUser has no enabled allowed_models (or all assigned models are blocked by auth error)
429quota_exceededNoUser's weekly_token_quota reached; retry_at indicates next Monday 00:00 UTC
503no_available_modelNoAll assigned models are currently cooling down (quota or rate_limit); retry_at gives earliest recovery time
502upstream_unavailableTransientAll available candidates failed with transient 5xx or network errors

POST /v1/register Error Codes ​

json
{
  "code": "invite_code_exhausted",
  "message": "This invite code has reached its maximum uses."
}

Possible code values: invalid_content_type (415), invalid_json, invite_code_required, invalid_invite_code, invite_code_expired, invite_code_exhausted, email_already_registered, validation_failed, registration_failed.

Licensed under AGPL-3.0 (Commercial licensing available: [email protected])