> 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`를 확인하십시오           |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.genesis.autify.com/features-ko/integrations/api-guide.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.