Create item

POST

https://api.catenda.com/v2/projects/{project-id}/libraries/{library-id}/items

Add a new library item.

Supported library types are document, link and classification.

For file upload, only document library type is supported. There are two ways to upload a file:

Content-Type: application/octet-stream — the file is the request body and the parameters go in the Bimsync-Params header. Header values are limited to ISO-8859-1, so non-ASCII characters in document.filename must be percent-encoded, and name cannot carry them at all.
Content-Type: multipart/form-data — the parameters go in a Bimsync-Params part and the file in a file part. Part bodies are read as UTF-8, so non-ASCII filenames are sent as they are and a literal percent sign is left alone. Send the Bimsync-Params part before the file part — the upload is streamed, so parameters arriving after the file are rejected with a 400.

Path Parameters

project-idstringrequired
Example
af2d8af0fa54465b89bf26dd3d92cfd0
Description
Catenda project id
library-idstringrequired
Description
Id of the library

Header Parameters

Bimsync-Paramslibrary-item-upload-params
Description
Upload parameters, as a JSON object.

Required with Content-Type: application/octet-stream. Percent-encode any non-ASCII characters in document.filename; name is not percent-decoded, so a non-ASCII name can only be sent via the request body with Content-Type: multipart/form-data.
- namestringrequired
  Example
  Document Name
  Description
  Name of the document
- parentIdstring
  Example
  924809076a694255b589d236517a55da
  Description
  A unique identifier for the parent of the library item represented as compacted UUID using 32 hexadecimal characters.
  
  If no parent is present, the parent is the root of the library.
- documentobject
  Description
  Fields specific for document library items.
  - typestring<file>
    Example
    file
    Description
    Value must be "file".
    Allowed
    file
  - filenamestring
    Example
    Document Revision Name
    Description
    Name of the document revision.
- failOnDocumentExistsboolean
  Example
  true
  Description
  Supported in libraries of type document.
  
  Default value is true which means when a file with the same name already exists in the folder the response will be 25 CONFLICT and upload will fail. When set to false a new revision will be created.

Body Parameters

bodyobject
- objectlibrary-item-document-create
  - namestring
    Example
    Folder name 1
    Description
    The name of the folder
  - typestring<folder>
    Example
    folder
    Description
    The type of document, value must be set to "folder"
    Allowed
    folder
  - parentIdstring
    Example
    502b06247f744b7492fd1a44e386f21e
    Description
    A unique identifier for the parent of the library item.
    
    Represented as compacted UUID using 32 hexadecimal characters.
    
    If no parent is present, the value is null.
  - documentobject
    - typestring
      Example
      folder
      Description
      Value is folder
- objectlibrary-item-link-create
  - namestring
    Example
    Library item 1
    Description
    The name of the library item
  - typestring<link>
    Example
    link
    Description
    Type of the library item, value must be set to "link"
    Allowed
    link
  - linkobject
    - urlstring
      Example
      https://www.example.com
      Description
      The URL of the link
- objectlibrary-item-classification-create
  - namestring
    Example
    Library item 1
    Description
    The name of the library item
  - typestring<classification>
    Example
    classification
    Description
    Type of the library item, value must be set to "classification"
    Allowed
    classification
  - parentIdstring
    Example
    502b06247f744b7492fd1a44e386f21e
    Description
    A unique identifier for the parent of the library item.
    
    Represented as compacted UUID using 32 hexadecimal characters.
    
    If no parent is present, the value is null.
  - classificationobject
    - identificationstring
      Example
      A1
      Description
      Identification of the classification
    - descriptionstring
      Example
      Classification description
      Description
      Description of the classification

Responses

200OK

object
- objectlibrary-item-document[]
  - idstring
    Example
    tttbe1ce36ce4b4c37f7060c76d241e7
    Description
    A unique identifier for a library item, represented as compacted UUID using 32 hexadecimal characters.
  - libraryIdstring
    Example
    9f71c88b7d7942ffa316c7a450c89358
    Description
    Id of the library that the item belongs to
  - namestring
    Example
    Library item 1
    Description
    The name of the library item
  - typestring<document | folder>
    Example
    document
    Description
    Type of the document library item, valid values are:
    
    document
    
    folder
    Allowed
    documentfolder
  - parentIdstring
    Example
    502b06247f744b7492fd1a44e386f21e
    Description
    A unique identifier for the parent of the library item.
    
    Represented as compacted UUID using 32 hexadecimal characters.
    
    If no parent is present, the value is null.
  - documentobject
    - file
      - typestring
        Example
        file
        Description
        Value is file
      - createdAtstring
        Example
        2023-12-09T10:07:56.000Z
        Description
        The date and time the file was created in ISO 8601 format
      - ownerstring
        Example
        gh7fe246cea6442834052404eth08drj
        Description
        User id of the file owner
      - revisionlibrary-item-document-file-revision
        idstring
        Example
        h4c21c0e89774c8e92f42959c73561yh
        Description
        Id of the revision
        parentIdstring
        Description
        A unique identifier for the parent of the library item.
        
        Represented as compacted UUID using 32 hexadecimal characters.
        
        If no parent is present, the value is null.
        versionnumber
        Example
        9
        Description
        Version of the revision
        extendedVersionobject
        Description
        Extended version of the revision
        majornumber
        Example
        1
        Description
        Major version of the revision
        minorstring
        Example
        1
        Description
        Minor version of the revision
        namestring
        Example
        File.txt
        Description
        File name of the revision
        createdAtstring
        Example
        2023-03-01T11:52:45.000Z
        Description
        The date and time the revision was created in ISO 8601 format
        sizenumber
        Example
        3745
        Description
        Size of the file in bytes
        createdByuser
        Description
        Represents a User, Organization or Team.
        
        A User is someone with a Catenda account, commonly representing a person.
        
        An Organization represents a company, project organization or an application. Organizations do not have a username and cannot sign in to Catenda.
        
        A Team represents a group of users within a project. Teams do not have a username and cannot sign in to Catenda.
        idstring
        Example
        524809076a694255b989d236517a55da
        Description
        Represented as compacted UUID using 32 hexadecimal characters
        namestring
        Example
        John Doe
        Description
        The name of the user, limited to 128 characters
        usernamestring
        Example
        [email protected]
        Description
        The handle the user identifies with.
        
        Commonly the username will be in email address format. Usernames are unique but subject to change, we recommend using the id field to reference users instead.
        
        If the user represents an organization or a team the value is always null.
        
        Limited to 50 characters.
        emailstring
        Example
        [email protected]
        Description
        Email address of the User
        createdAtstring
        Example
        2016-09-20T14:55:22.000Z
        Description
        The date and time the user was created in ISO 8601 format
        avatarUrlstring
        Example
        https://api.catenda.com/v2/avatar/397t0ccd8f74516096c738de15dc6512
        Description
        The URL for the user avatar
        typestring<user | organization | team>
        Example
        user
        Description
        The type of user, valid values are:
        
        user
        
        organization
        
        team
        
        Allowed
        userorganizationteam
        additionalFormatsobject[]
        Description
        Additional formats available for the file revision
        sizenumber
        Example
        7147
        Description
        Size of the file in bytes
        mediaTypestring
        Example
        application/xod
        Description
        Media type of the additional format file
        downloadFileNamestring
        Example
        File-1.txt
        Description
        Filename on disk
    - folder
      - typestring
        Example
        folder
        Description
        Value is folder
      - createdAtstring
        Example
        2023-12-09T10:07:56.000Z
        Description
        The date and time the folder was created in ISO 8601 format
      - ownerstring
        Example
        gh7fe246cea6442834052404eth08drj
        Description
        User id of the folder owner
  - deletedboolean
    Description
    Deletion status of the library item
- objectlibrary-item-link[]
  - idstring
    Example
    tttbe1ce36ce4b4c37f7060c76d241e7
    Description
    A unique identifier for a library item, represented as compacted UUID using 32 hexadecimal characters.
  - libraryIdstring
    Example
    9f71c88b7d7942ffa316c7a450c89358
    Description
    Id of the library that the item belongs to
  - namestring
    Example
    Library item 1
    Description
    The name of the library item
  - typestring<link>
    Example
    link
    Description
    Type of the library item, valid values are "link"
    Allowed
    link
  - parentIdstring
    Example
    502b06247f744b7492fd1a44e386f21e
    Description
    A unique identifier for the parent of the library item.
    
    Represented as compacted UUID using 32 hexadecimal characters.
    
    If no parent is present, the value is null.
  - linkobject
    - urlstring
      Example
      https://www.example.com
      Description
      The URL of the link
  - deletedboolean
    Description
    Deletion status of the library item
- objectlibrary-item-classification[]
  - idstring
    Example
    tttbe1ce36ce4b4c37f7060c76d241e7
    Description
    A unique identifier for a library item, represented as compacted UUID using 32 hexadecimal characters.
  - libraryIdstring
    Example
    9f71c88b7d7942ffa316c7a450c89358
    Description
    Id of the library that the item belongs to
  - namestring
    Example
    Library item 1
    Description
    The name of the library item
  - typestring<embedded_value>
    Example
    embedded_value
    Description
    Type of the library item, valid values are "embedded_value"
    Allowed
    embedded_value
  - parentIdstring
    Example
    502b06247f744b7492fd1a44e386f21e
    Description
    A unique identifier for the parent of the library item.
    
    Represented as compacted UUID using 32 hexadecimal characters.
    
    If no parent is present, the value is null.
  - classificationobject
    - identificationstring
      Example
      A1
      Description
      Identification of the classification
    - descriptionstring
      Example
      Classification description
      Description
      Description of the classification
  - deletedboolean
    Description
    Deletion status of the library item

curl

curl --request POST \
     --url https://api.catenda.com/v2/projects/{project-id}/libraries/{library-id}/items \
     --header 'accept: application/json' \
     --header 'bimsync-params: {"name":"string","document":{}}'

javascript

var myHeaders = new Headers();
myHeaders.append("accept", "application/json");
myHeaders.append("content-type", "application/json");
myHeaders.append("bimsync-params", "{\"name\":\"string\",\"document\":{}}");

var requestOptions = {
   method: 'POST',
   headers: myHeaders,
   redirect: 'follow'
};

fetch("https://api.catenda.com/v2/projects/{project-id}/libraries/{library-id}/items", requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));

ruby

require "uri"
require "json"
require "net/http"

url = URI("https://api.catenda.com/v2/projects/{project-id}/libraries/{library-id}/items")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["accept"] = "application/json"
request["content-type"] = "application/json"
request["bimsync-params"] = "{\"name\":\"string\",\"document\":{}}"

response = https.request(request)
puts response.read_body

python

import requests
import json

url = "https://api.catenda.com/v2/projects/{project-id}/libraries/{library-id}/items"

payload = {}
headers = {
   'accept': 'application/json',
   'content-type': 'application/json',
   'bimsync-params': '{"name":"string","document":{}}'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

200

// OK
{}