KinBot exposes a REST API used by the web UI and available for external integrations. All endpoints are under /api/ and require authentication unless noted otherwise.
Authenticate using either:
- API key header:
X-API-Key: <your-api-key>
- Session cookie set during login
Auth routes (/api/auth/*) are handled by Better Auth and don’t require pre-authentication.
| Method | Endpoint | Description |
|---|
GET | /api/kins | List all Kins |
POST | /api/kins | Create a new Kin |
GET | /api/kins/:id | Get Kin details |
PATCH | /api/kins/:id | Update a Kin |
DELETE | /api/kins/:id | Delete a Kin |
GET | /api/kins/:id/tools | List available tools (grouped by domain) |
GET | /api/kins/:id/context-usage | Get context window usage |
POST | /api/kins/:id/avatar | Upload avatar (multipart) |
POST | /api/kins/:id/avatar/generate | Generate avatar with AI |
POST | /api/kins/avatar/preview | Preview generated avatar |
POST | /api/kins/generate-config | AI-generate Kin config from description |
GET | /api/kins/:id/export | Export Kin as archive |
POST | /api/kins/import | Import Kin from archive |
| Method | Endpoint | Description |
|---|
GET | /api/kins/:kinId/messages | Get conversation history |
POST | /api/kins/:kinId/messages | Send a message to a Kin |
| Method | Endpoint | Description |
|---|
GET | /api/kins/:kinId/messages/:messageId/reactions | List reactions on a message |
POST | /api/kins/:kinId/messages/:messageId/reactions | Add or toggle a reaction |
| Method | Endpoint | Description |
|---|
GET | /api/kins/:id/compacting/snapshots | List compacting snapshots |
POST | /api/kins/:id/compacting/run | Trigger manual compacting |
POST | /api/kins/:id/compacting/purge | Purge compacting data |
POST | /api/kins/:id/compacting/rollback | Rollback to a snapshot |
Memories can be accessed via Kin-scoped routes or global maintenance routes.
| Method | Endpoint | Description |
|---|
GET | /api/kins/:id/memories | List memories for a Kin |
POST | /api/kins/:id/memories | Create a memory |
PATCH | /api/kins/:id/memories/:memoryId | Update a memory |
DELETE | /api/kins/:id/memories/:memoryId | Delete a memory |
| Method | Endpoint | Description |
|---|
GET | /api/memories | List all memories (cross-Kin) |
POST | /api/memories/backfill-importance | Backfill importance scores |
POST | /api/memories/consolidate | Run memory consolidation |
POST | /api/memories/reembed | Re-embed all memories |
Kin-scoped knowledge base (RAG document sources).
| Method | Endpoint | Description |
|---|
GET | /api/kins/:kinId/knowledge | List knowledge sources |
POST | /api/kins/:kinId/knowledge | Add a knowledge source |
GET | /api/kins/:kinId/knowledge/search | Search knowledge |
GET | /api/kins/:kinId/knowledge/:sourceId | Get source details |
DELETE | /api/kins/:kinId/knowledge/:sourceId | Delete a source |
POST | /api/kins/:kinId/knowledge/:sourceId/reprocess | Reprocess a source |
Channels are managed globally (not scoped to a Kin).
| Method | Endpoint | Description |
|---|
GET | /api/channels | List all channels |
POST | /api/channels | Create a channel |
GET | /api/channels/pending-count | Get pending message counts |
GET | /api/channels/:id | Get channel details |
PATCH | /api/channels/:id | Update a channel |
DELETE | /api/channels/:id | Delete a channel |
POST | /api/channels/:id/activate | Activate a channel |
POST | /api/channels/:id/deactivate | Deactivate a channel |
POST | /api/channels/:id/test | Test channel configuration |
GET | /api/channels/:id/user-mappings | List user mappings |
POST | /api/channels/:id/user-mappings/:mapId/approve | Approve a user mapping |
Platform-specific webhook endpoints (no auth required, verified by platform signature):
| Method | Endpoint | Description |
|---|
POST | /api/channels/telegram/:channelId | Telegram webhook |
POST | /api/channels/slack/webhook/:channelId | Slack Events API |
GET/POST | /api/channels/whatsapp/webhook/:channelId | WhatsApp verification & webhook |
POST | /api/channels/signal/webhook/:channelId | Signal webhook |
| Method | Endpoint | Description |
|---|
GET | /api/mini-apps | List all mini-apps |
POST | /api/mini-apps | Create a mini-app |
GET | /api/mini-apps/:id | Get mini-app details |
PATCH | /api/mini-apps/:id | Update a mini-app |
DELETE | /api/mini-apps/:id | Delete a mini-app |
GET | /api/mini-apps/by-slug/:kinId/:slug | Get mini-app by Kin + slug |
GET | /api/mini-apps/gallery/browse | Browse mini-app gallery |
POST | /api/mini-apps/:id/generate-icon | Generate an icon with AI |
| Method | Endpoint | Description |
|---|
GET | /api/mini-apps/:id/files | List app files |
GET | /api/mini-apps/:id/files/* | Read a file |
PUT | /api/mini-apps/:id/files/* | Write a file |
DELETE | /api/mini-apps/:id/files/* | Delete a file |
| Method | Endpoint | Description |
|---|
GET | /api/mini-apps/:id/storage | List all keys |
GET | /api/mini-apps/:id/storage/:key | Get a value |
PUT | /api/mini-apps/:id/storage/:key | Set a value |
DELETE | /api/mini-apps/:id/storage/:key | Delete a key |
DELETE | /api/mini-apps/:id/storage | Clear all storage |
| Method | Endpoint | Description |
|---|
GET | /api/mini-apps/:id/snapshots | List snapshots |
POST | /api/mini-apps/:id/snapshots | Create a snapshot |
POST | /api/mini-apps/:id/snapshots/:version/rollback | Rollback to snapshot |
| Method | Endpoint | Description |
|---|
POST | /api/mini-apps/:id/http | Proxy HTTP request to app backend |
GET | /api/mini-apps/:id/events | SSE stream from app backend |
GET | /api/mini-apps/:id/memories/search | Search mini-app memories |
POST | /api/mini-apps/:id/memories | Create a mini-app memory |
| Method | Endpoint | Description |
|---|
GET | /api/mini-apps/:id/serve | Serve mini-app HTML |
GET | /api/mini-apps/:id/static/* | Serve static assets |
| Method | Endpoint | Description |
|---|
GET | /api/mini-apps/sdk/kinbot-sdk.js | SDK JavaScript |
GET | /api/mini-apps/sdk/kinbot-react.js | React bindings |
GET | /api/mini-apps/sdk/kinbot-components.js | Component library |
GET | /api/mini-apps/sdk/kinbot-sdk.css | SDK stylesheet |
GET | /api/mini-apps/sdk/*.d.ts | TypeScript declarations |
Ephemeral conversation sessions for quick interactions.
All session responses include an expiresAt field (Unix timestamp in ms, or null). Sending a message to an expired session returns 409 SESSION_EXPIRED.
| Method | Endpoint | Description |
|---|
GET | /api/kins/:kinId/quick-sessions | List sessions for a Kin |
POST | /api/kins/:kinId/quick-sessions | Create a session |
| Method | Endpoint | Description |
|---|
GET | /api/quick-sessions/:id | Get session with messages |
POST | /api/quick-sessions/:id/messages | Send a message |
POST | /api/quick-sessions/:id/messages/stop | Stop AI generation |
POST | /api/quick-sessions/:id/close | Close a session |
Sub-tasks spawned by Kins (inter-Kin delegation, subtasks). Tasks support concurrency groups — tasks in the same group are limited to a max number of parallel executions, with excess tasks queued and auto-promoted.
| Method | Endpoint | Description |
|---|
GET | /api/tasks | List all tasks |
GET | /api/tasks/:id | Get task details with messages |
POST | /api/tasks/:id/cancel | Cancel a running task |
POST | /api/tasks/:id/force-promote | Force-start a queued task (ignoring concurrency limit) |
| Method | Endpoint | Description |
|---|
GET | /api/plugins | List installed plugins |
POST | /api/plugins | Install a plugin |
PATCH | /api/plugins/:id | Update plugin config |
DELETE | /api/plugins/:id | Uninstall a plugin |
See Plugin API for the full plugin store and registry routes.
| Method | Endpoint | Description |
|---|
GET | /api/providers | List providers with status |
POST | /api/providers | Configure a provider |
PATCH | /api/providers/:id | Update provider config |
DELETE | /api/providers/:id | Remove provider config |
POST | /api/providers/:id/test | Test provider connection |
See Providers for the full provider reference.
| Method | Endpoint | Description |
|---|
GET | /api/contacts | List contacts |
POST | /api/contacts | Create a contact |
GET | /api/contacts/:id | Get contact details |
PATCH | /api/contacts/:id | Update a contact |
DELETE | /api/contacts/:id | Delete a contact |
POST | /api/contacts/:id/identifiers | Add an identifier |
PATCH | /api/contacts/:id/identifiers/:identifierId | Update an identifier |
DELETE | /api/contacts/:id/identifiers/:identifierId | Remove an identifier |
GET | /api/contacts/:id/platform-ids | List platform IDs |
POST | /api/contacts/:id/platform-ids | Add a platform ID |
DELETE | /api/contacts/:id/platform-ids/:pidId | Remove a platform ID |
POST | /api/contacts/:id/notes | Add a note |
PATCH | /api/contacts/:id/notes/:noteId | Update a note |
DELETE | /api/contacts/:id/notes/:noteId | Delete a note |
| Method | Endpoint | Description |
|---|
GET | /api/mcp-servers | List MCP server configs |
POST | /api/mcp-servers | Add an MCP server |
PATCH | /api/mcp-servers/:id | Update MCP server |
POST | /api/mcp-servers/:id/approve | Approve an MCP server |
DELETE | /api/mcp-servers/:id | Remove MCP server |
Cron jobs are managed globally (not scoped to a Kin).
| Method | Endpoint | Description |
|---|
GET | /api/crons | List cron jobs |
POST | /api/crons | Create a cron job |
PATCH | /api/crons/:id | Update a cron job |
POST | /api/crons/:id/trigger | Trigger a job immediately |
POST | /api/crons/:id/approve | Approve a pending job |
DELETE | /api/crons/:id | Delete a cron job |
Webhooks are managed globally.
| Method | Endpoint | Description |
|---|
GET | /api/webhooks | List webhooks |
POST | /api/webhooks | Create a webhook |
PATCH | /api/webhooks/:id | Update a webhook |
DELETE | /api/webhooks/:id | Delete a webhook |
GET | /api/webhooks/:id/logs | Get webhook execution logs |
POST | /api/webhooks/:id/regenerate-token | Regenerate webhook token |
POST | /api/webhooks/:id/test-filter | Test a payload filter against a sample payload |
POST | /api/webhooks/:id/suggest-fields | Extract field path suggestions from the last received payload |
| Method | Endpoint | Description |
|---|
POST | /api/webhooks/incoming/:webhookId | Receive an incoming webhook (rate-limited) |
Secure storage for secrets and sensitive data.
| Method | Endpoint | Description |
|---|
GET | /api/vault | List vaults |
POST | /api/vault | Create a vault |
PATCH | /api/vault/:id | Update a vault |
DELETE | /api/vault/:id | Delete a vault |
| Method | Endpoint | Description |
|---|
GET | /api/vault/entries | List entries |
POST | /api/vault/entries | Create an entry |
GET | /api/vault/entries/:id | Get entry details |
PATCH | /api/vault/entries/:id | Update an entry |
DELETE | /api/vault/entries/:id | Delete an entry |
| Method | Endpoint | Description |
|---|
GET | /api/vault/entries/:id/attachments | List attachments |
POST | /api/vault/entries/:id/attachments | Upload attachment |
GET | /api/vault/attachments/:id | Download attachment |
DELETE | /api/vault/attachments/:id | Delete attachment |
| Method | Endpoint | Description |
|---|
GET | /api/vault/types | List vault types |
POST | /api/vault/types | Create a type |
PATCH | /api/vault/types/:id | Update a type |
DELETE | /api/vault/types/:id | Delete a type |
Shared file hosting with optional expiration and passwords.
| Method | Endpoint | Description |
|---|
GET | /api/file-storage | List stored files |
POST | /api/file-storage | Upload a file (multipart) |
GET | /api/file-storage/:id | Download a file |
PATCH | /api/file-storage/:id | Update file metadata |
DELETE | /api/file-storage/:id | Delete a file |
Internal file uploads (used by messages).
| Method | Endpoint | Description |
|---|
POST | /api/files/upload | Upload a file (multipart) |
| Method | Endpoint | Description |
|---|
GET | /api/notifications | List notifications |
GET | /api/notifications/unread-count | Get unread count |
PATCH | /api/notifications/:id/read | Mark as read |
POST | /api/notifications/mark-all-read | Mark all as read |
DELETE | /api/notifications/:id | Delete a notification |
Pending approval prompts (e.g. tool use confirmations).
| Method | Endpoint | Description |
|---|
GET | /api/prompts/pending | List pending prompts |
POST | /api/prompts/:id/respond | Respond to a prompt |
| Method | Endpoint | Description |
|---|
GET | /api/users | List users |
GET | /api/users/mentionables | List mentionable users |
DELETE | /api/users/:id | Delete a user |
| Method | Endpoint | Description |
|---|
GET | /api/invitations | List invitations |
POST | /api/invitations | Create an invitation |
DELETE | /api/invitations/:id | Delete an invitation |
GET | /api/invitations/:token/validate | Validate an invitation token |
| Method | Endpoint | Description |
|---|
GET | /api/settings/global-prompt | Get global system prompt |
PUT | /api/settings/global-prompt | Update global prompt |
GET | /api/settings/models | Get model configuration |
PUT | /api/settings/extraction-model | Set memory extraction model |
PUT | /api/settings/embedding-model | Set embedding model |
GET | /api/settings/search-provider | Get search provider config |
PUT | /api/settings/search-provider | Update search provider |
GET | /api/settings/hub | Get Hub settings |
PUT | /api/settings/hub | Update Hub settings |
GET | /api/settings/compacting-threshold | Get compacting threshold percent |
PUT | /api/settings/compacting-threshold | Set compacting threshold percent (50-95) |
| Method | Endpoint | Description |
|---|
GET | /api/me | Get current user info |
PATCH | /api/me | Update profile |
POST | /api/me/avatar | Upload avatar (multipart) |
Public access to shared files (no auth required, token-based).
| Method | Endpoint | Description |
|---|
GET | /s/:token | View shared content |
POST | /s/:token | Access password-protected share |
| Method | Endpoint | Description |
|---|
GET | /api/version-check | Get cached version info (current version, latest, update available, release notes). Returns isUpdateAvailable: false if disabled |
POST | /api/version-check/check | Force a fresh version check (admin only). Returns 400 if version check is disabled |
POST | /api/version-check/update | Self-update: runs git pull + bun install and restarts (admin only, non-Docker). Returns 400 in Docker mode |
| Method | Endpoint | Description |
|---|
GET | /api/sse | SSE event stream (see SSE Events) |