REST API

Web UI 做的每一件事都走同一套 REST API，你自己的代码只需要一个 Service Token 就能用同一套。CI 里开一个 workspace、脚本批量导 prompt、本地 agent 把长任务甩给云端的——都是这一个面。

交互式参考在你自己的实例上

你自己那套 NAP 就在 serve 它：

https://<你的 NAP 域名>/api/docs

登录状态下 ⌘K → API 文档 直接过去。机器可读的文档在旁边：/api/docs/openapi.json。

这里没有镜像一份，是有意的：你的实例吐出来的那份是从你真正在跑的那个 control plane 生成的，版本和你手里的对得上，而不是和我们的对得上。

认证

在 UI 里建 token —— ⌘K → Service Tokens（路由 /integration/tokens）→ 创建。token 只显示一次，当场复制。

每个请求都带上它：

Authorization: Bearer <token>

Base URL 与约定

路径都相对于你的域名，所以列 workspace 是 GET $NAP_BASE_URL/api/workspaces。

有一条约定值得先知道，否则一定会踩：带路径的 query 参数要整体 URL-encode。整个值一起编码，里面的斜杠是字面量不是分隔符。原样传中文或带斜杠的值，要么 400，要么路由到别处去。

最常用的那一个调用

对 service token 来说，故意没有 exec 端点。活儿是以 prompt 的形式交给 agent 的，而 agent 背后是它的全套工具——bash、改文件，和它在 UI 里能用的一样：

BASE="${NAP_BASE_URL:?}"
NAP_WS="<workspace-id>"

# 发起一轮。async 立刻返回 202 和一个 session id。
SID=$(curl -s -X POST "$BASE/api/workspaces/$NAP_WS/chat" \
  -H "Authorization: Bearer $NAP_TOKEN" -H "Content-Type: application/json" \
  -d '{"message":"列一下仓库里的文件，总结 README","mode":"async","source":"api"}' \
  | jq -r .session_id)

# 然后轮询这个 session 直到 agent 跑完，再读对话记录。

也可以流式返回，想盯着它干活而不是等结果的话。

不在你第一直觉那个位置的几件事：

你想	去哪
让 agent 干活——跑任务、改文件、回答它做过什么	POST /api/workspaces/{id}/chat
读写、列 workspace 里的文件	agent-files 资源
访问共享的 /mnt/afs 卷	agent-afs-files 资源——是另一个挂载点
建 workspace 并配置它	POST /api/workspaces，然后 PUT /api/workspaces/{id}/config
批量管 prompt / 模板 / skill	prompts、templates、skills 资源

接下来

与其自己读操作列表，不如把它交给 agent：nap-api skill 就是从同一份 spec 生成的，本地 agent 靠它来驱动 NAP。