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):

{
  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

curl -sS --fail-with-body "https://api.fabric.so/v2/user/me" \
  -H "X-Api-Key: $FABRIC_API_KEY"

POST (JSON)

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.

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

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

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

).

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…”).

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.