Yapper API
Api reference
POST
/sessions/{sessionId}/workspace/documents

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.

Authorization

bearerAuth processes:write
AuthorizationBearer <token>

In: header

Scope: processes:write

Path Parameters

sessionId*string

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.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/sessions/string/workspace/documents" \  -H "Content-Type: application/json" \  -d '{    "path": "/Scripts/Episode 1.md",    "content": "string"  }'
{  "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"}
{  "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 by path 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. 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.