Documentation

Workspaces

Workspace contexts — create, list, restore and remove them, read their status and event feed, and warp a session from one workspace into another.

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

11 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.

get	/experimental/workspace/adaptor	experimental.workspace.adaptor.list
post	/experimental/workspace/sync-list	experimental.workspace.syncList
get	/experimental/workspace/status	experimental.workspace.status
post	/experimental/workspace/{id}	experimental.workspace.create
delete	/experimental/workspace/{id}	experimental.workspace.remove
get	/experimental/workspace	experimental.workspace.list
post	/experimental/workspace/{id}/restore	experimental.workspace.restore
post	/experimental/workspace/{id}/session/{sessionID}/restore	experimental.workspace.session.restore
post	/experimental/workspace/warp	experimental.workspace.warp
get	/experimental/workspace/{id}/events	experimental.workspace.events
post	/experimental/workspace/session/{sessionID}/warp	experimental.workspace.session.warp

get /experimental/workspace/adaptor # experimental.workspace.adaptor.list

Parameters

Name	In	Type	Required
directory	query	string	optional
workspace	query	string	optional

Responses

200 Success application/json

({
  type: string
  name: string
  description: string
  available?: boolean | null
})[]

Example response from schema

[
  {
    "type": "",
    "name": "",
    "description": "",
    "available": false
  }
]

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

SDK example

experimental.workspace.adaptor.list

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

const client = createNikcliClient()
await client.experimental.workspace.adaptor.list({
  ...
})

Try it

directory query workspace query

post /experimental/workspace/sync-list # experimental.workspace.syncList

Parameters

Name	In	Type	Required
directory	query	string	optional
workspace	query	string	optional

Responses

204 <No Content>

SDK example

experimental.workspace.syncList

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

const client = createNikcliClient()
await client.experimental.workspace.syncList({
  ...
})

Try it

directory query workspace query

get /experimental/workspace/status # experimental.workspace.status

Parameters

Name	In	Type	Required
directory	query	string	optional
workspace	query	string	optional

Responses

200 Success application/json

({
  workspaceID: string
  status: 
    | "connected"
    | "connecting"
    | "disconnected"
    | "error"
})[]

Example response from schema

[
  {
    "workspaceID": "",
    "status": "connected"
  }
]

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

SDK example

experimental.workspace.status

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

const client = createNikcliClient()
await client.experimental.workspace.status({
  ...
})

Try it

directory query workspace query

post /experimental/workspace/{id} # experimental.workspace.create

Parameters

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

Request body · required · application/json

{
  branch: string | null
  config: WorkspaceConfig
}

Responses

200 Workspace application/json

{
  id: string
  name: string
  timeUsed: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
  branch: string | null
  projectID: string
  config: WorkspaceConfig
}

Example response from schema

{
  "id": "",
  "name": "",
  "timeUsed": 0,
  "branch": "",
  "projectID": "",
  "config": {
    "type": "worktree",
    "directory": "",
    "strategy": "git",
    "eventLimit": 0
  }
}

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

SDK example

experimental.workspace.create

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

const client = createNikcliClient()
await client.experimental.workspace.create({
  ...
})

Try it

id path · required directory query workspace query

Request body application/json

delete /experimental/workspace/{id} # experimental.workspace.remove

Parameters

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

Responses

200 OptionalWorkspace application/json

Workspace_1 | null

Example response from schema

{
  "id": "",
  "name": "",
  "timeUsed": 0,
  "branch": "",
  "projectID": "",
  "config": {
    "type": "worktree",
    "directory": "",
    "strategy": "git",
    "eventLimit": 0
  }
}

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

SDK example

experimental.workspace.remove

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

const client = createNikcliClient()
await client.experimental.workspace.remove({
  ...
})

Try it

id path · required directory query workspace query

This changes or removes server state, against whatever base URL is set above.

get /experimental/workspace # experimental.workspace.list

Parameters

Name	In	Type	Required
directory	query	string	optional
workspace	query	string	optional

Responses

200 Success application/json

({
  id: string
  name: string
  timeUsed: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
  branch: string | null
  projectID: string
  config: WorkspaceConfig
})[]

Example response captured

[]

SDK example

experimental.workspace.list

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

const client = createNikcliClient()
await client.experimental.workspace.list({
  ...
})

Try it

directory query workspace query

post /experimental/workspace/{id}/restore # experimental.workspace.restore

Parameters

Name	In	Type	Required
id	path	string	required
timeoutMs	query	string \| null	optional
directory	query	string	optional
workspace	query	string	optional

Responses

200 WorkspaceRestore application/json

{
  workspaceID: string
  sessions: string[]
  events: unknown[]
}

Example response from schema

{
  "workspaceID": "",
  "sessions": [
    ""
  ],
  "events": []
}

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

SDK example

experimental.workspace.restore

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

const client = createNikcliClient()
await client.experimental.workspace.restore({
  ...
})

Try it

id path · required timeoutMs query directory query workspace query

post /experimental/workspace/{id}/session/{sessionID}/restore # experimental.workspace.session.restore

Parameters

Name	In	Type	Required
id	path	string	required
sessionID	path	string	required
timeoutMs	query	string \| null	optional
directory	query	string	optional
workspace	query	string	optional

Responses

200 WorkspaceSessionRestore application/json

{
  workspaceID: string
  sessionID: string
  sessions: string[]
  events: unknown[]
}

Example response from schema

{
  "workspaceID": "",
  "sessionID": "",
  "sessions": [
    ""
  ],
  "events": []
}

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

SDK example

experimental.workspace.session.restore

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

const client = createNikcliClient()
await client.experimental.workspace.session.restore({
  ...
})

Try it

id path · required sessionID path · required timeoutMs query directory query workspace query

post /experimental/workspace/warp # experimental.workspace.warp

Parameters

Name	In	Type	Required
directory	query	string	optional
workspace	query	string	optional

Request body · required · application/json

{
  id: string | null
  sessionID: string
  copyChanges?: boolean | null
  timeoutMs?: 
    | 
    | number
    | "Infinity" | "-Infinity" | "NaN"
    | null
}

Responses

204 <No Content>

SDK example

experimental.workspace.warp

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

const client = createNikcliClient()
await client.experimental.workspace.warp({
  ...
})

Try it

directory query workspace query

Request body application/json

get /experimental/workspace/{id}/events # experimental.workspace.events

Parameters

Name	In	Type	Required
id	path	string	required
from	query	string \| null	optional
directory	query	string	optional
workspace	query	string	optional

Responses

200 Success application/json

unknown[]

Example response from schema

[]

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

SDK example

experimental.workspace.events

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

const client = createNikcliClient()
await client.experimental.workspace.events({
  ...
})

Try it

id path · required from query directory query workspace query

post /experimental/workspace/session/{sessionID}/warp # experimental.workspace.session.warp

Parameters

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

Request body · required · application/json

{
  workspaceID: string | null
  copyChanges?: boolean | null
  timeoutMs?: 
    | 
    | number
    | "Infinity" | "-Infinity" | "NaN"
    | null
}

Responses

200 WorkspaceSessionWarpResponse application/json

{
  sessionID: string
  workspaceID: string | null
}

Example response from schema

{
  "sessionID": "",
  "workspaceID": ""
}

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

SDK example

experimental.workspace.session.warp

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

const client = createNikcliClient()
await client.experimental.workspace.session.warp({
  ...
})

Try it

sessionID path · required directory query workspace query

Request body application/json

Schemas

The 12 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.

OptionalWorkspace

Workspace_1 | null

Workspace_1

{
  id: string
  name: string
  timeUsed: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
  branch: string | null
  projectID: string
  config: WorkspaceConfig
}

WorkspaceAdaptorInfo

{
  type: string
  name: string
  description: string
  available?: boolean | null
}

WorkspaceConfig

  | {
  type: "worktree"
  directory: string
  strategy?: "git" | "cow" | null
  eventLimit?: 
    | 
    | number
    | "Infinity" | "-Infinity" | "NaN"
    | null
}
  | {
  type: "container"
  directory: string
  runtime: "docker" | "podman"
  image: string
  containerName: string
  port: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
  serverUrl: string
  eventLimit?: 
    | 
    | number
    | "Infinity" | "-Infinity" | "NaN"
    | null
}
  | {
  type: "branch"
  directory: string
  branch?: string | null
  eventLimit?: 
    | 
    | number
    | "Infinity" | "-Infinity" | "NaN"
    | null
}

WorkspaceConnectionStatus

{
  workspaceID: string
  status: 
    | "connected"
    | "connecting"
    | "disconnected"
    | "error"
}

WorkspaceCreateInput

{
  branch: string | null
  config: WorkspaceConfig
}

WorkspaceJournalEventEncoded

unknown

WorkspaceRestore

{
  workspaceID: string
  sessions: string[]
  events: unknown[]
}

WorkspaceSessionRestore

{
  workspaceID: string
  sessionID: string
  sessions: string[]
  events: unknown[]
}

WorkspaceSessionWarpInput

{
  workspaceID: string | null
  copyChanges?: boolean | null
  timeoutMs?: 
    | 
    | number
    | "Infinity" | "-Infinity" | "NaN"
    | null
}

WorkspaceSessionWarpResponse

{
  sessionID: string
  workspaceID: string | null
}

WorkspaceWarpInput

{
  id: string | null
  sessionID: string
  copyChanges?: boolean | null
  timeoutMs?: 
    | 
    | number
    | "Infinity" | "-Infinity" | "NaN"
    | null
}