---
title: API 개요
description: Human Plugin 엔드포인트와 그 관계, 모든 응답에 공통으로 적용되는 규칙, API가 제공하지 않는 기능을 설명합니다.
canonical: https://developer.unico.io/ko/human-plugin/api-reference/overview
locale: ko
generated_by: markdown-export
---

# API 개요

프로세스 엔드포인트 3개와 헬스 프로브 2개.

Human Plugin은 사용자가 설정한 포트(기본값 `8080`)에서 일반 HTTP로 제공됩니다. 기본 URL은 네트워크 내부에서 컨테이너를 노출하는 주소이며, 예를 들어 `http://human-plugin.internal:8080`입니다.

| Method | Path | 용도 |
| --- | --- | --- |
| `POST` | `/v1/processes` | [프로세스 생성](/ko/human-plugin/api-reference/create-process), [플로우](/ko/human-plugin/api-reference/create-process#flows) 중 하나를 사용 |
| `GET` | `/v1/processes/{id}` | [프로세스 조회](/ko/human-plugin/api-reference/get-process) |
| `GET` | `/v1/processes/{id}/selfie` | [셀피 조회](/ko/human-plugin/api-reference/get-selfie) |
| `GET` | `/health/live` | 라이브니스. [상태 확인 및 모니터링](/ko/human-plugin/self-hosting/health-and-monitoring) 참조 |
| `GET` | `/health/ready` | 준비 상태(데이터베이스 ping) |

프로세스를 목록으로 조회하거나, 삭제하거나, 검색하는 엔드포인트는 없으며, 웹훅 수신기도 없습니다.

## 모든 호출에 적용되는 규칙

- **인증 헤더 없음.** Human Plugin은 호출자를 검증하지 않습니다. 대신 네트워크 접근을 제한하세요. [네트워킹 및 보안](/ko/human-plugin/self-hosting/networking-and-security)을 참조하세요.
- **JSON만 사용하며**, 필드 이름은 camelCase입니다.
- **응답은 `Cache-Control: no-store`입니다.**
- **오류**는 하나의 envelope인 `{"message": "INVALID_REQUEST", "details": []}`를 사용합니다. [오류 및 재시도](/ko/human-plugin/api-reference/errors-and-retries)를 참조하세요.
- **`id`는 Human Plugin의 프로세스 id입니다.** 생성할 때 보관해 두세요. 나중에 프로세스를 조회하는 데 사용합니다.

## 일반적인 순서

```mermaid
sequenceDiagram
  participant B as Your back-end
  participant H as Human Plugin
  B->>H: POST /v1/processes
  H-->>B: 201 + id, state, data
  B->>H: GET /v1/processes/{id}
  H-->>B: 200 + id, state, data (humanToken, ndocs)
```

다음: [프로세스 생성](/ko/human-plugin/api-reference/create-process).