API Overview

How to Make API Calls to ProcessMind

This guide provides examples and best practices for calling the ProcessMind API to retrieve data, submit information, or automate workflows.

For complete endpoint documentation with request/response formats, see the API Reference.

For additional examples and client libraries, visit the API Documentation on GitHub.

API Base URL

All API requests should be made to:

https://api.processmind.com

All routes are versioned under /v1. The full machine-readable API specification is available (OpenAPI 3.1) at:

GET https://api.processmind.com/v1/openapi.json

Authentication

All API requests require your API key in the x-api-key header:

x-api-key: your-api-key-here

The API key can be obtained from your ProcessMind account settings. See Getting your API Key for instructions.

Status Codes

ProcessMind’s API follows standard HTTP status codes:

Key Concepts

• apiKey: Your authentication token for all API requests.
• tenantId: Identifies your workspace/organization context. Found in your account settings.
• datatableId: Identifies a specific datatable for data operations. Available from the Get Data Table ID option in the dataset settings menu within ProcessMind.

What You Can Do

The ProcessMind API enables you to:

• Manage Tenants: Retrieve tenant info, update settings, view statistics
• Manage Users: Add, update, or remove users from tenants and organizations
• Manage Processes: Create processes, upload BPMN models, organize in folders
• Connect Data: Map datatables to processes for analysis
• Upload Data: Upload CSV/XLSX files directly to datatables
• Manage Datasets: List, inspect, and delete datasets and datatables

Common Examples

Below are practical examples showing how to perform common operations with the ProcessMind API.

Getting a Presigned Upload URL

To upload a file to a datatable, first obtain a presigned URL:

const presignedUrl = await getPresignedUploadUrl({
	apiKey,
	tenantId: "tenant-123",
	datatableId: "table-456"
});
console.log(presignedUrl); // https://s3.amazonaws.com/…?X-Amz-Signature=…

Listing Datasets

Retrieve all datasets in your tenant:

const datasets = await getDatasets({
	apiKey,
	tenantId: "tenant-123"
});
console.log(datasets);

Getting Tenant Information

Retrieve details about your tenant:

const tenantInfo = await getTenant({
	apiKey,
	tenantId: "tenant-123"
});
console.log(tenantInfo);

Creating a Process

Create a new process in your tenant:

const process = await createProcess({
	apiKey,
	tenantId: "tenant-123",
	displayName: "Order to Cash"
});
console.log(process.id); // Use this ID for subsequent operations

Uploading a BPMN Model

Upload a BPMN file to define your process model:

const fs = require("fs");
const bpmnXml = fs.readFileSync("./my-process.bpmn", "utf8");

await uploadBpmn({
	apiKey,
	tenantId: "tenant-123",
	processId: "process-456",
	bpmnXml
});

Mapping Data to a Process

Connect a datatable to a process for analysis:

const mapping = await createProcessMapping({
	apiKey,
	tenantId: "tenant-123",
	processId: "process-456",
	dataTableId: "datatable-789",
	displayName: "Sales Data 2024",
	showByDefault: true
});

Adding a User to a Tenant

Add a user to your tenant:

const result = await addTenantUser({
	apiKey,
	tenantId: "tenant-123",
	id: "user-456",
	email: "colleague@example.com",
	isAdminInTenant: false,
	isActiveInTenant: true,
	sendInvitationEmail: true
});

Note: Role fields in the body (isAdminInTenant, access, isDashboardViewer) are honored verbatim. The user-management endpoints are a full tenant-admin surface, so only issue write-scoped API keys to callers you trust with administrative control. No invitation email is sent by the System API; you are responsible for onboarding the user.

Uploading Files

The general flow for uploading a file to ProcessMind is:

1. Get a presigned URL using the getPresignedUploadUrl call.
2. Perform a PUT request to that URL with the file contents.
3. The presigned URL authorizes the upload directly to cloud storage; no additional credentials needed.

Here is a simplified example using fetch:

async function uploadFile({ apiKey, tenantId, datatableId, file }) {
	// Step 1: Obtain a presigned URL
	const uploadUrl = await getPresignedUploadUrl({ apiKey, tenantId, datatableId });
	
	// Step 2: Upload the file via PUT
	await fetch(uploadUrl, {
		method: "PUT",
		headers: {
			"Content-Type": file.type
		},
		body: file
	});
}

Complete Examples

Below are complete, copy-paste ready examples in different languages.

Bash Example: Uploading a File

Minimal Bash script to upload a file to ProcessMind using two curl calls, with placeholders for all values

#!/bin/bash
# Minimal Bash script to upload a file to ProcessMind using two curl calls, with placeholders for all values

# Replace the following placeholders with your actual values:
# <API_KEY>, <TENANT_ID>, <DATATABLE_ID>, <FILE_PATH>

curl -s -H "x-api-key: <API_KEY>" \
	"https://api.processmind.com/v1/tenant/<TENANT_ID>/datatables/<DATATABLE_ID>/uploads/presigned-url" \
	| grep -oP '"PreSignedUploadUrl"\s*:\s*"\K[^"]+' \
	| xargs -I {} curl -s -X PUT --upload-file "<FILE_PATH>" "{}"

Node.js Example: Uploading a Local CSV File

Uploads a local CSV file to ProcessMind using a presigned URL.

Steps:

1. Fetch a presigned upload URL from the API.
2. Read the local file from disk.
3. Upload the file to the presigned URL using HTTP PUT.

Configuration:

• Provide your API key, tenantId, datatableId, and filePath when calling uploadFile().
• The API base URL is set to https://api.processmind.com

/**
 * Uploads a local CSV file to ProcessMind using a presigned URL.
 *
 * Steps:
 * 1. Fetch a presigned upload URL from the API.
 * 2. Read the local file from disk.
 * 3. Upload the file to the presigned URL using HTTP PUT.
 *
 * Configuration:
 * - Provide your API key, tenantId, datatableId, and filePath when calling uploadFile().
 * - The API base URL is set to https://api.processmind.com
 */

const fs = require("node:fs");

/**
 * Uploads a file to ProcessMind datatable using a presigned URL.
 * @param {string} apiKey - Your API key for authentication.
 * @param {string} tenantId - Your tenant identifier.
 * @param {string} datatableId - Your datatable identifier.
 * @param {string} filePath - Path to the file to upload.
 */

async function getApi({path, apiKey, apiUrl = "https://api.processmind.com"}) {
	try {
        const response = await fetch(`${apiUrl}${path}`, {
            method: "GET",
            headers: {
                "x-api-key": apiKey
            }
        });
        const body = await response.json();
        if (!response.ok) {
            console.error(`Error loading from API: ${response.status}, ${response.statusText}: ${body.message}`);
            return;
        }
        return body;
    } catch (err) {
        console.error("Unexpected error:", err);
    }
}

async function getPresignedUploadUrl({apiKey, tenantId, datatableId, apiUrl = "https://api.processmind.com"}) {
	return (await getApi({apiKey, path: `/v1/tenant/${tenantId}/datatables/${datatableId}/uploads/presigned-url`, apiUrl})).PreSignedUploadUrl;
}

async function getDatasets({apiKey, tenantId, apiUrl = "https://api.processmind.com"}) {
	return await getApi({apiKey, path: `/v1/tenant/${tenantId}/datasets`, apiUrl});
}

async function getTenant({apiKey, tenantId, apiUrl = "https://api.processmind.com"}) {
	return await getApi({apiKey, path: `/v1/tenant/${tenantId}`, apiUrl});
}

async function getOrganization({apiKey, tenantId, apiUrl = "https://api.processmind.com"}) {
	return await getApi({apiKey, path: `/v1/tenant/${tenantId}/organization`, apiUrl});
}

async function uploadFile({apiKey, tenantId, datatableId, filePath, apiUrl = "https://api.processmind.com"}) {
    try {
        const uploadUrl = await getPresignedUploadUrl({apiKey, tenantId, datatableId, apiUrl});

		console.log("Uploading file...");
        fs.readFile(filePath, async (err, data) => {
            if (err) {
                console.error("Error reading file:", err);
                return;
            }
            try {
                const uploadRes = await fetch(uploadUrl, {
                    method: "PUT",
                    body: data
                });
                if (!uploadRes.ok) {
                    console.error("Upload failed:", uploadRes.status, uploadRes.statusText);
                } else {
                    console.log("File uploaded successfully.");
                }
            } catch (uploadErr) {
                console.error("Error uploading file:", uploadErr);
            }
        });
    } catch (err) {
        console.error("Unexpected error:", err);
    }
}

// Export the function for use in other modules
module.exports = { 
	getPresignedUploadUrl,
	getDatasets,
	getTenant,
	getOrganization,
	uploadFile 
};

Python Example: Uploading a Local CSV File

Uploads a local CSV file to a remote API using a presigned URL.

Steps:

1. Fetch a presigned upload URL from the API.
2. Read the local file from disk.
3. Upload the file to the presigned URL using HTTP PUT.

Configuration:

• Update api_key, tenant_id, datatable_id, file_path as needed.

"""
Uploads a local CSV file to a remote API using a presigned URL.

Steps:
1. Fetch a presigned upload URL from the API.
2. Read the local file from disk.
3. Upload the file to the presigned URL using HTTP PUT.

Configuration:
- Update api_key, tenant_id, datatable_id, file_path as needed.
"""

import requests

# === Configuration ===
api_key = ""  # API key for authentication
tenant_id = ""  # Tenant identifier
datatable_id = ""  # Datatable identifier
file_path = ""  # Path to the file to upload


print("Fetching upload URL...")
api_url = "https://api.processmind.com"  # Base API URL
presign_url = f"{api_url}/v1/tenant/{tenant_id}/datatables/{datatable_id}/uploads/presigned-url"
presign_res = requests.get(presign_url, headers={"x-api-key": api_key})
if not presign_res.ok:
	print(f"Error fetching upload URL: {presign_res.status_code}, {presign_res.reason}: {presign_res.text}")
	exit(1)

presign_body = presign_res.json()
upload_url = presign_body.get("PreSignedUploadUrl")
if not upload_url:
	print("No presigned upload URL returned.")
	exit(1)

print("Uploading file...")
with open(file_path, "rb") as f:
	upload_res = requests.put(upload_url, data=f)
if not upload_res.ok:
	print(f"Upload failed: {upload_res.status_code}, {upload_res.reason}")
else:
	print("File uploaded successfully.")

Pagination

List endpoints accept limit and offset query parameters and return a bare JSON array (no envelope, no total count):

GET /v1/tenant/{tenantId}/processes?limit=50&offset=100

To page through everything, keep requesting with offset += limit until the response array is shorter than the requested limit (or empty). Values above the maximum are rejected with 400. The versioned data endpoints (datasets, datatables, versions, webhooks) follow the same convention.

Versioning & Deprecation

• All routes are versioned under /v1; breaking changes ship in a new version rather than silently changing /v1.
• Deprecations are announced in the changelog and on this page at least 6 months before a route is removed, and deprecated routes keep working during that window.
• Responses of deprecated routes carry a Sunset header with the removal date, and Deprecation: true.
• Major client-visible changes are always listed in the changelog; subscribe or check back before upgrading pinned API clients.

Next Steps

• API Reference: Complete documentation for all endpoints with request/response formats
• GitHub Examples: Downloadable examples and client libraries
• Getting your API Key: How to obtain and manage your API key