본문 바로가기
개발가이드시작하기프로젝트별 연동 지시문

프로젝트별 연동 지시문

명세 내보내기
OpenAPI 3.0.3Postman 컬렉션Markdown

GEThttps://apick.app/rest/subagent/v1/status전체 10개 경로
인증
Bearer 키
요청 형식
form-data / GET
응답
JSON
경로
10개

알아둘 점

에이픽 서브에이전트

조사·추출·요약·비교를 위임하고, 원문 인용과 해시로 검수합니다.

각 프로젝트에 전달할 연동 지침에서 복사해 사용하는 지시문, 연결 코드로 인증키 연결, 첫 확인(목록 작업 1P), 프로젝트별 파일 범위, 실제 위임·근거 검수와 오류 대응을 확인하세요. 지침 파일 내려받기

Node.js 22.17 이상에서 설치합니다. Codex·Claude Code 설정의 기존 항목은 보존합니다.

npm install -g apick-subagent
apick-subagent install
# 마이페이지 › API 정보에서 연결 코드를 발급해 붙여 넣은 뒤 클라이언트 재시작
apick-subagent login
apick-subagent doctor

프로젝트 폴더를 열고 “이 자료의 비교를 apick-subagent에 위임하고 핵심 근거를 검수해 줘”라고 요청하세요. 설치만으로 모든 요청의 위임이 강제되지는 않습니다. 작업에 맞는 위임 여부는 주 에이전트가 판단합니다.

배포 파일로 직접 설치할 수도 있습니다: npm install -g https://apick.app/downloads/apick-subagent-1.0.5.tgz

모든 요청에 Authorization: Bearer API_KEY가 필요합니다. 접수에는 Idempotency-Key를 보내세요. 같은 키와 같은 내용은 기존 작업을 반환하며, 다른 내용은 409 오류입니다. 연결 종료는 작업 취소가 아닙니다.

메서드
경로
설명
GET
/rest/subagent/v1/status
접수 상태·잔액·지원 작업
POST
/rest/subagent/v1/files
상대경로 path, bytes, sha256, retention으로 업로드 시작
POST
/rest/subagent/v1/files/{file_id}/parts
part_no(0부터), base64 data를 반환된 part_bytes 크기로 순서대로 업로드
POST
/rest/subagent/v1/files/{file_id}/complete
전체 크기·해시·텍스트 검증 후 파일 준비
DELETE
/rest/subagent/v1/files/{file_id}
원문·관련 결과·캐시 즉시 삭제, 처리 중 작업 취소
POST
/rest/subagent/v1/jobs
kind, goal, file_ids, focus, acceptance, retention으로 접수
GET
/rest/subagent/v1/jobs/{job_id}
상태·결과·결과 해시, cursor로 다음 결과 조회
POST
/rest/subagent/v1/jobs/{job_id}/evidence
evidence_ids로 원문 인용·줄 번호·해시 조회
POST
/rest/subagent/v1/jobs/{job_id}/review
result_hash와 decision(accepted 또는 rejected) 기록
POST
/rest/subagent/v1/jobs/{job_id}/cancel
작업 취소. 이미 쓴 비용이 확정되지 않았으면 확정된 뒤 정산합니다.
DELETE
/rest/subagent/v1/jobs/{job_id}
결과·근거·캐시 삭제
GET
/rest/subagent/v1/usage
호출·토큰·캐시·과금·최근 작업
curl https://apick.app/rest/subagent/v1/status \
  -H "Authorization: Bearer $APICK_API_KEY"

curl -X POST https://apick.app/rest/subagent/v1/jobs \
  -H "Authorization: Bearer $APICK_API_KEY" \
  -H "Idempotency-Key: project-review-20261004-001" \
  -H "Content-Type: application/json" \
  -d '{"kind":"compare","goal":"문서 두 개의 차이와 충돌을 비교하세요","file_ids":["업로드 완료한 파일 ID"],"focus":[],"acceptance":["모든 주장에 원문 근거"],"retention":"seven_days"}'

kind는 inventory(목록), extract(추출), summarize(요약), compare(비교) 중 하나입니다. 파일 수·토큰·누적 사용액의 상품 한도는 없습니다. 파일은 part_bytes 크기로 나눠 올리고, 결과가 길면 cursor로 다음 부분을 조회합니다.

원격 주소는 https://apick.app/mcp/subagent입니다. Bearer 인증을 지원하는 Streamable HTTP 클라이언트에서 연결하세요. 원격 MCP는 이미 업로드한 자료로 작업합니다. 내 컴퓨터의 파일을 올리는 일은 설치 패키지가 합니다.

도구
기능
apick_status
상태·잔액 확인
apick_dispatch
멱등 작업 접수
apick_collect
짧은 결과와 다음 페이지 확인
apick_evidence
근거 조회
apick_review
결과 해시에 검수 기록
apick_cancel
작업 취소
apick_usage
내 사용 통계

설치비·도입비·구독료는 없고, 성공한 작업의 실제 사용량에 따라 정산합니다. 성공한 작업은 최소 1P, AI를 사용한 작업은 작업당 기본요금 5P가 최소액입니다. 승인된 동일 결과 캐시 재사용은 1P입니다. 접수 시 예상 최대 비용을 예약하고 차액을 해제합니다. 실패·취소·자동 검증 실패는 청구하지 않습니다. 비용 미확정이 24시간 지속되면 예약을 해제합니다.

자료는 7일 후 만료됩니다. retention을 none으로 보내면 검수 완료 후 삭제하며, 임시 보관은 최대 1시간입니다. 즉시 삭제도 가능합니다.

코드
대응
AUTH_REQUIRED
키·계정·허용 IP 확인
INSUFFICIENT_POINTS
포인트 충전 후 다시 접수
IDEMPOTENCY_CONFLICT
기존 요청 내용 확인. 응답 유실에는 같은 키·같은 내용을 유지
INTEGRITY_FAILED
자료·근거 검증 실패. 청구하지 않으며 상태 확인 후 내용 검토
SCOPE_TOO_LARGE
한 작업은 파일 150개·합계 5MB 이하. 범위를 나눠 따로 접수하며 청구하지 않음
UNAVAILABLE
기존 작업 ID로 상태 확인. 새 키로 무작정 재접수하지 않음
EXPIRED
자료 보관 기간 종료. 필요한 자료를 다시 업로드

사용량·비용 확인 · 제품 소개와 검증 사례

요약은 목표와 관련된 원문 인용을 자료(파일)별로 묶습니다. 비교는 동일 문구와 자료별 고유 문구를 구분합니다. 자동 근거 검증은 인용·행·해시 일치 검사이며 의미 판단과 최종 결론은 주 에이전트가 검수합니다.

요청과 응답

1상태·목록 조회
GET/rest/subagent/v1/status
  • Bearer 인증
  • 요청 본문 없음
  • JSON 응답
요청 파라미터 없음

추가 폼 항목이 없습니다. 인증 헤더만 보내면 됩니다.

응답 필드

이 경로의 응답 형식은 오른쪽 응답 예시를 확인하세요.

2작업 접수
POST/rest/subagent/v1/jobs
  • Bearer 인증
  • multipart/form-data
  • JSON 응답
요청 파라미터 없음

추가 폼 항목이 없습니다. 인증 헤더만 보내면 됩니다.

응답 필드

이 경로의 응답 형식은 오른쪽 응답 예시를 확인하세요.

3API 요청
POST/rest/subagent/v1/files
  • Bearer 인증
  • multipart/form-data
  • JSON 응답
요청 파라미터 없음

추가 폼 항목이 없습니다. 인증 헤더만 보내면 됩니다.

응답 필드

이 경로의 응답 형식은 오른쪽 응답 예시를 확인하세요.

4API 요청
POST/rest/subagent/v1/files/:file_id/parts
  • Bearer 인증
  • multipart/form-data
  • JSON 응답

경로의 file_id는 앞 단계에서 받은 값으로 바꾸세요. 예제는 APICK_FILE_ID 환경변수에서 읽습니다.

요청 파라미터 없음

추가 폼 항목이 없습니다. 인증 헤더만 보내면 됩니다.

응답 필드

이 경로의 응답 형식은 오른쪽 응답 예시를 확인하세요.

5API 요청
POST/rest/subagent/v1/files/:file_id/complete
  • Bearer 인증
  • multipart/form-data
  • JSON 응답

경로의 file_id는 앞 단계에서 받은 값으로 바꾸세요. 예제는 APICK_FILE_ID 환경변수에서 읽습니다.

요청 파라미터 없음

추가 폼 항목이 없습니다. 인증 헤더만 보내면 됩니다.

응답 필드

이 경로의 응답 형식은 오른쪽 응답 예시를 확인하세요.

6상태·목록 조회
GET/rest/subagent/v1/jobs/:job_id
  • Bearer 인증
  • 요청 본문 없음
  • JSON 응답

경로의 job_id는 앞 단계에서 받은 값으로 바꾸세요. 예제는 APICK_JOB_ID 환경변수에서 읽습니다.

요청 파라미터 없음

추가 폼 항목이 없습니다. 인증 헤더만 보내면 됩니다.

응답 필드

이 경로의 응답 형식은 오른쪽 응답 예시를 확인하세요.

7API 요청
POST/rest/subagent/v1/jobs/:job_id/evidence
  • Bearer 인증
  • multipart/form-data
  • JSON 응답

경로의 job_id는 앞 단계에서 받은 값으로 바꾸세요. 예제는 APICK_JOB_ID 환경변수에서 읽습니다.

요청 파라미터 없음

추가 폼 항목이 없습니다. 인증 헤더만 보내면 됩니다.

응답 필드

이 경로의 응답 형식은 오른쪽 응답 예시를 확인하세요.

8API 요청
POST/rest/subagent/v1/jobs/:job_id/review
  • Bearer 인증
  • multipart/form-data
  • JSON 응답

경로의 job_id는 앞 단계에서 받은 값으로 바꾸세요. 예제는 APICK_JOB_ID 환경변수에서 읽습니다.

요청 파라미터 없음

추가 폼 항목이 없습니다. 인증 헤더만 보내면 됩니다.

응답 필드

이 경로의 응답 형식은 오른쪽 응답 예시를 확인하세요.

9작업 취소
POST/rest/subagent/v1/jobs/:job_id/cancel
  • Bearer 인증
  • multipart/form-data
  • JSON 응답

경로의 job_id는 앞 단계에서 받은 값으로 바꾸세요. 예제는 APICK_JOB_ID 환경변수에서 읽습니다.

요청 파라미터 없음

추가 폼 항목이 없습니다. 인증 헤더만 보내면 됩니다.

응답 필드

이 경로의 응답 형식은 오른쪽 응답 예시를 확인하세요.

10상태·목록 조회
GET/rest/subagent/v1/usage
  • Bearer 인증
  • 요청 본문 없음
  • JSON 응답
요청 파라미터 없음

추가 폼 항목이 없습니다. 인증 헤더만 보내면 됩니다.

응답 필드

이 경로의 응답 형식은 오른쪽 응답 예시를 확인하세요.

응답 처리

HTTP 성공과 업무 결과를 구분하세요. 경로별 응답 필드와 예시는 위 요청과 응답에 함께 있습니다.

오류 코드

응답을 아래 순서로 확인하세요. 결과 유무와 과금 여부는 서로 다릅니다.

  1. HTTP 상태전송·인증·입력 오류
  2. api.successAPI 처리 여부
  3. data · result업무 결과와 오류 문구
  4. api.cost이번 요청의 과금
인증·포인트 오류 result.error 문구
코드
HTTP
의미·조치
유효하지 않은 API키 입니다.
401
Authorization: Bearer 헤더의 인증키를 확인하세요.
허용되지 않은 IP주소 입니다.
401
마이페이지의 허용 IP 설정과 요청 서버 IP를 확인하세요.
비활성화된 계정입니다.
401
계정 이용 상태를 고객지원으로 문의하세요.
사용 가능한 포인트이 부족합니다.
200
HTTP 200이어도 result.error가 있으면 실패입니다. 포인트를 충전한 뒤 다시 요청하세요. 이 응답은 과금되지 않습니다.
인증 정보를 확인할 수 없습니다.
424
일시적인 확인 실패입니다. 잠시 후 다시 시도하세요.
폼 입력 오류 error.code
코드
HTTP
의미·조치
FORM_DATA_INVALID
400
필드 이름·값의 타입·배열 인덱스를 확인하세요. 인덱스는 0부터 연속으로 사용합니다.
FORM_DATA_FIELD_CONFLICT
400
같은 값과 중첩 경로를 동시에 지정하지 마세요.
MULTIPART_LIMIT_OR_PARSE_ERROR
400·413
boundary·파일 크기·필드 개수를 확인하세요. 서비스별 제한이 우선 적용됩니다.

요금·이용 조건

기본 요금서비스별 요금 조건 확인

실제 차감 금액은 응답의 api.cost로 확인하세요. 상세 요금은 요금정책에서 볼 수 있습니다.

연동 팁

  • 요청 예제의 오류 처리 포함 모드는 시간 제한과 업무 실패 판정을 함께 보여줍니다.
  • 인증키는 서버 환경변수에 두고 브라우저·앱에 넣지 마세요.
  • HTTP 성공과 업무 결과를 구분하고, 실패 응답의 오류 문구를 그대로 기록하세요.

개발가이드 검색

API 이름·경로·파라미터·오류 코드로 찾을 수 있습니다.

표시 가격은 기본 단가입니다. 상세 과금 조건은 각 가이드에서 확인하세요.