REST conventions

Base URL: https://api.tefily.com. JSON request bodies. Unless noted, successful responses look like:

{ "success": true, "data": { } }

Errors look like:

{ "success": false, "message": "..." }

Validation failures include errors as a JSON array of strings:

{
  "success": false,
  "message": "Validation failed",
  "errors": ["Field \"title\" is required"]
}

The SDKs throw KataflaxException with message, optional errors, and statusCode (status_code in Python).

Status codes

Concept pages list the 400 messages for each call. These statuses show up across the data API:

401 { "success": false, "message" }. On the auth routes this includes Invalid email or password, Email not verified, and Invalid or expired token on /auth/me. A missing token on a requireAuth collection route is 403 Authentication required.

403 { "success": false, "message" } for rule denials, and Service token required on POST /auth/verify.

413 { "success": false, "message": "File too large" } when the declared upload size exceeds the plan max_file_bytes. There is no code. See Files and Usage and limits.

429 quota, including storage writes over kallax_storage_mb:

{
  "success": false,
  "message": "...",
  "code": "quota_exceeded",
  "limit_key": "kallax_storage_mb"
}

limit and current are included only when the gate sets them. Reads and deletes are not blocked by the storage quota. See Usage and limits.

402 when the account is suspended. The fallback body is:

{
  "success": false,
  "message": "This organization cannot use its API right now.",
  "code": "payment_required"
}

The gate may substitute its own message. limit_key is included when the gate has one.

429 rate limit. The retry_after value is the seconds left in the current 60-second window (at least 1). Honor the retry-after header. The 12 below is that remaining time for one request:

{
  "success": false,
  "message": "Too many requests for this project. Retry in 12 seconds.",
  "code": "rate_limited",
  "limit_key": "kallax_requests_per_minute",
  "retry_after": 12
}

The response header is retry-after: 12. Plan ceilings are 600, 6000, and 30000. See Usage and limits.

Authorization

Authorization: Bearer <token>

Token	Data API /api/p/...	Console /api/...
Platform JWT	Yes, bypasses rules	Yes
PAT kfx_…	Yes, bypasses rules	Yes
Service token kfxs_…	Yes, bypasses rules	No
Project JWT	Yes, subject to rules	No

CORS

The public data API reflects the caller Origin, so browser apps on any site can call /api/p/.... Console routes use a server allowlist (CORS_ALLOWED_ORIGINS).

Git Smart HTTP

Clone/push is not under /api. It lives at /git/:projectId/:repoSlug/.... See Git.