Conversations

List, read and delete the threads belonging to each of your end users.

Every question belongs to a thread, and every thread belongs to one of your end users. These three endpoints let you build a history view, resume a conversation, and delete on your own schedule.

end_user_id scopes everything

All three endpoints take end_user_id as a query parameter. Get it wrong and you get 404, not someone else's data. The isolation is enforced on the server, not by convention.

List threads

GET/api/v1/conversations

Most recently updated first.

end_user_id

query

Whose threads to return. Defaults to the same `default` bucket the chat endpoint uses.

limit

query

Page size.

offset

query

Rows to skip, for paging.

bash

curl "https://api-seerahai.karmat-hq.com/api/v1/conversations?end_user_id=user-8842&limit=20" \
  -H "X-API-Key: $SEERAH_API_KEY"

json

[
  {
    "id": 4182,
    "title": "Patience in the Quran",
    "created_at": "2026-08-26T14:02:11Z",
    "updated_at": "2026-08-27T09:15:40Z"
  }
]

Read one thread

GET/api/v1/conversations/{conversation_id}

Returns the full message history, alternating user and assistant turns.

bash

curl "https://api-seerahai.karmat-hq.com/api/v1/conversations/4182?end_user_id=user-8842" \
  -H "X-API-Key: $SEERAH_API_KEY"

json

{
  "id": 4182,
  "title": "Patience in the Quran",
  "messages": [
    {
      "id": 9001,
      "role": "user",
      "content": "What does the Quran say about patience?",
      "extra_data": null,
      "created_at": "2026-08-26T14:02:11Z"
    },
    {
      "id": 9002,
      "role": "assistant",
      "content": "Patience (sabr) is among the most frequently commended...",
      "extra_data": { "sources_found": 7, "run_id": "run_01HQB7Y4K2" },
      "created_at": "2026-08-26T14:02:19Z"
    }
  ]
}

Assistant turns carry their retrieval metadata in extra_data, so a history view can show the same sources the user saw at the time.

Delete a thread

DELETE/api/v1/conversations/{conversation_id}

Removes the thread and every message in it. There is no undo.

bash

curl -X DELETE "https://api-seerahai.karmat-hq.com/api/v1/conversations/4182?end_user_id=user-8842" \
  -H "X-API-Key: $SEERAH_API_KEY"

Wire this to your own deletion flow

When one of your users deletes their account or asks to be forgotten, their Seerah threads do not disappear on their own. Call this endpoint as part of that flow. Otherwise you are holding their question history after promising you would not.

Building a history view

const BASE = "https://api-seerahai.karmat-hq.com";
const headers = { "X-API-Key": process.env.SEERAH_API_KEY! };

// Your route already knows who is signed in; never take end_user_id
// from the client, or one user can read another's threads.
export async function GET(request: Request) {
  const user = await authenticate(request);

  const params = new URLSearchParams({
    end_user_id: user.id,
    limit: "20",
  });

  const response = await fetch(
    `${BASE}/api/v1/conversations?${params}`,
    { headers },
  );

  return Response.json(await response.json());
}

Never accept end_user_id from the browser

It is the entire isolation boundary. If a client can send it, a client can send someone else's. Derive it server-side from your own session.