---
title: Document Library
slug: document-api/document-library
docTags: 
createdAt: 2026-09-11T14:18:01.652Z
---

All Catenda projects have a document library, use the document library to store files and folders. All items in the document library are library items. A library item can be a file or a folder. A folder can contain other folders and files. The `parentId` of a file is the library item id of the folder it is stored in. File library items can have multiple revisions. Each revision is a separate file.

## List documents

Use the list library items endpoint with the following supported parameters to limit the result:

- `parentId`
- `associations`
- `labels`
- `search`
- `createdAtFrom`
- `createdAtTo`
- `revisionCreatedAtFrom`
- `revisionCreatedAtTo`
- `include`
- `subFolders`
- `scope`

## Upload a file

Use the create library item endpoint to upload a file. The upload parameters can be sent either in the `Bimsync-Params` request header or as a part of the request body.

**Prepare upload parameters**

Set the necessary fields of the JSON object.

```json
{
  "name": "Document name",
  "parentId": "Parent folder ID",
  "document": {
    "type": "file",
    "filename": "document.pdf"
  },
  "failOnDocumentExists": false // optional, defaults to false
}
```

**Make request with the parameters in the header**

Set the value to the `Bimsync-Params` request header, attach the file to the request and set the `Content-Type` header to `application/octet-stream`.

```curl
curl -X POST \
  'https://api.catenda.com/v2/projects/{project-id}/libraries/{library-id}/items' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/octet-stream' \
  --header 'Bimsync-Params: {"name":"Document name","parentId":"Parent folder ID","document":{"type":"file","filename":"document.pdf"},"failOnDocumentExists":false}' \
  --data-binary '@/path/to/document.pdf'
```

HTTP header values are limited to ISO-8859-1, so non-ASCII characters in `document.filename` must be percent-encoded — `Blåbær.pdf` is sent as `Bl%C3%A5b%C3%A6r.pdf`. `name` is **not** percent-decoded on this route, so encoding it stores the literal `Bl%C3%A5b%C3%A6r`. To use non-ASCII characters in `name`, send the parameters in the request body instead.

**Make request with the parameters in the body**

Send the parameters as a `Bimsync-Params` part and the file as a `file` part, with `Content-Type: multipart/form-data`. Part bodies are read as UTF-8, so non-ASCII filenames need no percent-encoding and values are taken verbatim — a filename containing a literal percent sign, such as `100%20final.pdf`, is stored as written (the header route would read it as `100 final.pdf`).

Send the `Bimsync-Params` part **before** the `file` part. The upload is streamed rather than held in memory, so parameters arriving after the file are rejected with a 400.

```curl
curl -X POST \
  'https://api.catenda.com/v2/projects/{project-id}/libraries/{library-id}/items' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --form 'Bimsync-Params={"name":"Blåbær","parentId":"Parent folder ID","document":{"type":"file","filename":"Blåbær.pdf"},"failOnDocumentExists":false};type=application/json' \
  --form 'file=@/path/to/Blåbær.pdf'
```

With `--form`, `curl` sets `Content-Type: multipart/form-data` and its boundary itself — do not set that header yourself.

## Upload a file revision

Use the create library item revision endpoint to upload a new revision of a file. The upload parameters can be sent in the `Bimsync-Params` request header or as a request body part, exactly as when uploading a file.

```curl
curl -X POST \
  'https://api.catenda.com/v2/projects/{project-id}/libraries/{library-id}/items/{item-id}/revisions' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --form 'Bimsync-Params={"name":"Blåbær.pdf"};type=application/json' \
  --form 'file=@/path/to/Blåbær.pdf'
```

## Download a file

Use the get library item endpoint to download a file.

**Make request**

Set the `Accept` header to `application/octet-stream`.

```curl
curl -X GET \
  'https://api.catenda.com/v2/projects/{project-id}/libraries/{library-id}/items/{item-id}' \
  --header 'Accept: application/octet-stream' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

## Update a file

Use the update library item endpoint with the following supported parameters:

- `name`
- `parentId`
- `labelsToAdd`
- `labelsToRemove`

## Create a folder

Use the create library item endpoint to create a folder.

**Prepare request body**

Set the necessary fields of the JSON request body.

```json
{
  "name": "Folder name",
  "type": "folder",
  "parentId": "Parent folder ID",
  "document": {
    "type": "folder"
  }
}
```

**Make request**

Send a POST request to the endpoint.

```curl
curl -X POST \
  'https://api.catenda.com/v2/projects/{project-id}/libraries/{library-id}/items' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "name": "Folder name",
      "type": "folder",
      "parentId": "Parent folder ID",
      "document": {
          "type": "folder"
      }
  }'
```

## Update a folder

Use the update library item endpoint with the following supported parameters:

- `name`