fabric-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Fabric API (HTTP via Node/Python)

Fabric API（基于Node/Python的HTTP实现）

Use this skill when you need to read or write content in a user's Fabric workspace using the Fabric HTTP API (

https://api.fabric.so

This version avoids bash-only wrapper scripts. It ships cross-platform helpers:

Node:
```
{baseDir}/scripts/fabric.mjs
```
(recommended)
Python:
```
{baseDir}/scripts/fabric.py
```

当你需要通过Fabric HTTP API（

https://api.fabric.so

）读取或写入用户Fabric工作区中的内容时，可以使用此技能。

本版本摒弃了仅支持bash的包装脚本，提供跨平台辅助工具：

Node：
```
{baseDir}/scripts/fabric.mjs
```
（推荐）
Python：
```
{baseDir}/scripts/fabric.py
```

Critical gotchas (read first)

关键注意事项（请先阅读）

There is no
```
POST /v2/notes
```
endpoint in the bundled OpenAPI spec. To create a “note”, use POST /v2/notepads
.
Most create endpoints require parentId
:
- A folder UUID or one of:
```
@alias::inbox
```
  ,
```
@alias::bin
```
Notepad creation requires:
- ```
parentId
```
- and either
```
text
```
  (markdown string) or
```
ydoc
```
  (advanced/structured)
```
tags
```
must be an array of objects, each item either:
- ```
{ "name": "tag name" }
```
  or
```
{ "id": "<uuid>" }
```
- Never strings, never nested arrays.
Field name gotcha: the API schema uses
```
name
```
(not
```
title
```
). If the user says “title”, map it to
```
name
```
in requests.

When the user doesn’t specify a destination folder, default to:

```
parentId: "@alias::inbox"
```

捆绑的OpenAPI规范中没有
```
POST /v2/notes
```
端点。要创建“笔记”，请使用**
```
POST /v2/notepads
```
**。
大多数创建端点需要**
```
parentId
```
**：
- 文件夹UUID 或以下别名之一：
```
@alias::inbox
```
  、
```
@alias::bin
```
创建记事本需要：
- ```
parentId
```
- 以及**
```
text
```
  （Markdown字符串）或
```
ydoc
```
  （高级/结构化格式）二者之一**
```
tags
```
必须是对象数组，每个元素需为：
- ```
{ "name": "tag name" }
```
  或
```
{ "id": "<uuid>" }
```
- 不能是字符串，也不能是嵌套数组。
字段名称注意事项：API架构使用
```
name
```
（而非
```
title
```
）。如果用户提到“标题”，请在请求中映射为
```
name
```
字段。

当用户未指定目标文件夹时，默认使用：

```
parentId: "@alias::inbox"
```

Setup (OpenClaw / Clawdbot)

设置（OpenClaw / Clawdbot）

This skill expects the Fabric API key in:

```
FABRIC_API_KEY
```

OpenClaw config example (

~/.openclaw/openclaw.json

json5

{
  skills: {
    entries: {
      "fabric-api": {
        enabled: true,
        apiKey: "YOUR_FABRIC_API_KEY"
      }
    }
  }
}

Notes:

```
apiKey
```
is a convenience for skills that declare
```
primaryEnv
```
; it injects
```
FABRIC_API_KEY
```
for the duration of an agent run.
Don’t paste the API key into prompts, client-side code, or logs.

此技能需要将Fabric API密钥存储在：

```
FABRIC_API_KEY
```

OpenClaw配置示例（

~/.openclaw/openclaw.json

）：

json5

{
  skills: {
    entries: {
      "fabric-api": {
        enabled: true,
        apiKey: "YOUR_FABRIC_API_KEY"
      }
    }
  }
}

注意：

```
apiKey
```
是为声明了
```
primaryEnv
```
的技能提供的便捷配置；它会在Agent运行期间注入
```
FABRIC_API_KEY
```
环境变量。
请勿将API密钥粘贴到提示词、客户端代码或日志中。

HTTP basics

HTTP基础

Base URL:
```
https://api.fabric.so
```
(override with
```
FABRIC_BASE
```
if needed)
Auth header:
```
X-Api-Key: $FABRIC_API_KEY
```
JSON header (for JSON bodies):
```
Content-Type: application/json
```

基础URL：
```
https://api.fabric.so
```
（如有需要，可通过
```
FABRIC_BASE
```
覆盖）
认证头：
```
X-Api-Key: $FABRIC_API_KEY
```
JSON头（用于JSON请求体）：
```
Content-Type: application/json
```

Convenience scripts (cross-platform)

便捷脚本（跨平台）

Node helper (recommended)

Node辅助工具（推荐）

bash

node {baseDir}/scripts/fabric.mjs GET /v2/user/me

node {baseDir}/scripts/fabric.mjs POST /v2/notepads --json '{"name":"Test note","text":"Hello","parentId":"@alias::inbox"}'

bash

node {baseDir}/scripts/fabric.mjs GET /v2/user/me

node {baseDir}/scripts/fabric.mjs POST /v2/notepads --json '{"name":"Test note","text":"Hello","parentId":"@alias::inbox"}'

Python helper

Python辅助工具

bash

python3 {baseDir}/scripts/fabric.py GET /v2/user/me

python3 {baseDir}/scripts/fabric.py POST /v2/notepads --json '{"name":"Test note","text":"Hello","parentId":"@alias::inbox"}'

Notes:

Both helpers print the response body on success.
On HTTP errors (4xx/5xx), they print
```
HTTP <code> <reason>
```
to stderr and still print the response body, then exit non‑zero (similar to
```
curl --fail-with-body
```
).
If you pass an absolute URL (
```
https://...
```
), the helpers do not attach
```
X-Api-Key
```
unless you explicitly pass
```
--with-key
```
.

bash

python3 {baseDir}/scripts/fabric.py GET /v2/user/me

python3 {baseDir}/scripts/fabric.py POST /v2/notepads --json '{"name":"Test note","text":"Hello","parentId":"@alias::inbox"}'

注意：

两个辅助工具在成功时都会打印响应体。
遇到HTTP错误（4xx/5xx）时，它们会向stderr打印
```
HTTP <code> <reason>
```
，同时仍会打印响应体，然后以非零状态码退出（类似
```
curl --fail-with-body
```
的行为）。
如果传入绝对URL（
```
https://...
```
），除非显式传递
```
--with-key
```
参数，否则辅助工具不会附加
```
X-Api-Key
```
头。

Core workflows

核心工作流

1) Create a notepad (note)

1) 创建记事本（笔记）

Endpoint:

POST /v2/notepads

Rules:

Map user “title” →
```
name
```
Use
```
text
```
for markdown content
Always include
```
parentId
```
If you’re debugging 400s, start minimal (required fields only), then add
```
name
```
, then
```
tags
```
.

Minimal create:

bash

node {baseDir}/scripts/fabric.mjs POST /v2/notepads --json '{"parentId":"@alias::inbox","text":"Hello"}'

Create with a name:

bash

node {baseDir}/scripts/fabric.mjs POST /v2/notepads --json '{"name":"Calendar Test Note","text":"Created via OpenClaw","parentId":"@alias::inbox"}'

Create with tags (correct shape):

bash

node {baseDir}/scripts/fabric.mjs POST /v2/notepads --json '{"name":"Ideas","text":"# Ideas\\n\\n- First\\n- Second\\n","parentId":"@alias::inbox","tags":[{"name":"ideas"},{"name":"draft"}]}'

If you keep seeing tag validation errors, temporarily omit

tags

and create the notepad first.

端点：

POST /v2/notepads

规则：

将用户所说的“title”映射为
```
name
```
字段
使用
```
text
```
字段存储Markdown内容
始终包含
```
parentId
```
如果调试400错误，请从最小配置开始（仅必填字段），然后添加
```
name
```
，再添加
```
tags
```
。

最简创建命令：

bash

node {baseDir}/scripts/fabric.mjs POST /v2/notepads --json '{"parentId":"@alias::inbox","text":"Hello"}'

带名称的创建命令：

bash

node {baseDir}/scripts/fabric.mjs POST /v2/notepads --json '{"name":"Calendar Test Note","text":"Created via OpenClaw","parentId":"@alias::inbox"}'

带标签的创建命令（正确格式）：

bash

node {baseDir}/scripts/fabric.mjs POST /v2/notepads --json '{"name":"Ideas","text":"# Ideas\\n\\n- First\\n- Second\\n","parentId":"@alias::inbox","tags":[{"name":"ideas"},{"name":"draft"}]}'

如果持续遇到标签验证错误，请暂时省略

tags

字段，先创建记事本。

2) Create a folder

2) 创建文件夹

Endpoint:

POST /v2/folders

bash

node {baseDir}/scripts/fabric.mjs POST /v2/folders --json '{"name":"My new folder","parentId":"@alias::inbox","description":null}'

端点：

POST /v2/folders

bash

node {baseDir}/scripts/fabric.mjs POST /v2/folders --json '{"name":"My new folder","parentId":"@alias::inbox","description":null}'

3) Create a bookmark

3) 创建书签

Endpoint:

POST /v2/bookmarks

bash

node {baseDir}/scripts/fabric.mjs POST /v2/bookmarks --json '{"url":"https://example.com","parentId":"@alias::inbox","name":"Example","tags":[{"name":"reading"}]}'

端点：

POST /v2/bookmarks

bash

node {baseDir}/scripts/fabric.mjs POST /v2/bookmarks --json '{"url":"https://example.com","parentId":"@alias::inbox","name":"Example","tags":[{"name":"reading"}]}'

4) Browse resources (list children of a folder)

4) 浏览资源（列出文件夹子项）

Endpoint:

POST /v2/resources/filter

Important:

This endpoint’s
```
parentId
```
expects a UUID (not an alias).
If you only have an alias, resolve it by listing resource roots and picking the inbox/bin folder ID.

bash

node {baseDir}/scripts/fabric.mjs POST /v2/resources/filter --json '{"parentId":"PARENT_UUID_HERE","limit":50,"order":{"property":"modifiedAt","direction":"DESC"}}'

端点：

POST /v2/resources/filter

重要提示：

此端点的
```
parentId
```
需要UUID（而非别名）。
如果只有别名，请通过列出资源根目录并选择收件箱/垃圾箱的文件夹ID来解析。

bash

node {baseDir}/scripts/fabric.mjs POST /v2/resources/filter --json '{"parentId":"PARENT_UUID_HERE","limit":50,"order":{"property":"modifiedAt","direction":"DESC"}}'

5) Search

5) 搜索

Endpoint:

POST /v2/search

Use search when the user gives a fuzzy description (“the note about…”).

bash

node {baseDir}/scripts/fabric.mjs POST /v2/search --json '{"queries":[{"mode":"text","text":"meeting notes","filters":{"kinds":["notepad"]}}],"pagination":{"page":1,"pageSize":20},"sort":{"field":"modifiedAt","order":"desc"}}'

端点：

POST /v2/search

当用户给出模糊描述（如“关于……的笔记”）时，使用搜索功能。

bash

node {baseDir}/scripts/fabric.mjs POST /v2/search --json '{"queries":[{"mode":"text","text":"meeting notes","filters":{"kinds":["notepad"]}}],"pagination":{"page":1,"pageSize":20},"sort":{"field":"modifiedAt","order":"desc"}}'

Error handling + retries (practical guidance)

错误处理与重试（实用指南）

400 Bad Request: schema validation. Re-check required fields, and that
```
tags
```
is
```
[{name}|{id}]
```
not nested.
401/403: auth/subscription/permission. Stop and report the error details; don’t brute-force.
404: wrong endpoint, wrong ID, or no access.
429: rate limiting. Back off (sleep + jitter) and retry reads. Avoid blind retries on create (you may create duplicates).
5xx: transient; retry with backoff.

400 Bad Request：架构验证错误。重新检查必填字段，确保
```
tags
```
是
```
[{name}|{id}]
```
格式而非嵌套结构。
401/403：认证/订阅/权限问题。停止操作并报告错误详情；不要暴力重试。
404：端点错误、ID错误或无访问权限。
429：速率限制。退避（休眠+随机延迟）并重试读取操作。避免对创建操作盲目重试（可能会创建重复项）。
5xx：临时错误；退避后重试。

Reference files

参考文件

OpenAPI spec (source of truth):
```
{baseDir}/fabric-api.yaml
```
Extra schema notes:
```
{baseDir}/references/REFERENCE.md
```
Debug playbook:
```
{baseDir}/references/TROUBLESHOOTING.md
```

OpenAPI规范（权威来源）：
```
{baseDir}/fabric-api.yaml
```
额外架构说明：
```
{baseDir}/references/REFERENCE.md
```
调试手册：
```
{baseDir}/references/TROUBLESHOOTING.md
```