API reference

Base URL: https://api.usekaras.com

Everything is JSON over HTTPS. Interactive API documentation is not exposed; this page is the reference.

Authentication

Either header, not both:

• X-API-Key: <your api key> — for calls from your own backend. See API keys.
• X-Widget-Key: <your widget key> — for calls from a browser, which must also come from an allowlisted domain. See Your widget key and domain allowlist.

Your account is determined by the key. It can never be supplied in a request body; a body that tries is rejected.

Ask a question

POST /v1/qa/query

{
  "query": "How long does delivery take to Ireland?",
  "session_id": "abc123def456",
  "top_k": 8
}

query is required, up to 4000 characters. session_id is optional but strongly recommended — it is what lets a follow-up question understand the previous few turns. top_k is optional, between 1 and 100.

Response:

{
  "answer_markdown": "Delivery to Ireland takes 3-5 working days...",
  "sources": [
    { "doc_id": "kb-114", "title": "Delivery times by country",
      "url": "https://example.com/help/delivery-times", "section_id": "kb-114:002-europe" }
  ],
  "resolution_state": "answered",
  "trace_id": "7f3a9c2e...",
  "metadata": {}
}

answer_markdown is Markdown. resolution_state tells you what kind of outcome this was — an answer, a clarifying question, or a conversation that needs a person. trace_id identifies the request and is what to quote when reporting a problem.

Answers are returned complete rather than streamed. This is deliberate: the safety checks run on the finished text and some of them replace it, so there is no safe prefix to send early.

Record feedback

POST /v1/qa/feedback

{
  "trace_id": "7f3a9c2e...",
  "session_id": "abc123def456",
  "rating": -1,
  "comment": "Quoted the old returns window",
  "question": "How long do I have to return something?",
  "answer": "You can return any unworn item within 14 days...",
  "doc_ids": ["kb-114", "kb-087"]
}

trace_id and rating are required; rating is 1, 0 or -1.

Everything else is optional, and sending it is what makes a rating useful to read later — without question, answer and doc_ids, a thumbs-down records only that something was wrong, not what. Send the answer as it was served to you, not a display-trimmed version, and doc_ids as the doc_id of each source you showed.

Limits: question 4000 characters, answer 6000 (longer is stored with a truncation marker), comment 4000, doc_ids at most 50 entries of which the first 10 unique ids are kept. Exceeding a limit is a 422, so trim client-side rather than relying on the server to accept it.

Card numbers, security codes, passwords and tokens are stripped from question, answer and comment before storage. Ratings are deleted automatically 12 months after they are given.

Get the starter questions

GET /v1/qa/suggestions

Returns the questions configured for your account, each with an id, a question and a category.

Get widget configuration

GET /v1/widget/config

Returns your branding, greeting, agent, composer and starter questions. Requires a widget key and an allowlisted origin.

Request a handoff

POST /v1/handoff

{
  "session_id": "abc123def456",
  "requester": { "name": "Sam Doyle", "email": "sam@example.com" },
  "identity_source": "form"
}

state comes back as created, queued, failed or rejected_email. A created response carries the helpdesk's own reference. existing: true means this session already had a ticket and that is the one you were given.

POST /v1/handoff/status with { "session_id": "..." } reports what became of a request. The session identifier goes in the body rather than the URL so it stays out of access logs.

Errors

401 unknown or missing key. 403 widget key used from a domain that is not allowlisted. 422 malformed body. Unknown fields are rejected rather than ignored, on every endpoint — a typo in a field name is an error you see immediately, not a value silently dropped. 429 rate limited — see Rate limits.