Items and clusters are managed via the same endpoint as they share many properties and appear in the same contexts.
The cluster object has a childIds
attribute, but it does not have content related attributes.
object
string: "cluster"
id
uuid
workspaceId
uuid
url
string
title
string
createdAt
date
createdUserId
uuid
lastUpdatedAt
date
lastUpdatedUserId
uuid
childIds
Array[uuid]: An array of all the child item and cluster IDs of this cluster.
The item object does not have a childIds
attribute, but it has content related attributes.
object
string: "item"
id
uuid
workspaceId
uuid
url
string
title
string
createdAt
date
createdUserId
uuid
lastUpdatedAt
date
lastUpdatedUserId
uuid
content
string: The content of the item formatted as Markdown (see Item content format).
contentMeta
object
itemIds
Array[uuid]: An array of IDs of all the items and clusters that appear inside the content.
fileIds
Array[uuid]: An array of IDs of all the files that appear inside the content.
Endpoint: POST /v0/items
Body:
workspaceId
uuid: The ID of the workspace where the item should be created.
Should not be set if parentId
is set.
parentId
uuid: The ID of the cluster where the item should be created.
Should not be set if workspaceId
is set.
object
string (optional, default: "item"): Either "item" or "cluster"
title
string (optional)
content
string (optional): Content formatted as Markdown (see Item content format).
Not supported when object
is set to "cluster".
index
integer (optional): The zero-based index at which to insert the item/cluster in the parent. Defaults to the end of the parent.
curl https://api.nuclino.com/v0/items \
-H "Authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"workspaceId":"127a8c4a-b3c6-4a42-8fef-b6c521e6c8cf", "object":"item", "title":"Hello", "content":"Some markdown text."}'
{
"status": "success",
"data": {
"object": "item",
"id": "561dc946-088d-444a-9061-f4a38a2543f3",
"url": "https://app.nuclino.com/t/b/561dc946-088d-444a-9061-f4a38a2543f3",
"title": "Hello",
"createdAt": "2021-12-15T16:26:54.292Z",
"createdUserId": "2e96f3bb-c742-4164-af2c-151ab2fd346b",
"lastUpdatedAt": "2021-12-15T16:26:54.292Z",
"lastUpdatedUserId": "2e96f3bb-c742-4164-af2c-151ab2fd346b",
"childIds": [],
"content": "Some markdown text.\n",
"contentMeta": { "itemIds": [], "fileIds": [] },
"workspaceId": "127a8c4a-b3c6-4a42-8fef-b6c521e6c8cf"
}
}
Endpoint: PUT /v0/items/:id
Body:
title
string (optional)
content
string (optional): Content formatted as Markdown (see Item content format).
Not supported when updating a cluster.
curl https://api.nuclino.com/v0/items/a18e9b3d-268a-4551-8cd8-4ee42022387c \
-X PUT \
-H "Authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"title":"Updated title", "content":"Updated content"}'
{
"status": "success",
"data": {
"object": "item",
"id": "a18e9b3d-268a-4551-8cd8-4ee42022387c",
"workspaceId": "127a8c4a-b3c6-4a42-8fef-b6c521e6c8cf",
"url": "https://app.nuclino.com/t/b/a18e9b3d-268a-4551-8cd8-4ee42022387c",
"title": "New title",
"createdAt": "2021-12-15T16:51:18.765Z",
"createdUserId": "2e96f3bb-c742-4164-af2c-151ab2fd346b",
"lastUpdatedAt": "2021-12-15T16:52:47.840Z",
"lastUpdatedUserId": "2e96f3bb-c742-4164-af2c-151ab2fd346b",
"content": "Updated content\n",
"contentMeta": { "itemIds": [], "fileIds": [] }
}
}
Endpoint: GET /v0/items
Query parameters:
teamId
uuid : Filter items and clusters that belong to the given team.
Should not be set if workspaceId
is set.
workspaceId
uuid: Filter items and clusters that belong to the given workspace.
Should not be set if teamId
is set.
limit
integer (optional, default: 100): Number between 1 and 100 to limit the results.
after
uuid (optional): Only return items and clusters that come after the given ID (used for pagination usually in combination with the limit
parameter).
Response:
Please note that this endpoint does not return full item objects. Item objects are returned without the content
field. To get the content of an item, please use the GET
endpoint for individual items.
curl 'https://api.nuclino.com/v0/items?workspaceId=127a8c4a-b3c6-4a42-8fef-b6c521e6c8cf&limit=2' \
-H "Authorization: YOUR_API_KEY"
{
"status": "success",
"data": {
"object": "list",
"results": [
{
"object": "item",
"id": "aaf6d580-565d-497b-9ff3-b32075de3f4c",
"workspaceId": "127a8c4a-b3c6-4a42-8fef-b6c521e6c8cf",
"url": "https://app.nuclino.com/t/b/aaf6d580-565d-497b-9ff3-b32075de3f4c",
"title": "My Item",
"createdAt": "2021-12-15T15:55:19.527Z",
"createdUserId": "2e96f3bb-c742-4164-af2c-151ab2fd346b",
"lastUpdatedAt": "2021-12-15T17:02:53.487Z",
"lastUpdatedUserId": "2e96f3bb-c742-4164-af2c-151ab2fd346b",
"contentMeta": { "itemIds": [], "fileIds": [] }
},
{
"object": "cluster",
"id": "e9e648b3-8ce3-410d-8ef8-51b46c63cdaf",
"workspaceId": "127a8c4a-b3c6-4a42-8fef-b6c521e6c8cf",
"url": "https://app.nuclino.com/t/b/e9e648b3-8ce3-410d-8ef8-51b46c63cdaf",
"title": "My cluster",
"createdAt": "2021-12-15T17:02:56.276Z",
"createdUserId": "2e96f3bb-c742-4164-af2c-151ab2fd346b",
"lastUpdatedAt": "2021-12-15T17:03:00.389Z",
"lastUpdatedUserId": "2e96f3bb-c742-4164-af2c-151ab2fd346b",
"childIds": []
}
]
}
}
Endpoint: GET /v0/items/:id
Response:
This endpoint returns a full item object including the content.
curl https://api.nuclino.com/v0/items/aaf6d580-565d-497b-9ff3-b32075de3f4c \
-H "Authorization: YOUR_API_KEY"
{
"status": "success",
"data": {
"object": "item",
"id": "aaf6d580-565d-497b-9ff3-b32075de3f4c",
"workspaceId": "127a8c4a-b3c6-4a42-8fef-b6c521e6c8cf",
"url": "https://app.nuclino.com/t/b/aaf6d580-565d-497b-9ff3-b32075de3f4c",
"title": "My Item",
"createdAt": "2021-12-15T15:55:19.527Z",
"createdUserId": "2e96f3bb-c742-4164-af2c-151ab2fd346b",
"lastUpdatedAt": "2021-12-15T17:02:53.487Z",
"lastUpdatedUserId": "2e96f3bb-c742-4164-af2c-151ab2fd346b",
"content": "Hello world!\n",
"contentMeta": { "itemIds": [], "fileIds": [] }
}
}
Endpoint: DELETE /v0/items/:id
This will move the item/cluster to the workspace trash.
curl https://api.nuclino.com/v0/items/aaf6d580-565d-497b-9ff3-b32075de3f4c \
-X DELETE \
-H "Authorization: YOUR_API_KEY"
{
"status": "success",
"data": { "id": "aaf6d580-565d-497b-9ff3-b32075de3f4c" }
}
Endpoint: GET /v0/items
teamId
uuid: Filter items and clusters that belong to the given team.
Should not be set if workspaceId
is set.
workspaceId
uuid: Filter items and clusters that belong to the given workspace.
Should not be set if teamId
is set.
search
string: The search query used to search for items and clusters.
limit
integer (optional, default: 100): Number between 1 and 100 to limit the results.
Response:
Please note that this endpoint does not return full item objects. Item objects are returned without the content
field. To get the content of an item, please use the GET
endpoint for individual items.
The item object will include an additional highlight
attribute, which can be used to display search matches.
curl 'https://api.nuclino.com/v0/items?workspaceId=127a8c4a-b3c6-4a42-8fef-b6c521e6c8cf&search=hello' \
-H "Authorization: YOUR_API_KEY"
{
"status": "success",
"data": {
"object": "list",
"results": [
{
"object": "item",
"id": "dd9a69db-048d-4644-8738-36bee31bbee0",
"workspaceId": "127a8c4a-b3c6-4a42-8fef-b6c521e6c8cf",
"url": "https://app.nuclino.com/t/b/dd9a69db-048d-4644-8738-36bee31bbee0",
"title": "My Item",
"createdAt": "2021-12-15T17:19:01.500Z",
"createdUserId": "2e96f3bb-c742-4164-af2c-151ab2fd346b",
"lastUpdatedAt": "2021-12-15T17:19:20.779Z",
"lastUpdatedUserId": "2e96f3bb-c742-4164-af2c-151ab2fd346b",
"contentMeta": { "itemIds": [], "fileIds": [] },
"highlight": "test item saying <b>hello</b> to the world"
}
]
}
}