Authentication.
Two interchangeable schemes. Bearer tokens are short-lived (~24h) and issued by /v1/auth/login. API keys are long-lived and read from /v1/account. Use the bearer for interactive sessions and the API key for CI.
Scheme 01 . bearer
Authorization: Bearer <token>
HTTP Bearer (RFC 6750). JWT. ~24h lifetime. Issued by /v1/auth/login or /v1/auth/signup.
Scheme 02 . api key
X-Kolm-Key: <key>
Long-lived. Rotates on demand from /account. Use this from CI runners and from server-to-server calls.
# curl with bearer curl https://api.kolm.ai/v1/account \ -H "Authorization: Bearer $KOLM_TOKEN" # curl with API key curl https://api.kolm.ai/v1/account \ -H "X-Kolm-Key: $KOLM_API_KEY"
auth.
Sign up, sign in, get a bearer token. No auth required on these two endpoints.
example request
curl -X POST https://api.kolm.ai/v1/auth/login \
-H "Content-Type: application/json" \
-d '{"email":"you@org.com","password":"********"}'
example response
{
"token": "eyJhbGc...<jwt>",
"user_id": "usr_01HW..."
}
example request
curl -X POST https://api.kolm.ai/v1/auth/signup \
-H "Content-Type: application/json" \
-d '{"email":"you@org.com","password":"********","org_name":"Acme Health"}'
example response
{
"token": "eyJhbGc...<jwt>",
"user_id": "usr_01HW..."
}
account.
Read your plan, quota, and API key. Most users hit this once on first login and cache the key.
example request
curl https://api.kolm.ai/v1/account \ -H "Authorization: Bearer $KOLM_TOKEN"
example response
{
"user_id": "usr_01HW...",
"email": "you@org.com",
"plan": "pro",
"compiles_count": 7,
"compiles_remaining": 43,
"api_key": "kolm_live_01HW..."
}
compile.
Submit a recipe, poll for a signed .kolm. The compile job is async. Poll GET /v1/compile/{id} until status is done or failed.
example request
curl -X POST https://api.kolm.ai/v1/compile \
-H "Authorization: Bearer $KOLM_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"recipe": {
"task": "redact PHI from clinical notes",
"objective": "f1",
"adapter": "lora",
"evaluator": "hipaa-redact-v1"
},
"examples": [],
"base_model": "qwen2.5-7b-instruct",
"k_min": 0.90,
"compliance_pack": "hipaa-redact-v1"
}'
example response (202)
{
"compile_id": "cmp_01HW...",
"status": "pending",
"eta_seconds": 540
}
example request
curl https://api.kolm.ai/v1/compile/cmp_01HW... \ -H "Authorization: Bearer $KOLM_TOKEN"
example response (done)
{
"compile_id": "cmp_01HW...",
"status": "done",
"logs": [
"[1/6] synthesizing pairs ... 1,840",
"[5/6] K-score gate ... K=0.982 > 0.92",
"[6/6] sign + package ... 9.4 KB"
],
"k_score": 0.982,
"artifact_url": "https://api.kolm.ai/dl/cmp_01HW.../phi-redactor.kolm",
"cid": "cidv1:sha256:1bcf2323...",
"error": null
}
run.
Run a compiled artifact against an input. Receipt is HMAC-signed over (cid, input_hash, output_hash, ts). Replay months later with the same input + receipt to prove the output.
example request
curl -X POST https://api.kolm.ai/v1/run \
-H "Authorization: Bearer $KOLM_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"artifact_cid": "cidv1:sha256:1bcf2323...",
"input": "Mrs. Jane Doe (DOB 1962-03-04) presented with chest pain."
}'
example response
{
"output": {
"redacted": "Mrs. [NAME] (DOB [DATE]) presented with chest pain.",
"spans": [
{"type": "NAME", "start": 4, "end": 12},
{"type": "DATE", "start": 19, "end": 29}
]
},
"receipt": {
"cid": "cidv1:sha256:1bcf2323...",
"hmac": "hmac-sha256:9af28e...",
"ts": "2026-05-15T12:34:56Z",
"k_score": 0.982
}
}
verify.
Re-verify an artifact by CID against the manifest and the publisher's signature. The CLI verb kolm verify runs the same check offline; this endpoint is for one-off web checks or third-party auditors.
example request
curl https://api.kolm.ai/v1/verify/cidv1:sha256:1bcf2323...
example response
{
"cid": "cidv1:sha256:1bcf2323...",
"verified": true,
"manifest": {
"version": "0.1",
"task": "redact PHI from clinical notes",
"base_model": "qwen2.5-7b-instruct",
"k_score": 0.982,
"compliance_pack": "hipaa-redact-v1"
},
"k_score": 0.982,
"signed_by": "kolm.ai",
"signed_at": "2026-05-15T10:12:30Z"
}
registry.
Public artifact registry. Anyone can search and fetch metadata. Signed-in publishers can submit hosted .kolm URLs for inclusion.
example request
curl "https://api.kolm.ai/v1/registry/search?task=redact+PHI&size_max=20000&hardware=cpu&license=Apache-2.0"
example response
{
"artifacts": [
{
"cid": "cidv1:sha256:1bcf2323...",
"name": "phi-redactor",
"task": "redact PHI from clinical notes",
"base_model": "qwen2.5-7b-instruct",
"size_bytes": 9420,
"k_score": 0.982,
"license": "Apache-2.0",
"hardware": ["cpu", "cuda", "mps"],
"downloads": 1284
}
],
"total": 1
}
example request
curl https://api.kolm.ai/v1/registry/get/cidv1:sha256:1bcf2323...
example response
{
"cid": "cidv1:sha256:1bcf2323...",
"name": "phi-redactor",
"task": "redact PHI from clinical notes",
"base_model": "qwen2.5-7b-instruct",
"size_bytes": 9420,
"k_score": 0.982,
"license": "Apache-2.0",
"hardware": ["cpu", "cuda", "mps"],
"downloads": 1284,
"submitted_at": "2026-05-10T09:14:22Z"
}
example request
curl -X POST https://api.kolm.ai/v1/registry/submit \
-H "Authorization: Bearer $KOLM_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"artifact_url": "https://cdn.acme.com/phi-redactor.kolm",
"name": "phi-redactor",
"task": "redact PHI from clinical notes"
}'
example response (202)
{
"submission_id": "sub_01HW...",
"status": "verifying"
}
usage.
Per-billing-period counters. Defaults to the current month. Use this to build a dashboard or to set a hard CI budget.
example request
curl "https://api.kolm.ai/v1/usage?period=2026-05" \ -H "Authorization: Bearer $KOLM_TOKEN"
example response
{
"period": "2026-05",
"compiles": 7,
"runs": 142903,
"tokens": 18402113,
"dollars": 24.62
}
health.
Cheap liveness probe. No auth. Same shape self-hosted and on api.kolm.ai.
example request
curl https://api.kolm.ai/v1/healthz
example response
{ "status": "ok" }
Next.
The OpenAPI 3.0 source is at /openapi.json. Paste it into any OpenAPI tool (Stoplight, Insomnia, Postman, Speakeasy, oapi-codegen) to generate a client. Or use one of our SDKs.