Get started

Quickstart

Before you begin

You need an API key and a base URL. The base URL is the origin this app is served from; everything below is relative to it and lives under /api/v1.

Exampleshell
export QUIRK_API_URL="http://localhost:3000"
export QUIRK_API_KEY="qk_..."

Create a key

Keys are created on the API keys page. The token is shown exactly once, when the key is created, and cannot be read back afterwards -- only its hash is stored. Copy it then.

Start a chat

A chat is a conversation. It starts with every response policy switched on, which is what makes the decision model answer for each message. The name is optional: a chat with no name takes its title from the first message it is given.

POST
/api/v1/chats
Exampleshell
curl -X POST "$QUIRK_API_URL/api/v1/chats" \
  -H "Authorization: Bearer $QUIRK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Release notes"}'

The answer carries the chat's id. Keep it: every other request names it.

Send a message

Send a message and wait. The reply arrives whole, with the decision turn that informed it. In the app this is streamed, because a browser has somewhere to be pushed to and a request does not.

POST
/api/v1/chats/:chatId/messages
Exampleshell
curl -X POST "$QUIRK_API_URL/api/v1/chats/$CHAT_ID/messages" \
  -H "Authorization: Bearer $QUIRK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Should I ship this on Friday?"}'

The answer is the message as saved, the reply, and the turn:

Examplejson
{
  "message": {
    "id": "6f1c...",
    "chatId": "9ab2...",
    "role": "U",
    "text": "Should I ship this on Friday?",
    "created": "2026-01-14T10:04:11.220Z",
    "prompt": null
  },
  "reply": {
    "id": "2d70...",
    "chatId": "9ab2...",
    "role": "A",
    "text": "I'd hold it until Monday. Friday releases ...",
    "created": "2026-01-14T10:04:14.801Z",
    "prompt": "You are Quirk, an assistant that..."
  },
  "turn": {
    "id": "77c0...",
    "chatId": "9ab2...",
    "messageId": "6f1c...",
    "replyId": "2d70...",
    "created": "2026-01-14T10:04:12.640Z",
    "model": "jane-4",
    "estimates": [
      {
        "id": "core",
        "value": "thoughtful",
        "probability": 0.72,
        "probabilities": {
          "thoughtful": 0.72,
          "frustrated": 0.11,
          "confused": 0.09,
          "neutral": 0.08
        }
      }
    ]
  }
}

Where next

The reference pages cover every endpoint and every field. If you would rather send requests from a page than from a terminal, the API playground runs the same requests with one of your keys and never puts the key in the browser.