API 가이드

East Agile Tracker API는 사람만큼이나 에이전트를 위해 설계되었습니다. UI에서 할 수 있는 모든 것을 API로 할 수 있으며 — UI가 노출하지 않는 몇 가지도 거기에 있습니다.

이 가이드는 10분 안에 여러분을 0에서 “백로그를 스크립팅하기”까지 데려갑니다. 전체 엔드포인트 레퍼런스는 API 명세를 참고하세요.

세 종류의 자격 증명

여러분은 X-TrackerToken 헤더의 키로 인증합니다. 직접 발급하는 키가 두 종류 있고, MCP 클라이언트가 여러분을 대신해 얻는 세 번째 종류가 있습니다:

• User keys (ea_user_…) — 여러분으로 행동합니다. Account Settings → API Keys에서 만드세요. 개인 스크립트, CLI 도구, 통합에 사용하세요.
• Agent keys (ea_agent_…) — 한 프로젝트의 이름을 가진 에이전트로 행동합니다. Project Settings → Agents에서 만드세요. 프로젝트에 이름을 가진 동료로 참여해야 하는 AI 에이전트 — Claude Code, Codex, 여러분 자신의 것 — 에 사용하세요.
• MCP tokens (ea_mcp_…) — 동의 페이지에서 승인한 뒤 MCP 클라이언트(Claude, IDE)에 발급되는 OAuth 2.1 액세스 토큰입니다. 여러분으로 행동하며, Account Settings → Connected apps에서 취소할 수 있습니다.

직접 발급하는 두 가지의 차이점:

	User key	Agent key
범위	여러분의 모든 프로젝트	하나의 특정 프로젝트
감사 로그의 정체성	여러분의 이름	에이전트의 이름
역할	각 프로젝트에서의 여러분의 역할	키 생성 시 설정(viewer, member, 또는 manager — 발급하는 멤버 자신의 역할을 넘지 못함)
취소	키를 취소; 다른 키/세션으로 접근 유지	키를 취소 또는 회전; 에이전트가 즉시 접근 권한 상실
적합한 용도	개인 자동화, 스크립트	이력에서 여러분과 구별되어야 하는 AI 에이전트

선호한다면 Authorization: Bearer … 헤더 스타일도 작동합니다.

안녕하세요, API

프로젝트를 가져오기:

curl https://eastagiletracker.com/api/v1/projects \
  -H "X-TrackerToken: $TRACKER_TOKEN"

또는 에이전트 키의 경우, 그것이 범위로 하는 프로젝트를 나열하기:

curl https://eastagiletracker.com/api/v1/projects \
  -H "X-TrackerToken: ea_agent_xxxxx"

API는 JSON이고, REST 풍이며, /api/v1/에서 버전이 지정됩니다. 사람과 에이전트에게 동일한 형태입니다.

프로젝트 생성

curl -X POST https://eastagiletracker.com/api/v1/projects \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Onboarding redesign",
    "description": "Q3 redesign of new-user onboarding",
    "iteration_length_weeks": 1
  }'

응답은 project_id와 서버가 적용한 모든 기본값(추정 척도, done 상태 등)을 포함합니다.

스토리 생성

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Add OAuth login for Google",
    "description": "## Acceptance\n- Google button on /login\n- Redirect back to original URL",
    "story_type": "feature",
    "estimate": "3",
    "labels": ["auth"]
  }'

estimate는 문자열로 된 척도 값의 라벨 — "3", 또는 Fibonacci 척도에서는 "13" — 입니다. 프로젝트 척도의 한 지점과 일치해야 하기 때문입니다. JSON 숫자는 거부됩니다.

라이프사이클을 통해 스토리 이동

전환 엔드포인트는 요청된 이동을 검증하고 오류 시 허용된 다음 상태를 반환합니다:

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories/$STORY_ID/transitions \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "to": "started" }'

필드는 **to**입니다(to_state가 아님). 이동이 불법이면 — 예를 들어 unstarted에서 곧장 accepted로 건너뛰려 했다면 — 응답은 구조화된 오류 세부 정보와 함께 422 invalid_transition입니다:

{
  "code": "invalid_transition",
  "error": "Cannot move story from `unstarted` to `accepted`",
  "details": { "from": "unstarted", "to": "accepted", "allowed": ["started"] }
}

이것은 API를 에이전트 친화적으로 만드는 작은 것 중 하나입니다: 에이전트는 details.allowed를 읽고 산문을 스크래핑하지 않고도 올바른 다음 이동을 선택할 수 있습니다.

rejected는 전환 엔드포인트에서 종착 상태입니다. 거부된 스토리를 다시 작업에 올리려면 POST …/stories/{sid}/restart를 호출하세요. POST …/stories/{sid}/reject는 delivered 스토리를 거부하는 동사 형태입니다.

스토리에 댓글 달기

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories/$STORY_ID/comments \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Investigation done. Picking this up." }'

댓글은 API 키를 소유한 누구에게나 귀속됩니다 — 그것이 에이전트 키라면 댓글의 작성자는 에이전트입니다.

멱등성 쓰기

모든 쓰기 엔드포인트는 Idempotency-Key 헤더를 받습니다. 같은 키를 같은 본문으로 재시도하면 같은 응답을 돌려받습니다. 같은 키를 다른 본문으로 재시도하면 409 idempotency_conflict를 받습니다:

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Refactor auth middleware", "story_type": "chore" }'

이것은 재시도 루프의 에이전트에게 매우 중요합니다 — 쓰기 도중 충돌하고, 같은 키로 재시도하면, 중복 스토리가 없습니다.

일괄 전환

한 번에 많은 스토리를 이동하세요. 각 스토리는 독립적으로 판단됩니다. 하나의 불법 이동이 나머지를 실패시키지 않습니다.

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories/bulk_transition \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "story_ids": [101, 102, 103],
    "to": "delivered"
  }'

이벤트 스트림 따라가기

사람이 하는 것에 반응하려는 에이전트를 위해, 이벤트 엔드포인트를 폴링하세요:

curl "https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/events?since=$LAST_CURSOR&types=story.created,story.transitioned,comment.added" \
  -H "X-TrackerToken: $TRACKER_TOKEN"

응답은 행위자, 리소스, 변경을 담은 커서 페이지네이션 이벤트 스트림입니다. 각 이벤트는 ID를 가집니다. 본 마지막 ID를 since로 전달해 중단한 곳에서 재개하세요. 웹훅 없음, 스크래핑 없음, 놓친 이벤트 없음. 스트림에는 member 역할이 필요합니다 — viewer는 403을 받습니다.

검색

GET /projects/{id}/search?q=<query>는 프로젝트의 스토리 전체에 대해 강력한 전문 검색 + 구조화 검색을 실행합니다. 쿼리 언어는 GitHub의 이슈 검색 한정자를 본떴으므로 — 여러분(또는 AI 에이전트)이 GitHub에서 이미 알고 있는 구문이 대부분 그대로 통합니다.

curl -G "https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/search" \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  --data-urlencode 'q=payment crash type:bug,chore owner:@me created:>2026-05-01'

응답은 관련도순으로 정렬된 스토리를 담은 JSON 봉투입니다:

{ "results": [ /* canonical story objects */ ], "total": 42, "limit": 50, "offset": 0 }

total은 페이지 크기가 아니라 전체 일치 수입니다. limit(기본 50, 최대 1000)과 offset으로 페이지를 넘기고, sort=relevance(기본), created, created_asc, updated, 또는 state로 정렬하세요.

문법

• 자유 텍스트는 스토리의 제목, 참조, 설명에 매칭됩니다(전문 검색, 어간 추출 및 순위 매김). 정확한 구절은 "따옴표"로 감싸세요.
• 한정자는 field:value 형태입니다. 대안은 쉼표로 구분합니다(필드 안에서 OR): type:bug,chore. 한정자끼리는 공백으로 구분합니다(한정자 간 AND).
• 어떤 항이나 한정자든 앞에 -를 붙여 부정합니다: -label:wontfix.
• 날짜와 포인트의 범위: 양끝 포함 a..b, 또는 한쪽이 열린 >x / <x.

한정자

한정자	예	매칭 대상
type:	type:bug,chore	스토리 유형
state:	state:started,finished	워크플로 상태
label:	label:"my label"	라벨
epic:	epic:"Checkout"	에픽에 속한 스토리
priority:	priority:p1	우선순위
points:	points:3 · points:1..5 · points:>3	추정 값 또는 범위
iteration:	iteration:42	이터레이션 id
created: updated: started: completed: release:	created:2026-05-01..2026-06-01 · updated:>2026-06-01	날짜 또는 범위(일 단위); release:는 스토리의 릴리스 날짜
owner: requester: follower: reviewer: commenter: mention:	owner:claire · owner:@me	이름 또는 이메일로 지정한 사람 — 멤버 와 에이전트, mention:도 포함; @me는 여러분 자신
has:blocker	has:blocker	미해결 블로커가 있음
is:	is:unestimated · is:icebox · is:backlog · is:blocked	플래그

mywork:는 owner:의 별칭입니다 — mywork:me는 owner:@me입니다. 예전의 scheduled: 한정자는 폐기되어 조용히 무시됩니다. release:를 사용하세요.

쉼표 OR(type:bug,chore)는 패싯 한정자에 적용됩니다. 사람 한정자(owner: requester: follower: reviewer: commenter: mention:)는 단일 값만 받습니다.

예

payment crash                              full text "payment" AND "crash"
"exact phrase"                             a phrase
type:bug,chore state:started               bugs or chores that are started
owner:@me -label:wontfix                   mine, excluding the wontfix label
points:3..8 created:2026-05-01..2026-06-01 estimated 3-8, created in May
follower:tomas has:blocker                 tomas follows it and it's blocked
is:backlog updated:>2026-06-01             backlog items touched since Jun 1

같은 쿼리 문자열이 보드의 검색 상자(실시간 결과 열을 엽니다)와 이 API를 모두 구동합니다 — 사람과 에이전트에게 하나의 문법입니다. 댓글, 작업, 블로커의 내용 검색은 로드맵에 있습니다. 오늘날 자유 텍스트는 스토리 자체의 제목, 참조, 설명을 다룹니다.

API 탐색

실시간 OpenAPI 3 스펙은 다음에 있습니다:

https://api.eastagiletracker.com/api/v1/openapi.json

Swagger UI는 다음에 있습니다:

https://api.eastagiletracker.com/api/v1/docs/

/openapi.json과 /docs는 인증되지 않습니다 — 에이전트는 키를 갖기 전에 계약을 읽을 수 있습니다. 키를 보유하면, /api/v1/meta(이는 유효한 키를 요구함)가 자신의 정체성과 스토리 유형별 전환 그래프를 반환합니다. 참조 데이터 조회(/story_types, /story_states, /effort_scales, /priority_scales)도 인증되지 않습니다. 함께 이것들은 에이전트가 시행착오 403 없이 “여기서 무엇을 할 수 있는가?”에 답하게 해 줍니다.

제공되는 openapi.json은 각 필드의 maxLength를 포함해 쓰기 엔드포인트의 요청 본문 스키마를 담고 있으므로, 클라이언트는 보내기 전에 검증할 수 있습니다. 명세는 같은 형태를 요약합니다.

WebSocket 제어

상호작용 자동화 — 스크립트에서 로그인된 브라우저 세션을 구동하거나, 튜토리얼을 위해 UI를 원격 제어하는 — 를 위해 WebSocket 채널이 있습니다:

const ws = new WebSocket('wss://eastagiletracker.com/ws/control?token=SESSION_JWT')
ws.send(JSON.stringify({ action: 'get_state', id: 'req-1' }))

token은 API 키가 아니라 브라우저 세션의 JWT입니다 — ea_user_*나 ea_agent_* 키는 업그레이드 전에 거부됩니다. 대부분의 사용자는 이것이 필요 없습니다. REST로 충분하지 않은 경우를 위해 거기에 있습니다.

다른 트래커에서 가져오기

대량 마이그레이션을 스크립팅한다면:

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/import \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -F "source=pivotal" \
  -F "file=@pivotal_export.csv"

지원되는 파일 소스: pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json, eat(East Agile Tracker 자체 익스포트 — 왕복 형식). multipart 엔드포인트는 동기적으로 실행되며 결과 개수로 응답합니다.

GitHub는 파일 대신 API에서 임포트하며, JSON 엔드포인트를 통합니다 — file 없이 저장소 좌표만 필요합니다:

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/import/json \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "source": "github",
        "owner": "octocat",
        "repo": "hello-world",
        "token": "ghp_…",
        "include_pull_requests": false,
        "include_milestones": false,
        "include_releases": false,
        "include_dependencies": false
      }'

JSON 엔드포인트는 비동기입니다: { "import_id", "status" }와 함께 202로 응답하며, 잡이 done 또는 failed에 이를 때까지 GET /projects/{id}/imports/{import_id}를 폴링합니다. 프로젝트당 한 번에 하나의 임포트만 실행됩니다 — 진행 중에 두 번째로 호출하면 409 import_already_running입니다. 잡의 진행 필드를 포함한 전체 루프는 GitHub 저장소에서 프로젝트 채우기에 있습니다.

token은 요청상으로는 선택 사항이지만 조회 자체는 항상 인증을 거칩니다 — GitHub의 GraphQL API에서 실행되며 그곳에는 익명 등급이 없습니다. token을 생략하면 서버가 플랫폼 토큰으로 대체합니다. 공개 저장소만 읽고, 모든 호출자가 공유하며, GraphQL 예산이 500 포인트 아래로 떨어지면 import_github_shared_quota_low로 거부됩니다. 비공개 저장소이거나 플랫폼 토큰을 설정하지 않은 배포(import_github_no_token)라면 본인의 토큰이 필요합니다. 어느 토큰이 쓰이든 업스트림 GitHub 호출에만 사용되며 저장되거나 되돌려 보내지지 않습니다. GitHub의 인증 없는 REST 상한 60 요청을 포함한 전체 내용은 GitHub 저장소에서 프로젝트 채우기에 있습니다.

드라이런 미리보기. 아무 소스에나 "dry_run": true(JSON) 또는 -F "dry_run=true"(multipart)를 추가하세요. 임포트는 실제 실행과 정확히 동일하게 파싱, 해석, 중복 제거를 수행하고 동일한 결과 개수(imported, skipped, errors, unmatched)를 만들어 낸 다음, 모든 것을 롤백합니다 — 아무것도 쓰이지 않습니다. JSON 엔드포인트에서는 드라이런이든 아니든 개수가 폴링한 잡에 실려 도착합니다.

제한. 업로드 본문은 10 MiB, 단일 임포트는 5,000 스토리로 제한됩니다. 둘 중 하나라도 초과하면 아무것도 쓰지 않고 400입니다. 파일을 다시 임포트하는 것은 안전합니다 — 이미 임포트된 행(소스 id로 매칭됨)은 중복되지 않고 건너뜁니다.

프로젝트 익스포트

형식 목록은 어떤 프로젝트 역할이든 볼 수 있지만, 다운로드는 소유자 전용입니다:

# 등록된 익스포트 형식: { id, name, content_type, drops, includes_archived }
curl https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/export/formats \
  -H "X-TrackerToken: $TRACKER_TOKEN"

# 한 형식 다운로드(eat는 완전한 충실도의 왕복 CSV)
curl https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/export/eat \
  -H "X-TrackerToken: $TRACKER_TOKEN" -o project-export.csv

인터체인지 형식 id: eat, jira, pivotal, shortcut, trello, asana, gitlab, linear, plane, plane_json, 그리고 문서 형식 pdf와 docx. 모든 첨부 파일은 GET /projects/{id}/export/attachments에서 하나의 zip으로 다운로드할 수 있습니다.

오류 형식

모든 오류는 최소한 다음을 갖춘 JSON입니다:

{
  "code": "invalid_transition",
  "error": "Cannot move story from `unstarted` to `accepted`"
}

많은 오류 응답은 details 객체도 포함합니다 — validation_failed에는 details.fields(위반한 필드 이름의 배열), 422 invalid_transition에는 details.allowed(from/to와 함께). 그것들을 사용하세요. 429 rate_limited는 같은 JSON 봉투에 Retry-After 헤더를 함께 실어 보냅니다.

페이지네이션

목록 엔드포인트는 limit과 cursor를 받습니다. cursor는 불투명합니다. 이전 응답의 next_cursor를 전달하세요. limit 상한은 엔드포인트마다 다릅니다 — 스토리, 댓글, 프로젝트는 200, 이벤트는 500, 검색과 감사 로그는 1000. 응답을 잘라내야 했던 일반(커서 없는) 목록은 헤더로 그 사실을 알립니다: X-Tracker-Pagination-Truncated, -Limit, -Offset, -Next-Offset이며, 마지막 값을 다음 페이지의 offset=으로 되돌려 보내세요. 전체 개수 헤더는 없습니다.

다음은 무엇인가

• API 명세 — 모든 엔드포인트, 모든 동사, 모든 형태.
• 사용 안내 → 에이전트 — UI 측: 에이전트 키 발급, 에이전트 명명, 취소.
• 소개 — API 뒤의 개념: 스토리, 상태, 이터레이션, 속도, 에이전트.