Build on Knowledge Spaces

Register, generate your Organization API Key in the console, and get a bot answer with your organization's governance (tenant isolation, logged calls) applied automatically.

1. Register and Generate Your Key

Sign up at spaces.sprinklenet.com/register with your organization name to create your workspace, then open Account Settings in the console, find Organization API Key, and select Regenerate Key (or Generate API Key if no key is set) to view your key. The full key is shown only once, so store it in a secret manager now. Regenerating replaces the previous key immediately.

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

2. Call the Bot

One POST with a session_id you control and the user's text.

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": {
    "content": "Start with the implementation brief...",
    "resources": [],
    "isComplete": true
  }
}

That call ran with your org's governance applied: the key is scoped to a single organization, so it can only reach bots and sessions your org owns, and the call is tenant-scoped and logged. The answer is in text.content. Want tokens as they generate? Add "stream": true and the response becomes a text/event-stream of Server-Sent Events.

3. Read the Rate-Limit Headers

Every response carries RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset, and a 429 carries Retry-After. Read your limits from these headers rather than hard-coding them, and back off on 429. GET /rate-limit/info returns the published policy without authentication.

Keep one conversation across many calls, then read the transcript and manage the session's lifecycle.

1. Mint an Unguessable Session ID

session_id is caller-controlled: reuse a value to continue a thread, use a new value to start fresh. A predictable id (an email, a row number) risks one user's messages landing in another user's thread inside your product, so mint a UUID per conversation.

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

2. Chat, Then Chat Again With the Same ID

The second call answers with the earlier turns in context.

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": { "content": "You said your name is Dana.", ... } }

3. Retrieve the Transcript

Returns the 10 most recent messages in the session, oldest first. Each message carries role, text, resources, and createdAt; ignore fields you do not use.

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", "text": "My name is Dana. Which plan...", "createdAt": "2026-07-08T14:03:12.000Z" },
    { "role": "assistant", "text": "For a two-person team...", "createdAt": "2026-07-08T14:03:14.000Z" }
  ]
}

4. Inspect and Manage the Session

GET /sessions/{session_id} returns the record: session_id, chatbot_id, created_at, last_active_at, message_count, status. Attach your own metadata with PUT /sessions/{session_id}/context, close with POST /sessions/{session_id}/end (transcript retained), or erase entirely with DELETE /sessions/{session_id} for GDPR erasure requests.

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" } }'