Fabric API docsGuideReference

Creating resources

Fabric supports creating resources such as bookmarks, notes, folders, and files – each through its own dedicated API endpoint. To create resources, it is necessary to always provide a parent id. You can read more about the Fabric filesystem structure here.

Limitations

Our API implements some (temporary) technical limitations as well as there are subscription limitations which you should handle when the creation of an item fails.

Technical limitations

  • Only markdown can be provided to create a note through the public API.

  • Maximum file size is 5GB, or further limited by subscription plan.

Reaching subscription limits

There are several subscription limits which you might hit when creating resources. If you hit a limit, the API will respond with 403 Forbidden and the following body response:

{
  "title": "Forbidden",
  "status": 403,
  "traceid": "XXX",
  "detail": "exceeds_storage_limit"
}

Example limits:

  1. Storage limit. Triggered when creating an item would exceed allowed storage capacity. Detail code: exceeds_storage_limit .

  2. Credits depleted. Triggered when creating an item would exceed the user’s credit balance. Detail code: exceeds_credit_limit

Creating file resources

To create a file resource, it is necessary to upload the file to the storage first before requesting a /v2/files POST. This requires several steps:

Step 1: Obtain a signed file upload URL

First, you need to request a signed URL which is used to upload the file. The request needs to provide the file size in bytes, and the filename.

curl 'https://api.fabric.so/v2/upload?filename=SOME_NAME&size=1024' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

You’ll receive a signed upload URL, which can be used to upload the file in a PUT request.

Step 2: Upload the file

Use the provided URL to upload a file in a PUT request.

curl '<response.url>' \
  --request PUT
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
  --header 'Content-Disposition: <response.headers['Content-disposition']>
  --header ... other headers
  --body-raw <FILE DATA>

Step 3: Create the file resource

Once the file is uploaded, you need to create a record of the resource.

From the signed URL returned in step 1, you can extract the pathname, which then should be provided as the attachment.path:

FILE_PATH = "stored-files/a8221d04-ec5a-4799-97e6-bc7ca452ba8e.png"

This should then be provided in a final PUT request.

curl https://api.fabric.so/v2/files \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "name": null,
  "attachment": {
    "path": <FILE_PATH>,
    "filename": <FILENAME>
  },
  "parentId": <Parent id or @alias::inbox>,
  "mimeType": <File mimeType, e.g. image/png>
}'

Assigning tags to a new resource

To assign a tag to a new resource, you can pass the tags property, which is an array of either:

  • { id: string } – if you know the existing id of a tag you want to assign, choose the later option.

  • { name: string } – our API will consume the name property. If a tag with this name already exists, the existing tag will be assigned. If the tag doesn't exist, it will be created and assigned.

Example array:

[
  {"name": "ideas"},
  {"id": "779e08e4-8589-44d0-b5d7-ad3bef3f3f87"},
  {"name": "code snippets"}
]

© 2025 Fabric