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

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](/docs/guides/api-tour).

## Operations

42 endpoints, generated from the server's own [OpenAPI document](/docs/api). Every path also accepts the `directory` and `workspace` query parameters that select which instance handles the request.

<table class="api-index not-prose"><tbody><tr><td class="api-index-method"><span class="api-method api-method-get">get</span></td><td><a href="#op-get-session">/session</a></td><td class="api-index-id">session.list</td></tr><tr><td class="api-index-method"><span class="api-method api-method-post">post</span></td><td><a href="#op-post-session">/session</a></td><td class="api-index-id">session.create</td></tr><tr><td class="api-index-method"><span class="api-method api-method-get">get</span></td><td><a href="#op-get-session-status">/session/status</a></td><td class="api-index-id">session.status</td></tr><tr><td class="api-index-method"><span class="api-method api-method-get">get</span></td><td><a href="#op-get-session-sessionID">/session/{sessionID}</a></td><td class="api-index-id">session.get</td></tr><tr><td class="api-index-method"><span class="api-method api-method-patch">patch</span></td><td><a href="#op-patch-session-sessionID">/session/{sessionID}</a></td><td class="api-index-id">session.update</td></tr><tr><td class="api-index-method"><span class="api-method api-method-delete">delete</span></td><td><a href="#op-delete-session-sessionID">/session/{sessionID}</a></td><td class="api-index-id">session.delete</td></tr><tr><td class="api-index-method"><span class="api-method api-method-post">post</span></td><td><a href="#op-post-session-sessionID-fork">/session/{sessionID}/fork</a></td><td class="api-index-id">session.fork</td></tr><tr><td class="api-index-method"><span class="api-method api-method-post">post</span></td><td><a href="#op-post-session-sessionID-abort">/session/{sessionID}/abort</a></td><td class="api-index-id">session.abort</td></tr><tr><td class="api-index-method"><span class="api-method api-method-post">post</span></td><td><a href="#op-post-session-sessionID-revert">/session/{sessionID}/revert</a></td><td class="api-index-id">session.revert</td></tr><tr><td class="api-index-method"><span class="api-method api-method-post">post</span></td><td><a href="#op-post-session-sessionID-unrevert">/session/{sessionID}/unrevert</a></td><td class="api-index-id">session.unrevert</td></tr><tr><td class="api-index-method"><span class="api-method api-method-post">post</span></td><td><a href="#op-post-session-sessionID-share">/session/{sessionID}/share</a></td><td class="api-index-id">session.share</td></tr><tr><td class="api-index-method"><span class="api-method api-method-delete">delete</span></td><td><a href="#op-delete-session-sessionID-share">/session/{sessionID}/share</a></td><td class="api-index-id">session.unshare</td></tr><tr><td class="api-index-method"><span class="api-method api-method-post">post</span></td><td><a href="#op-post-session-sessionID-summarize">/session/{sessionID}/summarize</a></td><td class="api-index-id">session.summarize</td></tr><tr><td class="api-index-method"><span class="api-method api-method-post">post</span></td><td><a href="#op-post-session-sessionID-generate">/session/{sessionID}/generate</a></td><td class="api-index-id">session.generate</td></tr><tr><td class="api-index-method"><span class="api-method api-method-post">post</span></td><td><a href="#op-post-session-sessionID-command">/session/{sessionID}/command</a></td><td class="api-index-id">session.command</td></tr><tr><td class="api-index-method"><span class="api-method api-method-post">post</span></td><td><a href="#op-post-session-sessionID-shell">/session/{sessionID}/shell</a></td><td class="api-index-id">session.shell</td></tr><tr><td class="api-index-method"><span class="api-method api-method-post">post</span></td><td><a href="#op-post-session-sessionID-permissions-permissionID">/session/{sessionID}/permissions/{permissionID}</a></td><td class="api-index-id">permission.respond</td></tr><tr><td class="api-index-method"><span class="api-method api-method-get">get</span></td><td><a href="#op-get-session-sessionID-children">/session/{sessionID}/children</a></td><td class="api-index-id">session.children</td></tr><tr><td class="api-index-method"><span class="api-method api-method-get">get</span></td><td><a href="#op-get-session-sessionID-todo">/session/{sessionID}/todo</a></td><td class="api-index-id">session.todo</td></tr><tr><td class="api-index-method"><span class="api-method api-method-get">get</span></td><td><a href="#op-get-session-sessionID-diff">/session/{sessionID}/diff</a></td><td class="api-index-id">session.diff</td></tr><tr><td class="api-index-method"><span class="api-method api-method-get">get</span></td><td><a href="#op-get-session-sessionID-message">/session/{sessionID}/message</a></td><td class="api-index-id">session.messages</td></tr><tr><td class="api-index-method"><span class="api-method api-method-get">get</span></td><td><a href="#op-get-session-sessionID-pending">/session/{sessionID}/pending</a></td><td class="api-index-id">session.pending</td></tr><tr><td class="api-index-method"><span class="api-method api-method-post">post</span></td><td><a href="#op-post-session-sessionID-pending-pendingID-steer">/session/{sessionID}/pending/{pendingID}/steer</a></td><td class="api-index-id">session.pendingSteer</td></tr><tr><td class="api-index-method"><span class="api-method api-method-get">get</span></td><td><a href="#op-get-session-sessionID-message-messageID">/session/{sessionID}/message/{messageID}</a></td><td class="api-index-id">session.message</td></tr><tr><td class="api-index-method"><span class="api-method api-method-delete">delete</span></td><td><a href="#op-delete-session-sessionID-message-messageID">/session/{sessionID}/message/{messageID}</a></td><td class="api-index-id">session.messageRemove</td></tr><tr><td class="api-index-method"><span class="api-method api-method-patch">patch</span></td><td><a href="#op-patch-session-sessionID-message-messageID-part-partID">/session/{sessionID}/message/{messageID}/part/{partID}</a></td><td class="api-index-id">part.update</td></tr><tr><td class="api-index-method"><span class="api-method api-method-delete">delete</span></td><td><a href="#op-delete-session-sessionID-message-messageID-part-partID">/session/{sessionID}/message/{messageID}/part/{partID}</a></td><td class="api-index-id">part.delete</td></tr><tr><td class="api-index-method"><span class="api-method api-method-get">get</span></td><td><a href="#op-get-session-sessionID-v2-entries">/session/{sessionID}/v2/entries</a></td><td class="api-index-id">session.v2.entries</td></tr><tr><td class="api-index-method"><span class="api-method api-method-get">get</span></td><td><a href="#op-get-session-sessionID-v2-state">/session/{sessionID}/v2/state</a></td><td class="api-index-id">session.v2.state</td></tr><tr><td class="api-index-method"><span class="api-method api-method-get">get</span></td><td><a href="#op-get-session-sessionID-v2-events">/session/{sessionID}/v2/events</a></td><td class="api-index-id">session.v2.events</td></tr><tr><td class="api-index-method"><span class="api-method api-method-get">get</span></td><td><a href="#op-get-session-sessionID-instructions">/session/{sessionID}/instructions</a></td><td class="api-index-id">session.instructions</td></tr><tr><td class="api-index-method"><span class="api-method api-method-get">get</span></td><td><a href="#op-get-session-sessionID-context">/session/{sessionID}/context</a></td><td class="api-index-id">session.context</td></tr><tr><td class="api-index-method"><span class="api-method api-method-post">post</span></td><td><a href="#op-post-session-sessionID-context-toggle">/session/{sessionID}/context/toggle</a></td><td class="api-index-id">session.contextToggle</td></tr><tr><td class="api-index-method"><span class="api-method api-method-get">get</span></td><td><a href="#op-get-session-sessionID-goal">/session/{sessionID}/goal</a></td><td class="api-index-id">session.goal</td></tr><tr><td class="api-index-method"><span class="api-method api-method-get">get</span></td><td><a href="#op-get-session-sessionID-background">/session/{sessionID}/background</a></td><td class="api-index-id">session.background</td></tr><tr><td class="api-index-method"><span class="api-method api-method-get">get</span></td><td><a href="#op-get-session-sessionID-background-delegationID">/session/{sessionID}/background/{delegationID}</a></td><td class="api-index-id">session.background.inspect</td></tr><tr><td class="api-index-method"><span class="api-method api-method-get">get</span></td><td><a href="#op-get-session-sessionID-background-delegationID-read">/session/{sessionID}/background/{delegationID}/read</a></td><td class="api-index-id">session.background.read</td></tr><tr><td class="api-index-method"><span class="api-method api-method-post">post</span></td><td><a href="#op-post-session-sessionID-background-delegationID-cancel">/session/{sessionID}/background/{delegationID}/cancel</a></td><td class="api-index-id">session.background.cancel</td></tr><tr><td class="api-index-method"><span class="api-method api-method-post">post</span></td><td><a href="#op-post-session-sessionID-background-delegationID-resume">/session/{sessionID}/background/{delegationID}/resume</a></td><td class="api-index-id">session.background.resume</td></tr><tr><td class="api-index-method"><span class="api-method api-method-get">get</span></td><td><a href="#op-get-session-sessionID-monitor-monitorID">/session/{sessionID}/monitor/{monitorID}</a></td><td class="api-index-id">session.monitor</td></tr><tr><td class="api-index-method"><span class="api-method api-method-get">get</span></td><td><a href="#op-get-session-sessionID-monitor-monitorID-log">/session/{sessionID}/monitor/{monitorID}/log</a></td><td class="api-index-id">session.monitorLog</td></tr><tr><td class="api-index-method"><span class="api-method api-method-post">post</span></td><td><a href="#op-post-session-sessionID-monitor-monitorID-cancel">/session/{sessionID}/monitor/{monitorID}/cancel</a></td><td class="api-index-id">session.monitorCancel</td></tr></tbody></table>

### Session

get /session [#](#op-get-session) `session.list`

Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| directory | query | string | optional |
| roots | query | string | optional |
| start | query | string | optional |
| search | query | string | optional |
| limit | query | string | optional |
| workspace | query | string | optional |

Responses

200 SessionList application/json

[Session\_2](#schema-Session_2)\[\]

Example response captured

```
[]
```

SDK example

session.list

ts 

1

2

3

4

5

6

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

const client = createNikcliClient()
await client.session.list({
  ...
})
```

Try it

directory _query_  roots _query_  start _query_  search _query_  limit _query_  workspace _query_

---

Source: https://nikcli-ai.dev/docs/api/session