Documentation

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.

Playground

Send these requests to your own running server. Values stay in this browser.

Not connected

Base URL Directory optional Bearer token optional

How this works

Start a server with nikcli serve --hostname 127.0.0.1 --port 4096. Requests go straight from this page to that address — the browser allows it because loopback counts as a secure origin, and the server allows it because nikcli-ai.dev is in its CORS allowlist.

To try things without touching your real sessions or config, start the server with NIKCLI_TEST_HOME pointed at a throwaway directory — see the guided tour.

Operations

2 endpoints, generated from the server's own OpenAPI document. Every path also accepts the directory and workspace query parameters that select which instance handles the request.

post	/session/{sessionID}/message	session.prompt
post	/session/{sessionID}/prompt_async	session.prompt_async

post /session/{sessionID}/message # session.prompt

Parameters

Name	In	Type	Required
sessionID	path	string	required
directory	query	string	optional
workspace	query	string	optional

Request body · required · application/json

{
  messageID?: string
  delivery?: "steer" | "queue"
  model?: {
    providerID: string
    modelID: string
  }
  agent?: string
  noReply?: boolean
  tools?: {
    [key: string]: boolean
  }
  format?: OutputFormat_1
  system?: string
  variant?: string
  parts: PromptPartInput[]
}

Responses

200 SessionPromptResponse application/json

{
  info: Message_1
  parts: Part_1[]
}

Example response from schema

{
  "info": {
    "id": "",
    "sessionID": "",
    "role": "user",
    "time": {
      "created": 0
    },
    "format": {
      "type": "text"
    },
    "summary": {
      "title": "",
      "body": "",
      "diffs": []
    },
    "agent": "",
    "model": {
      "providerID": "",
      "modelID": ""
    },
    "system": "",
    "tools": {},
    "variant": ""
  },
  "parts": [
    {
      "id": "",
      "sessionID": "",
      "messageID": "",
      "type": "text",
      "text": "",
      "synthetic": false,
      "ignored": false,
      "time": {
        "start": null,
        "end": null
      },
      "metadata": {}
    }
  ]
}

Generated from the response schema — field values are placeholders, the shape is real.

SDK example

session.prompt

import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.session.prompt({
  ...
})

Try it

sessionID path · required directory query workspace query

Request body application/json

post /session/{sessionID}/prompt_async # session.prompt_async

Parameters

Name	In	Type	Required
sessionID	path	string	required
directory	query	string	optional
workspace	query	string	optional

Request body · required · application/json

{
  messageID?: string
  delivery?: "steer" | "queue"
  model?: {
    providerID: string
    modelID: string
  }
  agent?: string
  noReply?: boolean
  tools?: {
    [key: string]: boolean
  }
  format?: OutputFormat_1
  system?: string
  variant?: string
  parts: PromptPartInput[]
}

Responses

204 <No Content>

SDK example

session.prompt_async

import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.session.prompt_async({
  ...
})

Try it

sessionID path · required directory query workspace query

Request body application/json

Schemas

The 46 schemas reachable from these endpoints. Each is shown one level deep; nested types link to their own entry below. Names ending in _2, _3 and so on are the OpenAPI emitter disambiguating same-named schemas declared by different HttpApi groups — they are distinct shapes, not duplicates.

AgentPart_1

{
  id: string
  sessionID: string
  messageID: string
  type: "agent"
  name: string
  source?: {
    value: string
    start: number
    end: number
  }
}

AgentPartInput_1

{
  type: "agent"
  name: string
  source?: {
    value: string
    start: number
    end: number
  }
  id?: string | null
}

APIError_2

{
  name: "APIError"
  data: {
    message: string
    statusCode?: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
    isRetryable: boolean
    responseHeaders?: {
      [key: string]: string
    }
    responseBody?: string
    metadata?: {
      [key: string]: string
    }
    classification?: "payload-too-large"
  }
}

AssistantMessage_1

{
  id: string
  sessionID: string
  role: "assistant"
  time: {
    created: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
    completed?: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
  }
  error?: 
    | ProviderAuthError_1
    | UnknownError_1
    | MessageOutputLengthError_1
    | MessageContextOverflowError_1
    | MessageAbortedError_1
    | StructuredOutputError_1
    | APIError_2
  parentID: string
  modelID: string
  providerID: string
  mode: string
  agent: string
  path: {
    cwd: string
    root: string
  }
  summary?: boolean
  cost: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
  tokens: {
    total?: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
    input: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
    output: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
    reasoning: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
    cache: {
      read: 
        | number
        | "Infinity" | "-Infinity" | "NaN"
      write: 
        | number
        | "Infinity" | "-Infinity" | "NaN"
    }
  }
  structured?: unknown
  finish?: string
}

CompactionPart_1

{
  id: string
  sessionID: string
  messageID: string
  type: "compaction"
  auto: boolean
}

FileDiff_2

{
  file: string
  patch: string
  additions: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
  deletions: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
  status?: 
    | "added" | "deleted" | "modified"
    | null
  before: string
  after: string
}

FilePart_2

{
  id: string
  sessionID: string
  messageID: string
  type: "file"
  mime: string
  filename?: string
  url: string
  source?: FilePartSource_2
}

FilePartInput_1

{
  type: "file"
  mime: string
  filename?: string
  url: string
  source?: FilePartSource_2
  id?: string | null
}

FilePartSource_2

FileSource_2 | SymbolSource_2 | ResourceSource_2

FilePartSourceText_6

{
  value: string
  start: number
  end: number
}

FileSource_2

{
  text: FilePartSourceText_6
  type: "file"
  path: string
}

JSONSchema_1

{ [key: string]: unknown }

Message_1

UserMessage_1 | AssistantMessage_1

MessageAbortedError_1

{
  name: "MessageAbortedError"
  data: {
    message: string
  }
}

MessageContextOverflowError_1

{
  name: "MessageContextOverflowError"
  data: {
    message: string
    statusCode?: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
    responseBody?: string
  }
}

MessageOutputLengthError_1

{
  name: "MessageOutputLengthError"
  data: { [key: string]: unknown } | unknown[]
}

OutputFormat_1

OutputFormatText_1 | OutputFormatJsonSchema_1

OutputFormatJsonSchema_1

{
  type: "json_schema"
  schema: JSONSchema_1
  retryCount: number
}

OutputFormatText_1

{
  type: "text"
}

Part_1

  | TextPart_1
  | SubtaskPart_1
  | ReasoningPart_1
  | FilePart_2
  | ToolPart_1
  | StepStartPart_1
  | StepFinishPart_1
  | SnapshotPart_1
  | PatchPart_1
  | AgentPart_1
  | RetryPart_1
  | CompactionPart_1

PatchPart_1

{
  id: string
  sessionID: string
  messageID: string
  type: "patch"
  hash: string
  files: string[]
}

PromptPartInput

  | TextPartInput_1
  | FilePartInput_1
  | AgentPartInput_1
  | SubtaskPartInput_1

ProviderAuthError_1

{
  name: "ProviderAuthError"
  data: {
    providerID: string
    message: string
  }
}

Range_2

{
  start: {
    line: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
    character: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
  }
  end: {
    line: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
    character: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
  }
}

ReasoningPart_1

{
  id: string
  sessionID: string
  messageID: string
  type: "reasoning"
  text: string
  metadata?: { [key: string]: unknown }
  time: {
    start: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
    end?: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
  }
}

ResourceSource_2

{
  text: FilePartSourceText_6
  type: "resource"
  clientName: string
  uri: string
}

RetryPart_1

{
  id: string
  sessionID: string
  messageID: string
  type: "retry"
  attempt: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
  error: APIError_2
  time: {
    created: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
  }
}

SessionPromptInput

{
  messageID?: string
  delivery?: "steer" | "queue"
  model?: {
    providerID: string
    modelID: string
  }
  agent?: string
  noReply?: boolean
  tools?: {
    [key: string]: boolean
  }
  format?: OutputFormat_1
  system?: string
  variant?: string
  parts: PromptPartInput[]
}

SessionPromptResponse

{
  info: Message_1
  parts: Part_1[]
}

SnapshotPart_1

{
  id: string
  sessionID: string
  messageID: string
  type: "snapshot"
  snapshot: string
}

StepFinishPart_1

{
  id: string
  sessionID: string
  messageID: string
  type: "step-finish"
  reason: string
  snapshot?: string
  cost: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
  tokens: {
    total?: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
    input: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
    output: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
    reasoning: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
    cache: {
      read: 
        | number
        | "Infinity" | "-Infinity" | "NaN"
      write: 
        | number
        | "Infinity" | "-Infinity" | "NaN"
    }
  }
}

StepStartPart_1

{
  id: string
  sessionID: string
  messageID: string
  type: "step-start"
  snapshot?: string
}

StructuredOutputError_1

{
  name: "StructuredOutputError"
  data: {
    message: string
    retries: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
  }
}

SubtaskPart_1

{
  id: string
  sessionID: string
  messageID: string
  type: "subtask"
  prompt: string
  description: string
  agent: string
  model?: {
    providerID: string
    modelID: string
  }
  command?: string
  background?: boolean
}

SubtaskPartInput_1

{
  type: "subtask"
  prompt: string
  description: string
  agent: string
  model?: {
    providerID: string
    modelID: string
  }
  command?: string
  background?: boolean
  id?: string | null
}

SymbolSource_2

{
  text: FilePartSourceText_6
  type: "symbol"
  path: string
  range: Range_2
  name: string
  kind: number
}

TextPart_1

{
  id: string
  sessionID: string
  messageID: string
  type: "text"
  text: string
  synthetic?: boolean
  ignored?: boolean
  time?: {
    start: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
    end?: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
  }
  metadata?: { [key: string]: unknown }
}

TextPartInput_1

{
  type: "text"
  text: string
  synthetic?: boolean
  ignored?: boolean
  time?: {
    start: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
    end?: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
  }
  metadata?: { [key: string]: unknown }
  id?: string | null
}

ToolPart_1

{
  id: string
  sessionID: string
  messageID: string
  type: "tool"
  callID: string
  tool: string
  state: ToolState_1
  metadata?: { [key: string]: unknown }
}

ToolState_1

  | ToolStatePending_1
  | ToolStateRunning_1
  | ToolStateCompleted_1
  | ToolStateError_1

ToolStateCompleted_1

{
  status: "completed"
  input: { [key: string]: unknown }
  output: string
  title: string
  metadata: { [key: string]: unknown }
  time: {
    start: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
    end: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
    compacted?: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
  }
  attachments?: FilePart_2[]
}

ToolStateError_1

{
  status: "error"
  input: { [key: string]: unknown }
  error: string
  metadata?: { [key: string]: unknown }
  time: {
    start: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
    end: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
  }
}

ToolStatePending_1

{
  status: "pending"
  input: { [key: string]: unknown }
  raw: string
}

ToolStateRunning_1

{
  status: "running"
  input: { [key: string]: unknown }
  title?: string
  metadata?: { [key: string]: unknown }
  structured?: { [key: string]: unknown }
  content?: (
    | {
    type: "text"
    text: string
  }
    | {
    type: "file"
    data: string
    mime: string
    name?: string
  })[]
  time: {
    start: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
  }
}

UnknownError_1

{
  name: "UnknownError"
  data: {
    message: string
  }
}

UserMessage_1

{
  id: string
  sessionID: string
  role: "user"
  time: {
    created: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
  }
  format?: OutputFormat_1
  summary?: {
    title?: string
    body?: string
    diffs: FileDiff_2[]
  }
  agent: string
  model: {
    providerID: string
    modelID: string
  }
  system?: string
  tools?: {
    [key: string]: boolean
  }
  variant?: string
}