SDK Reference

import Kairn from '@kairnsh/sdk'

const kairn = new Kairn({
  apiKey: 'kn_live_...',           // required
  baseUrl: 'https://api.kairn.sh', // optional — override for self-hosted
})

const result = await kairn.invoke({
  agent: 'assistant',   // soul name
  userId: 'user_123',   // your user's ID
  input: 'Help me update my billing address.',
  role: 'default',      // optional
  sessionId: 'chat_1',  // optional — enables multi-turn history
})

for await (const event of kairn.stream({
  agent: 'assistant',
  userId: 'user_123',
  input: 'Summarise my last 5 actions.',
})) {
  switch (event.type) {
    case 'token':
      process.stdout.write(event.text)
      break
    case 'tool_start':
      console.log(`Using tool: ${event.name}`)
      break
    case 'memory_delta':
      console.log('Memory written:', event.delta)
      break
    case 'done':
      console.log('Final output:', event.output)
      break
    case 'error':
      console.error('Agent error:', event.error)
      break
  }
}

// app/api/chat/route.ts
import Kairn from '@kairnsh/sdk'

const kairn = new Kairn({ apiKey: process.env.KAIRN_API_KEY! })

export async function POST(req: Request) {
  const { userId, input, sessionId } = await req.json()

  const encoder = new TextEncoder()
  const stream = new ReadableStream({
    async start(controller) {
      for await (const event of kairn.stream({ agent: 'assistant', userId, input, sessionId })) {
        if (event.type === 'token') {
          controller.enqueue(encoder.encode(event.text))
        }
        if (event.type === 'done' || event.type === 'error') {
          controller.close()
        }
      }
    },
  })

  return new Response(stream, {
    headers: { 'Content-Type': 'text/plain; charset=utf-8' },
  })
}

const job = await kairn.invokeAsync({
  agent: 'advisor',
  userId: 'user_123',
  input: 'Research our top 5 competitors and summarise findings.',
  callbackUrl: 'https://yourapp.com/webhooks/kairn', // optional
})

const status = await job.poll()
// { jobId, status: 'running', ... }

// Simple: fire and wait
const result = await job.wait()
console.log(result.output)

// With custom poll interval and timeout
const result = await job.wait({ intervalMs: 3000, timeoutMs: 60000 })

// In your API handler
const job = await kairn.invokeAsync({ agent: 'advisor', userId, input })
await db.jobs.insert({ id: job.jobId, userId })
return res.status(202).json({ jobId: job.jobId })

// In a separate polling endpoint
const status = await kairn.jobs.get(savedJobId)
if (status.status === 'completed') {
  return res.json({ output: status.output })
}

await kairn.invokeAsync({
  agent: 'advisor',
  userId,
  input: 'Run the weekly review.',
  callbackUrl: 'https://yourapp.com/webhooks/kairn',
})
// Kairn POSTs { job_id, status, output, memory_delta, ... } to your URL when done

const job = await kairn.jobs.get('2e4edc0c-8597-4e04-bf0a-c16349c6d35e')

const memory = await kairn.memory.get('user_123', 'default')
// { plan: 'pro', name: 'Alex' }

const all = await kairn.memory.get('user_123')
// { default: { plan: 'pro' }, manager: { team_size: '12' } }

await kairn.memory.set('user_123', 'default', {
  plan: 'pro',
  onboarding_done: 'true',
  temp_flag: null, // deletes this key
})

await kairn.memory.delete('user_123')

const souls = await kairn.souls.list()

await kairn.souls.create({
  name: 'advisor',
  label: 'Growth Advisor',
  soulMd: 'You are a seasoned growth advisor...',
  defaultModel: 'anthropic/claude-sonnet-4-6',
  allowedSkills: ['web_search'],
})

await kairn.souls.update('advisor', {
  soulMd: 'Updated identity...',
})

const skills = await kairn.skills.list()

await kairn.skills.create({
  name: 'my_skill',
  label: 'My Skill',
  instructionsMd: 'How to use this skill.',
  webhookUrl: 'https://example.com/webhook',
  httpMethod: 'POST',
})

const skill = await kairn.skills.get('my_skill')
await kairn.skills.update('my_skill', { label: 'Updated Label', instructionsMd: 'New instructions.' })
await kairn.skills.delete('my_skill')

await kairn.mandates.create({
  userId: 'user_123',
  soul: 'advisor',
  label: 'Weekly check-in',
  taskPrompt: 'Review goals and write a weekly summary to memory.',
  trigger: { type: 'cron', cron: '0 9 * * 1' },
})

const mandates = await kairn.mandates.list()
const mandate  = await kairn.mandates.get(mandate.id)
await kairn.mandates.pause(mandate.id)
await kairn.mandates.cancel(mandate.id)

const { invocations, nextCursor } = await kairn.invocations.list({
  userId: 'user_123',
  status: 'completed',
  limit: 20,
})

// Paginate
const next = await kairn.invocations.list({ cursor: nextCursor })

const inv = await kairn.invocations.get('inv_abc123')

import Kairn, { KairnError } from '@kairnsh/sdk'

try {
  await kairn.invoke({ agent: 'advisor', userId, input })
} catch (err) {
  if (err instanceof KairnError) {
    console.error(err.message)    // human-readable
    console.error(err.status)     // HTTP status code
    console.error(err.errorType)  // machine-readable type

    if (err.status === 429 && err.errorType === 'quota_exceeded') {
      // Monthly plan limit hit
    }
    if (err.status === 429 && err.errorType === 'rate_limit_exceeded') {
      // Too many requests per minute
    }
    if (err.status === 404 && err.errorType === 'soul_not_found') {
      // Soul name doesn't exist for this tenant
    }
  }
}

import type {
  InvokeParams,
  InvokeResult,
  AsyncInvokeParams,
  AsyncJob,
  StreamEvent,
  MemoryMap,
  MemoryDelta,
  Soul,
  SoulCreateParams,
  Skill,
  SkillCreateParams,
  Mandate,
  MandateCreateParams,
  Invocation,
  KairnOptions,
} from '@kairnsh/sdk'