fabric-api

# Fabric API (HTTP via Node/Python) 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` ## 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"` ## Setup (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. ## HTTP basics - 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` ## Convenience scripts (cross-platform) ### Node helper (recommended) ```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 ```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`. ## Core workflows ### 1) Create a notepad (note) 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. ### 2) Create a folder Endpoint: `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 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"}]}' ``` ### 4) Browse resources (list children of a folder) 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"}}' ``` ### 5) Search 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"}}' ``` ## 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. ## Reference files - OpenAPI spec (source of truth): `{baseDir}/fabric-api.yaml` - Extra schema notes: `{baseDir}/references/REFERENCE.md` - Debug playbook: `{baseDir}/references/TROUBLESHOOTING.md`