Canonical: https://krasis.ai/docs/api/

[Documentation](https://krasis.ai/docs/)

Start here

[Overview](https://krasis.ai/docs/)[Getting started](https://krasis.ai/docs/getting-started/)

Everyday guides

[Choosing a model](https://krasis.ai/docs/models/)[Connecting your apps](https://krasis.ai/docs/clients/)[Memory and speed](https://krasis.ai/docs/memory/)[Troubleshooting](https://krasis.ai/docs/troubleshooting/)

Technical reference

[Configuration](https://krasis.ai/docs/configuration/)[API and authentication](https://krasis.ai/docs/api/)

For Krasis 1.0.22  
[Release history](https://krasis.ai/releases/)

Krasis documentation

# API and authentication

Discover models, send chat requests and manage API keys without a restart.

On this page

[Endpoints and base URL](https://krasis.ai/docs/api/#endpoints-and-base-url)[Send a chat request](https://krasis.ai/docs/api/#send-a-chat-request)[API keys](https://krasis.ai/docs/api/#api-keys)[Tool calls](https://krasis.ai/docs/api/#tool-calls)

## Endpoints and base URL

The default OpenAI-compatible base URL is `http://127.0.0.1:8012/v1`. Use the configured address and port if different.

| Request                     | Purpose                                                                      |
| --------------------------- | ---------------------------------------------------------------------------- |
| GET /health                 | Public server health check.                                                  |
| GET /v1/models              | Discover the loaded model ID. Requires a key when authentication is enabled. |
| POST /v1/chat/completions   | Chat, streaming and supported structured tool calls.                         |
| GET /v1/session-cache/stats | Conversation-cache statistics; protected when authentication is enabled.     |

## Send a chat request

First query `/v1/models` and copy the model ID. The following Bash example assumes authentication is enabled and `KRASIS_API_KEY` is set to one of your actual secrets. Replace `MODEL_ID_FROM_V1_MODELS` with the returned ID:

```
curl http://127.0.0.1:8012/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $KRASIS_API_KEY" \
  -d '{
    "model": "MODEL_ID_FROM_V1_MODELS",
    "messages": [{"role": "user", "content": "Explain MoE models in three sentences."}],
    "max_tokens": 128,
    "stream": false
  }'
```

If authentication has never been enabled, omit the Authorization header. To stream, set `"stream": true` and add `-N` to curl so it displays streamed events promptly. Your prompt plus requested output must fit the effective context.

## API keys

In 1.0.22, creating `~/.krasis/api-keys.json` under the account running the server automatically enables authentication, including launches from the TUI. On Windows this is `%USERPROFILE%\.krasis\api-keys.json`. If `KRASIS_HOME` is set, the default file is inside that directory instead.

Create the directory if needed, then save a JSON object like this, replacing the examples with long random secrets:

```
{
  "desktop": "replace-with-a-long-random-secret",
  "laptop": "replace-with-another-long-random-secret"
}
```

The names identify clients for your own administration. Clients send the **secret value** in `Authorization: Bearer <key>`. Names must be nonempty and keys must contain only nonempty visible ASCII without spaces. Keep the file private; on Linux, use `chmod 600 ~/.krasis/api-keys.json`.

Use `--api-keys-file /path/to/keys.json` or `CFG_API_KEYS_FILE="/path/to/keys.json"` for a custom location. An explicit file must exist and be valid at startup. Empty or unset selects the default location.

### Edit keys live

The file is re-read when each request is admitted. Add a new key or remove an old one without restarting. Requests already admitted can finish. Save changes by atomic file replacement where possible, so requests cannot see a partially written file.

An empty object denies all protected requests. Invalid, unreadable, removed or oversized files (over 1 MiB) deny requests once authentication has been detected. Fixing the file restores access on the next request. An invalid existing file prevents startup.

### Protected routes and disabling authentication

Authentication covers inference-server routes, including model discovery and internal diagnostics. `GET /health` and CORS `OPTIONS` preflight remain public. Invalid or missing credentials return HTTP 401 before body processing or model queueing.

If the default file has never existed, the server remains unauthenticated. To intentionally return to that mode, remove the default file and restart without a custom path. Removing the file while the server runs keeps requests denied.

API keys control the inference server. Krasis Manager is a separate service with its own owner token and access boundary. Bearer authentication does not encrypt traffic; use a trusted connection or an encrypted tunnel for remote access.

## Tool calls

Send OpenAI-style `tools` definitions to `/v1/chat/completions`. Supported model templates render their native grammar, and Krasis translates generated calls into structured `tool_calls` for both ordinary and streaming responses. Prior assistant tool calls and tool-role results are supported.

Model behaviour matters as well as transport. Check the [release-pinned tool-use matrix](https://github.com/brontoguana/krasis/blob/v1.0.22/ADVANCED.md#tool-use) for native grammar and live-client evidence. Allow room for tool schemas and results in your context budget.