API reference

Authentication

?

API keys

Every endpoint requires an API key. A key belongs to one account, and a request authenticated with it answers for that account: it reaches that account's chats and nothing else.

Keys are managed on the API keys page, where one can be created, renamed, deactivated and deleted.

Send a bearer token

The key goes in the Authorization header, prefixed with Bearer. A key is qk_ followed by 256 bits of randomness.

Exampleshell
curl "$QUIRK_API_URL/api/v1/chats" \
  -H "Authorization: Bearer qk_..."

Key security

The token is shown exactly once, when the key is created. Only its SHA-256 is stored, so a key that is lost cannot be read back -- issue a new one instead. Nothing above the database ever holds the token.

If a key leaks, deactivate it rather than deleting it. Deactivating refuses every request that presents it straight away while keeping the name and the history, so you can tell afterwards which key was the one that leaked.

Authentication errors

A request with no key, a malformed header, an unknown key, or a deactivated one is refused with 401 and this body:

Examplejson
{
  "error": "A valid active API key is required."
}
ParameterTypeDescription
errorstringWhat went wrong, in words safe to show a person. It never contains the key, the token, or anything about the account.