API calls

How to Make API Calls to ProcessMind

This guide will provide you with examples and best practices for making API calls to ProcessMind’s services. Whether you’re looking to retrieve data, submit information, or automate workflows, understanding how to interact with our API is essential. For detailed API documentation, including available endpoints, authentication methods, example requests, response formats, and step-by-step integration guides, please visit our API Documentation on GitHub.

Authentication Variables

• apiKey For all API requests, you will need to include your API key in the request headers for authentication. The API key can be obtained from your ProcessMind account settings.
• tenantId Some API endpoints require a Tenant ID to specify the context of the request. This ID is unique to your organization and can also be found in your account settings.
• datatableId When working with datasets, you will need to provide the Datatable ID to identify which datatable you are interacting with. This ID is available in the dataset settings menu [Get Data Table ID] within ProcessMind.

Direct File Uploads

ProcessMind supports direct file uploads to datatables using presigned URLs. This method allows you to securely upload files without exposing your API key or other sensitive information. Keep in mind that presigned URLs are time-limited and should be used promptly after retrieval. To access the direct upload URL you need to make a GET request to the endpoint. This URL can be retrieved by going to the dataset settings menu [Get upload URL] within ProcessMind. Here the time limit can be set from 1 hour, 1 week or 1 month maximum.

API Endpoint Overview

API Base URL

All API requests should be made to the following base URL: https://api.processmind.com

How to Get a Pre‑signed Upload URL

Endpoint: GET /tenant/{tenantId}/datatable/{datatableId}/uploads/presignedurl
Parameters:

• tenantId – ID of the tenant (string).
• datatableId – ID of the datatable you want to upload to (string).
• apiKey – Your API key (string).

Returns:
A response object containing PreSignedUploadUrl, which is a temporary URL you can use to upload a file directly (usually via HTTP PUT).

Example (using the helper):

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

How to List Datasets

Endpoint: GET /tenant/{tenantId}/datasets
Parameters:

• tenantId – ID of the tenant.
• apiKey – Your API key.

Returns:
An array of dataset objects belonging to the tenant.

Example:

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

How to Retrieve Tenant Details

Endpoint: GET /tenant/{tenantId}
Parameters:

• tenantId – ID of the tenant.
• apiKey – Your API key.

Returns:
An object with metadata about the tenant such as name, created date and plan.

Example:

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

How to Retrieve Organization Details

Endpoint: GET /tenant/{tenantId}/organization
Parameters:

• tenantId – ID of the tenant.
• apiKey – Your API key.

Returns:
Information about the organization associated with the tenant (e.g. company name, address, contact details).

Example:

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

How to Upload a File

The uploadFile function demonstrates how to upload a file using the pre‑signed URL. The general flow is:

1. Get the pre‑signed URL using the getPresignedUploadUrl call.
2. Perform a PUT request to that URL with the file contents. The pre‑signed URL authorizes the upload directly to the storage provider, so no further credentials are needed.
3. (Optionally) Notify your API that the upload is complete, if required by your backend.

Here is a simplified example using fetch to upload a file:

async function uploadFile({ apiKey, tenantId, datatableId, file }) {
	// Step 1: Obtain a pre-signed 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
	});
	
	// Step 3: Optionally notify your API of completion
	// (depends on your backend implementation)
}

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/tenant/<TENANT_ID>/datatable/<DATATABLE_ID>/uploads/presignedurl" \
	| 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 uploadFileToProcessMind().
• 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 uploadFileToProcessMind().
 * - 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: `/tenant/${tenantId}/datatable/${datatableId}/uploads/presignedurl`, apiUrl})).PreSignedUploadUrl;
}

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

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

async function getOrganization({apiKey, tenantId, apiUrl = "https://api.processmind.com"}) {
	return await getApi({apiKey, path: `/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}/tenant/{tenant_id}/datatable/{datatable_id}/uploads/presignedurl"
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.")