Items and Collections

Items and collections are managed via the same endpoint as they share many properties and appear in the same contexts.

The collection object

The collection object has a childIds attribute, but it does not have the fields attribute.

object string: "collection"
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 collection IDs.
content string: The content of the item formatted as Markdown (see Item content format).
contentVersion integer: A counter that increments on every content change. Pass it to the partial content update endpoint (PATCH /v0/items/:id/content) for optimistic concurrency control.
contentMeta object
- itemIds Array[uuid]: An array of IDs of all the items and collections that appear inside the content.
- fileIds Array[uuid]: An array of IDs of all the files that appear inside the content.

The item object

The item object does not have a childIds attribute, but it has the fields attribute.

object string: "item"
id uuid
workspaceId uuid
url string
title string
createdAt date
createdUserId uuid
lastUpdatedAt date
lastUpdatedUserId uuid
fields object: An object mapping field names to field values (see Fields).
content string: The content of the item formatted as Markdown (see Item content format).
contentVersion integer: A counter that increments on every content change. Pass it to the partial content update endpoint (PATCH /v0/items/:id/content) for optimistic concurrency control.
contentMeta object
- itemIds Array[uuid]: An array of IDs of all the items and collections that appear inside the content.
- fileIds Array[uuid]: An array of IDs of all the files that appear inside the content.

Create an item or collection

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 collection where the item should be created.
- Should not be set if workspaceId is set.
object string (optional, default: "item"): Either "item" or "collection"
title string (optional)
content string (optional): Content formatted as Markdown (see Item content format).
fields object (optional): Field values to set on the item, mapping field names to values (see Fields). Only applies when creating an item (not a collection).
index integer (optional): The zero-based index at which to insert the item/collection in the parent. Defaults to the end of the parent.

Example request

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."}'

Example response

{
  "status": "success",
  "data": {
    "object": "item",
    "id": "561dc946-088d-444a-9061-f4a38a2543f3",
    "workspaceId": "127a8c4a-b3c6-4a42-8fef-b6c521e6c8cf",
    "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",
    "fields": {},
    "content": "Some markdown text.\n",
    "contentVersion": 7,
    "contentMeta": { "itemIds": [], "fileIds": [] }
  }
}

Update an item or collection

Endpoint: PUT /v0/items/:id

Body:

title string (optional)
content string (optional): Content formatted as Markdown (see Item content format).
fields object (optional): Field values to set, mapping field names to values (see Fields). Only the fields you include are changed; set a field to null to clear it.

At least one of title, content, or fields must be provided.

Example request

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"}'

Example response

{
  "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",
    "fields": {},
    "content": "Updated content\n",
    "contentVersion": 7,
    "contentMeta": { "itemIds": [], "fileIds": [] }
  }
}

Example request (setting field values)

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 '{"fields": {"Status": "Done", "Due date": "2025-01-20"}}'

Example response

{
  "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": "My item",
    "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",
    "fields": {
      "Status": { "id": "561dc946-088d-444a-9061-f4a38a2543f3", "name": "Done" },
      "Due date": "2025-01-20"
    },
    "content": "Some markdown text.\n",
    "contentVersion": 7,
    "contentMeta": { "itemIds": [], "fileIds": [] }
  }
}

Update the content of an item or collection (partial edit)

Endpoint: PATCH /v0/items/:id/content

Applies a batch of line-based edits to the item's Markdown content instead of replacing all of it — more efficient than PUT for small changes to large items. Line numbers are 1-based and refer to the Markdown returned by the GET endpoint for the item.

Body:

contentVersion integer: The contentVersion from your most recent read of the item. If it no longer matches the item's current version, the request is rejected with a 409 so you can re-fetch and retry.
edits Array: A list of non-overlapping edits, each with:
- from integer: First line of the range to replace (1-based, inclusive).
- to integer: Last line of the range (1-based, inclusive). Use the same value as from to affect a single line.
- text string (optional): The replacement Markdown for the range. Omit it (or pass null or an empty string) to delete the lines.

At least one edit is required. The endpoint returns the full updated item, including its new contentVersion. Edits that reference out-of-range lines or overlap each other are rejected with a 422.

Example request

curl https://api.nuclino.com/v0/items/a18e9b3d-268a-4551-8cd8-4ee42022387c/content \
  -X PATCH \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contentVersion": 12, "edits": [{"from": 3, "to": 3, "text": "Updated third line"}]}'

Example response

{
  "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": "My item",
    "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",
    "fields": {},
    "content": "First line\n\nUpdated third line\n",
    "contentVersion": 13,
    "contentMeta": { "itemIds": [], "fileIds": [] }
  }
}

Move an item or collection

Endpoint: POST /v0/items/:id/move

Moves the item or collection to a new location and removes it from all the collections it currently appears in (including the trash and archive). Collections are moved together with all of their children.

Body:

workspaceId uuid: The ID of the workspace to whose top level the item should be moved.
- Should not be set if parentId is set.
parentId uuid: The ID of the collection the item should be moved into.
- Should not be set if workspaceId is set.
index integer (optional): The zero-based position among the children of the new parent. Defaults to the end of the parent.

The target can be in a different workspace of the same team. In that case, field values are carried over to fields with the same name and type in the target workspace (select options are matched by name) and dropped otherwise. Moving requires edit access in both the source and the target workspace (403). A collection cannot be moved into itself or one of its descendants (422).

Example request

curl https://api.nuclino.com/v0/items/aaf6d580-565d-497b-9ff3-b32075de3f4c/move \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"parentId":"e9e648b3-8ce3-410d-8ef8-51b46c63cdaf", "index":0}'

Example response

{
  "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",
    "fields": {
      "My date field": "2025-01-20"
    },
    "content": "Hello world!\n",
    "contentVersion": 7,
    "contentMeta": { "itemIds": [], "fileIds": [] }
  }
}

Get items and collections

Endpoint: GET /v0/items

Query parameters:

teamId uuid : Filter items and collections that belong to the given team.
- Should not be set if workspaceId is set.
workspaceId uuid: Filter items and collections 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 collections that come after the given ID (used for pagination usually in combination with the limit parameter).

Response:

This endpoint does not include the content field in its response. To get the content of an item or collection, please use the GET endpoint for individual items and collections.

Example request

curl 'https://api.nuclino.com/v0/items?workspaceId=127a8c4a-b3c6-4a42-8fef-b6c521e6c8cf&limit=2' \
  -H "Authorization: YOUR_API_KEY"

Example response

{
  "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",
        "fields": {
          "My date field": "2025-01-20"
        },
        "contentMeta": { "itemIds": [], "fileIds": [] }
      },
      {
        "object": "collection",
        "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 collection",
        "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": [],
        "contentMeta": { "itemIds": [], "fileIds": [] }
      }
    ]
  }
}

Get an item or collection (including content)

Endpoint: GET /v0/items/:id

Response:

This endpoint returns a full object including the content.

Example request

curl https://api.nuclino.com/v0/items/aaf6d580-565d-497b-9ff3-b32075de3f4c \
  -H "Authorization: YOUR_API_KEY"

Example response

{
  "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",
    "fields": {
      "My date field": "2025-01-20"
    },
    "content": "Hello world!\n",
    "contentVersion": 7,
    "contentMeta": { "itemIds": [], "fileIds": [] }
  }
}

Delete an item or collection

Endpoint: DELETE /v0/items/:id

This will move the item/collection to the workspace trash.

Example request

curl https://api.nuclino.com/v0/items/aaf6d580-565d-497b-9ff3-b32075de3f4c \
  -X DELETE \
  -H "Authorization: YOUR_API_KEY"

Example response

{
  "status": "success",
  "data": { "id": "aaf6d580-565d-497b-9ff3-b32075de3f4c" }
}

The version object

Nuclino automatically saves versions of an item's content, for example after larger edits or deletions, after a pause in editing, and before a version is restored.

object string: "version"
itemId uuid
version integer: The version number. It corresponds to the item's contentVersion at the time the version was saved.
title string: The title of the item at the time the version was saved.
createdAt date
authorIds Array[uuid]: The users whose edits since the previous version led to this version.
content string: The content of the version formatted as Markdown (see Item content format). Only included when getting a single version.

Get the versions of an item or collection

Endpoint: GET /v0/items/:id/versions

Query parameters:

limit integer (optional, default: 100): Number between 1 and 100 to limit the results.
before integer (optional): Only return versions older than the given version number (used for pagination usually in combination with the limit parameter).

Response:

The versions are sorted from newest to oldest and do not include the content. The current content of the item is not part of the list; use the GET endpoint for individual items and collections to get it.

Example request

curl 'https://api.nuclino.com/v0/items/aaf6d580-565d-497b-9ff3-b32075de3f4c/versions?limit=2' \
  -H "Authorization: YOUR_API_KEY"

Example response

{
  "status": "success",
  "data": {
    "object": "list",
    "results": [
      {
        "object": "version",
        "itemId": "aaf6d580-565d-497b-9ff3-b32075de3f4c",
        "version": 42,
        "title": "My Item",
        "createdAt": "2026-09-23T14:12:08.132Z",
        "authorIds": ["2e96f3bb-c742-4164-af2c-151ab2fd346b"]
      },
      {
        "object": "version",
        "itemId": "aaf6d580-565d-497b-9ff3-b32075de3f4c",
        "version": 17,
        "title": "My Item",
        "createdAt": "2026-09-20T09:30:51.720Z",
        "authorIds": ["2e96f3bb-c742-4164-af2c-151ab2fd346b"]
      }
    ]
  }
}

Get a version of an item or collection (including content)

Endpoint: GET /v0/items/:id/versions/:version

Example request

curl https://api.nuclino.com/v0/items/aaf6d580-565d-497b-9ff3-b32075de3f4c/versions/17 \
  -H "Authorization: YOUR_API_KEY"

Example response

{
  "status": "success",
  "data": {
    "object": "version",
    "itemId": "aaf6d580-565d-497b-9ff3-b32075de3f4c",
    "version": 17,
    "title": "My Item",
    "createdAt": "2026-09-20T09:30:51.720Z",
    "authorIds": ["2e96f3bb-c742-4164-af2c-151ab2fd346b"],
    "content": "Hello world!\n"
  }
}

Restore a version of an item or collection

Endpoint: POST /v0/items/:id/versions/:version/restore

Restores the content of the item or collection to the given version. Only the content is restored; the title and field values are not changed. The current content is saved as a new version first, so a restore can be undone. Restoring requires edit access to the workspace (403).

The endpoint returns the full updated item, including its new contentVersion.

Example request

curl https://api.nuclino.com/v0/items/aaf6d580-565d-497b-9ff3-b32075de3f4c/versions/17/restore \
  -X POST \
  -H "Authorization: YOUR_API_KEY"

Example response

{
  "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": "2026-09-24T10:02:53.487Z",
    "lastUpdatedUserId": "2e96f3bb-c742-4164-af2c-151ab2fd346b",
    "fields": {},
    "content": "Hello world!\n",
    "contentVersion": 44,
    "contentMeta": { "itemIds": [], "fileIds": [] }
  }
}

Search items and collections

Endpoint: GET /v0/items

teamId uuid: Filter items and collections that belong to the given team.
- Should not be set if workspaceId is set.
workspaceId uuid: Filter items and collections 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 collections (max. 100 characters).
limit integer (optional, default: 100): Number between 1 and 100 to limit the results.

Response:

This endpoint does not include the content field in its response. To get the content of an item or collection, please use the GET endpoint for individual items and collections.
Items and collections in the trash or archive are not included in the results.
Each object will include an additional highlight attribute, which can be used to display search matches.

Example request

curl 'https://api.nuclino.com/v0/items?workspaceId=127a8c4a-b3c6-4a42-8fef-b6c521e6c8cf&search=hello' \
  -H "Authorization: YOUR_API_KEY"

Example response

{
  "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:19:20.779Z",
        "lastUpdatedUserId": "2e96f3bb-c742-4164-af2c-151ab2fd346b",
        "fields": {
          "My date field": "2025-01-20"
        },
        "contentMeta": { "itemIds": [], "fileIds": [] },
        "highlight": "test item saying <b>hello</b> to the world"
      }
    ]
  }
}

Items and Collections

The collection object

The item object

Create an item or collection

Example request

Example response

Update an item or collection

Example request

Example response

Example request (setting field values)

Example response

Update the content of an item or collection (partial edit)

Example request

Example response

Move an item or collection

Example request

Example response

Get items and collections

Example request

Example response

Get an item or collection (including content)

Example request

Example response

Delete an item or collection

Example request

Example response

The version object

Get the versions of an item or collection

Example request

Example response

Get a version of an item or collection (including content)

Example request

Example response

Restore a version of an item or collection

Example request

Example response

Search items and collections

Example request

Example response

Product

Company

Resources

Follow us