Authentication

API tokens

All /v1/ endpoints authenticate via an API token. Tokens:

Start with the prefix ab_
Are 51 characters long
Are scoped to a single organization
Never expire (but can be revoked instantly)

Create a token: Dashboard → Settings → API tokens → New token. API token access requires the Team plan. The token value is shown only once at creation — store it in a secrets manager or environment variable immediately.

Authorization header

Pass your token in the Authorization header on every request:

curl https://api.kallima.bio/v1/me \
  -H "Authorization: Bearer ab_your_token_here"

from kallima import KallimaClient
client = KallimaClient("ab_your_token_here")

Requests without a valid token return 401 unauthorized.

Check your balance

Before submitting compute jobs, verify your credit balance with:

curl https://api.kallima.bio/v1/me \
  -H "Authorization: Bearer ab_your_token_here"

{
  "org_id": "aabbccdd-...",
  "plan": "team",
  "subscription_balance": 11840,
  "purchased_balance": 500,
  "total_credits": 12340,
  "monthly_grant": 12000
}

See Credits for the full cost table and how to buy additional credits.

Rate limits

Every /v1/ response carries rate-limit headers:

Header	Meaning
`X-RateLimit-Limit`	Requests allowed per minute
`X-RateLimit-Remaining`	Requests left in the current window
`X-RateLimit-Reset`	RFC 7231 timestamp when the window resets
`X-Quota-Limit`	Write requests allowed this calendar month
`X-Quota-Remaining`	Write requests left this month
`X-Quota-Reset`	RFC 7231 timestamp when the monthly quota resets

Reads (GET) consume the rate bucket but do not count against your monthly write quota — polling for job status is free. Writes (POST/PATCH/DELETE) consume both the rate bucket and the quota. Pipeline submits additionally spend credits.

Plan	Rate	Monthly writes
Team	60 req/min	25,000
Enterprise	custom	custom

When you hit a limit the API returns 429 with a Retry-After header giving the seconds until the window resets.

Errors

All error responses use RFC 9457 problem+json with Content-Type: application/problem+json.

{
  "type": "https://docs.kallima.bio/errors/insufficient_credits",
  "title": "Insufficient credits",
  "status": 402,
  "detail": "Humanization costs 1 credit; balance is 0.",
  "instance": "/v1/humanizations",
  "code": "insufficient_credits",
  "request_id": "req_01JB..."
}

Switch on the code field — it is stable across API versions.

`code`	HTTP	Meaning
`unauthorized`	401	Missing or invalid token
`not_found`	404	Resource doesn’t exist in your org
`insufficient_credits`	402	Not enough credits — top up or upgrade
`plan_required`	402	Endpoint requires a higher plan
`rate_limit_exceeded`	429	Slow down — check `Retry-After`
`quota_exceeded`	429	Monthly write quota exhausted
`invalid_request`	400	Malformed body
`validation_failed`	422	Field-level validation error — see `errors` array
`idempotency_mismatch`	422	Same `Idempotency-Key` with different body
`conflict`	409	e.g. canceling an already-running job
`internal_error`	500	Something went wrong on our side

Python SDK error handling

from kallima import (
    KallimaClient,
    KallimaError,
    InsufficientCreditsError,
    RateLimitError,
    NotFoundError,
)
import time

client = KallimaClient(api_key)

try:
    job = client.humanizations.submit(variant_id=variant_id)
except InsufficientCreditsError as e:
    print(f"Out of credits: {e}")
except RateLimitError as e:
    time.sleep(e.retry_after or 60)
    job = client.humanizations.submit(variant_id=variant_id)
except NotFoundError:
    print("Variant not found or doesn't belong to your org")
except KallimaError as e:
    print(f"API error {e.status_code} [{e.code}]: {e}")

Idempotency

All write endpoints accept an Idempotency-Key header. Send a unique UUID per logical operation — replayed requests with the same key return the cached response without creating a duplicate job or spending credits twice.

curl -X POST https://api.kallima.bio/v1/humanizations \
  -H "Authorization: Bearer ab_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"variant_id": "11112222-3333-4444-5555-666677778888"}'

Keys expire after 24 hours. Sending the same key with a different request body returns 422 idempotency_mismatch.

Getting started

Guides

API Reference

API tokens

Authorization header

Check your balance

Rate limits

Errors

Python SDK error handling

Idempotency

​API tokens

​Authorization header

​Check your balance

​Rate limits

​Errors

​Python SDK error handling

​Idempotency

API tokens

Authorization header

Check your balance

Rate limits

Errors

Python SDK error handling

Idempotency