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

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

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

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

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:

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