> For the complete documentation index, see [llms.txt](https://help.genesis.autify.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.genesis.autify.com/features-ko/integrations/api-guide.md).

# API 가이드

이 문서에서는 Autify Genesis에서 사용할 수 있는 API의 종류·사용법·제한을 설명합니다.

## API 키 관리

API 키의 생성·확인·삭제는 [API 키 관리](/features-ko/settings/organization-settings/api-key-management.md) 참조.

## API로 워크플로 실행하기

외부 애플리케이션이나 프로그램에서 워크플로를 실행하려면 **API 액세스**를 활성화해야 합니다.

다음 절차로 설정 활성화와 엔드포인트 확인을 진행합니다.

### 1. 워크플로 편집 화면 열기

API로 실행하려는 워크플로의 편집 화면을 여십시오.

### 2. 트리거 설정 메뉴 표시하기

화면 상단의 **기타 작업**을 클릭하고, 표시된 메뉴에서 **트리거**를 클릭하십시오.

<figure><img src="/files/XFrhM0lLuPDxcsr50BZe" alt="트리거 설정 메뉴 스크린샷"><figcaption><p>트리거 설정 메뉴</p></figcaption></figure>

### 3. API 액세스 활성화하기

기본적으로 API 액세스는 OFF로 설정되어 있습니다.

1. **API 액세스** 스위치를 ON으로 설정하십시오.
2. **동시 실행 정책**에서 같은 워크플로의 이전 API 실행이 아직 대기 중이거나 실행 중일 때, 새 요청을 어떻게 처리할지 선택하십시오.

| 선택지      | 내용                                                       |
| -------- | -------------------------------------------------------- |
| 병렬로 실행   | 새 실행을 시작하고 이전 실행도 그대로 계속합니다                              |
| 이전 실행 취소 | 같은 워크플로의 API 실행에서 대기 중이거나 실행 중인 이전 실행을 취소한 후 새 실행을 시작합니다 |

### 4. API 엔드포인트 확인하기

API 액세스를 ON으로 설정하면 전용 **API 엔드포인트**가 표시됩니다.

<figure><img src="/files/TYeAG9ekiwAEhhgVIivB" alt="API 액세스 설정 스크린샷"><figcaption><p>API 액세스 설정</p></figcaption></figure>

* 엔드포인트 형식: `https://genesis.autify.com/api/workflows/{templateId}/trigger`

## REST API

API 키를 사용하여 외부 시스템에서 Genesis의 워크플로를 실행하거나 실행 상황을 확인할 수 있습니다.

### 워크플로 트리거

**엔드포인트**

```http
POST /api/workflows/{templateId}/trigger
```

**요청 헤더**

| 헤더             | 값                  | 설명 |
| -------------- | ------------------ | -- |
| `x-api-key`    | 발급한 API 키          | 필수 |
| `Content-Type` | `application/json` | 권장 |

**요청 본문**

워크플로에 정의된 컨텍스트 변수에 대응하는 키와 값의 쌍을 JSON 형식으로 지정합니다.

```json
{
  "변수명1": "값1",
  "변수명2": "값2"
}
```

{% hint style="info" %}
페이로드의 값은 모두 **문자열 형식**으로 지정하십시오. 숫자·배열·객체는 사용할 수 없습니다. 워크플로에 정의되지 않은 키를 포함하면 오류가 됩니다.
{% endhint %}

{% hint style="info" %}
트리거 설정에서 **이전 실행 취소**를 선택한 경우, 새 API 요청을 보내면 같은 워크플로의 대기 중이거나 실행 중인 이전 API 실행이 취소된 후 새 실행이 시작됩니다.
{% endhint %}

**응답(성공 시)**

```json
{
  "success": true,
  "executionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

반환된 `executionId`를 사용하여 실행 상황을 확인할 수 있습니다.

**요청 예(curl)**

```bash
curl -X POST https://genesis.autify.com/api/workflows/{templateId}/trigger \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"target_url": "https://example.com"}'
```

### 실행 상황 가져오기

**엔드포인트**

```http
GET /api/executions/{executionId}
```

**요청 헤더**

| 헤더          | 값         | 설명 |
| ----------- | --------- | -- |
| `x-api-key` | 발급한 API 키 | 필수 |

**요청 예(curl)**

```bash
curl -X GET https://genesis.autify.com/api/executions/{executionId} \
  -H "x-api-key: your-api-key"
```

**응답 예(성공 시)**

```json
{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "running",
  "workflowName": "워크플로 이름",
  "blockCount": 5,
  "completedBlocks": 2,
  "createdAt": "2026-03-16T00:00:00.000Z",
  "updatedAt": "2026-03-16T00:00:05.000Z",
  "startedAt": "2026-03-16T00:00:01.000Z",
  "finishedAt": null,
  "cancelRequestedAt": null,
  "cancelReason": null,
  "error": null,
  "triggerType": "api",
  "triggerPayload": {
    "exampleField": "exampleValue"
  },
  "triggerMetadata": {
    "ip": "xxx.xxx.xxx.xxx",
    "userAgent": "curl/8.0.0",
    "apiKeyId": "ak_xxxxxxxxxxxx"
  },
  "state": {
    "workflowId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "executionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "status": "running",
    "blocks": {
      "block-1": {
        "status": "completed",
        "startTime": "2026-03-16T00:00:01.000Z",
        "endTime": "2026-03-16T00:00:02.000Z",
        "inputs": {},
        "output": "..."
      }
    },
    "createdAt": "2026-03-16T00:00:00.000Z",
    "updatedAt": "2026-03-16T00:00:05.000Z"
  }
}
```

**실행 상태 종류**

| 상태               | 설명       |
| ---------------- | -------- |
| `pending`        | 실행 대기    |
| `running`        | 실행 중     |
| `completed`      | 완료       |
| `failed`         | 실패       |
| `cancelled`      | 취소됨      |
| `skipped`        | 조건으로 미실행 |
| `review_pending` | 검토 대기    |

## 문제 해결

### 인증 오류

| 상황                                                       | 원인                           | 해결 방법                      |
| -------------------------------------------------------- | ---------------------------- | -------------------------- |
| `Missing API key`(401)                                   | `x-api-key` 헤더가 없음           | `x-api-key` 헤더를 추가하십시오     |
| `Invalid API key`(401)                                   | API 키가 유효하지 않거나 존재하지 않음      | 올바른 API 키를 사용하고 있는지 확인하십시오 |
| `API key is not associated with an organization`(403)    | API 키에 조직이 연결되어 있지 않음        | 유효한 API 키를 다시 생성하십시오       |
| `Unauthorized`(403)                                      | API 키의 사용자가 대상 조직의 구성원이 아님   | 조직의 구성원이 발급한 API 키를 사용하십시오 |
| `API key does not have access to this organization`(403) | API 키의 조직과 워크플로의 조직이 일치하지 않음 | 같은 조직에서 발급한 API 키를 사용하십시오  |

### 페이로드 오류

| 상황                                                         | 원인                       | 해결 방법                       |
| ---------------------------------------------------------- | ------------------------ | --------------------------- |
| `Invalid JSON payload`(400)                                | 요청 본문이 올바른 JSON 형식이 아님   | JSON 구문을 확인하십시오             |
| `Payload too large`(413)                                   | 페이로드가 10 MB를 초과함         | 페이로드 크기를 10 MB 이내로 줄이십시오    |
| `Invalid payload: expected object with string values`(500) | 페이로드의 값이 문자열 이외(숫자·배열 등) | 모든 값을 문자열 형식으로 하십시오         |
| `Unexpected fields in payload`(500)                        | 워크플로에 정의되지 않은 키가 포함됨     | 워크플로의 컨텍스트 변수에 맞게 키를 수정하십시오 |

### 리소스 오류

| 상황                                                           | 원인                                | 해결 방법                               |
| ------------------------------------------------------------ | --------------------------------- | ----------------------------------- |
| `Workflow template not found or API access not enabled`(404) | 템플릿 ID가 존재하지 않거나 API 트리거가 비활성화됨   | 템플릿 ID를 확인하거나 워크플로의 API 설정을 활성화하십시오 |
| `Invalid template ID`(400)                                   | 템플릿 ID가 UUID 형식이 아님               | 올바른 템플릿 ID를 사용하십시오                  |
| `Usage limit reached`(403)                                   | 조직의 크레딧 한도에 도달함                   | 관리자에게 크레딧 추가를 요청하십시오                |
| `Workflow template must belong to a project`(400)            | 템플릿이 프로젝트에 연결되어 있지 않음             | 템플릿을 기존 프로젝트에 연결하십시오                |
| `Project not found`(404)                                     | 템플릿에 연결된 프로젝트가 존재하지 않음            | 프로젝트 설정을 확인하십시오                     |
| `Execution not found`(404)                                   | 지정한 `executionId`의 실행 기록이 존재하지 않음 | 유효한 `executionId`를 확인하십시오           |