이 페이지에서

API 개요

ProcessMind API 호출 방법

이 가이드에서는 데이터를 조회하고 정보를 제출하거나 워크플로를 자동화할 때 ProcessMind API를 호출하는 방법과 권장 사항을 예제로 설명합니다.

요청 및 응답 형식을 포함한 전체 엔드포인트 문서는 API 레퍼런스를 참조하세요.

추가 예제와 클라이언트 라이브러리는 GitHub의 API 문서에서 확인하세요.

API 기본 URL

모든 API 요청은 다음 주소로 전송합니다.

https://api.processmind.com

모든 경로는 /v1 아래 버전별로 제공됩니다. 전체 API 사양은 기계 판독이 가능한 형식(OpenAPI 3.1)으로 다음 주소에서 확인할 수 있습니다.

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

인증

공개 OpenAPI 문서(/v1/openapi.json)와 MCP OAuth 엔드포인트를 제외한 모든 API 요청에는 x-api-key 헤더에 API 키가 필요합니다.

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

API 키는 ProcessMind 계정 설정에서 확인할 수 있습니다. 자세한 내용은 API 키 확인을 참조하세요.

상태 코드

ProcessMind API는 표준 HTTP 상태 코드를 사용합니다.

상태 코드 의미
200 OK 요청이 성공했습니다
201 Created 리소스가 생성되었습니다
204 No Content 요청이 성공했으며 응답 본문은 없습니다
400 Bad Request 요청이 잘못되었거나 매개변수가 없거나 유효하지 않습니다
401 Unauthorized API 키가 없거나 유효하지 않습니다
403 Forbidden 인증은 되었지만 해당 작업을 수행할 권한이 없습니다
404 Not Found 리소스가 존재하지 않습니다
500 Internal Server Error 예상하지 못한 서버 오류가 발생했습니다

주요 개념

  • apiKey: 모든 API 요청에 사용하는 인증 토큰입니다.
  • tenantId: 작업공간 또는 조직의 범위를 식별합니다. 계정 설정에서 확인할 수 있습니다.
  • datatableId: 데이터 작업에 사용할 특정 데이터 테이블을 식별합니다. ProcessMind의 데이터셋 설정 메뉴에서 데이터 테이블 ID 가져오기를 선택해 확인할 수 있습니다.

API로 할 수 있는 작업

ProcessMind API를 사용하면 다음 작업을 수행할 수 있습니다.

  • 테넌트 관리: 테넌트 정보 조회, 설정 업데이트, 통계 확인
  • 사용자 관리: 테넌트와 조직의 사용자 추가, 업데이트 또는 삭제
  • 프로세스 관리: 프로세스 생성, BPMN 모델 업로드, 폴더별 정리
  • 데이터 연결: 분석을 위해 데이터 테이블을 프로세스에 매핑
  • 데이터 업로드: CSV/XLSX 파일을 데이터 테이블에 직접 업로드
  • 데이터셋 관리: 데이터셋과 데이터 테이블 목록 조회, 확인 및 삭제

자주 사용하는 예제

다음 예제에서는 ProcessMind API로 자주 사용하는 작업을 수행하는 방법을 설명합니다.

사전 서명된 업로드 URL 가져오기

데이터 테이블에 파일을 업로드하려면 먼저 사전 서명된 URL을 가져옵니다.

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

데이터셋 목록 조회

테넌트의 모든 데이터셋을 조회합니다.

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

테넌트 정보 가져오기

테넌트 세부 정보를 조회합니다.

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

프로세스 생성

테넌트에 새 프로세스를 생성합니다.

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

BPMN 모델 업로드

프로세스 모델을 정의할 BPMN 파일을 업로드합니다.

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

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

프로세스에 데이터 매핑

분석을 위해 데이터 테이블을 프로세스에 연결합니다.

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

테넌트에 사용자 추가

테넌트에 사용자를 추가합니다.

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

참고: 본문에 지정한 역할 필드(isAdminInTenant, access, isDashboardViewer)는 입력한 그대로 적용됩니다. 사용자 관리 엔드포인트는 테넌트 관리자 권한 전체를 다루므로, 관리 권한을 부여해도 되는 호출자에게만 쓰기 권한이 있는 API 키를 발급하세요. System API는 초대 이메일을 보내지 않으므로 사용자를 온보딩하는 책임은 사용자에게 있습니다.

파일 업로드

ProcessMind에 파일을 업로드하는 기본 절차는 다음과 같습니다.

  1. getPresignedUploadUrl 호출로 사전 서명된 URL을 가져옵니다.
  2. 파일 내용을 포함해 해당 URL로 PUT 요청을 보냅니다.
  3. 사전 서명된 URL을 사용하면 추가 인증 정보 없이 클라우드 스토리지에 직접 업로드할 수 있습니다.

다음은 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
	});
}

info

  • 사전 서명된 URL은 정해진 시간이 지나면 만료됩니다(기본값은 업로드와 다운로드 모두 1시간). URL을 가져온 후 바로 사용하세요.
  • 업로드가 실패한 경우(예: 네트워크 연결 중단) 재시도하기 전에 새 사전 서명 URL을 요청하세요.
  • apiKey를 안전하게 보관하고 클라이언트 측(예: 공개 프런트엔드)에 노출하지 마세요.

전체 예제

다음은 여러 언어로 작성한 전체 예제입니다. 복사해 바로 사용할 수 있습니다.

Bash 예제: 파일 업로드

모든 값이 자리표시자로 지정된, curl을 두 번 호출해 ProcessMind에 파일을 업로드하는 최소한의 Bash 스크립트입니다.

Bash 예제 다운로드
#!/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 예제: 로컬 CSV 파일 업로드

사전 서명된 URL을 사용해 로컬 CSV 파일을 ProcessMind에 업로드합니다.

단계:

  1. API에서 사전 서명된 업로드 URL을 가져옵니다.
  2. 디스크에서 로컬 파일을 읽습니다.
  3. HTTP PUT을 사용해 사전 서명된 URL로 파일을 업로드합니다.

설정:

  • uploadFile()을 호출할 때 API 키, tenantId, datatableId, filePath를 지정합니다.
  • API 기본 URL은 https://api.processmind.com로 설정되어 있습니다.
Node.js 예제 다운로드
/**
 * 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 예제: 로컬 CSV 파일 업로드

사전 서명된 URL을 사용해 로컬 CSV 파일을 원격 API에 업로드합니다.

단계:

  1. API에서 사전 서명된 업로드 URL을 가져옵니다.
  2. 디스크에서 로컬 파일을 읽습니다.
  3. HTTP PUT을 사용해 사전 서명된 URL로 파일을 업로드합니다.

설정:

  • 필요에 따라 api_key, tenant_id, datatable_id, file_path를 업데이트합니다.
Python 예제 다운로드
"""
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.")

페이지네이션

목록 엔드포인트는 limit 및 offset 쿼리 매개변수를 받으며, 별도 래퍼가 없는 JSON 배열을 반환합니다(래퍼와 전체 개수 없음).

매개변수 유형 기본값 최대값
limit 정수 100 1,000(데이터 테이블 목록은 250)
offset 정수 0 없음
GET /v1/tenant/{tenantId}/processes?limit=50&offset=100

전체 결과를 페이지 단위로 조회하려면 응답 배열이 요청한 limit보다 짧거나 비어 있을 때까지 offset += limit를 지정해 요청을 반복합니다. 최대값을 초과하면 400 오류가 반환됩니다. 버전이 지정된 데이터 엔드포인트(데이터셋, 버전, 웹훅)도 같은 방식을 따르며, 두 데이터 테이블 목록의 최대 limit 값은 250입니다.

버전 관리 및 지원 중단

  • 모든 경로는 /v1 아래에서 버전별로 제공됩니다. 호환성을 깨는 변경 사항은 /v1를 예고 없이 변경하는 대신 새 버전으로 제공됩니다.
  • 경로 변경 및 삭제는 릴리스 노트에 안내합니다.
  • 클라이언트에 영향을 주는 주요 변경 사항은 항상 변경 로그에 기록합니다. API 클라이언트를 업그레이드하기 전에 구독하거나 변경 로그를 확인하세요.

다음 단계

  • API 레퍼런스: 모든 엔드포인트의 요청 및 응답 형식을 확인할 수 있습니다.
  • GitHub 예제: 다운로드 가능한 예제와 클라이언트 라이브러리
  • API 키 발급: API 키 발급 및 관리 방법

info

API 관련 문의나 지원이 필요하시면 지원팀에 문의하거나 API 예제 저장소에 이슈를 등록하세요.

더 나은 프로세스를 설계하고, 연결된 아키텍처를 구축해 관리하세요.

신용카드 등록이나 대기 없이 바로 이용할 수 있습니다. 조직의 업무 방식을 명확하고 유기적으로 연결된 프로세스 설계로 바꿔 보세요.

프로세스 아키텍처를 구축하고, 소유권과 통제 기준을 정립하며, 모든 계층의 역할과 책임을 조율하세요.

무료 체험을 시작하고 프로세스를 관리·운영하고 지속적으로 개선할 수 있는 신뢰할 만한 기반을 마련하세요.