--- title: List items slug: document-api/list-items docTags: createdAt: 2025-10-20T09:39:14.634Z --- { "id": "--Jvkad7V_bjS1lmUEl5z", "type": "api-oas-v2", "data": { "method": "GET", "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": "List items", "description": "

List all library items.

\n

If the library supports revisions then the latest revision for each item will be returned.

\n

Supported library types are document, link, embedded_value and classification.

", "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" } ], "queryParameters": [ { "kind": "optional", "name": "parentId", "type": "string", "description": "

Parent item of the library items, represented as compacted UUID using 32 hexadecimal characters. Setting this will only list the items with this parentId, to specify the root items, set parentId to root.

" }, { "kind": "optional", "name": "associations", "type": "string", "description": "Limit result to only contain library items linked to the specified IFC guids. Provide a comma separated list of IFC guids." }, { "kind": "optional", "name": "labels", "type": "string", "description": "Filter the result by providing a comma separated list of label ids." }, { "kind": "optional", "name": "search", "type": "string", "description": "Filter the result by search text." }, { "kind": "optional", "name": "createdAtFrom", "type": "string", "description": "Filter the result by providing a date in ISO 8601 format.\n\nResult will only contain items created after this date.\n" }, { "kind": "optional", "name": "createdAtTo", "type": "string", "description": "Filter the result by providing a date in ISO 8601 format.\n\nResult will only contain items created before this date.\n" }, { "kind": "optional", "name": "revisionCreatedAtFrom", "type": "string", "description": "Filter the result by providing a date in ISO 8601 format.\n\nResult will only contain items with the last revision being created after this date.\n" }, { "kind": "optional", "name": "revisionCreatedAtTo", "type": "string", "description": "Filter the result by providing a date in ISO 8601 format.\n\nResult will only contain items with the last revision being created before this date.\n" }, { "kind": "optional", "name": "include", "type": "string", "description": "

Comma separated list of referenced properties that will be added to the items of the result. Valid values are labels, labelGroups and path.

" }, { "kind": "optional", "name": "subFolders", "type": "boolean", "description": "

Include library items within folders in result, recursive search.

" }, { "kind": "optional", "name": "scope", "type": "string", "description": "

Determine which library items to return.

\n", "enum": [ "all", "published" ] }, { "kind": "optional", "name": "page", "type": "integer", "description": "Default value is 1" }, { "kind": "optional", "name": "pageSize", "type": "integer", "description": "

Default 100, max 1000

" } ], "bodyDataParameters": [], "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", "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", "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": "deleted", "kind": "optional", "type": "boolean", "description": "Deletion status of the library item", "example": false } ], "type": "array", "modelRef": "#/components/schemas/library-item-embedded_value", "customType": "library-item-embedded_value[]" }, { "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": "zSo_1gkxCHnHkgFDtG4Ou", "language": "curl", "label": "cURL", "code": "curl --request GET \\\n --url https://api.catenda.com/v2/projects/{project-id}/libraries/{library-id}/items \\\n --header 'accept: application/json'" }, { "id": "UT3rBJhSkNwrQQIYZlDWb", "language": "javascript", "label": "javascript", "code": "var myHeaders = new Headers();\nmyHeaders.append(\"accept\", \"application/json\");\nmyHeaders.append(\"content-type\", \"application/json\");\n\nvar requestOptions = {\n method: 'GET',\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": "YFc1xwboy1myjX3Xv6cvD", "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::Get.new(url)\nrequest[\"accept\"] = \"application/json\"\nrequest[\"content-type\"] = \"application/json\"\n\nresponse = https.request(request)\nputs response.read_body\n" }, { "id": "EREYWQeKQ0116z8akHDVA", "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}\n\nresponse = requests.request(\"GET\", url, headers=headers, data=payload)\n\nprint(response.text)\n" } ], "selectedLanguageId": "zSo_1gkxCHnHkgFDtG4Ou" }, "results": { "languages": [ { "id": "Mx8alwHFlElIqVixsBrYY", "language": "200", "code": "// OK\n{}" } ], "selectedLanguageId": "Mx8alwHFlElIqVixsBrYY" } }, "children": [ { "text": "" } ] }