API Documentation

Query a Denser chatbot from your own code, keep each of your users' conversations, and read them back. Before you start, generate an API key and copy your chatbot ID — see the REST API quick start.

AuthenticationCopy Anchor Link

Each chatbot has its own API key, generated in its API channel (see the quick start). Regenerating the key immediately invalidates the old one.

• /api/query takes the key in the key field of the JSON body.
• /api/v2/conversations/api takes the key in the x-api-key header.

Both endpoints stop working when the chatbot's API channel is turned off. Every answer from /api/query uses one query from your workspace's plan.

Query a chatbotCopy Anchor Link

Send the body as Content-Type: application/json.

Request bodyCopy Anchor Link

Choosing a modelCopy Anchor Link

model picks a model family, not an exact model. Each family runs one model, chosen by Denser:

• Versioned names select their family, not that version. gpt-4o-mini runs GPT-5, and claude-haiku-4-5 runs Claude Sonnet 5. They're accepted so existing code keeps working.
• Recognized prefixes: gpt, openai, chatgpt, o1, o3 and o4 select GPT; gemini and google select Gemini; claude and anthropic select Claude. Case doesn't matter.
• Anything else runs Claude. Other providers, such as Mistral, Llama or DeepSeek, aren't supported, and an unrecognized value doesn't return an error.
• Leave model out to use the model set in the chatbot's settings.

The models behind each family are upgraded over time, so the same value can run a newer model later.

Example requestCopy Anchor Link

curl -X POST "https://denser.ai/api/query" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What can you help me with?",
    "chatbotId": "11111111-1111-1111-1111-111111111111",
    "key": "00000000-0000-0000-0000-000000000000",
    "userId": "user_8842"
  }'

ResponseCopy Anchor Link

A successful request returns HTTP 200 with:

{
  "statusCode": "200",
  "answer": "I can help you with questions about our products, orders and returns...",
  "passages": [
    {
      "source": "https://example.com/help/returns",
      "text": "Returns are accepted within 30 days of delivery...",
      "score": 7.904721
    }
  ],
  "conversationId": "1791582688917-qzltde6lii",
  "messageId": "1791582688915-hq4r1oxjrz"
}

Streaming the answerCopy Anchor Link

Send "stream": true to receive the answer word by word, as the chat widget shows it, instead of waiting for the whole response. The answer comes back as Server-Sent Events (Content-Type: text/event-stream), in this order:

event: start
data: {"conversationId":"1791582688917-qzltde6lii","messageId":"1791582688915-hq4r1oxjrz"}

event: delta
data: {"text":"Returns are accepted "}

event: delta
data: {"text":"within 30 days [1]."}

event: done
data: {"statusCode":"200","answer":"Returns are accepted within 30 days [1](https://example.com/help/returns PassageID:0).","passages":[…],"conversationId":"1791582688917-qzltde6lii","messageId":"1791582688915-hq4r1oxjrz"}

• Citations appear in delta text as [1], the same number as the link in the done answer.
• A request refused before the answer starts (invalid key, quota used up, conversation not found) is answered as JSON, exactly as without stream. Check the response's Content-Type before reading it as a stream.
• A comment line, : ping, is sent every 15 seconds while the answer is being prepared, so proxies keep the connection open. Ignore it.
• Closing the connection stops the answer.

curl -sN -X POST "https://denser.ai/api/query" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What can you help me with?",
    "chatbotId": "11111111-1111-1111-1111-111111111111",
    "key": "00000000-0000-0000-0000-000000000000",
    "userId": "user_8842",
    "stream": true
  }' \
| jq -R --unbuffered -j '
    if startswith("data: ") then (.[6:] | fromjson | .text // empty)
    elif startswith("event:") or . == "" then empty
    else . end'; echo

ErrorsCopy Anchor Link

Some outcomes are reported in the body's statusCode with HTTP 200; others use the HTTP status.

With "stream": true, these are answered the same way, as JSON. A failure after the answer has started is an error event instead.

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": ["question must be a string"]
}

End users and conversationsCopy Anchor Link

Pass userId to tie each question to one of your users, and conversationId to keep a conversation going. Both are optional: without them every call is a conversation of its own.

1. Ask, with your user's ID. The response's conversationId and messageId identify the conversation and the answer.

   Copy Text

   { "chatbotId": "…", "key": "…", "question": "What is your refund policy?", "userId": "user_8842" }

2. Follow up in the same conversation by sending its conversationId with the same userId. Without context, the conversation's recent turns are the history, so a follow-up such as "Does that apply to sale items?" is understood.

   Copy Text

   { "chatbotId": "…", "key": "…", "question": "Does that apply to sale items?", "userId": "user_8842", "conversationId": "1791582688917-qzltde6lii" }

3. Record feedback on your side, such as thumbs up or down, keyed to the answer's messageId.

4. List the user's conversations with List conversations and their userId.

Conversations made through the API also appear in the chatbot's Chat logs, with the userId as the client ID.

List conversationsCopy Anchor Link

Send the API key in the x-api-key header and the filters as a JSON body. Up to 60 requests a minute per key.

Request bodyCopy Anchor Link

Example requestCopy Anchor Link

curl -X POST "https://denser.ai/api/v2/conversations/api" \
  -H "Content-Type: application/json" \
  -H "x-api-key: 00000000-0000-0000-0000-000000000000" \
  -d '{ "chatbotId": "11111111-1111-1111-1111-111111111111", "userId": "user_8842" }'

ResponseCopy Anchor Link

{
  "success": true,
  "data": {
    "conversations": [
      {
        "id": "1791582688917-qzltde6lii",
        "title": "",
        "status": "active",
        "clientType": "api",
        "userId": "user_8842",
        "currentAgent": "bot",
        "createdAt": "2026-10-09T18:24:48.917Z",
        "updatedAt": "2026-10-09T18:26:05.403Z",
        "lastMessage": { "content": "…", "role": "assistant", "createdAt": "2026-10-09T18:26:07.120Z" },
        "messages": [
          { "id": "1791582688917-hihu5fongia", "role": "user", "content": "What is your refund policy?", "createdAt": "2026-10-09T18:24:48.917Z" },
          { "id": "1791582688915-hq4r1oxjrz", "role": "assistant", "content": "…", "createdAt": "2026-10-09T18:24:52.310Z" }
        ]
      }
    ],
    "pagination": { "nextCursor": null, "hasMore": false, "count": 1, "limit": 20 }
  }
}

Each conversation has userId when one was sent (or the website widget's client ID), and each message carries userFeedback when a visitor rated it in the widget. When pagination.hasMore is true, pass pagination.nextCursor back as cursor for the next page.

ErrorsCopy Anchor Link

Errors have success: false and an error.code: