> ## Documentation Index
> Fetch the complete documentation index at: https://www.octoparse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Octoparse OpenAPI
> 인증, 작업 관리, 클라우드 추출 및 데이터 내보내기를 위한 Octoparse OpenAPI 레퍼런스입니다.
Octoparse OpenAPI를 사용하면 프로그래밍 방식으로 작업을 관리하고 클라우드 추출을 실행하며 스크래핑한 데이터를 가져올 수 있습니다.
## 인증
보호된 엔드포인트를 인증하는 가장 간단한 방법은 Octoparse API 키입니다. Octoparse 계정 센터에서 키를 생성한 뒤 `x-api-key` 요청 헤더에 포함하세요. 같은 API 키를 Octoparse OpenAPI, MCP 서버 및 CLI에서 사용할 수 있습니다.
Octoparse 계정 센터에서 API 키 페이지를 엽니다.
API 키는 일반적으로 `op_sk_`로 시작합니다.
```bash theme={null}
curl "https://openapi.octoparse.com/taskGroup" \
--header "x-api-key: op_sk_xxxxx"
```
API 키를 안전하게 보관하세요. 브라우저 측 코드, 공개 저장소, 스크린샷 또는 로그에 노출하지 마세요.
액세스 토큰 인증도 지원됩니다. `POST /token`에서 액세스 토큰을 받은 뒤 `Authorization: Bearer ` 형식으로 전송하세요.
## AgentTools API
AgentTools API는 기존의 저수준 작업, 클라우드 추출 및 데이터 API 위에 구축된 템플릿 기반 AI 에이전트 워크플로 계층입니다. 에이전트나 자동화가 모든 저수준 엔드포인트를 직접 연결하지 않고 적합한 스크래핑 템플릿을 찾고, 실행을 시작하며, 서버가 제공하는 다음 단계 안내를 따르고, 내보내기 메타데이터를 가져와야 할 때 사용하세요.
새 스크래핑 흐름:
```text theme={null}
searchTemplates -> executeTask -> exportData
```
기존 작업 흐름:
```text theme={null}
searchTasks -> startOrStopTask -> exportData
```
AgentTools를 처음 사용하나요? [엔드투엔드 워크플로 튜토리얼](https://helpcenter.octoparse.com/ko/articles/15855832-run-a-scraping-workflow-with-the-octoparse-agenttools-api)에서 템플릿 검색, 작업 시작 및 결과 내보내기 방법을 알아보세요.
AgentTools 응답의 비즈니스 필드는 `data` 안에 있습니다. `requestId`는 문제 해결에만 사용하고, 폴링 간격을 하드코딩하는 대신 `retryGuidance`, `suggestedNextCall`, `workflow`, `toolHint`를 따르세요.
AgentTools API에는 `x-api-key` 인증이 필요합니다. 일부 엔드포인트에는 `x-external-user-id`도 필요하므로 정확한 헤더는 각 엔드포인트 레퍼런스를 확인하세요.
## 시작하기 전에
Octoparse OpenAPI를 사용하려면 실행 가능한 작업이 하나 이상 있는 **스탠다드, 프로페셔널 또는 엔터프라이즈** 계정이 필요합니다. 계정이 없다면 [여기에서 회원가입](https://www.octoparse.kr/signup)하세요.
현재 API 버전: **v1.0**
## 기본 URL
모든 요청은 기본 URL을 기준으로 URL 인코딩해야 합니다.
```text theme={null}
https://openapi.octoparse.com
```
자리 표시자는 `{xxxx}` 형식으로 표시되며 실제 값으로 바꿔야 합니다. 예를 들어 *작업 검색* 요청 URL은 다음과 같습니다.
```text theme={null}
GET https://openapi.octoparse.com/task/search?taskGroupId={taskGroupId}
```
작업 그룹 ID가 `abc`라면 URL은 `https://openapi.octoparse.com/task/search?taskGroupId=abc`가 됩니다.
## 요청 한도
Octoparse는 API 사용량을 **초당 20개 요청**으로 제한합니다. `429` 상태 코드가 반환되면 요청 속도를 낮추세요.
성공한 응답은 HTTP `200`을 반환합니다. 다른 상태 코드는 각 엔드포인트의 [레퍼런스](#) 섹션을 확인하세요.
## 권한
계정에 각 서비스를 사용할 권한이 있는지 확인하세요. 권한이 없다면 계정을 업그레이드하세요.
| 서비스 | API | 필수 플랜 |
| ------- | ----------------------- | ------------------- |
| 액세스 토큰 | 새 토큰 발급 | 모든 사용자 |
| 액세스 토큰 | 토큰 새로 고침 | 모든 사용자 |
| 작업 그룹 | 작업 그룹 정보 가져오기 | 스탠다드, 프로페셔널, 엔터프라이즈 |
| 작업 | 작업 검색 | 스탠다드, 프로페셔널, 엔터프라이즈 |
| 작업 | 작업 복제 | 스탠다드, 프로페셔널, 엔터프라이즈 |
| 작업 | 작업 이동 | 스탠다드, 프로페셔널, 엔터프라이즈 |
| 작업 | 액션 매개변수 가져오기 | 프로페셔널, 엔터프라이즈 |
| 작업 | 작업 매개변수 업데이트 | 프로페셔널, 엔터프라이즈 |
| 작업 | 액션 매개변수 업데이트 | 프로페셔널, 엔터프라이즈 |
| 작업 | 루프 아이템 목록 업데이트 | 프로페셔널, 엔터프라이즈 |
| 작업 | 작업 URL 업데이트 | 프로페셔널, 엔터프라이즈 |
| 클라우드 추출 | 작업 시작 | 프로페셔널, 엔터프라이즈 |
| 클라우드 추출 | 작업 중지 | 프로페셔널, 엔터프라이즈 |
| 클라우드 추출 | 작업 상태 가져오기 | 프로페셔널, 엔터프라이즈 |
| 클라우드 추출 | 작업 상태 V2 가져오기 | 프로페셔널, 엔터프라이즈 |
| 클라우드 추출 | 하위 작업 상태 가져오기 | 프로페셔널, 엔터프라이즈 |
| 클라우드 추출 | 하위 작업 시작 | 프로페셔널, 엔터프라이즈 |
| 클라우드 추출 | 하위 작업 중지 | 프로페셔널, 엔터프라이즈 |
| 데이터 | 내보내지 않은 데이터 가져오기 | 스탠다드, 프로페셔널, 엔터프라이즈 |
| 데이터 | 데이터를 내보냄으로 표시 | 스탠다드, 프로페셔널, 엔터프라이즈 |
| 데이터 | 오프셋으로 데이터 가져오기 | 스탠다드, 프로페셔널, 엔터프라이즈 |
| 데이터 | 지정된 배치에서 오프셋으로 데이터 가져오기 | 스탠다드, 프로페셔널, 엔터프라이즈 |
| 데이터 | 데이터 삭제 | 스탠다드, 프로페셔널, 엔터프라이즈 |
## 문제 해결
모든 응답에는 `requestId`가 포함됩니다. 요청이 실패하면 문제 진단을 위해 `requestId`를 [Octoparse 지원팀](mailto:support@octoparse.com)에 전달하세요.