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 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": [] }
  }
}

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

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.

• 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.

• 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"
      }
    ]
  }
}