Yapper API
Api reference
PATCH
/sessions/{sessionId}/workspace/nodes

Moves, renames, or annotates one item. Send only the fields to change; unknown or invalid fields are rejected before anything is written. Renaming a file renames its asset everywhere it is used, as in the web app. parentPath creates missing folders. A name already used in the destination folder returns conflict. The workspace root cannot be changed. Addresses the item by its path; /workspace/nodes/{nodeId} does the same by id. The change shows up in the Yapper web app and is recorded with the API key or MCP client that made it; the in-app Yapper agent in that session is told about it on its next turn. Free. Uses the processes:write scope.

Authorization

bearerAuth processes:write
AuthorizationBearer <token>

In: header

Scope: processes:write

Path Parameters

sessionId*string

Query Parameters

path*string

Absolute workspace path, such as /Characters/hero. Names match exactly first, then ignoring case.

Length1 <= length <= 4000

Header Parameters

Idempotency-Key?string

Optional key that makes the edit safe to retry: a retry with the same key and body replays instead of editing twice, and the same key with a different body returns idempotency_conflict. Scoped to the credential and session.

Length1 <= length <= 255

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Properties1 <= properties

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/sessions/string/workspace/nodes?path=%2FCharacters%2Fhero" \  -H "Content-Type: application/json" \  -d '{}'
{  "id": "string",  "parentId": "string",  "name": "string",  "path": "/Characters/hero",  "type": "folder",  "kind": "folder",  "assetId": "string",  "previewUrl": "http://example.com",  "note": "string",  "pinned": true,  "selected": true,  "brief": true,  "color": "string",  "semantic": "string",  "childCount": 0,  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z"}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}

Update a workspace item PATCH

Moves, renames, or annotates one item. Send only the fields to change; unknown or invalid fields are rejected before anything is written. Renaming a file renames its asset everywhere it is used, as in the web app. parentPath creates missing folders. A name already used in the destination folder returns conflict. The workspace root cannot be changed. The change shows up in the Yapper web app and is recorded with the API key or MCP client that made it; the in-app Yapper agent in that session is told about it on its next turn. Free. Uses the processes:write scope.

Write a workspace document POST

Creates or overwrites the text document at path, which includes the file name (such as /Scripts/Episode 1.md); missing folders are created. content is the full text and replaces any existing text. Anything other than a text document already at path returns conflict. Set brief: true for the session brief, the document the in-app Yapper agent always reads; a brief is the natural place for a multi-step production's plan. The change shows up in the Yapper web app and is recorded with the API key or MCP client that made it; the in-app Yapper agent in that session is told about it on its next turn. Free. Uses the processes:write scope.