API-Übersicht

API-Aufrufe an ProcessMind senden

Diese Anleitung enthält Beispiele und bewährte Vorgehensweisen für Aufrufe der ProcessMind-API, mit denen Sie Daten abrufen, Informationen übermitteln oder Workflows automatisieren.

Die vollständige Dokumentation der Endpunkte mit Anfrage- und Antwortformaten finden Sie in der API-Referenz.

Weitere Beispiele und Client-Bibliotheken finden Sie in der API-Dokumentation auf GitHub.

API-Basis-URL

Senden Sie alle API-Anfragen an:

https://api.processmind.com

Alle Routen sind unter /v1versioniert. Die vollständige maschinenlesbare API-Spezifikation (OpenAPI 3.1) finden Sie unter:

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

Authentifizierung

Für alle API-Anfragen ist Ihr API-Schlüssel im Header x-api-key erforderlich. Ausgenommen sind das öffentliche OpenAPI-Dokument (/v1/openapi.json) und die MCP-OAuth-Endpunkte:

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

Den API-Schlüssel finden Sie in den Einstellungen Ihres ProcessMind-Kontos. Eine Anleitung enthält der Abschnitt API-Schlüssel abrufen.

Statuscodes

Die ProcessMind-API verwendet die standardmäßigen HTTP-Statuscodes:

Wichtige Begriffe

• apiKey: Ihr Authentifizierungstoken für alle API-Anfragen.
• tenantId: Kennzeichnet den Kontext Ihres Arbeitsbereichs bzw. Ihrer Organisation. Sie finden die ID in Ihren Kontoeinstellungen.
• datatableId: Kennzeichnet eine bestimmte Datentabelle für Datenoperationen. Sie finden die ID über die Option ID der Datentabelle abrufen im Einstellungsmenü des Datensatzes in ProcessMind.

Mögliche Aktionen

Mit der ProcessMind-API können Sie:

• Mandanten verwalten: Mandanteninformationen abrufen, Einstellungen aktualisieren und Statistiken anzeigen
• Benutzer verwalten: Benutzer zu Mandanten und Organisationen hinzufügen, aktualisieren oder daraus entfernen
• Prozesse verwalten: Prozesse erstellen, BPMN-Modelle hochladen und in Ordnern organisieren
• Daten verbinden: Datentabellen zur Analyse Prozessen zuordnen
• Daten hochladen: CSV- und XLSX-Dateien direkt in Datentabellen hochladen
• Datensätze verwalten: Datensätze und Datentabellen auflisten, prüfen und löschen

Häufige Beispiele

Die folgenden Praxisbeispiele zeigen, wie Sie häufige Vorgänge mit der ProcessMind-API ausführen.

Vorab signierte Upload-URL abrufen

Um eine Datei in eine Datentabelle hochzuladen, rufen Sie zunächst eine vorab signierte URL ab:

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

Datensätze auflisten

Rufen Sie alle Datensätze in Ihrem Mandanten ab:

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

Mandanteninformationen abrufen

Rufen Sie die Details zu Ihrem Mandanten ab:

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

Prozess erstellen

Erstellen Sie einen neuen Prozess in Ihrem Mandanten:

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

BPMN-Modell hochladen

Laden Sie eine BPMN-Datei hoch, um Ihr Prozessmodell festzulegen:

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

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

Daten einem Prozess zuordnen

Verbinden Sie eine Datentabelle mit einem Prozess, um sie zu analysieren:

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

Benutzer zu einem Mandanten hinzufügen

Fügen Sie Ihrem Mandanten einen Benutzer hinzu:

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

Hinweis: Rollenfelder im Request-Body (isAdminInTenant, access, isDashboardViewer) werden unverändert übernommen. Die Endpunkte für die Benutzerverwaltung bieten vollständige Mandantenadministration. Geben Sie daher nur Aufrufern API-Schlüssel mit Schreibrechten, denen Sie administrative Kontrolle anvertrauen. Die System-API versendet keine Einladungs-E-Mail. Sie sind dafür verantwortlich, den Benutzer einzurichten.

Dateien hochladen

Der allgemeine Ablauf für den Datei-Upload in ProcessMind:

1. Rufen Sie mit dem Aufruf getPresignedUploadUrl eine vorab signierte URL ab.
2. Senden Sie den Dateiinhalt mit einer PUT-Anfrage an diese URL.
3. Die vorab signierte URL autorisiert den Upload direkt in den Cloud-Speicher. Weitere Zugangsdaten sind nicht erforderlich.

Hier ein vereinfachtes Beispiel mit 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
	});
}

Vollständige Beispiele

Im Folgenden finden Sie vollständige, direkt kopierbare Beispiele in verschiedenen Programmiersprachen.

Bash-Beispiel: Datei hochladen

Ein minimales Bash-Skript, das mit zwei curl-Aufrufen eine Datei in ProcessMind hochlädt. Alle Werte sind Platzhalter.

#!/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-Beispiel: Lokale CSV-Datei hochladen

Lädt eine lokale CSV-Datei über eine vorab signierte URL in ProcessMind hoch.

Schritte:

1. Rufen Sie über die API eine vorab signierte Upload-URL ab.
2. Lesen Sie die lokale Datei von der Festplatte ein.
3. Laden Sie die Datei mit HTTP PUT über die vorab signierte URL hoch.

Konfiguration:

• Geben Sie beim Aufruf von uploadFile() Ihren API-Schlüssel, tenantId, datatableId und filePath an.
• Die API-Basis-URL ist auf https://api.processmind.com gesetzt.

/**
 * 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-Beispiel: Lokale CSV-Datei hochladen

Lädt eine lokale CSV-Datei über eine vorab signierte URL an eine Remote-API hoch.

Schritte:

1. Rufen Sie über die API eine vorab signierte Upload-URL ab.
2. Lesen Sie die lokale Datei von der Festplatte ein.
3. Laden Sie die Datei mit HTTP PUT über die vorab signierte URL hoch.

Konfiguration:

• Passen Sie api_key, tenant_id, datatable_id und file_path bei Bedarf an.

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

Seitennummerierung

Listen-Endpunkte akzeptieren die Abfrageparameter limit und offset und geben ein unverpacktes JSON-Array zurück, ohne Umschlag und ohne Gesamtanzahl:

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

Um alle Ergebnisse seitenweise abzurufen, fragen Sie wiederholt mit offset += limit an, bis das Antwort-Array weniger Einträge enthält als der angeforderte Wert für limit oder leer ist. Werte über dem Maximum werden mit 400 abgelehnt. Für versionierte Daten-Endpunkte (Datensätze, Versionen, Webhooks) gilt dieselbe Konvention. Bei den beiden Datentabellenlisten ist limit auf 250 begrenzt.

Versionierung und Veraltung

• Alle Routen sind unter /v1 versioniert. Änderungen, die die Abwärtskompatibilität beeinträchtigen, erscheinen in einer neuen Version und ändern /v1 nicht unbemerkt.
• Änderungen an Routen und deren Entfernung werden in den Versionshinweisen angekündigt.
• Wichtige, für Clients sichtbare Änderungen sind immer im Änderungsprotokoll aufgeführt. Abonnieren Sie es oder prüfen Sie es vor dem Upgrade festgelegter API-Clients.

Nächste Schritte

• API-Referenz: Vollständige Dokumentation aller Endpunkte mit Anfrage- und Antwortformaten
• GitHub-Beispiele: Herunterladbare Beispiele und Client-Bibliotheken
• API-Schlüssel abrufen: API-Schlüssel abrufen und verwalten