Block Management

Get, Update, and Delete Analysis Blocks

Manage analysis blocks within notebooks. Blocks are the fundamental analysis units that perform data transformations, calculations, filtering operations, and alerting.

Connectivity Testing

Unauthorized Ping

GET /api/{tenantId}/{projectId}/block/unauthorized-ping

Test endpoint that does not require authentication. Use this to verify the Block API is accessible.

Response

Ping Successful

Authenticated Ping

GET /api/{tenantId}/{projectId}/block/ping

Authenticated ping endpoint to verify API access for a specific tenant and project.

Response (200 OK)

Ping Successful (tenant id: {tenantId})

Response (401 Unauthorized)

{error message describing authorization failure}

Get Block Details

GET /api/{tenantId}/{projectId}/block/{blockId}

Retrieves comprehensive information about a specific analysis block including its configuration, execution history, and metadata.

Path Parameters

Parameter	Type	Required	Description
tenantId	GUID	Yes	The tenant identifier
projectId	GUID	Yes	The project identifier
blockId	GUID	Yes	The block identifier

Response (200 OK)

{
  "blockId": "550e8400-e29b-41d4-a716-446655440000",
  "notebookId": "660e8400-e29b-41d4-a716-446655440000",
  "blockType": "Filter",
  "blockTitle": "Date Range Filter",
  "blockDescription": "Filters data for the last 30 days",
  "blockOrder": 0,
  "configuration": "{\"filterType\": \"dateRange\", \"startDate\": \"2024-01-01\"}",
  "isDisabled": false,
  "dateCreated": "2024-01-15T10:30:00Z",
  "dateModified": "2024-01-15T14:45:00Z",
  "createdBy": "user@example.com",
  "modifiedBy": "user@example.com",
  "lastExecutionDate": "2024-01-15T14:45:00Z",
  "lastExecutionStatus": "Success",
  "executionCount": 12
}

Response Fields

Field	Type	Description
blockId	GUID	Unique identifier for the block
notebookId	GUID	ID of the notebook containing this block
blockType	string	Type of block (Filter, Calculator, Alert, etc.)
blockTitle	string	Display title of the block
blockDescription	string	Description of the block's purpose
blockOrder	integer	Order of the block in the notebook (default: 0)
configuration	string	JSON string containing block settings
isDisabled	boolean	Whether the block is disabled
dateCreated	datetime	When the block was created
dateModified	datetime	When the block was last modified
createdBy	string	User who created the block
modifiedBy	string	User who last modified the block
lastExecutionDate	datetime	When the block was last executed
lastExecutionStatus	string	Status of last execution
executionCount	integer	Number of times block has been executed

Error Responses

Not Found (404):

{
  "Error": "Block not found",
  "BlockId": "550e8400-e29b-41d4-a716-446655440000"
}

Update Block

PUT /api/{tenantId}/{projectId}/block/{blockId}

Updates an existing block's metadata. Preserves execution history while updating the specified fields.

Request Body

{
  "blockTitle": "Updated Date Filter",
  "blockDescription": "Filters data for custom date range",
  "isDisabled": false
}

Request Fields

Field	Type	Required	Description
blockTitle	string	No	New title for the block
blockDescription	string	No	New description for the block
isDisabled	boolean	No	Whether to disable the block

Response (200 OK)

Returns the updated block object with the same structure as the GET endpoint.

Error Responses

Bad Request (400):

Failed to update block.

Delete Block

DELETE /api/{tenantId}/{projectId}/block/{blockId}

Permanently removes a block and all its execution history from the notebook. This operation cannot be undone.

Response Codes

• 204 No Content - Block deleted successfully
• 400 Bad Request - Failed to delete block
• 401 Unauthorized - Not authenticated or lacks access
• 404 Not Found - Block not found

Creating Blocks

Block creation is handled through the Notebook API, not the Block API.

POST /api/{tenantId}/{projectId}/notebook/{notebookId}/blocks

See Notebook API for complete block creation documentation.

Implementation Examples

cURL

# Test connectivity (no auth)
curl -X GET "https://your-mindzie-instance.com/api/12345678-1234-1234-1234-123456789012/87654321-4321-4321-4321-210987654321/block/unauthorized-ping"

# Test connectivity (authenticated)
curl -X GET "https://your-mindzie-instance.com/api/12345678-1234-1234-1234-123456789012/87654321-4321-4321-4321-210987654321/block/ping" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Get block details
curl -X GET "https://your-mindzie-instance.com/api/12345678-1234-1234-1234-123456789012/87654321-4321-4321-4321-210987654321/block/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Update block
curl -X PUT "https://your-mindzie-instance.com/api/12345678-1234-1234-1234-123456789012/87654321-4321-4321-4321-210987654321/block/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"blockTitle": "Updated Filter", "isDisabled": false}'

# Delete block
curl -X DELETE "https://your-mindzie-instance.com/api/12345678-1234-1234-1234-123456789012/87654321-4321-4321-4321-210987654321/block/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

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 BlockManager {
  constructor(token) {
    this.token = token;
    this.headers = {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    };
  }

  async getBlock(blockId) {
    const url = `${BASE_URL}/api/${TENANT_ID}/${PROJECT_ID}/block/${blockId}`;
    const response = await fetch(url, { headers: this.headers });

    if (response.ok) {
      return await response.json();
    } else if (response.status === 404) {
      throw new Error('Block not found');
    } else {
      throw new Error(`Failed to get block: ${response.status}`);
    }
  }

  async updateBlock(blockId, updates) {
    const url = `${BASE_URL}/api/${TENANT_ID}/${PROJECT_ID}/block/${blockId}`;
    const response = await fetch(url, {
      method: 'PUT',
      headers: this.headers,
      body: JSON.stringify(updates)
    });

    if (response.ok) {
      return await response.json();
    } else {
      throw new Error(`Failed to update block: ${response.status}`);
    }
  }

  async deleteBlock(blockId) {
    const url = `${BASE_URL}/api/${TENANT_ID}/${PROJECT_ID}/block/${blockId}`;
    const response = await fetch(url, {
      method: 'DELETE',
      headers: this.headers
    });

    return response.status === 204;
  }
}

// Usage
const manager = new BlockManager('your-auth-token');

// Get block details
const block = await manager.getBlock('block-guid');
console.log(`Block: ${block.blockTitle} (${block.blockType})`);

// Update block
const updated = await manager.updateBlock('block-guid', {
  blockTitle: 'Updated Title',
  isDisabled: false
});

// Delete block
const deleted = await manager.deleteBlock('block-guid');

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 BlockManager:
    def __init__(self, token):
        self.headers = {
            'Authorization': f'Bearer {token}',
            'Content-Type': 'application/json'
        }

    def get_block(self, block_id):
        """Get block details."""
        url = f'{BASE_URL}/api/{TENANT_ID}/{PROJECT_ID}/block/{block_id}'
        response = requests.get(url, headers=self.headers)

        if response.ok:
            return response.json()
        elif response.status_code == 404:
            raise Exception('Block not found')
        else:
            raise Exception(f'Failed to get block: {response.status_code}')

    def update_block(self, block_id, title=None, description=None, disabled=None):
        """Update block metadata."""
        url = f'{BASE_URL}/api/{TENANT_ID}/{PROJECT_ID}/block/{block_id}'
        payload = {}
        if title is not None:
            payload['blockTitle'] = title
        if description is not None:
            payload['blockDescription'] = description
        if disabled is not None:
            payload['isDisabled'] = disabled

        response = requests.put(url, json=payload, headers=self.headers)

        if response.ok:
            return response.json()
        else:
            raise Exception(f'Failed to update block: {response.status_code}')

    def delete_block(self, block_id):
        """Delete a block."""
        url = f'{BASE_URL}/api/{TENANT_ID}/{PROJECT_ID}/block/{block_id}'
        response = requests.delete(url, headers=self.headers)
        return response.status_code == 204

# Usage
manager = BlockManager('your-auth-token')

# Get block
block = manager.get_block('block-guid')
print(f"Block: {block['blockTitle']} ({block['blockType']})")
print(f"Execution count: {block['executionCount']}")

# Update block
updated = manager.update_block('block-guid', title='New Title', disabled=False)
print(f"Updated: {updated['blockTitle']}")

# Delete block
if manager.delete_block('block-guid'):
    print('Block deleted successfully')

C#

using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

public class BlockReturn
{
    public Guid BlockId { get; set; }
    public Guid NotebookId { get; set; }
    public string BlockType { get; set; }
    public string BlockTitle { get; set; }
    public string BlockDescription { get; set; }
    public int BlockOrder { get; set; }
    public string Configuration { get; set; }
    public bool IsDisabled { get; set; }
    public DateTime DateCreated { get; set; }
    public DateTime DateModified { get; set; }
    public string CreatedBy { get; set; }
    public string ModifiedBy { get; set; }
    public DateTime? LastExecutionDate { get; set; }
    public string LastExecutionStatus { get; set; }
    public int ExecutionCount { get; set; }
}

public class BlockApiClient
{
    private readonly HttpClient _httpClient;
    private readonly string _baseUrl;
    private readonly Guid _tenantId;
    private readonly Guid _projectId;

    public BlockApiClient(string baseUrl, Guid tenantId, Guid projectId, string accessToken)
    {
        _baseUrl = baseUrl;
        _tenantId = tenantId;
        _projectId = projectId;
        _httpClient = new HttpClient();
        _httpClient.DefaultRequestHeaders.Authorization =
            new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", accessToken);
    }

    public async Task<BlockReturn> GetBlockAsync(Guid blockId)
    {
        var url = $"{_baseUrl}/api/{_tenantId}/{_projectId}/block/{blockId}";
        var response = await _httpClient.GetAsync(url);

        if (response.IsSuccessStatusCode)
        {
            var json = await response.Content.ReadAsStringAsync();
            return JsonSerializer.Deserialize<BlockReturn>(json,
                new JsonSerializerOptions { PropertyNameCaseInsensitive = true });
        }

        throw new Exception($"Failed to get block: {response.StatusCode}");
    }

    public async Task<BlockReturn> UpdateBlockAsync(Guid blockId, string title, string description, bool? isDisabled)
    {
        var url = $"{_baseUrl}/api/{_tenantId}/{_projectId}/block/{blockId}";
        var payload = new
        {
            blockTitle = title,
            blockDescription = description,
            isDisabled = isDisabled
        };

        var content = new StringContent(
            JsonSerializer.Serialize(payload),
            Encoding.UTF8,
            "application/json");

        var response = await _httpClient.PutAsync(url, content);

        if (response.IsSuccessStatusCode)
        {
            var json = await response.Content.ReadAsStringAsync();
            return JsonSerializer.Deserialize<BlockReturn>(json,
                new JsonSerializerOptions { PropertyNameCaseInsensitive = true });
        }

        throw new Exception($"Failed to update block: {response.StatusCode}");
    }

    public async Task<bool> DeleteBlockAsync(Guid blockId)
    {
        var url = $"{_baseUrl}/api/{_tenantId}/{_projectId}/block/{blockId}";
        var response = await _httpClient.DeleteAsync(url);
        return response.StatusCode == System.Net.HttpStatusCode.NoContent;
    }
}