Document Library

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

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.

{
  "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 -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 -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 -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 -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.

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

Make request

Send a POST request to the endpoint.

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