API overview

An InkBot server exposes everything the app does over HTTP: bots and chats, replies, approvals, providers, plugins, routines, triggers and more. The app itself uses this API. You can use it to script your bots, build your own client or connect other tools.

Basics

Base URL	https://your-server/api
Format	JSON in and out (UTF-8). Property names are camelCase, enums are strings ("AllowOnce"), dates are ISO 8601, and properties that are null are left out of responses.
Live updates	A WebSocket at /api/events. See Events.
Webhooks	POST /hooks/{id} (outside /api, no token). See Webhook triggers.

Authentication

Every request under /api needs the server's access token as a bearer token:

Authorization: Bearer <access token>

The token is printed by the install script and kept in server-token in the data folder (see Configure a server). It gives full access to the server, so keep it like a password. There is one token per server and no scopes.

Your first request

export INKBOT=https://bots.example.com
export TOKEN=...   # the server's access token

curl -s $INKBOT/api/info -H "Authorization: Bearer $TOKEN"

{ "name": "My server", "version": "1.0.0+5b59ec3…", "operatingSystem": "Unix 6.8.0.45", "workspaceFolder": "/home/inkbot/Documents/InkBot" }

Errors

Status	Body	Meaning
401	empty	No token, or the wrong one
400	an error object	Something the person should see: a bad key, a model that isn't connected, an unknown bot, a sign-in that's needed
400	not JSON	The request body is missing or isn't valid JSON for that endpoint
404	empty	The thing isn't there (attachments, skills, skill files)
204	empty	Success with nothing to return

The error object:

{
  "message": "Claude (API) isn't connected on this server.",
  "signInRequired": false
}

• message is written to be shown to a person as it is.
• signInRequired is true when a provider needs signing in again.
• pluginSignInUrl, pluginResourceMetadata and pluginScope are set when a plugin needs a browser sign-in the server can't do itself. The app does the sign-in and passes it back in POST /plugins/{id}/connect.

Endpoints

Area	Endpoints
Bots and chats	/bots, /bots/{id}, messages, attachments, memory, prompt, changes, outputs, goals
Replies	send, respond, steer, stop, approvals, questions
Events	/events (WebSocket)
Models and settings	/info, /models, /settings, /providers
Integrations	/plugins, /composio, /logins, /quill, /blotter
Automation and team	/routines, /triggers, /handoffs, /incidents
Workspace and tools	/search, /usage, /export, /import, /skills, /team-memory, /background-tasks, /terminals, /computers, /local-models
Object reference	The shapes these endpoints send and receive