URL Generation

Generate Entity URLs

GET /api/{tenantId}/url/generate

Generate direct URLs to mindzieStudio pages and entities. This API creates properly formatted URLs for navigating to projects, dashboards, investigations, notebooks, blocks, and other entities.

Authentication

Requires Bearer token authentication:

Authorization: Bearer {api_key}

Request

GET /api/{tenantId}/url/generate?type={urlType}&entityId={id}&parentId={parentId}
Authorization: Bearer {token}

Path Parameters

Parameter	Type	Required	Description
`tenantId`	GUID	Yes	The tenant identifier

Query Parameters

Parameter	Type	Required	Description
`type`	String	Yes	The URL type to generate (see URL Types below)
`entityId`	GUID	Conditional	Entity ID for entity-specific pages
`parentId`	GUID	Conditional	Parent ID (projectId or notebookId depending on type)
`baseUrl`	String	No	Override base URL (defaults to request origin)

URL Types

List Pages

These URL types return direct URLs to list/index pages:

Type	parentId Required	Generated URL Pattern
`projects`	No	`/projects?tenantId={tenantId}`
`apps`	No	`/apps?tenantId={tenantId}`
`investigations`	Yes (projectId)	`/investigations?projectId={parentId}`
`dashboards-list`	Yes (projectId)	`/dashboards?projectId={parentId}`
`datasets`	Yes (projectId)	`/manage-datasets?projectId={parentId}`
`actions`	Yes (projectId)	`/actions?projectId={parentId}`
`bpmn`	Yes (projectId)	`/bpmn-editor?projectId={parentId}`

Entity Pages

These URL types return /navigate URLs that route to specific entities:

Type	entityId	parentId	Description
`dashboard`	dashboardId	-	Single dashboard view
`analysis`	notebookId	-	Notebook/analysis page
`block`	blockId	notebookId	Specific block on a notebook page
`enrichment`	enrichmentNotebookId	projectId (optional)	Enrichment notebook

Response

Response Structure

{
  "url": "https://your-instance.mindziestudio.com/projects?tenantId=...",
  "entityType": "projects",
  "entityId": null,
  "tenantId": "660e8400-e29b-41d4-a716-446655440000"
}

Response Fields

Field	Type	Description
`url`	String	The fully qualified URL to the requested page or entity
`entityType`	String	The type of URL generated (matches the `type` parameter)
`entityId`	GUID or null	The entity ID if an entity-specific URL was generated
`tenantId`	GUID	The tenant ID used in the request

Examples

List Pages

Get Projects List URL

curl -H "Authorization: Bearer {api_key}" \
  "https://host/api/{tenantId}/url/generate?type=projects"

Response:

{
  "url": "https://host/projects?tenantId=660e8400-e29b-41d4-a716-446655440000",
  "entityType": "projects",
  "entityId": null,
  "tenantId": "660e8400-e29b-41d4-a716-446655440000"
}

Get Investigations for a Project

curl -H "Authorization: Bearer {api_key}" \
  "https://host/api/{tenantId}/url/generate?type=investigations&parentId={projectId}"

Response:

{
  "url": "https://host/investigations?projectId=770e8400-e29b-41d4-a716-446655440001",
  "entityType": "investigations",
  "entityId": null,
  "tenantId": "660e8400-e29b-41d4-a716-446655440000"
}

Get Dashboards List for a Project

curl -H "Authorization: Bearer {api_key}" \
  "https://host/api/{tenantId}/url/generate?type=dashboards-list&parentId={projectId}"

Entity Pages

Direct Link to a Dashboard

curl -H "Authorization: Bearer {api_key}" \
  "https://host/api/{tenantId}/url/generate?type=dashboard&entityId={dashboardId}"

Response:

{
  "url": "https://host/navigate?type=dashboard&id=880e8400-e29b-41d4-a716-446655440002",
  "entityType": "dashboard",
  "entityId": "880e8400-e29b-41d4-a716-446655440002",
  "tenantId": "660e8400-e29b-41d4-a716-446655440000"
}

Direct Link to a Notebook/Analysis

curl -H "Authorization: Bearer {api_key}" \
  "https://host/api/{tenantId}/url/generate?type=analysis&entityId={notebookId}"

Direct Link to a Specific Block

curl -H "Authorization: Bearer {api_key}" \
  "https://host/api/{tenantId}/url/generate?type=block&entityId={blockId}&parentId={notebookId}"

Response:

{
  "url": "https://host/navigate?type=block&id=990e8400-e29b-41d4-a716-446655440003&notebookId=aa0e8400-e29b-41d4-a716-446655440004",
  "entityType": "block",
  "entityId": "990e8400-e29b-41d4-a716-446655440003",
  "tenantId": "660e8400-e29b-41d4-a716-446655440000"
}

JavaScript Example

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

  async generateUrl(type, options = {}) {
    const params = new URLSearchParams({ type });

    if (options.entityId) {
      params.append('entityId', options.entityId);
    }
    if (options.parentId) {
      params.append('parentId', options.parentId);
    }
    if (options.baseUrl) {
      params.append('baseUrl', options.baseUrl);
    }

    const response = await fetch(
      `${this.baseUrl}/api/${this.tenantId}/url/generate?${params}`,
      { headers: this.headers }
    );

    if (!response.ok) {
      throw new Error(`Failed to generate URL: ${response.status}`);
    }

    return response.json();
  }

  // Convenience methods
  async getProjectsUrl() {
    return this.generateUrl('projects');
  }

  async getInvestigationsUrl(projectId) {
    return this.generateUrl('investigations', { parentId: projectId });
  }

  async getDashboardUrl(dashboardId) {
    return this.generateUrl('dashboard', { entityId: dashboardId });
  }

  async getBlockUrl(blockId, notebookId) {
    return this.generateUrl('block', {
      entityId: blockId,
      parentId: notebookId
    });
  }
}

// Usage
const urlGen = new UrlGenerator(
  'https://your-instance.mindziestudio.com',
  'tenant-guid',
  'your-api-token'
);

// Get URL to projects list
const projectsUrl = await urlGen.getProjectsUrl();
console.log('Projects URL:', projectsUrl.url);

// Get URL to a specific dashboard
const dashboardUrl = await urlGen.getDashboardUrl('dashboard-guid');
console.log('Dashboard URL:', dashboardUrl.url);

// Get URL to a specific block
const blockUrl = await urlGen.getBlockUrl('block-guid', 'notebook-guid');
console.log('Block URL:', blockUrl.url);

Python Example

import requests
from typing import Optional, Dict, Any

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

    def generate_url(
        self,
        url_type: str,
        entity_id: Optional[str] = None,
        parent_id: Optional[str] = None,
        base_url_override: Optional[str] = None
    ) -> Dict[str, Any]:
        """Generate a URL for the specified type and entity"""
        params = {'type': url_type}

        if entity_id:
            params['entityId'] = entity_id
        if parent_id:
            params['parentId'] = parent_id
        if base_url_override:
            params['baseUrl'] = base_url_override

        url = f"{self.base_url}/api/{self.tenant_id}/url/generate"
        response = requests.get(url, params=params, headers=self.headers)
        response.raise_for_status()
        return response.json()

    # Convenience methods for list pages
    def get_projects_url(self) -> str:
        return self.generate_url('projects')['url']

    def get_investigations_url(self, project_id: str) -> str:
        return self.generate_url('investigations', parent_id=project_id)['url']

    def get_dashboards_list_url(self, project_id: str) -> str:
        return self.generate_url('dashboards-list', parent_id=project_id)['url']

    def get_datasets_url(self, project_id: str) -> str:
        return self.generate_url('datasets', parent_id=project_id)['url']

    def get_actions_url(self, project_id: str) -> str:
        return self.generate_url('actions', parent_id=project_id)['url']

    # Convenience methods for entity pages
    def get_dashboard_url(self, dashboard_id: str) -> str:
        return self.generate_url('dashboard', entity_id=dashboard_id)['url']

    def get_analysis_url(self, notebook_id: str) -> str:
        return self.generate_url('analysis', entity_id=notebook_id)['url']

    def get_block_url(self, block_id: str, notebook_id: str) -> str:
        return self.generate_url('block', entity_id=block_id, parent_id=notebook_id)['url']

    def get_enrichment_url(self, enrichment_id: str, project_id: Optional[str] = None) -> str:
        return self.generate_url('enrichment', entity_id=enrichment_id, parent_id=project_id)['url']


# Usage
url_gen = UrlGenerator(
    'https://your-instance.mindziestudio.com',
    'tenant-guid',
    'your-api-token'
)

# Get various URLs
projects_url = url_gen.get_projects_url()
print(f"Projects: {projects_url}")

investigations_url = url_gen.get_investigations_url('project-guid')
print(f"Investigations: {investigations_url}")

dashboard_url = url_gen.get_dashboard_url('dashboard-guid')
print(f"Dashboard: {dashboard_url}")

block_url = url_gen.get_block_url('block-guid', 'notebook-guid')
print(f"Block: {block_url}")

MCP Server Integration

AI coding assistants can generate URLs using the MCP server:

mindzie_generate_url type="dashboard" entityId="{dashboardId}"

See MCP Server Integration for complete documentation.

Use Cases

Generate shareable URLs to specific dashboards, investigations, or analysis blocks.

Integration Workflows

Create navigation links in external systems that deep-link into mindzieStudio.

Enable AI tools to generate and open specific pages in the application.

Automated Reporting

Include direct links to relevant dashboards or analyses in automated reports.

Error Handling

Status Code	Description
200	Success - URL generated
400	Bad Request - Invalid type or missing required parameters
401	Unauthorized - Invalid or missing authentication token
404	Not Found - Entity not found (for entity-specific URLs)

URL Generation

Generate Entity URLs

Authentication

Request

Path Parameters

Query Parameters

URL Types

List Pages

Entity Pages

Response

Response Structure

Response Fields

Examples

List Pages

Get Projects List URL

Get Investigations for a Project

Get Dashboards List for a Project

Entity Pages

Direct Link to a Dashboard

Direct Link to a Notebook/Analysis

Direct Link to a Specific Block

JavaScript Example

Python Example

MCP Server Integration

Use Cases

Sharing Links

Integration Workflows

AI Assistant Navigation

Automated Reporting

Error Handling