V2 플로우를 위한 직접 실행 API

통합이 UI, 에이전트, 일정이 아니라 API를 통해 워크플로우를 직접 호출하는 경우, 기존 V1 워크플로우 마이그레이션 시에도 포함하여 V2 플로우를 올바르게 호출하기 위해 이 레퍼런스를 사용하세요.

개요

V1 워크플로우는 다음을 통해 실행됩니다:

POST /actions/execute/direct

V2 플로우의 경우 다음을 사용하세요:

POST /tools/execute-workflow

경고

V2 엔드포인트는 페이로드를 그대로 대체하는 방식이 아닙니다. V2 플로우 ID는 tool_id로 전송되며, 플로우 입력은 inputs 아래의 일반 런타임 값으로 전송됩니다.

인증

EKB API 자격 증명을 요청 헤더로 제공하세요:

X-API-KEY: <api-key>
X-API-SECRET: <api-secret>
Content-Type: application/json

경고

문서, 소스 관리, 티켓, 채팅 메시지에 실제 자격 증명을 절대 포함하지 마세요. 노출된 자격 증명은 즉시 해제하고 재생성하세요.

요청 본문

{
  "project_id": "<project-id>",
  "tool_id": "<v2-flow-id>",
  "inputs": {
    "<flow-input-name>": "<runtime-value>"
  },
  "execution_mode": "workflow",
  "mode": "manual"
}

입력 이름은 대소문자를 구분합니다 — V2 플로우에 구성된 입력 이름을 사용하세요. 예를 들어 New Input 1이라는 입력은 다음과 같이 제출해야 합니다:

{
  "inputs": {
    "New Input 1": "I am Gaurav"
  }
}

플로우 입력의 전체 정의를 런타임 값으로 전송하지 마세요:

{
  "inputs": {
    "New Input 1": {
      "id": "new_input_1",
      "type": "string",
      "value": "I am Gaurav",
      "required": true
    }
  }
}

id, type, description, required 필드는 저장된 플로우 구성에 속하며, 실행 요청에는 값만 포함되어야 합니다.

예제

curl --location 'https://api.getodin.ai/tools/execute-workflow' \
  --header 'X-API-KEY: <api-key>' \
  --header 'X-API-SECRET: <api-secret>' \
  --header 'Content-Type: application/json' \
  --data '{
    "project_id": "<project-id>",
    "tool_id": "<v2-flow-id>",
    "inputs": {
      "New Input 1": "I am Gaurav"
    },
    "execution_mode": "workflow",
    "mode": "manual"
  }'

게시된 버전 실행

플로우를 게시하거나 승격한 후 다음을 추가하세요:

{
  "environment": "live"
}

이렇게 하면 라이브 환경에 배포된 버전이 선택됩니다. 플로우가 게시되기 전의 초기 테스트 동안에는 environment를 생략하세요.

엔드포인트는 기본적으로 완전한 실행 결과를 기다립니다. 필요할 때 명시적으로 제공할 수 있습니다:

{
  "return_response": true
}

응답

성공적인 요청은 실행 결과를 반환합니다:

{
  "success": true,
  "message": "Workflow executed successfully",
  "node_results": {},
  "execution_time_ms": 1250,
  "execution_id": "<execution-id>",
  "error": null
}

node_results의 내용은 플로우가 사용하는 노드에 따라 다릅니다.

일반적인 오류

상태	의미
401 Unauthorized	API 키 또는 시크릿이 없거나, 유효하지 않거나, 해제됨
402 Payment Required	연결된 팀에 충분한 크레딧이 없음
403 Forbidden	API 사용자가 프로젝트 구성원이 아니거나 플로우를 실행할 권한이 없음
404 Not Found	tool_id가 존재하지 않거나 지정된 프로젝트에 속하지 않음
422 Unprocessable Entity	필수 요청 필드가 없거나 유효하지 않은 유형임
200 및 "success": false	요청은 수락되었지만 플로우 노드가 실패함 — error, node_results, execution_id를 검사하세요

문제 해결 시 HTTP 상태와 전체 응답 본문을 기록하세요. 공유하기 전에 자격 증명과 민감한 입력 데이터를 제거하세요.

V1 엔드포인트에서의 마이그레이션

V1	V2
엔드포인트: /actions/execute/direct	엔드포인트: /tools/execute-workflow
flow_id	tool_id
ui_form	inputs
입력 정의 포함	포함되지 않음 — 일반 런타임 값만, 구성된 플로우 입력 이름을 키로 사용

정보

엔드포인트 /v2/actions/execute/direct는 레거시 Automator/Activepieces 실행용이며, 마이그레이션된 V2 플로우를 실행하는 데 사용해서는 안 됩니다.

워크플로우 V1 마이그레이션 도구

플랫폼 내 마이그레이션 도구로 기존 V1 워크플로우를 V2로 마이그레이션하세요.