API 레퍼런스

Ara에서 키를 생성하고, 검증하고, 공개 API를 사용해 보세요.

Markdown으로 보기

공개 API는 https://api.ara.so/v3에 있습니다. ara_ API 키는 키가 생성된 Ara 워크스페이스에 바인딩됩니다.

API 키 발급

  1. Ara에 로그인하고 워크스페이스를 엽니다.
  2. 설정 → Ara CLI를 엽니다.
  3. CI용 API 키 아래에서 키 생성을 선택합니다.
  4. 가장 좁은 범위의 스코프와 만료 기간을 선택한 후 키를 복사합니다.

키를 비밀번호처럼 취급하세요. 시크릿 매니저에 저장하고, 소스 컨트롤이나 브라우저 코드에는 절대 저장하지 마세요.

키 검증

셸에 키를 설정하고 /v3/self을 호출합니다:

$export ARA_API_KEY="ara_..."
$
$curl https://api.ara.so/v3/self \
>  -H "Authorization: Bearer $ARA_API_KEY"

응답에는 키에 바인딩된 조직 ID가 포함됩니다:

1{
2  "principal_type": "service_user",
3  "service_user_id": "key_3f9a",
4  "service_user_name": "ci-bot",
5  "org_id": "org_8c2d1e"
6}

나머지 예제에서 해당 값을 사용합니다:

$export ARA_ORG_ID="org_8c2d1e"

API 사용해 보기

연결된 저장소 목록 조회

repos:read 스코프가 필요합니다.

$curl "https://api.ara.so/v3/organizations/$ARA_ORG_ID/repositories" \
>  -H "Authorization: Bearer $ARA_API_KEY"

세션 시작

run 스코프가 필요합니다. acme/web을 워크스페이스에 연결된 저장소로 교체하세요.

$curl "https://api.ara.so/v3/organizations/$ARA_ORG_ID/sessions" \
>  -H "Authorization: Bearer $ARA_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "repo": "acme/web",
>    "prompt": "Fix the flaky auth test, add a regression case, and open a PR."
>  }'

응답에는 session_id가 포함됩니다. 세션 생성은 비동기로 처리됩니다.

세션 읽기

sessions:read 스코프가 필요합니다.

$export ARA_SESSION_ID="ses_91af3c"
$
$curl "https://api.ara.so/v3/organizations/$ARA_ORG_ID/sessions/$ARA_SESSION_ID" \
>  -H "Authorization: Bearer $ARA_API_KEY"

주요 스코프

스코프용도
run에이전트 작업 시작, 조정, 취소 및 예약
sessions:read세션, 메시지, 태그, 인사이트 및 첨부 파일 읽기
repos:read, repos:write저장소 읽기 및 인덱싱 관리
memory:read, memory:write편집 가능한 저장소 노트 읽기 및 관리
secrets:read, secrets:write시크릿 이름 목록 조회 및 값 쓰기 또는 삭제
plugins:read, plugins:writeMCP 서버 및 git 플러그인 읽기 및 관리
reviews:read, reviews:write풀 리퀘스트 리뷰 읽기 또는 트리거
analytics:read사용량, 큐 상태 및 감사 로그 읽기

필요한 최소한의 스코프만 사용하세요. 시크릿 값은 쓰기 전용이며 API를 통해 다시 읽을 수 없습니다.

정확한 요청 필드, 응답 스키마 및 모든 공개 엔드포인트는 전체 엔드포인트 레퍼런스를 참조하세요.

오류

상태 코드의미
401키가 없거나, 유효하지 않거나, 만료됨
403키에 필요한 스코프가 없거나, 워크스페이스에 접근할 수 없음
429요청 횟수 제한 초과. Retry-After 헤더를 준수하세요