Build on Knowledge Spaces

export KS_API_KEY="ks_live_your_key_here"
export BOT_ID="665f1a2b3c4d5e6f7a8b9c0d"   # from your bot in the console

curl -X POST "https://spaces.sprinklenet.com/api/bots/$BOT_ID/chat" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $KS_API_KEY" \
  -d '{ "session_id": "'"$(uuidgen)"'", "text": "What should I read first?" }'

200 OK
{ "success": true, "text": "Start with the implementation brief..." }

const sessionId = crypto.randomUUID();
// e.g. "6b3f2c9e-8a41-4d2f-9c57-1e2a7b3d4f80"

const BASE = "https://spaces.sprinklenet.com/api";
const headers = {
  "X-API-Key": process.env.KS_API_KEY,
  "Content-Type": "application/json",
};

await fetch(`${BASE}/bots/${process.env.BOT_ID}/chat`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    session_id: sessionId,
    text: "My name is Dana. Which plan fits a two-person team?",
  }),
});

const followUp = await fetch(`${BASE}/bots/${process.env.BOT_ID}/chat`, {
  method: "POST",
  headers,
  body: JSON.stringify({ session_id: sessionId, text: "What was my name again?" }),
});
console.log(await followUp.json());
// { "success": true, "text": "You said your name is Dana." }

const history = await fetch(
  `${BASE}/bots/${process.env.BOT_ID}/chat?session_id=${sessionId}`,
  { headers: { "X-API-Key": process.env.KS_API_KEY } }
);
console.log(await history.json());

200 OK
{
  "success": true,
  "messages": [
    { "role": "user", "content": "My name is Dana. Which plan...", "timestamp": "2026-07-08T14:03:12.000Z" },
    { "role": "assistant", "content": "For a two-person team...", "timestamp": "2026-07-08T14:03:14.000Z" }
  ]
}

curl -X PUT "https://spaces.sprinklenet.com/api/sessions/$SESSION_ID/context" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $KS_API_KEY" \
  -d '{ "end_user_id": "user_42", "custom_context": { "plan": "enterprise" } }'

curl -X POST "https://spaces.sprinklenet.com/api/orgs/$ORG_ID/webhooks" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $KS_API_KEY" \
  -d '{
    "name": "Ops alerting",
    "url": "https://example.com/hooks/knowledge-spaces",
    "events": ["session.ended", "escalation.fired"]
  }'

POST /hooks/knowledge-spaces
Content-Type: application/json
X-Webhook-Signature: t=1751980393000,v1=5f2d8c...e9a1
X-Webhook-Timestamp: 1751980393000
X-Webhook-Event: session.ended

{ "event_type": "session.ended", "timestamp": "2026-07-08T14:33:13.000Z", "data": { ... } }

import express from "express";
import crypto from "node:crypto";

const app = express();

// The signature covers the raw bytes, so use express.raw on this
// route and verify BEFORE any JSON parsing.
app.post(
  "/hooks/knowledge-spaces",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const header = req.get("X-Webhook-Signature") || "";
    const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
    const t = Number(parts.t);
    const theirs = parts.v1 || "";

    // Timestamp is Unix milliseconds. Reject anything outside 5 minutes.
    if (!t || Math.abs(Date.now() - t) > 5 * 60 * 1000) {
      return res.status(400).send("stale timestamp");
    }

    const ours = crypto
      .createHmac("sha256", process.env.KS_WEBHOOK_SECRET)
      .update(`${t}.${req.body}`) // req.body is a Buffer here
      .digest("hex");

    let valid = false;
    try {
      valid = crypto.timingSafeEqual(Buffer.from(ours), Buffer.from(theirs));
    } catch {
      valid = false;
    }
    if (!valid) return res.status(401).send("bad signature");

    const event = JSON.parse(req.body);
    console.log(req.get("X-Webhook-Event"), event.data);

    // Respond 2xx fast. Non-2xx and timeouts are retried with
    // exponential backoff (retry_count default 3, timeout_ms default 10s).
    res.sendStatus(200);
  }
);

app.listen(3000);