# Projects

Project registry: the known projects, the one the current request resolved to, the directories inside it, and the project-copy lifecycle.

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

7 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-project">/project</a></td><td class="api-index-id">project.list</td></tr><tr><td class="api-index-method"><span class="api-method api-method-get">get</span></td><td><a href="#op-get-project-current">/project/current</a></td><td class="api-index-id">project.current</td></tr><tr><td class="api-index-method"><span class="api-method api-method-patch">patch</span></td><td><a href="#op-patch-project-projectID">/project/{projectID}</a></td><td class="api-index-id">project.update</td></tr><tr><td class="api-index-method"><span class="api-method api-method-get">get</span></td><td><a href="#op-get-project-projectID-directory">/project/{projectID}/directory</a></td><td class="api-index-id">project.directory.list</td></tr><tr><td class="api-index-method"><span class="api-method api-method-post">post</span></td><td><a href="#op-post-project-projectID-copy">/project/{projectID}/copy</a></td><td class="api-index-id">project.copy.create</td></tr><tr><td class="api-index-method"><span class="api-method api-method-delete">delete</span></td><td><a href="#op-delete-project-projectID-copy">/project/{projectID}/copy</a></td><td class="api-index-id">project.copy.remove</td></tr><tr><td class="api-index-method"><span class="api-method api-method-post">post</span></td><td><a href="#op-post-project-projectID-copy-refresh">/project/{projectID}/copy/refresh</a></td><td class="api-index-id">project.copy.refresh</td></tr></tbody></table>

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

Parameters

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

Responses

200 Success application/json

({
  id: string
  worktree: string
  canonical: string
  vcs?: "git" | null
  name?: string | null
  icon?: 
    | {
    url?: string | null
    override?: string | null
    color?: string | null
  }
    | null
  commands?: 
    | {
    start?: string | null
  }
    | null
  time: {
    created: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
    updated: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
    initialized?: 
      | 
      | number
      | "Infinity" | "-Infinity" | "NaN"
      | null
  }
  sandboxes: string\[\]
})\[\]

Example response from schema

\[
  {
    "id": "",
    "worktree": "",
    "canonical": "",
    "vcs": "git",
    "name": "",
    "icon": {
      "url": "",
      "override": "",
      "color": ""
    },
    "commands": {
      "start": ""
    },
    "time": {
      "created": 0,
      "updated": 0,
      "initialized": 0
    },
    "sandboxes": \[
      ""
    \]
  }
\]

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

SDK example

project.list

ts 

1

2

3

4

5

6

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

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

Try it

directory _query_  workspace _query_

---

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