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 attributes fields, content, and contentMeta.

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

The item object

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

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

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

  • Not supported when object is set to "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",
    "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).

  • Not supported when updating a collection.

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

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

Get an item (including content) or collection

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

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