API-overzicht

API-aanroepen naar ProcessMind uitvoeren

Deze gids bevat voorbeelden en best practices voor het aanroepen van de ProcessMind API om data op te halen, informatie te versturen of workflows te automatiseren.

Bekijk de API-referentie voor de volledige documentatie van endpoints en de indeling van aanvragen en antwoorden.

Ga voor meer voorbeelden en clientbibliotheken naar de API-documentatie op GitHub.

Basis-URL van de API

Stuur alle API-aanvragen naar:

https://api.processmind.com

Alle routes zijn voorzien van een versienummer onder /v1. De volledige machineleesbare API-specificatie (OpenAPI 3.1) vind je op:

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

Verificatie

Voor alle API-aanvragen is je API-sleutel vereist in de x-api-key-header, behalve voor het openbare OpenAPI-document (/v1/openapi.json) en de MCP OAuth-endpoints:

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

Je vindt de API-sleutel in de accountinstellingen van ProcessMind. Raadpleeg Je API-sleutel ophalen voor instructies.

Statuscodes

De API van ProcessMind gebruikt de standaard HTTP-statuscodes:

Belangrijke begrippen

• apiKey: je verificatietoken voor alle API-aanvragen.
• tenantId: geeft aan op welke workspace of organisatie de aanvraag betrekking heeft. Je vindt deze waarde in de accountinstellingen.
• datatableId: verwijst naar een specifieke datatabel voor datahandelingen. Je vindt deze waarde via de optie ID van datatabel ophalen in het instellingenmenu van de dataset in ProcessMind.

Wat je kunt doen

Met de ProcessMind API kun je:

• Tenants beheren: tenantgegevens ophalen, instellingen bijwerken en statistieken bekijken
• Gebruikers beheren: gebruikers toevoegen aan of verwijderen uit tenants en organisaties, en hun gegevens bijwerken
• Processen beheren: processen aanmaken, BPMN-modellen uploaden en ze in mappen ordenen
• Data koppelen: datatabellen aan processen koppelen voor analyse
• Data uploaden: CSV- en XLSX-bestanden rechtstreeks naar datatabellen uploaden
• Datasets beheren: datasets en datatabellen weergeven, bekijken en verwijderen

Veelvoorkomende voorbeelden

Hieronder staan praktische voorbeelden van veelvoorkomende handelingen met de ProcessMind API.

Een vooraf ondertekende upload-URL ophalen

Haal eerst een vooraf ondertekende URL op om een bestand naar een datatabel te uploaden:

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

Datasets weergeven

Haal alle datasets in je tenant op:

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

Tenantgegevens ophalen

Haal de gegevens van je tenant op:

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

Een proces aanmaken

Maak een nieuw proces aan in je tenant:

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

Een BPMN-model uploaden

Upload een BPMN-bestand om je procesmodel vast te leggen:

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

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

Data aan een proces koppelen

Koppel een datatabel aan een proces voor analyse:

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

Een gebruiker aan een tenant toevoegen

Voeg een gebruiker toe aan je tenant:

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

Let op: rolvelden in de body (isAdminInTenant, access, isDashboardViewer) worden ongewijzigd overgenomen. De endpoints voor gebruikersbeheer bieden volledige beheerrechten voor de tenant. Geef daarom alleen API-sleutels met schrijfrechten uit aan aanroepers die je vertrouwt met beheertoegang. De System API verstuurt geen uitnodigingsmail. Je bent zelf verantwoordelijk voor het onboarden van de gebruiker.

Bestanden uploaden

Een bestand uploaden naar ProcessMind gaat in grote lijnen zo:

1. Haal een vooraf ondertekende URL op met de aanroep getPresignedUploadUrl.
2. Voer een PUT-aanvraag uit naar die URL met de bestandsinhoud.
3. De vooraf ondertekende URL geeft rechtstreeks toestemming om naar cloudopslag te uploaden. Je hebt geen extra inloggegevens nodig.

Hier volgt een eenvoudig voorbeeld met 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
	});
}

Volledige voorbeelden

Hieronder staan complete voorbeelden in verschillende programmeertalen die je direct kunt kopiëren en plakken.

Bash-voorbeeld: een bestand uploaden

Een minimaal Bash-script om met twee curl-aanroepen een bestand naar ProcessMind te uploaden. Alle waarden zijn placeholders.

#!/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-voorbeeld: een lokaal CSV-bestand uploaden

Uploadt een lokaal CSV-bestand naar ProcessMind met een vooraf ondertekende URL.

Stappen:

1. Haal via de API een vooraf ondertekende upload-URL op.
2. Lees het lokale bestand van de schijf.
3. Upload het bestand met HTTP PUT naar de vooraf ondertekende URL.

Configuratie:

• Geef je API-sleutel, tenantId, datatableId en filePath door wanneer je uploadFile() aanroept.
• De basis-URL van de API is ingesteld op 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-voorbeeld: een lokaal CSV-bestand uploaden

Uploadt met een vooraf ondertekende URL een lokaal CSV-bestand naar een externe API.

Stappen:

1. Haal via de API een vooraf ondertekende upload-URL op.
2. Lees het lokale bestand van de schijf.
3. Upload het bestand met HTTP PUT naar de vooraf ondertekende URL.

Configuratie:

• Pas zo nodig api_key, tenant_id, datatable_id en file_path aan.

"""
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.")

Paginering

Lijst-endpoints accepteren de queryparameters limit en offset en geven een platte JSON-array terug, zonder omhullend object of totaal aantal:

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

Vraag voor alle pagina’s herhaaldelijk data op met offset += limit totdat de antwoordarray korter is dan de aangevraagde limit (of leeg is). Waarden boven het maximum worden geweigerd met 400. De versiegebonden data-endpoints (datasets, versies en webhooks) volgen dezelfde regel. Voor de twee lijsten met datatabellen geldt een maximum van limit 250.

Versies en verouderde functies

• Alle routes hebben een versienummer onder /v1. Wijzigingen die bestaande toepassingen breken, verschijnen in een nieuwe versie en veranderen /v1 dus niet ongemerkt.
• Wijzigingen en verwijderingen van routes worden aangekondigd in de release notes.
• Belangrijke wijzigingen die clients raken, staan altijd in het changelog. Schrijf je in voor updates of controleer de release notes voordat je vastgezette API-clients bijwerkt.

Volgende stappen

• API-documentatie: complete documentatie van alle endpoints, inclusief request- en response-indeling
• Voorbeelden op GitHub: downloadbare voorbeelden en clientbibliotheken
• Je API-sleutel ophalen: zo verkrijg en beheer je je API-sleutel