Investigation Notebooks

Access notebooks within an investigation. Notebooks contain the analysis blocks that define process mining workflows.

Prerequisites

Before accessing notebooks via this API, you must load the project into cache using the Project API.

# Load project into cache first
curl -X GET "https://your-mindzie-instance.com/api/{tenantId}/project/{projectId}/load" \
  -H "Authorization: Bearer YOUR_API_KEY"

See Project Cache API for details.

---

List Investigation Notebooks

GET /api/{tenantId}/{projectId}/investigation/{investigationId}/notebooks

Retrieves all notebooks within an investigation from the project cache.

Path Parameters

Parameter	Type	Required	Description
tenantId	GUID	Yes	The tenant identifier
projectId	GUID	Yes	The project identifier
investigationId	GUID	Yes	The investigation identifier

Response (200 OK)

{
  "notebooks": [
    {
      "notebookId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "investigationId": "11111111-2222-3333-4444-555555555555",
      "name": "Main",
      "description": "",
      "dateCreated": "2024-01-15T10:30:00Z",
      "dateModified": "2024-01-20T14:45:00Z",
      "createdBy": null,
      "modifiedBy": null,
      "notebookType": null,
      "notebookOrder": 1.0,
      "lastExecutionDuration": 0,
      "blockCount": 12
    },
    {
      "notebookId": "bbbbbbbb-cccc-dddd-eeee-ffffffffffff",
      "investigationId": "11111111-2222-3333-4444-555555555555",
      "name": "Variant Analysis",
      "description": "",
      "dateCreated": "2024-01-16T09:00:00Z",
      "dateModified": "2024-01-18T11:30:00Z",
      "createdBy": null,
      "modifiedBy": null,
      "notebookType": null,
      "notebookOrder": 2.0,
      "lastExecutionDuration": 0,
      "blockCount": 8
    }
  ],
  "totalCount": 2
}

Notebook Object Fields

Field	Type	Description
notebookId	GUID	Unique identifier for the notebook
investigationId	GUID	Investigation this notebook belongs to
name	string	Display name of the notebook
description	string	Description of the notebook
dateCreated	datetime	When the notebook was created
dateModified	datetime	When the notebook was last modified
createdBy	GUID	User who created the notebook
modifiedBy	GUID	User who last modified the notebook
notebookType	integer	Type of notebook (0 = standard)
notebookOrder	decimal	Display order within the investigation
lastExecutionDuration	double	Last execution time in seconds
blockCount	integer	Number of blocks in the notebook

Error Responses

Not Found (404) - Project not cached:

"Project not found in cache. Please load the project first using the ProjectController.LoadProject endpoint."

Not Found (404) - Investigation not found:

{
  "error": "Investigation not found",
  "investigationId": "11111111-2222-3333-4444-555555555555"
}

---

Get Main Notebook

GET /api/{tenantId}/{projectId}/investigation/{investigationId}/main-notebook

Retrieves the main notebook for an investigation. The main notebook is automatically created when an investigation is created and typically contains the core filtering and analysis workflow.

Path Parameters

Parameter	Type	Required	Description
tenantId	GUID	Yes	The tenant identifier
projectId	GUID	Yes	The project identifier
investigationId	GUID	Yes	The investigation identifier

Response (200 OK)

{
  "notebookId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "investigationId": "11111111-2222-3333-4444-555555555555",
  "name": "Main",
  "description": "Primary analysis notebook",
  "dateCreated": "2024-01-15T10:30:00Z",
  "dateModified": "2024-01-20T14:45:00Z",
  "createdBy": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "modifiedBy": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "notebookType": 0,
  "notebookOrder": 1.0,
  "lastExecutionDuration": 2.5,
  "blockCount": 12
}

Error Responses

Not Found (404) - Investigation not found:

{
  "error": "Investigation not found",
  "investigationId": "11111111-2222-3333-4444-555555555555"
}

Not Found (404) - Main notebook not found:

{
  "error": "Main notebook not found for investigation",
  "investigationId": "11111111-2222-3333-4444-555555555555"
}

---

Implementation Examples

cURL

# Step 1: Load project into cache first
curl -X GET "https://your-mindzie-instance.com/api/12345678-1234-1234-1234-123456789012/project/87654321-4321-4321-4321-210987654321/load" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Step 2: List all notebooks in an investigation
curl -X GET "https://your-mindzie-instance.com/api/12345678-1234-1234-1234-123456789012/87654321-4321-4321-4321-210987654321/investigation/11111111-2222-3333-4444-555555555555/notebooks" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Get the main notebook directly
curl -X GET "https://your-mindzie-instance.com/api/12345678-1234-1234-1234-123456789012/87654321-4321-4321-4321-210987654321/investigation/11111111-2222-3333-4444-555555555555/main-notebook" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Python

import requests

TENANT_ID = '12345678-1234-1234-1234-123456789012'
PROJECT_ID = '87654321-4321-4321-4321-210987654321'
BASE_URL = 'https://your-mindzie-instance.com'

class NotebookAccessor:
    def __init__(self, token):
        self.headers = {
            'Authorization': f'Bearer {token}',
            'Content-Type': 'application/json'
        }

    def load_project(self):
        """Load project into cache before accessing notebooks."""
        url = f'{BASE_URL}/api/{TENANT_ID}/project/{PROJECT_ID}/load'
        response = requests.get(url, headers=self.headers)
        response.raise_for_status()
        return response.json()

    def list_notebooks(self, investigation_id):
        """List all notebooks in an investigation."""
        url = f'{BASE_URL}/api/{TENANT_ID}/{PROJECT_ID}/investigation/{investigation_id}/notebooks'
        response = requests.get(url, headers=self.headers)
        response.raise_for_status()
        return response.json()

    def get_main_notebook(self, investigation_id):
        """Get the main notebook for an investigation."""
        url = f'{BASE_URL}/api/{TENANT_ID}/{PROJECT_ID}/investigation/{investigation_id}/main-notebook'
        response = requests.get(url, headers=self.headers)
        response.raise_for_status()
        return response.json()

# Usage
accessor = NotebookAccessor('your-auth-token')
investigation_id = '11111111-2222-3333-4444-555555555555'

# Step 1: Load project into cache
print("Loading project into cache...")
load_result = accessor.load_project()
print(f"Project loaded: {load_result['projectName']}")

# Step 2: List notebooks
notebooks = accessor.list_notebooks(investigation_id)
print(f"\nFound {notebooks['totalCount']} notebooks:")

for nb in notebooks['notebooks']:
    print(f"  - {nb['name']}: {nb['blockCount']} blocks")

# Get main notebook
main = accessor.get_main_notebook(investigation_id)
print(f"\nMain notebook: {main['name']} ({main['blockCount']} blocks)")

JavaScript/Node.js

const TENANT_ID = '12345678-1234-1234-1234-123456789012';
const PROJECT_ID = '87654321-4321-4321-4321-210987654321';
const BASE_URL = 'https://your-mindzie-instance.com';

class NotebookAccessor {
  constructor(token) {
    this.headers = {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    };
  }

  async loadProject() {
    const url = `${BASE_URL}/api/${TENANT_ID}/project/${PROJECT_ID}/load`;
    const response = await fetch(url, { headers: this.headers });
    if (!response.ok) throw new Error(`Failed: ${response.status}`);
    return await response.json();
  }

  async listNotebooks(investigationId) {
    const url = `${BASE_URL}/api/${TENANT_ID}/${PROJECT_ID}/investigation/${investigationId}/notebooks`;
    const response = await fetch(url, { headers: this.headers });
    if (!response.ok) throw new Error(`Failed: ${response.status}`);
    return await response.json();
  }

  async getMainNotebook(investigationId) {
    const url = `${BASE_URL}/api/${TENANT_ID}/${PROJECT_ID}/investigation/${investigationId}/main-notebook`;
    const response = await fetch(url, { headers: this.headers });
    if (!response.ok) throw new Error(`Failed: ${response.status}`);
    return await response.json();
  }
}

// Usage
const accessor = new NotebookAccessor('your-auth-token');
const investigationId = '11111111-2222-3333-4444-555555555555';

// Step 1: Load project
console.log('Loading project into cache...');
const loadResult = await accessor.loadProject();
console.log(`Project loaded: ${loadResult.projectName}`);

// Step 2: List notebooks
const notebooks = await accessor.listNotebooks(investigationId);
console.log(`\nFound ${notebooks.totalCount} notebooks:`);

notebooks.notebooks.forEach(nb => {
  console.log(`  - ${nb.name}: ${nb.blockCount} blocks`);
});

// Get main notebook
const main = await accessor.getMainNotebook(investigationId);
console.log(`\nMain notebook: ${main.name} (${main.blockCount} blocks)`);

---

Best Practices

1. Always Load Project First: Before accessing notebooks, ensure the project is loaded into cache
2. Cache Duration: Projects remain in cache for 30 minutes after last access
3. Touch Session: API calls automatically extend cache lifetime
4. Use Main Notebook: For basic analysis, the main notebook contains the primary workflow
5. Notebook Order: Notebooks are ordered by notebookOrder for consistent display