nap-api

Files (200)

• SKILL.md
• app-spec.md · references/
• authentication.md · references/
• delete-api-credentials-name.md · references/operations/
• delete-api-environments-id-tokens-tokenId.md · references/operations/
• delete-api-environments-id.md · references/operations/
• delete-api-memory-stores-storeId.md · references/operations/
• delete-api-prompts-id.md · references/operations/
• delete-api-providers-id.md · references/operations/
• delete-api-shares-id.md · references/operations/
• delete-api-skills-id-exports-token.md · references/operations/
• delete-api-skills-id.md · references/operations/
• delete-api-skills-sources-id-draft-file.md · references/operations/
• delete-api-skills-sources-id-draft.md · references/operations/
• delete-api-skills-sources-id.md · references/operations/
• delete-api-tags-id.md · references/operations/
• delete-api-teams-id-invites-token.md · references/operations/
• delete-api-teams-id-members-userId.md · references/operations/
• delete-api-teams-id.md · references/operations/
• delete-api-templates-id.md · references/operations/
• delete-api-workspaces-id-afs-shares-shareId-members-memberWorkspaceId.md · references/operations/
• delete-api-workspaces-id-afs-shares-shareId.md · references/operations/
• delete-api-workspaces-id-agent-afs-files.md · references/operations/
• delete-api-workspaces-id-agent-export-tokens-token.md · references/operations/
• delete-api-workspaces-id-agent-files.md · references/operations/
• delete-api-workspaces-id-commands-cmdId.md · references/operations/
• delete-api-workspaces-id-schedules-scheduleId.md · references/operations/
• delete-api-workspaces-id-sessions-sessionId-pending.md · references/operations/
• delete-api-workspaces-id-sessions-sessionId.md · references/operations/
• delete-api-workspaces-id-team-shares-teamId.md · references/operations/
• delete-api-workspaces-id-transfer.md · references/operations/
• delete-api-workspaces-id.md · references/operations/
• delete-api-workspaces-workspaceId-memory-attachments-storeId.md · references/operations/
• delete-apps-v1-prompts-name.md · references/operations/
• delete-apps-v1-skills-name.md · references/operations/
• delete-apps-v1-users-external-id-agents-agent.md · references/operations/
• delete-apps-v1-users-external-id.md · references/operations/
• get-api-credentials.md · references/operations/
• get-api-environments-id-grants.md · references/operations/
• get-api-environments-id-tokens.md · references/operations/
• get-api-environments-id.md · references/operations/
• get-api-environments.md · references/operations/
• get-api-memory-stores-storeId-attachments.md · references/operations/
• get-api-memory-stores-storeId-memories.md · references/operations/
• get-api-memory-stores-storeId-memory-versions-versionId.md · references/operations/
• get-api-memory-stores-storeId-versions.md · references/operations/
• get-api-memory-stores-storeId.md · references/operations/
• get-api-memory-stores.md · references/operations/
• get-api-prompts-id-grants.md · references/operations/
• get-api-prompts-id-versions.md · references/operations/
• get-api-prompts-id.md · references/operations/
• get-api-prompts-public.md · references/operations/
• get-api-prompts.md · references/operations/
• get-api-providers-id-grants.md · references/operations/
• get-api-providers-id-models.md · references/operations/
• get-api-providers.md · references/operations/
• get-api-shares-public-id.md · references/operations/
• get-api-shares.md · references/operations/
• get-api-skills-id-dependents.md · references/operations/
• get-api-skills-id-dirs-zip.md · references/operations/
• …and 140 more

SKILL.md (first lines)

# NAP Control Plane API
REST API for the NAP control plane.

## How to Use This Skill

This API documentation is split into multiple files for on-demand loading.

**Directory structure:**
```
references/
├── resources/      # 18 resource index files
├── operations/     # 225 operation detail files
└── schemas/        # 9 schema groups, 23 schema files
```

**Navigation flow:**
1. Find the resource you need in the list below
2. Read `references/resources/<resource>.md` to see available operations
3. Read `references/operations/<operation>.md` for full details
4. If an operation references a schema, read `references/schemas/<prefix>/<schema>.md`

## Base URL

`https://nap.example.com` — or set `$NAP_BASE_URL` to your deployment's host. Every operation path below is relative to it (e.g. `GET $NAP_BASE_URL/api/workspaces`).

## Authentication

Supported methods: **bearerAuth**, **appClientAuth**. See `references/authentication.md` for details.

## Conventions

- Every operation path is relative to the Base URL above; send `Authorization: Bearer <token>` on every request.
- **URL-encode path-bearing query params** (e.g. `path`): encode the whole value — slashes inside it are literal, not separators. A raw CJK or slashed value will 400 or mis-route.

## Common Intents → Operation

Non-obvious capability routing (when the operation isn't where you'd first look):

| I want to… | Use |
|------------|-----|
| Have the workspace agent do something — run a task, edit files, run commands, answer about its work | Send a natural-language prompt to the in-workspace agent: `POST /api/workspaces/{id}/chat` (see operations/post-api-workspaces-id-chat.md). The agent has a full toolset (bash, file edit, etc.); this is the primary way to get work done in a workspace. There is no direct exec / command endpoint for service tokens by design — route the request through chat. |
| Read / write / list files in a workspace | Workspace filesystem → `agent-files` resource. The shared `/mnt/afs` volume → `agent-afs-files` resource (two distinct mounts). |
| Create / configure / start a workspace | `workspaces` resource — `POST /api/workspaces`, then `PUT /api/workspaces/{id}/config`. |
| Bulk-manage prompts / templates / skills | `prompts`, `templates`, `skills` resources. |
| Issue or rotate a token / credential | `credentials` resource and the service-token operations. |
| Give each user of an application its own agents — declare them, roll out changes, create a user's workspace | The application protocol (`apps` resource, `/apps/v1/*`, client id + secret). Read `references/app-spec.md` first: it covers the spec, the deploy step and the pitfalls. |


## Example — drive the agent (async chat + poll)

The most common task, end to end. Send a prompt, poll until the session is done, read the transcript — no other files needed:

```bash
BASE="${NAP_BASE_URL:-https://nap.example.com}"
NAP_WS="<workspace-id>"

# 1. Start the turn. mode=async returns 202 immediately with a 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":"List the files in the repo and summarize the README","mode":"async","source":"api"}' \
  | jq -r .session_id)

# 2. Poll the session until it is done: no turn running AND no agent calls outstanding.
#    chat_status: "agent" = a turn is running · "idle" / "human" = no turn running
#    pending_agent_calls: calls to other agents whose results have not come back yet
while :; do
  S=$(curl -s "$BASE/api/workspaces/$NAP_WS/sessions/$SID" -H "Authorization: Bearer $NAP_TOKEN")
  [ "$(echo "$S" | jq -r .chat_status)" != "agent" ] \
    && [ "$(echo "$S" | jq -r '.pending_agent_calls // 0')" = "0" ] && break
  sleep 3
done

# 3. Read the full transcript.
curl -s "$BASE/api/workspaces/$NAP_WS/messages?session_id=$SID" \
  -H "Authorization: Bearer $NAP_TOKEN" | jq .
```

### When is a session done?

**Done = `chat_status` is not `agent` AND `pending_agent_calls` is `0`.** Checking `chat_status` alone is not enough.

One chat request starts one turn, but a session can run more turns than you started. An agent that hands work to other agents (`call_agent`) may end its turn while those calls are still running — its reply at that point is an interim "dispatched, waiting". When a called agent finishes, the platform posts the result into the session and the agent runs a further turn on its own; results that finish together arrive in one turn. So between turns the session can read `chat_status: "idle"` with `pending_agent_calls` above `0`, and the last assistant message is not the final answer yet.

- **`async`** — poll `GET /api/workspaces/{id}/sessions/{sessionId}` with the condition above (the loop in step 2).
- **`sync`** — the response carries `pending_agent_calls` too. `0`: `final_message` is the answer. Above `0`: it is interim; switch to polling the session, then read the messages.
- **`stream`** — the stream closes when the first turn ends. Read the session afterwards; if `pending_agent_calls` is above `0`, poll as above.

The messages the platform posts for delivered results have `role: "user"`, are wrapped in `<agent-sys>…</agent-sys>`, and their first line starts with `[Automated delivery of call_agent results`. They are not something a person typed; when reading a transcript, take the last `assistant` message as the answer.

You may send a new message while calls are outstanding — the session is not busy between turns. The results still arrive afterwards as their own turn.

This applies to sessions started with `source` `api` or `web`. Sessions from schedules and chat connectors do not get results posted back: there the agent waits for its calls inside the one turn, and `pending_agent_calls` stays `0`.

Continue the same conversation by POSTing again with this `session_id` in the body. For token-by-token output instead of polling, omit `mode` (or use `mode: "stream"`) and read the `text/event-stream` of UniversalEvent frames.

## Building an application on NAP (App Spec)

When an application's own users should each get NAP agents, the application declares those agents in one document, the App Spec, and NAP creates and updates every user's workspaces from it. Read **`references/app-spec.md`** before writing or changing a spec: it covers what to share with the application first, the publish → dry run → apply deploy step, prompt pinning, `calls`, shared folders, scaling, rolling out changes and why `prune` needs a person's yes.

## Handoff — local agent → NAP cloud agent

A common use of async chat is **delegation**: a local agent (e.g. running on your laptop) hands a chunk of work to a NAP cloud agent that has its own persistent workspace, filesystem, and toolset, then collects the result.

The cloud agent is a **fresh, isolated agent** — it shares none of your local context, conversation, or files. Everything it needs travels through the workspace and the prompt, so front-load it:

- **Stage inputs** — write the files it needs into the workspace first (`PUT /api/workspaces/{id}/agent/files?path=…`, raw body), or tell it a repo to clone. Don't assume it can see your local tree.
- **Write a self-contained, autonomous prompt** — the task, where the inputs live, the acceptance criteria, and how to behave unattended: proceed without asking for approval, reply tersely, and don't echo large files (you'll inspect artifacts directly). A clarifying round-trip is expensive, so decide up front. This prompt is also where you keep the agent from blocking on approval gates — instruct it to proceed rather than ask.

### Driver script

A ready-to-run driver ships with this skill at **`scripts/handoff.sh`** — call it directly or adapt it. It dispatches a turn, polls until the session is done (see [When is a session done?](#when-is-a-session-done)), and prints the agent's reply. Pass `-s <session_id>` to **continue** an existing session instead of starting a new one — that's how you carry a conversation across calls.

```bash
export NAP_TOKEN=<service-token> NAP_WS=<workspace-id>   # NAP_BASE_URL defaults to https://nap.example.com

scripts/handoff.sh "implement what TASK.md describes"    # new session -> prints session_id + reply
scripts/handoff.sh -s <session_id> "now add tests"       # continue that session
echo "long task text..." | scripts/handoff.sh -          # task from stdin
```

From neutree-ai/agent-platform, Apache-2.0.

More from neutree-ai/agent-platform