REST API

Authorization: Bearer idk_live_…

curl https://YOUR_APP/api/v1/agents/AGENT_ID/chat \
  -H "Authorization: Bearer $INTELLIDESK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Where is my order?",
    "user": { "id": "u_123", "email": "ada@example.com", "name": "Ada" }
  }'

{
  "data": {
    "conversationId": "conversations_…",
    "messageId": "messages_…",
    "reply": "Your order shipped yesterday. Here's the tracking link: …",
    "sources": [{ "title": "Shipping policy", "url": "https://example.com/shipping" }],
    "handoff": "ai",
    "collectLead": false,
    "bookCall": null
  }
}

const res = await fetch(`https://YOUR_APP/api/v1/agents/${agentId}/chat`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.INTELLIDESK_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    message: question,
    conversationId,                 // from the previous reply, to continue the chat
    user: { id: user.id, email: user.email, name: user.name },
  }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
const { reply, conversationId: next } = body.data;

import os, requests

res = requests.post(
    f"https://YOUR_APP/api/v1/agents/{agent_id}/chat",
    headers={"Authorization": f"Bearer {os.environ['INTELLIDESK_API_KEY']}"},
    json={"message": question, "conversationId": conversation_id, "user": {"id": user_id}},
    timeout=60,
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
reply = body["data"]["reply"]

event: token
data: {"token":"Your order "}

event: token
data: {"token":"shipped yesterday."}

event: done
data: {"conversationId":"conversations_…","messageId":"messages_…","reply":"Your order shipped yesterday.", …}

const res = await fetch(`https://YOUR_APP/api/v1/agents/${agentId}/chat`, {
  method: "POST",
  headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
  body: JSON.stringify({ message: question, stream: true }),
});
const reader = res.body!.pipeThrough(new TextDecoderStream()).getReader();
let buffer = "";
for (;;) {
  const { value, done } = await reader.read();
  if (done) break;
  buffer += value;
  let end;
  while ((end = buffer.indexOf("\n\n")) >= 0) {
    const frame = buffer.slice(0, end);
    buffer = buffer.slice(end + 2);
    const event = /^event: (.*)$/m.exec(frame)?.[1];
    const data = JSON.parse(/^data: (.*)$/m.exec(frame)?.[1] || "{}");
    if (event === "token") process.stdout.write(data.token);
    if (event === "done") console.log("\nconversation:", data.conversationId);
    if (event === "error") throw new Error(`${data.code}: ${data.message}`);
  }
}

{
  "data": [
    {
      "id": "conversations_…",
      "agentId": "agents_…",
      "channel": "widget",
      "visitorId": "v_…",
      "createdAt": 1790467905529,
      "lastMessageAt": 1790468010311,
      "status": "open",
      "summary": "Asked where their order is; shared tracking.",
      "sentiment": "positive",
      "resolution": "resolved",
      "rating": 5
    }
  ],
  "nextBefore": 1790468010311
}

# Text
curl https://YOUR_APP/api/v1/agents/AGENT_ID/sources -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" -d '{"type":"text","title":"Returns","body":"Returns are free within 30 days."}'

# Q&A
curl … -d '{"type":"qa","question":"Do you ship abroad?","answer":"Yes, to 30 countries."}'

# Website (crawl, sitemap or a single link)
curl … -d '{"type":"website","url":"https://example.com/help","mode":"crawl","includePaths":["/help"]}'

# Then retrain, so the agent uses it
curl -X POST https://YOUR_APP/api/v1/agents/AGENT_ID/retrain -H "Authorization: Bearer $KEY"

{
  "error": {
    "status": 404,
    "code": "conversation_not_found",
    "message": "Conversation not found for this agent. Continue a conversation with the same user, visitorId or key that started it."
  }
}