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

The cluster object

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

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.

Create an item or cluster

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.

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

Update an item or cluster

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.

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

Get items and clusters

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.

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

Get an item (including content) or cluster

Endpoint: GET /v0/items/:id

Response:

• This endpoint returns a full item 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",
    "content": "Hello world!\n",
    "contentMeta": { "itemIds": [], "fileIds": [] }
  }
}

Delete an item or cluster

Endpoint: DELETE /v0/items/:id

This will move the item/cluster 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 clusters

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.

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