--- title: Create item slug: document-api/create-item docTags: createdAt: 2025-10-20T09:39:14.634Z --- { "id": "YD_Jx5uiC0PV7DeUF6xZv", "type": "api-oas-v2", "data": { "method": "POST", "url": "https://api.catenda.com/v2/projects/{project-id}/libraries/{library-id}/items", "servers": [ { "url": "https://api.catenda.com/v2/projects/{project-id}/libraries/{library-id}/items" } ], "name": "Create item", "description": "

Add a new library item.

\n

Supported library types are document, link and classification.

\n

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

\n", "contentType": "application/json", "request": { "pathParameters": [ { "kind": "required", "name": "project-id", "type": "string", "example": "af2d8af0fa54465b89bf26dd3d92cfd0", "description": "Catenda project id" }, { "kind": "required", "name": "library-id", "type": "string", "description": "Id of the library" } ], "headerParameters": [ { "name": "accept", "type": "string", "kind": "optional", "description": "Generated from available response content types", "enum": [ "application/json" ], "default": "application/json" }, { "kind": "optional", "name": "Bimsync-Params", "type": "object", "description": "

Upload parameters, as a JSON object.

\n

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.

", "customType": "library-item-upload-params", "schema": [ { "name": "name", "kind": "required", "type": "string", "description": "Name of the document", "example": "Document Name" }, { "name": "parentId", "kind": "optional", "type": "string", "description": "

A unique identifier for the parent of the library item represented as compacted UUID using 32 hexadecimal characters.

\n

If no parent is present, the parent is the root of the library.

", "example": "924809076a694255b589d236517a55da" }, { "name": "document", "kind": "optional", "type": "object", "description": "Fields specific for document library items.", "example": "", "schema": [ { "name": "type", "kind": "optional", "type": "string", "description": "Value must be \"file\".", "example": "file", "enum": [ "file" ] }, { "name": "filename", "kind": "optional", "type": "string", "description": "Name of the document revision.", "example": "Document Revision Name" } ] }, { "name": "failOnDocumentExists", "kind": "optional", "type": "boolean", "description": "

Supported in libraries of type document.

\n

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.

", "example": true } ], "modelRef": "#/components/schemas/library-item-upload-params" } ], "queryParameters": [], "bodyDataParameters": [ { "kind": "optional", "name": "body", "type": "object", "description": "", "schema": [], "complexItems": [ { "name": "object", "schema": [ { "name": "name", "kind": "optional", "type": "string", "description": "The name of the folder", "example": "Folder name 1" }, { "name": "type", "kind": "optional", "type": "string", "description": "

The type of document, value must be set to \"folder\"

", "example": "folder", "enum": [ "folder" ] }, { "name": "parentId", "kind": "optional", "type": "string", "nullable": true, "description": "

A unique identifier for the parent of the library item.

\n

Represented as compacted UUID using 32 hexadecimal characters.

\n

If no parent is present, the value is null.

", "example": "502b06247f744b7492fd1a44e386f21e" }, { "name": "document", "kind": "optional", "type": "object", "description": "", "example": "", "schema": [ { "name": "type", "kind": "optional", "type": "string", "description": "Value is folder", "example": "folder" } ] } ], "modelRef": "#/components/schemas/library-item-document-create", "customType": "library-item-document-create" }, { "name": "object", "schema": [ { "name": "name", "kind": "optional", "type": "string", "description": "The name of the library item", "example": "Library item 1" }, { "name": "type", "kind": "optional", "type": "string", "description": "

Type of the library item, value must be set to \"link\"

", "example": "link", "enum": [ "link" ] }, { "name": "link", "kind": "optional", "type": "object", "description": "", "example": "", "schema": [ { "name": "url", "kind": "optional", "type": "string", "description": "The URL of the link", "example": "https://www.example.com" } ] } ], "modelRef": "#/components/schemas/library-item-link-create", "customType": "library-item-link-create" }, { "name": "object", "schema": [ { "name": "name", "kind": "optional", "type": "string", "description": "The name of the library item", "example": "Library item 1" }, { "name": "type", "kind": "optional", "type": "string", "description": "

Type of the library item, value must be set to \"classification\"

", "example": "classification", "enum": [ "classification" ] }, { "name": "parentId", "kind": "optional", "type": "string", "nullable": true, "description": "

A unique identifier for the parent of the library item.

\n

Represented as compacted UUID using 32 hexadecimal characters.

\n

If no parent is present, the value is null.

", "example": "502b06247f744b7492fd1a44e386f21e" }, { "name": "classification", "kind": "optional", "type": "object", "description": "", "example": "", "schema": [ { "name": "identification", "kind": "optional", "type": "string", "description": "Identification of the classification", "example": "A1" }, { "name": "description", "kind": "optional", "type": "string", "description": "Description of the classification", "example": "Classification description" } ] } ], "modelRef": "#/components/schemas/library-item-classification-create", "customType": "library-item-classification-create" } ], "complexType": "oneOf", "isExpanded": true } ], "formDataParameters": [], "oAuthParameters": [ { "id": "Bearer", "name": "Bearer", "kind": "optional", "type": "http", "scheme": "bearer" } ], "cookieParameters": [] }, "responses": [ { "statusCode": "200", "description": "OK", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "", "schema": [], "complexItems": [ { "name": "object", "schema": [ { "name": "id", "kind": "optional", "type": "string", "description": "

A unique identifier for a library item, represented as compacted UUID using 32 hexadecimal characters.

", "example": "tttbe1ce36ce4b4c37f7060c76d241e7" }, { "name": "libraryId", "kind": "optional", "type": "string", "description": "Id of the library that the item belongs to", "example": "9f71c88b7d7942ffa316c7a450c89358" }, { "name": "name", "kind": "optional", "type": "string", "description": "The name of the library item", "example": "Library item 1" }, { "name": "type", "kind": "optional", "type": "string", "description": "

Type of the document library item, valid values are:

\n
    \n
  • document
    • \n
  • folder
    • \n
", "example": "document", "enum": [ "document", "folder" ] }, { "name": "parentId", "kind": "optional", "type": "string", "nullable": true, "description": "

A unique identifier for the parent of the library item.

\n

Represented as compacted UUID using 32 hexadecimal characters.

\n

If no parent is present, the value is null.

", "example": "502b06247f744b7492fd1a44e386f21e" }, { "name": "document", "kind": "optional", "type": "object", "description": "", "complexType": "oneOf", "complexItems": [ { "name": "file", "description": "", "modelRef": "#/components/schemas/file", "schema": [ { "name": "type", "kind": "optional", "type": "string", "description": "Value is file", "example": "file" }, { "name": "createdAt", "kind": "optional", "type": "string", "description": "The date and time the file was created in ISO 8601 format", "example": "2023-12-09T10:07:56.000Z" }, { "name": "owner", "kind": "optional", "type": "string", "description": "User id of the file owner", "example": "gh7fe246cea6442834052404eth08drj" }, { "name": "revision", "kind": "optional", "type": "object", "description": "", "modelRef": "#/components/schemas/library-item-document-file-revision", "customType": "library-item-document-file-revision", "schema": [ { "name": "id", "kind": "optional", "type": "string", "description": "Id of the revision", "example": "h4c21c0e89774c8e92f42959c73561yh" }, { "name": "parentId", "kind": "optional", "type": "string", "nullable": true, "description": "

A unique identifier for the parent of the library item.

\n

Represented as compacted UUID using 32 hexadecimal characters.

\n

If no parent is present, the value is null.

" }, { "name": "version", "kind": "optional", "type": "number", "description": "Version of the revision", "example": 9 }, { "name": "extendedVersion", "kind": "optional", "type": "object", "description": "Extended version of the revision", "example": "", "schema": [ { "name": "major", "kind": "optional", "type": "number", "description": "Major version of the revision", "example": 1 }, { "name": "minor", "kind": "optional", "type": "string", "nullable": true, "description": "Minor version of the revision", "example": 1 } ] }, { "name": "name", "kind": "optional", "type": "string", "description": "File name of the revision", "example": "File.txt" }, { "name": "createdAt", "kind": "optional", "type": "string", "description": "The date and time the revision was created in ISO 8601 format", "example": "2023-03-01T11:52:45.000Z" }, { "name": "size", "kind": "optional", "type": "number", "description": "Size of the file in bytes", "example": 3745 }, { "name": "createdBy", "kind": "optional", "type": "object", "description": "

Represents a User, Organization or Team.

\n

A User is someone with a Catenda account, commonly representing a person.

\n

An Organization represents a company, project organization or an application. Organizations do not have a username and cannot sign in to Catenda.

\n

A Team represents a group of users within a project. Teams do not have a username and cannot sign in to Catenda.

", "modelRef": "#/components/schemas/user", "customType": "user", "schema": [ { "name": "id", "kind": "optional", "type": "string", "description": "Represented as compacted UUID using 32 hexadecimal characters", "example": "524809076a694255b989d236517a55da" }, { "name": "name", "kind": "optional", "type": "string", "description": "

The name of the user, limited to 128 characters

", "example": "John Doe" }, { "name": "username", "kind": "optional", "type": "string", "nullable": true, "description": "

The handle the user identifies with.

\n

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.

\n

If the user represents an organization or a team the value is always null.

\n

Limited to 50 characters.

", "example": "john@doe.com" }, { "name": "email", "kind": "optional", "type": "string", "description": "Email address of the User", "example": "john@doe.com" }, { "name": "createdAt", "kind": "optional", "type": "string", "description": "The date and time the user was created in ISO 8601 format", "example": "2016-09-20T14:55:22.000Z" }, { "name": "avatarUrl", "kind": "optional", "type": "string", "description": "The URL for the user avatar", "example": "https://api.catenda.com/v2/avatar/397t0ccd8f74516096c738de15dc6512" }, { "name": "type", "kind": "optional", "type": "string", "description": "

The type of user, valid values are:

\n
    \n
  • user
    • \n
  • organization
    • \n
  • team
    • \n
", "example": "user", "enum": [ "user", "organization", "team" ] } ] }, { "name": "additionalFormats", "kind": "optional", "type": "array", "description": "Additional formats available for the file revision", "example": "", "itemType": "object", "customType": "object[]", "schema": [ { "name": "size", "kind": "optional", "type": "number", "description": "Size of the file in bytes", "example": 7147 }, { "name": "mediaType", "kind": "optional", "type": "string", "description": "Media type of the additional format file", "example": "application/xod" } ] }, { "name": "downloadFileName", "kind": "optional", "type": "string", "description": "Filename on disk", "example": "File-1.txt" } ] } ] }, { "name": "folder", "description": "", "modelRef": "#/components/schemas/folder", "schema": [ { "name": "type", "kind": "optional", "type": "string", "description": "Value is folder", "example": "folder" }, { "name": "createdAt", "kind": "optional", "type": "string", "description": "The date and time the folder was created in ISO 8601 format", "example": "2023-12-09T10:07:56.000Z" }, { "name": "owner", "kind": "optional", "type": "string", "description": "User id of the folder owner", "example": "gh7fe246cea6442834052404eth08drj" } ] } ], "schema": [] }, { "name": "deleted", "kind": "optional", "type": "boolean", "description": "Deletion status of the library item", "example": false } ], "type": "array", "modelRef": "#/components/schemas/library-item-document", "customType": "library-item-document[]" }, { "name": "object", "schema": [ { "name": "id", "kind": "optional", "type": "string", "description": "

A unique identifier for a library item, represented as compacted UUID using 32 hexadecimal characters.

", "example": "tttbe1ce36ce4b4c37f7060c76d241e7" }, { "name": "libraryId", "kind": "optional", "type": "string", "description": "Id of the library that the item belongs to", "example": "9f71c88b7d7942ffa316c7a450c89358" }, { "name": "name", "kind": "optional", "type": "string", "description": "The name of the library item", "example": "Library item 1" }, { "name": "type", "kind": "optional", "type": "string", "description": "

Type of the library item, valid values are \"link\"

", "example": "link", "enum": [ "link" ] }, { "name": "parentId", "kind": "optional", "type": "string", "nullable": true, "description": "

A unique identifier for the parent of the library item.

\n

Represented as compacted UUID using 32 hexadecimal characters.

\n

If no parent is present, the value is null.

", "example": "502b06247f744b7492fd1a44e386f21e" }, { "name": "link", "kind": "optional", "type": "object", "description": "", "example": "", "schema": [ { "name": "url", "kind": "optional", "type": "string", "description": "The URL of the link", "example": "https://www.example.com" } ] }, { "name": "deleted", "kind": "optional", "type": "boolean", "description": "Deletion status of the library item", "example": false } ], "type": "array", "modelRef": "#/components/schemas/library-item-link", "customType": "library-item-link[]" }, { "name": "object", "schema": [ { "name": "id", "kind": "optional", "type": "string", "description": "

A unique identifier for a library item, represented as compacted UUID using 32 hexadecimal characters.

", "example": "tttbe1ce36ce4b4c37f7060c76d241e7" }, { "name": "libraryId", "kind": "optional", "type": "string", "description": "Id of the library that the item belongs to", "example": "9f71c88b7d7942ffa316c7a450c89358" }, { "name": "name", "kind": "optional", "type": "string", "description": "The name of the library item", "example": "Library item 1" }, { "name": "type", "kind": "optional", "type": "string", "description": "

Type of the library item, valid values are \"embedded_value\"

", "example": "embedded_value", "enum": [ "embedded_value" ] }, { "name": "parentId", "kind": "optional", "type": "string", "nullable": true, "description": "

A unique identifier for the parent of the library item.

\n

Represented as compacted UUID using 32 hexadecimal characters.

\n

If no parent is present, the value is null.

", "example": "502b06247f744b7492fd1a44e386f21e" }, { "name": "classification", "kind": "optional", "type": "object", "description": "", "example": "", "schema": [ { "name": "identification", "kind": "optional", "type": "string", "description": "Identification of the classification", "example": "A1" }, { "name": "description", "kind": "optional", "type": "string", "description": "Description of the classification", "example": "Classification description" } ] }, { "name": "deleted", "kind": "optional", "type": "boolean", "description": "Deletion status of the library item", "example": false } ], "type": "array", "modelRef": "#/components/schemas/library-item-classification", "customType": "library-item-classification[]" } ], "complexType": "oneOf", "isExpanded": true } ] } ], "hasXCodeSamples": false, "examples": { "languages": [ { "id": "6rvl8jZwpTAnjSac8OZN0", "language": "curl", "label": "cURL", "code": "curl --request POST \\\n --url https://api.catenda.com/v2/projects/{project-id}/libraries/{library-id}/items \\\n --header 'accept: application/json' \\\n --header 'bimsync-params: {\"name\":\"string\",\"document\":{}}'" }, { "id": "kqmtkdetpNe_QrM9WNOh5", "language": "javascript", "label": "javascript", "code": "var myHeaders = new Headers();\nmyHeaders.append(\"accept\", \"application/json\");\nmyHeaders.append(\"content-type\", \"application/json\");\nmyHeaders.append(\"bimsync-params\", \"{\\\"name\\\":\\\"string\\\",\\\"document\\\":{}}\");\n\nvar requestOptions = {\n method: 'POST',\n headers: myHeaders,\n redirect: 'follow'\n};\n\nfetch(\"https://api.catenda.com/v2/projects/{project-id}/libraries/{library-id}/items\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));" }, { "id": "kgtDBk2eJUQzLW7WEVdWl", "language": "ruby", "label": "Ruby", "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://api.catenda.com/v2/projects/{project-id}/libraries/{library-id}/items\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Post.new(url)\nrequest[\"accept\"] = \"application/json\"\nrequest[\"content-type\"] = \"application/json\"\nrequest[\"bimsync-params\"] = \"{\\\"name\\\":\\\"string\\\",\\\"document\\\":{}}\"\n\nresponse = https.request(request)\nputs response.read_body\n" }, { "id": "WukMhw1HpeZcrUXBDyjoM", "language": "python", "label": "Python", "code": "import requests\nimport json\n\nurl = \"https://api.catenda.com/v2/projects/{project-id}/libraries/{library-id}/items\"\n\npayload = {}\nheaders = {\n 'accept': 'application/json',\n 'content-type': 'application/json',\n 'bimsync-params': '{\"name\":\"string\",\"document\":{}}'\n}\n\nresponse = requests.request(\"POST\", url, headers=headers, data=payload)\n\nprint(response.text)\n" } ], "selectedLanguageId": "6rvl8jZwpTAnjSac8OZN0" }, "results": { "languages": [ { "id": "WchAKcbt-aw6yAmyXjPdx", "language": "200", "code": "// OK\n{}" } ], "selectedLanguageId": "WchAKcbt-aw6yAmyXjPdx" } }, "children": [ { "text": "" } ] }