Quick Start

Getting Started

Get Up and Running in Minutes

Follow this step-by-step guide to make your first successful API calls to mindzieStudio and start integrating process mining capabilities into your applications.

Prerequisites

  • API Credentials: Access token, tenant ID, and project ID
  • Base URL: Your mindzie instance API endpoint
  • HTTPS Access: Secure connection to your mindzie instance
  • Development Environment: Your preferred programming language and HTTP client

Don't have credentials? Check the Authentication Guide to learn how to obtain your API access credentials.

Step 1: Test Basic Connectivity

Start by testing basic connectivity to ensure your mindzie instance is accessible:

curl -X GET "https://your-mindzie-instance.com/api/Action/ping"

Expected Response:

{
  "status": "ok",
  "timestamp": "2024-01-15T10:30:00Z",
  "version": "1.0.0"
}

Step 2: Verify Authentication

Test your authentication credentials with the authenticated ping endpoint:

curl -X GET "https://your-mindzie-instance.com/api/Action/ping/authenticated" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-Id: YOUR_TENANT_GUID" \
  -H "X-Project-Id: YOUR_PROJECT_GUID" \
  -H "Content-Type: application/json"

Expected Response:

{
  "status": "authenticated",
  "timestamp": "2024-01-15T10:30:00Z",
  "tenantId": "12345678-1234-1234-1234-123456789012",
  "projectId": "87654321-4321-4321-4321-210987654321",
  "userId": "user@company.com",
  "permissions": ["read", "write", "admin"]
}

Step 3: Your First API Call

Let's make a practical API call to retrieve action history:

curl -X GET "https://your-mindzie-instance.com/api/Action/history?limit=5" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-Id: YOUR_TENANT_GUID" \
  -H "X-Project-Id: YOUR_PROJECT_GUID" \
  -H "Content-Type: application/json"

Example Response:

{
  "actions": [
    {
      "actionId": "87654321-4321-4321-4321-210987654321",
      "actionType": "analyze",
      "status": "completed",
      "startTime": "2024-01-15T10:30:00Z",
      "endTime": "2024-01-15T10:32:15Z",
      "duration": 135,
      "userId": "user@company.com"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 1,
    "totalItems": 1,
    "itemsPerPage": 5
  }
}

Language-Specific Examples

JavaScript

Use fetch API or axios for modern web applications and Node.js backends.

Python

Use requests library for data science workflows and backend automation.

C#/.NET

Use HttpClient for enterprise applications and microservices.

JavaScript Example

Complete example using modern JavaScript and fetch API:

// Configuration
const API_CONFIG = {
  baseURL: 'https://your-mindzie-instance.com/api',
  token: 'YOUR_ACCESS_TOKEN',
  tenantId: 'YOUR_TENANT_GUID',
  projectId: 'YOUR_PROJECT_GUID'
};

// Helper function for API requests
async function callMindzieAPI(endpoint, options = {}) {
  const url = `${API_CONFIG.baseURL}${endpoint}`;

  const defaultHeaders = {
    'Authorization': `Bearer ${API_CONFIG.token}`,
    'X-Tenant-Id': API_CONFIG.tenantId,
    'X-Project-Id': API_CONFIG.projectId,
    'Content-Type': 'application/json'
  };

  try {
    const response = await fetch(url, {
      ...options,
      headers: { ...defaultHeaders, ...options.headers }
    });

    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }

    return await response.json();
  } catch (error) {
    console.error('API call failed:', error);
    throw error;
  }
}

// Example usage
async function quickStartExample() {
  try {
    // 1. Test connectivity
    console.log('Testing connectivity...');
    const pingResult = await callMindzieAPI('/Action/ping');
    console.log('Ping successful:', pingResult);

    // 2. Test authentication
    console.log('Testing authentication...');
    const authResult = await callMindzieAPI('/Action/ping/authenticated');
    console.log('Authentication successful:', authResult);

    // 3. Get action history
    console.log('Fetching action history...');
    const history = await callMindzieAPI('/Action/history?limit=5');
    console.log('Action history:', history);

    console.log('Quick start completed successfully!');
    return history;
  } catch (error) {
    console.error('Quick start failed:', error);
    throw error;
  }
}

// Run the example
quickStartExample();

Python Example

Complete example using Python requests library:

import requests
import json
from typing import Dict, Any

class MindzieQuickStart:
    def __init__(self, base_url: str, token: str, tenant_id: str, project_id: str):
        self.base_url = base_url.rstrip('/')
        self.headers = {
            'Authorization': f'Bearer {token}',
            'X-Tenant-Id': tenant_id,
            'X-Project-Id': project_id,
            'Content-Type': 'application/json'
        }

    def call_api(self, endpoint: str, method: str = 'GET', **kwargs) -> Dict[str, Any]:
        """Make an API call to mindzie"""
        url = f"{self.base_url}{endpoint}"

        try:
            response = requests.request(
                method=method,
                url=url,
                headers=self.headers,
                **kwargs
            )
            response.raise_for_status()
            return response.json()
        except requests.exceptions.RequestException as e:
            print(f"API call failed: {e}")
            raise

    def run_quick_start(self):
        """Execute the quick start sequence"""
        print("Starting mindzie API Quick Start...")

        try:
            # 1. Test connectivity
            print("1. Testing connectivity...")
            ping_result = requests.get(f"{self.base_url}/api/Action/ping")
            ping_result.raise_for_status()
            print(f"   Connectivity OK: {ping_result.json()}")

            # 2. Test authentication
            print("2. Testing authentication...")
            auth_result = self.call_api('/api/Action/ping/authenticated')
            print(f"   Authentication OK: {auth_result['status']}")

            # 3. Get action history
            print("3. Fetching action history...")
            history = self.call_api('/api/Action/history?limit=5')
            print(f"   Retrieved {len(history['actions'])} actions")

            print("Quick start completed successfully!")
            return history

        except Exception as e:
            print(f"Quick start failed: {e}")
            raise

# Usage example
if __name__ == "__main__":
    # Configure your credentials
    quick_start = MindzieQuickStart(
        base_url='https://your-mindzie-instance.com/api',
        token='YOUR_ACCESS_TOKEN',
        tenant_id='YOUR_TENANT_GUID',
        project_id='YOUR_PROJECT_GUID'
    )

    # Run the quick start
    result = quick_start.run_quick_start()
    print(f"Final result: {json.dumps(result, indent=2)}")

C#/.NET Example

Complete example using C# HttpClient:

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

public class MindzieQuickStart
{
    private readonly HttpClient _httpClient;
    private readonly string _baseUrl;

    public MindzieQuickStart(string baseUrl, string token, string tenantId, string projectId)
    {
        _baseUrl = baseUrl.TrimEnd('/');

        _httpClient = new HttpClient();
        _httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {token}");
        _httpClient.DefaultRequestHeaders.Add("X-Tenant-Id", tenantId);
        _httpClient.DefaultRequestHeaders.Add("X-Project-Id", projectId);
    }

    public async Task<T> CallApiAsync<T>(string endpoint)
    {
        try
        {
            var response = await _httpClient.GetAsync($"{_baseUrl}{endpoint}");
            response.EnsureSuccessStatusCode();

            var content = await response.Content.ReadAsStringAsync();
            return JsonSerializer.Deserialize<T>(content, new JsonSerializerOptions
            {
                PropertyNameCaseInsensitive = true
            });
        }
        catch (HttpRequestException ex)
        {
            Console.WriteLine($"API call failed: {ex.Message}");
            throw;
        }
    }

    public async Task RunQuickStartAsync()
    {
        Console.WriteLine("Starting mindzie API Quick Start...");

        try
        {
            // 1. Test connectivity
            Console.WriteLine("1. Testing connectivity...");
            using var pingClient = new HttpClient();
            var pingResponse = await pingClient.GetAsync($"{_baseUrl}/api/Action/ping");
            pingResponse.EnsureSuccessStatusCode();
            Console.WriteLine("   Connectivity OK");

            // 2. Test authentication
            Console.WriteLine("2. Testing authentication...");
            var authResult = await CallApiAsync<AuthResponse>("/api/Action/ping/authenticated");
            Console.WriteLine($"   Authentication OK: {authResult.Status}");

            // 3. Get action history
            Console.WriteLine("3. Fetching action history...");
            var history = await CallApiAsync<ActionHistoryResponse>("/api/Action/history?limit=5");
            Console.WriteLine($"   Retrieved {history.Actions.Length} actions");

            Console.WriteLine("Quick start completed successfully!");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Quick start failed: {ex.Message}");
            throw;
        }
    }

    public void Dispose()
    {
        _httpClient?.Dispose();
    }
}

// Data models
public class AuthResponse
{
    public string Status { get; set; }
    public string TenantId { get; set; }
    public string ProjectId { get; set; }
    public string UserId { get; set; }
}

public class ActionHistoryResponse
{
    public ActionItem[] Actions { get; set; }
    public PaginationInfo Pagination { get; set; }
}

public class ActionItem
{
    public string ActionId { get; set; }
    public string ActionType { get; set; }
    public string Status { get; set; }
    public DateTime StartTime { get; set; }
    public DateTime? EndTime { get; set; }
}

public class PaginationInfo
{
    public int CurrentPage { get; set; }
    public int TotalPages { get; set; }
    public int TotalItems { get; set; }
}

// Usage
class Program
{
    static async Task Main(string[] args)
    {
        var quickStart = new MindzieQuickStart(
            "https://your-mindzie-instance.com/api",
            "YOUR_ACCESS_TOKEN",
            "YOUR_TENANT_GUID",
            "YOUR_PROJECT_GUID"
        );

        try
        {
            await quickStart.RunQuickStartAsync();
        }
        finally
        {
            quickStart.Dispose();
        }
    }
}

Common Issues & Solutions

Authentication Failures

  • 401 Unauthorized: Verify your access token is correct and not expired
  • 403 Forbidden: Check tenant/project IDs and user permissions
  • 400 Bad Request: Ensure all required headers are included

Connection Issues

  • Network timeouts: Check firewall settings and network connectivity
  • SSL/TLS errors: Verify certificate validity and HTTPS configuration
  • DNS resolution: Confirm the mindzie instance URL is correct

Rate Limiting

  • 429 Too Many Requests: Implement exponential backoff retry logic
  • Monitor rate limits: Check response headers for rate limit information
  • Optimize requests: Use pagination and filtering to reduce API calls

Next Steps

Congratulations! You've successfully completed the mindzieAPI quick start. Next, explore the Actions API or Blocks API to start building powerful integrations.

An error has occurred. This application may no longer respond until reloaded. Reload ??