Configuration¶

Client-side¶

Two variables cover every client (SDK, MCP, your own code):

Variable	Default	Notes
`VENKAI_API_KEY`	—	`vk_live_…` or `vk_test_…`. Sent as `Authorization: Bearer <key>`.
`VENKAI_BASE_URL`	`https://api.venkai.fr` (MCP server) · `http://127.0.0.1:8000` (Python SDK)	The two defaults differ — pass it explicitly and the ambiguity goes away.

export VENKAI_API_KEY="vk_live_…"
export VENKAI_BASE_URL="https://api.venkai.fr"

Key environments¶

POST /api/auth/api-keys takes environment, which must be production or development, and controls the prefix:

Prefix	Meaning
`vk_live_`	Production key
`vk_test_`	Development key

Both are accepted by the API and grant the same organization scope. The prefix is a signal for humans and log scrubbers, not a permission boundary — a vk_test_ key reads and writes your real data.

Keeping keys out of source control¶

# .env — and make sure .env is in .gitignore
VENKAI_API_KEY=vk_live_…

import os
from venkai.sdk.client import VenkaiClient

client = VenkaiClient(
    api_key=os.environ["VENKAI_API_KEY"],   # raises KeyError if unset — fail loudly
    base_url=os.environ.get("VENKAI_BASE_URL", "https://api.venkai.fr"),
    project="billing-service",
)

Rotate with POST /api/auth/api-keys/{key_id}/rotate (revokes the old key and mints a new one with the same label) or revoke with DELETE /api/auth/api-keys/{key_id}.

Server-side¶

Only relevant if you run your own instance. The full table is in Environment variables; the ones that change behaviour you will notice:

Variable	Default	Effect
`VENKAI_DATABASE_URL`	local SQLite file	Any SQLAlchemy URL. Use `postgresql://…` in production.
`VENKAI_EMBEDDING_PROVIDER`	`hashing`	`hashing` (128-d, no dependency, not semantic) or `semantic` (384-d MiniLM).
`VENKAI_JWT_SECRET`	—	Signs dashboard sessions. Required. Use ≥32 bytes.
`VENKAI_ENV`	`development`	`production` turns on rate limiting and `Secure` session cookies.
`VENKAI_ALLOWED_ORIGINS`	—	CORS allow-list for the dashboard.
`VENKAI_RETRIEVAL_MAX_CANDIDATES`	`10000`	Ceiling on candidates scored per query.

VENKAI_EMBEDDING_PROVIDER=semantic fails loudly by design

If sentence-transformers is missing, startup raises rather than silently falling back to hashing. An operator who asked for semantic matching and got hash buckets instead would have no way to tell from the API's answers.

Rate limits¶

Applied only when VENKAI_ENV=production, per client IP, in a 60-second window:

Caller	Limit
Authenticated (Bearer key or session cookie)	300 req/min
Anonymous	60 req/min

Exceeding it returns 429 with a Retry-After header.