---
title: REST API 시작하기
description: 앱의 피드백을 조회하고 수정 작업과 GitHub PR을 연결하는 OpenTester REST API.
---

# REST API 시작하기 {#rest-api-quick-start}

OpenTester 자동화 API로 앱의 피드백을 읽고, 수정할 내용을 작업으로 기록하고, 완성한 GitHub PR을 연결할 수 있습니다. [MCP](/ko/mcp/)도 같은 API를 사용합니다. 자체 도구나 CI에서 HTTP로 연결하려면 이 문서를 따르세요.

## 기본 주소 {#base-url}

운영 환경에서는 서비스 운영자가 제공한 HTTPS API 주소를 사용합니다. 기본 경로는 `/api/v1`입니다. 아래 로컬 예시는 API 서버를 직접 호출합니다.

```sh
export OPENTESTER_API_URL="http://localhost:4000/api/v1"
export OPENTESTER_APP_ID="aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa"
```

`OPENTESTER_APP_ID`를 개발자 콘솔에서 확인한 앱 ID로 바꾸고, 해당 앱에서 발급한 토큰을 `OPENTESTER_AGENT_TOKEN` 환경변수에 비밀 값으로 주입하세요. 문서 사이트의 `docs.` 주소는 API 주소가 아닙니다.

::: tip 먼저 준비할 것
앱 소유자 계정으로 개발자 콘솔의 **앱 정보 및 SDK → 코딩 에이전트 연결**에서 토큰을 발급하세요. 조회부터 PR 연결까지 사용하려면 `feedback:read`, `work-items:read`, `work-items:write`가 필요합니다. [인증과 권한](/ko/api/authentication)을 참고하세요.
:::

## 첫 번째 요청 {#first-request}

```sh
curl --fail-with-body --get \
  "$OPENTESTER_API_URL/apps/$OPENTESTER_APP_ID/automation/feedback" \
  --header "Authorization: Bearer $OPENTESTER_AGENT_TOKEN" \
  --header "Accept-Language: ko" \
  --data-urlencode "status=open" \
  --data-urlencode "limit=20"
```

피드백이 없으면 정상 응답은 다음과 같습니다.

```json
{
  "feedback": [],
  "total": 0,
  "limit": 20,
  "offset": 0
}
```

## 엔드포인트 {#endpoints}

아래 경로는 모두 `/api/v1/apps/:appId/automation`을 기준으로 합니다.

| 메서드   | 경로                                       | 목적           | 에이전트 권한      |
| -------- | ------------------------------------------ | -------------- | ------------------ |
| `GET`    | `/feedback`                                | 피드백 목록    | `feedback:read`    |
| `GET`    | `/feedback/:issueId`                       | 피드백 상세    | `feedback:read`    |
| `POST`   | `/change-requests`                         | 수정 작업 생성 | `work-items:write` |
| `GET`    | `/change-requests`                         | 수정 작업 목록 | `work-items:read`  |
| `GET`    | `/change-requests/:requestId`              | 수정 작업 상세 | `work-items:read`  |
| `POST`   | `/change-requests/:requestId/pull-request` | GitHub PR 연결 | `work-items:write` |
| `GET`    | `/tokens`                                  | 발급 토큰 목록 | 웹 세션 전용       |
| `POST`   | `/tokens`                                  | 토큰 발급      | 웹 세션 전용       |
| `DELETE` | `/tokens/:tokenId`                         | 토큰 철회      | 웹 세션 전용       |

API의 모든 동작은 경로의 앱에 한정됩니다. 같은 소유자가 관리하는 앱이라도 앱마다 토큰을 따로 발급합니다.

## 요청과 응답 규칙 {#request-and-response-conventions}

- 본문은 JSON이며 `Content-Type: application/json`을 사용합니다. 본문 크기 제한은 64 KiB입니다.
- ID는 UUID 문자열입니다. 날짜는 UTC ISO 8601 문자열입니다.
- 정의되지 않은 요청 필드와 쿼리 파라미터는 `400` 오류입니다.
- 성공한 `GET`은 `200`, `POST`는 `201`, 토큰 철회 `DELETE`는 `200`을 반환합니다. 같은 작업을 재시도한 `POST`도 `201`입니다.
- 목록에는 `total`, `limit`, `offset`이 포함됩니다. 상세 응답은 `feedback` 또는 `changeRequest` 객체로 감쌉니다.
- API 응답에는 `Cache-Control: no-store`가 설정됩니다.

### 페이지 나누기 {#pagination}

피드백과 수정 작업 목록에 같은 규칙을 적용합니다.

| 파라미터 | 기본값 | 범위              |
| -------- | ------ | ----------------- |
| `limit`  | `20`   | 정수 `1`–`50`     |
| `offset` | `0`    | 정수 `0`–`100000` |

최신 생성 순서이며 생성 시각이 같으면 ID 내림차순입니다. 다음 페이지는 `offset + limit`으로 요청합니다. 조회 중 새 데이터가 생길 수 있으므로 전체 목록을 수집할 때는 ID로 중복을 제거하세요. 현재 커서 기반 페이지 나누기는 제공하지 않습니다.

### 언어와 오류 {#language-and-errors}

`Accept-Language: ko`를 보내면 지원하는 오류 메시지가 한국어로 반환됩니다. 응답의 `Content-Language`에서 선택된 언어를 확인할 수 있습니다. 클라이언트 분기는 번역되는 `message` 문자열 대신 HTTP 상태 코드를 기준으로 처리하세요. [오류와 재시도](/ko/api/errors)를 참고하세요.

## 연결 흐름 {#integration-workflow}

1. [피드백 조회](/ko/api/feedback)로 수정할 보고의 ID와 재현 정보를 확인합니다.
2. [수정 작업 생성](/ko/api/change-requests)으로 목표·완료 기준·관련 피드백을 기록합니다.
3. 사용하는 코딩 도구에서 수정과 테스트를 수행하고 GitHub PR을 만듭니다.
4. 같은 수정 작업에 PR URL을 연결합니다.

수정 작업 생성은 코딩 에이전트를 실행하지 않습니다. PR 연결은 URL을 기록하며 병합·배포·피드백 상태 변경을 수행하지 않습니다. 앱에서 피드백을 제출하려면 [Android SDK](/ko/sdk/)를 사용하세요.