fabric-api

# Fabric API (HTTP via curl) Use this skill to read/write content in a user's Fabric workspace using the Fabric HTTP API (`https://api.fabric.so`). ## Critical gotchas (read first) - "Notes" are created via **POST `/v2/notepads`** (not `/v2/notes`). - Most create endpoints require **`parentId`**: - A UUID **or** one of: `@alias::inbox`, `@alias::bin`. - Notepad create requires: - `parentId` - AND either `text` (markdown string) **or** `ydoc` (advanced/structured). - `tags` must be an array of objects, each *either*: - `{ "name": "tag name" }` or `{ "id": "<uuid>" }` - Never nested arrays; never strings. When the user doesn't specify a destination folder: default to `parentId: "@alias::inbox"`. ## Setup (Clawdbot) This skill expects the API key in: - `FABRIC_API_KEY` Recommended config (use `apiKey`; Clawdbot will inject `FABRIC_API_KEY` because `primaryEnv` is set): ```json5 { skills: { entries: { "fabric-api": { enabled: true, apiKey: "YOUR_FABRIC_API_KEY" } } } } ```` ## HTTP basics * Base: `https://api.fabric.so` * Auth: `X-Api-Key: $FABRIC_API_KEY` * JSON: `Content-Type: application/json` For debugging: prefer `--fail-with-body` so 4xx bodies are shown. ## Canonical curl templates (use heredocs to avoid quoting bugs) ### GET ```bash curl -sS --fail-with-body "https://api.fabric.so/v2/user/me" \ -H "X-Api-Key: $FABRIC_API_KEY" ``` ### POST (JSON) ```bash curl -sS --fail-with-body -X POST "https://api.fabric.so/v2/ENDPOINT" \ -H "X-Api-Key: $FABRIC_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "replace": "me" } JSON ``` ## Core workflows ### 1) Create a notepad (note) Endpoint: `POST /v2/notepads` * Map user-provided "title" → `name` in the API payload. * Always include `parentId`. * Use `text` for markdown content. ```bash curl -sS --fail-with-body -X POST "https://api.fabric.so/v2/notepads" \ -H "X-Api-Key: $FABRIC_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "name": "Calendar Test Note", "text": "Created via Clawdbot", "parentId": "@alias::inbox", "tags": [{"name":"calendar"},{"name":"draft"}] } JSON ``` If tags cause validation trouble, omit them and create/assign later via `/v2/tags`. ### 2) Create a folder Endpoint: `POST /v2/folders` ```bash curl -sS --fail-with-body -X POST "https://api.fabric.so/v2/folders" \ -H "X-Api-Key: $FABRIC_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "name": "My new folder", "parentId": "@alias::inbox", "description": null } JSON ``` ### 3) Create a bookmark Endpoint: `POST /v2/bookmarks` ```bash curl -sS --fail-with-body -X POST "https://api.fabric.so/v2/bookmarks" \ -H "X-Api-Key: $FABRIC_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "url": "https://example.com", "parentId": "@alias::inbox", "name": "Example", "tags": [{"name":"reading"}] } JSON ``` ### 4) Browse resources (list children of a folder) Endpoint: `POST /v2/resources/filter` Use this to list what's inside a folder (use a folder UUID as `parentId`). ```bash curl -sS --fail-with-body -X POST "https://api.fabric.so/v2/resources/filter" \ -H "X-Api-Key: $FABRIC_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "parentId": "PARENT_UUID_HERE", "limit": 50, "order": { "property": "modifiedAt", "direction": "DESC" } } JSON ``` ### 5) Search Endpoint: `POST /v2/search` Use search when the user gives a fuzzy description (“the note about…”). ```bash curl -sS --fail-with-body -X POST "https://api.fabric.so/v2/search" \ -H "X-Api-Key: $FABRIC_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "queries": [ { "mode": "text", "text": "meeting notes", "filters": { "kinds": ["notepad"] } } ], "pagination": { "page": 1, "pageSize": 20 }, "sort": { "field": "modifiedAt", "order": "desc" } } JSON ``` ## Tags (safe patterns) ### List tags `GET /v2/tags?limit=100` ### Create tag `POST /v2/tags` with `{ "name": "tag name", "description": null, "resourceId": null }` ### Assign tags on create Use `tags: [{"name":"x"}]` or `tags: [{"id":"<uuid>"}]` only. ## Rate limiting + retries If you get `429 Too Many Requests`: * Back off (sleep + jitter) and retry. * Avoid tight loops; do pagination slowly. Do not blindly retry create requests without idempotency (you may create duplicates). ## Troubleshooting quick map * `404 Not Found`: almost always wrong endpoint, wrong resourceId/parentId, or permissions. * `400 Bad Request`: schema validation; check required fields and tag shape. * `403 Forbidden`: subscription/permission limits. * `429 Too Many Requests`: back off + retry. ## API reference The OpenAPI schema lives here: * `{baseDir}/fabric-api.yaml` When in doubt, consult it before guessing endpoint names or payload shapes.