# API Reference Every HTTP endpoint the nikcli server exposes — 349 operations across 290 paths, generated from the server's own OpenAPI document. ## Overview The nikcli server is a single [Effect `HttpApi`](/docs/server-api). Every endpoint on this page is declared as a typed `HttpApiEndpoint` with schema-checked request and response bodies, so the reference below, the generated SDK and the running server all come from the same declaration — not from three copies of it that drift. Surface ### 349 operations Across 290 paths and 34 resource groups. Types ### 616 schemas Request and response shapes, each reachable from the endpoints that use it. Contract ### OpenAPI 3.1.0 Emitted by `nikcli generate` from the composed API, then consumed by the SDK generator and by this page. Clients ### One surface The CLI, TUI, web app, desktop app and mobile app all talk to these same routes. This page is generated; /docs/server-api is written Read [Server & API](/docs/server-api) for how the server is built — the request pipeline, the auth layers, why some paths are raw handlers instead of typed endpoints. Read this section for the endpoints themselves. ## Base URL There is no hosted nikcli API: the server runs on your machine, or on a machine you control. Start one and the base URL is whatever it binds to. Terminal bash ``` # loopback, no password needed nikcli serve --hostname 127.0.0.1 --port 4096 # reachable from the network — set a password first NIKCLI_SERVER_PASSWORD=secret \ nikcli serve --hostname 0.0.0.0 --port 4096 ``` $ shell · paste into your terminal `Server.listen()` falls back to an ephemeral port rather than failing when the requested one is taken, so read the URL the command prints instead of assuming `4096`. The TUI's server is not an HTTP server Inside the terminal UI, `sdk.url` is the synthetic origin `http://nikcli.local` and requests are dispatched in process. Use `sdk.client.*` there; a hand-built `fetch()` against that host fails DNS resolution silently. ## Authentication Four credential types resolve to one principal before any route runs. Which one you use depends on how the server was started; all of them are accepted on every non-public route. | Scheme | Sent as | Used by | | --- | --- | --- | | `bearerAuth` | `Authorization: Bearer ` | Mobile pairing tokens and `nku_` account tokens. | | `auth_token` | `?token=` | The same tokens, for clients that cannot set headers — `EventSource`, mostly. | | `basicAuth` | Username and password | `NIKCLI_SERVER_PASSWORD`, with the username defaulting to `nikcli`. | | Tailscale identity | `Tailscale-User-Login` | Trusted only on a loopback listener with `NIKCLI_SERVER_TAILSCALE_AUTH` set. | Terminal bash ``` curl -s http://127.0.0.1:4096/session \ -H "Authorization: Bearer $NIKCLI_TOKEN" curl -s -u nikcli:$NIKCLI_SERVER_PASSWORD \ http://127.0.0.1:4096/session ``` $ shell · paste into your terminal The share routes — `/s/:shareID`, `/share/:shareID` and `/api/share/:shareID` — answer before the auth check, and `/user/login`, `/user/register` and `/user/status` are public so an account can be created in the first place. ## Choosing an instance One server hosts many project instances. Every endpoint below accepts `directory` and `workspace` query parameters that decide which project handles the request; the same values can travel as `x-nikcli-directory` and `x-nikcli-workspace` headers instead. Terminal bash ``` curl -s "http://127.0.0.1:4096/session?directory=/Users/me/project" \ -H "Authorization: Bearer $NIKCLI_TOKEN" curl -s http://127.0.0.1:4096/session \ -H "x-nikcli-directory: /Users/me/project" \ -H "Authorization: Bearer $NIKCLI_TOKEN" ``` $ shell · paste into your terminal With neither set, a `/session/:sessionID/…` path recovers the directory from the session itself, and everything else falls back to the server's working directory. The `/global`, `/user` and `/account` roots never bind a directory at all. Why those parameters appear on every operation Instance selection is transport middleware rather than endpoint input, so the generator adds `directory` and `workspace` to each operation when it writes the OpenAPI document. They are optional everywhere. ## Conventions - **JSON in, JSON out.** Request and response bodies are `application/json` unless an operation says otherwise. - **Operation ids are dotted.** `session.prompt`, `mobile.git.commit`, `experimental.workspace.warp`. They map to the namespaced methods on the [generated client](/docs/build/client) — `session.prompt` is `client.session.prompt` — with a handful renamed where the dotted id would collide. - **Errors are typed too.** A failure schema such as `ConfigUpdateError` or `ProviderAuthError` is declared on the endpoint and encoded in the response, rather than collapsing into a bare 500. - **Schema names ending in `_2` are not duplicates.** The OpenAPI emitter disambiguates same-named schemas declared by different groups; the shapes differ. ## Streaming The long-lived paths cannot round-trip through a response schema, so they are served as raw handlers ahead of the typed bridge — while still being declared in the API, which is why they appear in this reference at all. | Path | Shape | Carries | | --- | --- | --- | | `GET /event` | SSE | Every event for the resolved instance. | | `GET /global/event` | SSE | Every event across every instance the server hosts. | | `GET /sync/stream` | SSE | Sync events; the one `/sync/` path served instance-less. | | `GET /session/:id/v2/events` | SSE | Entry-level events for one session. | | `POST /session/:id/message` | Streamed body | Assistant output as it is produced. | | `GET /pty/:ptyID/connect` | WebSocket upgrade | Terminal input and output. | Terminal bash ``` curl -N "http://127.0.0.1:4096/event?token=$NIKCLI_TOKEN" ``` $ shell · paste into your terminal ## Clients `@nikcli-ai/sdk/httpapi` is generated from this same document, so every operation id below is a typed method on the client. Reach for it before hand-writing requests. @nikcli-ai/sdk/httpapi ts 1 2 3 4 5 6 7 8 9 10 ``` import { createNikcliClient } from "@nikcli-ai/sdk/httpapi" const client = createNikcliClient({ baseUrl: "http://127.0.0.1:4096", directory: "/Users/me/project", }) // calls resolve with { data, error } unless throwOnError is set const { data: sessions } = await client.session.list() const { data: session } = await client.session.create({ title: "from the SDK" }) ``` For code running inside the nikcli process — plugins, tools, the TUI — [the embedded SDK](/docs/build/sdk) binds the same client to the in-process server instead of a socket. ## Resources 349 operations, grouped the way the server declares them. The mobile surface is split across five pages because it is a third of the API on its own. ### Core [ 11 endpoints ### Core Instance lifecycle, resolved paths, version control status and apply, and the registries of commands, agents, skills, language servers and formatters. Open reference → ](/docs/api/core)[ 42 endpoints ### Sessions The session lifecycle: create, fork, revert, share and delete sessions, read messages and parts, inspect todos, diffs, context and goals, and drive background delegations and monitors. Open reference → ](/docs/api/session)[ 2 endpoints ### Prompting The two entry points that send a prompt to a session: the synchronous call that returns the assistant message, and the async call that returns immediately and streams over the event feed. Open reference → ](/docs/api/session-prompt)[ 2 endpoints ### Events Server-sent event feeds. One feed is scoped to the resolved instance, the other spans every instance the server hosts. Open reference → ](/docs/api/events)[ 7 endpoints ### Files & Search Reading and writing files in the resolved project, listing a directory, reading the working-tree status, and the three search endpoints behind text, filename and symbol lookup. Open reference → ](/docs/api/file)[ 7 endpoints ### Projects Project registry: the known projects, the one the current request resolved to, the directories inside it, and the project-copy lifecycle. Open reference → ](/docs/api/project)[ 13 endpoints ### Tools & Worktrees Experimental surface: the tool registry, the resource list, plain git worktrees, and the managed worktrees that carry parent/child links. Open reference → ](/docs/api/experimental)[ 11 endpoints ### Workspaces Workspace contexts — create, list, restore and remove them, read their status and event feed, and warp a session from one workspace into another. Open reference → ](/docs/api/workspace)[ 10 endpoints ### Configuration Read and patch the merged nikcli config, reload it from disk, resolve the provider table, and manage MCP server entries and config profiles. Open reference → ](/docs/api/config)[ 8 endpoints ### Providers & Auth Model providers and the credentials behind them: list providers and their auth state, set or remove an API key, and run the OAuth authorize/callback pair. Open reference → ](/docs/api/provider)[ 4 endpoints ### Connectors Connector status, per-connector credentials, and cache invalidation. Open reference → ](/docs/api/connectors)[ 9 endpoints ### MCP Model Context Protocol servers: status, adding a server, connecting and disconnecting it, toggling it, and the OAuth flow for servers that need one. Open reference → ](/docs/api/mcp)[ 3 endpoints ### Permissions Pending permission requests and the reply that approves or denies one. Open reference → ](/docs/api/permission)[ 3 endpoints ### Questions Questions an agent has asked the user, and the reply or rejection that unblocks it. Open reference → ](/docs/api/question)[ 14 endpoints ### Loops Loop definitions and their runs: list, upsert, generate from a description, toggle, run, pause, resume and abort, plus the run history. Open reference → ](/docs/api/loop)[ 13 endpoints ### Missions Mission definitions, their feature list, and the execution lifecycle — start, pause, cancel — along with recent executions. Open reference → ](/docs/api/mission)[ 2 endpoints ### Brain Background learning status and the manual trigger that forces a pass. Open reference → ](/docs/api/brain)[ 6 endpoints ### Profile The declared user profile and the habits the Brain learned, plus the preview of what actually reaches the system prompt. Open reference → ](/docs/api/profile)[ 6 endpoints ### Analytics Usage rollups: global and daily totals, per-session detail, the session list that backs the project breakdown, the leaderboard, and the combined data payload. Open reference → ](/docs/api/analytics)[ 9 endpoints ### Sync Event-sourced sync: push events, read the outbox and snapshots, stream changes, and manage the connection and drain. Open reference → ](/docs/api/sync)[ 6 endpoints ### Terminals Pseudo-terminal sessions — create, resize, remove, and the upgrade endpoint that attaches to one. Open reference → ](/docs/api/pty)[ 14 endpoints ### TUI Control The control channel a running terminal UI exposes: append or submit a prompt, open a dialog, execute a command, show a toast, and the request/response pair behind remote control. Open reference → ](/docs/api/tui)[ 3 endpoints ### Chatbots Registered chat bots and the start/stop control for each one. Open reference → ](/docs/api/chatbot)[ 4 endpoints ### Discord Discord integration status, first-time setup, and the start/stop control. Open reference → ](/docs/api/discord)[ 1 endpoints ### Voice Audio transcription for voice input. Open reference → ](/docs/api/voice)[ 3 endpoints ### Skills & Logs Creating and deleting skills, and the log sink clients write into. Open reference → ](/docs/api/app)[ 6 endpoints ### Accounts & Users The nikcli account behind a server (login and its completion step) and the local UserDB records the server owns. Open reference → ](/docs/api/account)[ 4 endpoints ### Sharing Public read endpoints for a shared session, in both the page and JSON forms. Open reference → ](/docs/api/share)[ 3 endpoints ### Health & Doctor Server health, global dispose, and the doctor report that checks the install end to end. Open reference → ](/docs/api/global) ### Mobile [ 33 endpoints ### Host & Bootstrap The mobile host surface: pairing tokens, the bootstrap payload the app opens with, projects and commands, memory, worktrees, and the host capability probes behind browser, computer, island, devtools and LAN. Open reference → ](/docs/api/mobile)[ 21 endpoints ### Sessions Session endpoints shaped for the mobile app: list and create, send a message, stream updates, answer permissions and questions, read diffs and todos, and teleport a session between hosts. Open reference → ](/docs/api/mobile-session)[ 27 endpoints ### Git & GitHub The git toolbar behind the mobile review panel — status, diff, commits, branches, stage, commit, push and pull — plus the GitHub side: repos, branches, imports, Actions runs and the device OAuth flow. Open reference → ](/docs/api/mobile-git)[ 36 endpoints ### Automation Loops, missions and routines as the mobile app drives them, including the tokenised routine trigger. Open reference → ](/docs/api/mobile-automation)[ 6 endpoints ### Terminals Pseudo-terminals for the mobile app, including the connect endpoint the terminal view attaches to. Open reference → ](/docs/api/mobile-pty) ## The OpenAPI document The document behind this reference is served from this site and checked into the repository at `packages/sdk/openapi.json`. Point a generator at it to build a client in any language. Terminal bash ``` curl -s https://nikcli-ai.dev/docs/api/openapi.json -o nikcli-openapi.json # or regenerate it from a checkout bun run script/generate.ts ``` $ shell · paste into your terminal [Download the OpenAPI document](/docs/api/openapi.json) · OpenAPI 3.1.0, 290 paths, 616 schemas. ## Related - [Server & API The request pipeline, auth layers and route groups behind these endpoints.](/docs/server-api) - [Sessions The concepts the session endpoints operate on.](/docs/sessions) - [Mobile How the mobile host and the paired app use the /mobile surface.](/docs/mobile) - [Packages & Suite Where the generated SDK clients live in the monorepo.](/docs/packages) --- Source: https://nikcli-ai.dev/docs/api