# Kairn

## Docs

- [What is Kairn?](https://docs.kairn.sh/introduction.md): Agent infrastructure for AI products. One API to add persistent, memory-aware agents to your product.
- [Quickstart](https://docs.kairn.sh/quickstart.md): From zero to your first agent invocation in under 5 minutes.
- [Core Concepts](https://docs.kairn.sh/concepts.md): The mental model behind Kairn — souls, memory, sessions, mandates, and multi-tenancy.
- [SDK Reference](https://docs.kairn.sh/sdk-reference.md): Full API reference for the @kairnsh/sdk Node.js SDK.
- [Invoke an agent](https://docs.kairn.sh/api-reference/invoke.md): Run an agent for a user. Returns a full JSON response by default. Set `stream: true` or `Accept: text/event-stream` to receive a streaming SSE response instead.
- [Invoke an agent (async)](https://docs.kairn.sh/api-reference/invoke-async.md): Queue an agent invocation as a background job. Returns `202 Accepted` immediately with a `job_id`. The agent runs in the background — no connection held open, no timeout risk. Poll `GET /v1/agent/jobs/{job_id}` for the result, or provide a `callback_url` to receive a webhook when the job completes.
- [Poll async job](https://docs.kairn.sh/api-reference/jobs-get.md): Get the current status and result of an async job. Poll this endpoint until `status` is `completed` or `failed`. `output` and `memoryDelta` are only populated when `status === 'completed'`.
- [Get user memory](https://docs.kairn.sh/api-reference/memory-get.md): Get memory for a user. With `?role=`, returns a flat key-value map for that role. Without `role`, returns memory grouped by all roles.
- [Write memory](https://docs.kairn.sh/api-reference/memory-set.md): Write key-value pairs to a user's memory. Set a key's value to `null` to delete it. Writes are merged into existing memory — keys not in `delta` are unchanged.
- [Delete user memory](https://docs.kairn.sh/api-reference/memory-delete.md): Delete all memory for a user. With `?role=`, deletes only that role's memory. This cannot be undone.
- [Delete a memory key](https://docs.kairn.sh/api-reference/memory-delete-key.md): Delete a single key from a user's memory. The `role` query param is required.
- [List users with memory](https://docs.kairn.sh/api-reference/memory-list-users.md): Returns a list of user IDs that have memory stored for your tenant.
- [Create a soul](https://docs.kairn.sh/api-reference/souls-create.md): Create a new agent identity for your tenant. Soul names must be unique.
- [List skills](https://docs.kairn.sh/api-reference/skills-list.md): List all custom skills for your tenant.
- [Create a skill](https://docs.kairn.sh/api-reference/skills-create.md): Create a custom skill. At least one of `instructions_md` or `webhook_url` is required. Name must be lowercase letters, digits, or underscores.
- [Get a skill](https://docs.kairn.sh/api-reference/skills-get.md): Get a custom skill by name.
- [Update a skill](https://docs.kairn.sh/api-reference/skills-update.md): Update a custom skill by name. Returns { status: "ok" }.
- [Delete a skill](https://docs.kairn.sh/api-reference/skills-delete.md): Delete a custom skill by name. Returns { status: "ok" }.
- [Create a mandate](https://docs.kairn.sh/api-reference/mandates-create.md): Schedule an agent to run autonomously for a user on a cron schedule. The agent has access to the user's memory and the soul's permissions.
- [List mandates](https://docs.kairn.sh/api-reference/mandates-list.md): List all mandates for your tenant, ordered by creation date descending.
- [Get a mandate](https://docs.kairn.sh/api-reference/mandates-get.md): Get a mandate by ID including its current status, run count, and next scheduled run.
- [Pause a mandate](https://docs.kairn.sh/api-reference/mandates-pause.md): Pause a mandate. It will stop running until resumed.
- [Cancel a mandate](https://docs.kairn.sh/api-reference/mandates-cancel.md): Cancel a mandate permanently. This cannot be undone.
- [List invocations](https://docs.kairn.sh/api-reference/invocations-list.md): List invocations for your tenant with optional filters and cursor-based pagination.
- [Invocation stats](https://docs.kairn.sh/api-reference/invocations-stats.md): Aggregated stats for your tenant's invocations. Useful for usage dashboards.
- [Get an invocation](https://docs.kairn.sh/api-reference/invocations-get.md): Get the full record for a single invocation by ID, including input, output, memory delta, and tool calls.
- [Get sessions or messages](https://docs.kairn.sh/api-reference/sessions-get.md): With `soul`, `role`, and `session_id` all provided, returns the full message history for that session. Otherwise, returns a list of all sessions for the user.
- [Audit log](https://docs.kairn.sh/api-reference/audit-list.md): Retrieve the audit log for your tenant. Filter by `user_id` to see a specific user's activity.
- [Customer Support](https://docs.kairn.sh/use-cases/customer-support.md): An action-taking support agent that knows your users and acts inside your product.
- [HR Onboarding](https://docs.kairn.sh/use-cases/hr-onboarding.md): A personal onboarding guide for every new hire — personalised, proactive, and checklist-aware.
- [RevOps Pipeline](https://docs.kairn.sh/use-cases/revops.md): A pipeline assistant that updates your CRM from call notes and surfaces stale deals automatically.
- [FinTech Expenses](https://docs.kairn.sh/use-cases/fintech.md): Expense submission, policy enforcement, and budget reporting — without a spreadsheet.

## OpenAPI Specs

- [openapi](https://docs.kairn.sh/api-reference/openapi.json)

## Optional

- [SDK on npm](https://www.npmjs.com/package/@kairnsh/sdk)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.