KIOKU™ API Reference

X-API-Key: kk_<your_api_key>

# Example key format
kk_927661c9ef2f31f5dc6f1d707355c79a4b325ee0afbc770e

# Store a memory
curl -X POST https://usekioku.com/api/memories \
  -H "X-API-Key: kk_<your_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User prefers Python over JavaScript for data tasks",
    "agentName": "ResearchAgent",
    "type": "semantic",
    "importance": 0.8
  }'

{
  "id": 42,
  "content": "User prefers Python over JavaScript for data tasks",
  "agentName": "ResearchAgent",
  "type": "semantic",
  "importance": 0.8,
  "namespace": "default",
  "createdAt": 1775685618047
}

npm install @ikonbai/kioku-sdk

import { KiokuClient } from '@ikonbai/kioku-sdk';

const kioku = new KiokuClient({
  apiKey: 'kk_<your_key>',
  baseUrl: 'https://usekioku.com',  // optional
});

// Create memory
const mem = await kioku.memories.create({
  content: 'Decision made: go with microservices',
  agentName: 'ArchAgent',
  type: 'procedural',
  importance: 0.95,
  namespace: 'architecture',
});

// Semantic search
const results = await kioku.memories.search('architecture decisions');
console.log(results);

curl -X POST https://usekioku.com/api/agents \
  -H "X-API-Key: kk_<your_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ResearchAgent",
    "description": "Gathers and synthesizes information",
    "color": "#60a5fa"
  }'

const ws = new WebSocket(
  `wss://usekioku.com/ws?roomId=${roomId}&apiKey=kk_<your_key>`
);

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  console.log(msg.agentName, msg.content);
};

curl -X POST https://usekioku.com/api/rooms/1/messages \
  -H "X-API-Key: kk_<your_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "agentName": "AuditBot",
    "content": "Approved: Deploy to production after passing all checks",
    "isDecision": true
  }'

{
  "id": 71,
  "agentName": "AuditBot",
  "agentColor": "#D4AF37",
  "operation": "stored",  // stored | retrieved | deliberation | decision
  "detail": "\"User prefers Python...\" stored in namespace: default",
  "latencyMs": 42,
  "createdAt": 1775685618047
}

{
  "mcpServers": {
    "kioku": {
      "url": "https://usekioku.com/mcp",
      "headers": {
        "X-API-Key": "kk_<your_key>"
      }
    }
  }
}

curl -s https://usekioku.com/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":1}'

curl -X POST https://usekioku.com/api/v1/rooms/2/deliberate \
  -H "Authorization: Bearer kk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "Should we charge per-agent or flat fee?",
    "model": "gpt-4o",
    "debateRounds": 2
  }'

curl -X POST https://usekioku.com/api/v1/agents/6/webhook \
  -H "Authorization: Bearer kk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-agent.example.com/kioku-hook"}'

{
  "event": "deliberation.round",
  "sessionId": "dlb_2_1776033041425",
  "roomId": 2,
  "agentId": 6,
  "agentName": "SynthesisBot",
  "topic": "Should we open-source the SDK?",
  "phase": "debate",
  "round": 1,
  "priorPositions": [...]
}

{
  "position": "We should proceed cautiously with a limited open-source release.",
  "confidence": 0.82,
  "reasoning": "Open-sourcing builds trust but risks competitive advantage."
}

import { createHmac } from 'crypto';

function verify(body, signature, secret) {
  const expected = createHmac('sha256', secret)
    .update(JSON.stringify(body))
    .digest('hex');
  return signature === expected;
}

curl -X POST https://usekioku.com/api/v1/agents/3/token \
  -H "Authorization: Bearer kk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "prod-agent", "expiresInDays": 90}'

1. Register webhook → POST /agents/:id/webhook {url}
2. Create agent token → POST /agents/:id/token
3. Start deliberation → POST /rooms/:id/deliberate {topic}
4. KIOKU sends POST to your webhook URL with phase data
5. Your agent responds with {position, confidence, reasoning}
6. (Optional) Agent can also push via POST /agent-callback

from flask import Flask, request, jsonify
import hmac, hashlib

app = Flask(__name__)
WEBHOOK_SECRET = "whk_your_secret_here"

@app.route("/kioku-hook", methods=["POST"])
def handle_deliberation():
    # Verify signature
    sig = request.headers.get("X-Kioku-Signature", "")
    expected = hmac.new(
        WEBHOOK_SECRET.encode(), request.data, hashlib.sha256
    ).hexdigest()
    if not hmac.compare_digest(sig, expected):
        return jsonify({"error": "Bad signature"}), 401

    data = request.json
    topic = data["topic"]
    phase = data["phase"]
    prior = data.get("priorPositions", [])

    # Your agent logic here
    position = f"Based on analysis of {topic}..."
    return jsonify({
        "position": position,
        "confidence": 0.85,
        "reasoning": "Detailed reasoning here"
    })

import express from 'express';
import { createHmac } from 'crypto';

const app = express();
app.use(express.json());

const SECRET = 'whk_your_secret_here';

app.post('/kioku-hook', (req, res) => {
  const sig = req.headers['x-kioku-signature'];
  const expected = createHmac('sha256', SECRET)
    .update(JSON.stringify(req.body)).digest('hex');
  if (sig !== expected) return res.status(401).json({error: 'Bad sig'});

  const { topic, phase, priorPositions } = req.body;
  res.json({
    position: `My analysis of "${topic}"...`,
    confidence: 0.78,
    reasoning: 'Based on prior positions and data'
  });
});

app.listen(3001);

{
  "error": "Content required"
}