API 가이드

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

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

두 종류의 키

여러분은 X-TrackerToken 헤더의 API 키로 인증합니다. 두 종류가 있습니다:

• User keys (ea_user_…) — 여러분으로 행동합니다. Account Settings → API Keys에서 만드세요. 개인 스크립트, CLI 도구, 통합에 사용하세요.
• Agent keys (ea_agent_…) — 한 프로젝트의 이름을 가진 에이전트로 행동합니다. Project Settings → Agents에서 프로젝트 소유자로 만드세요. 프로젝트에 이름을 가진 동료로 참여해야 하는 AI 에이전트 — Claude Code, Codex, 여러분 자신의 것 — 에 사용하세요.

차이점:

	User key	Agent key
범위	여러분의 모든 프로젝트	하나의 특정 프로젝트
감사 로그의 정체성	여러분의 이름	에이전트의 이름
역할	각 프로젝트에서의 여러분의 역할	키 생성 시 설정(viewer 또는 member)
취소	키를 취소; 다른 키/세션으로 접근 유지	키를 취소; 에이전트가 즉시 접근 권한 상실
적합한 용도	개인 자동화, 스크립트	이력에서 여러분과 구별되어야 하는 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"]
  }'

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

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

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를 읽고 산문을 스크래핑하지 않고도 올바른 다음 이동을 선택할 수 있습니다.

스토리에 댓글 달기

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.created" \
  -H "X-TrackerToken: $TRACKER_TOKEN"

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

필터 구문으로 검색

curl "https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/search?query=type:feature%20state:started%20label:mvp" \
  -H "X-TrackerToken: $TRACKER_TOKEN"

사용 가능한 필터:

Filter	Example	Description
type:	type:feature	스토리 유형으로 필터
state:	state:started	상태로 필터
label:	label:"my label"	라벨로 필터
owner:	owner:claire	소유자로 필터
requester:	requester:tomas	요청자로 필터
has:	has:blocker	블로커가 있는 스토리
is:	is:unestimated	추정되지 않은 기능

자유 텍스트는 제목과 설명에 매칭됩니다. 공백으로 구분해 필터를 결합하세요 — AND로 묶입니다.

API 탐색

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

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

Swagger UI는 다음에 있습니다:

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

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

참고: 제공되는 openapi.json은 경로를 나열하지만 현재 빈 요청 본문을 제공합니다 — 쓰기에는 명세의 필드 형태를 사용하세요.

WebSocket 제어

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

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

대부분의 사용자는 이것이 필요 없습니다. 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.

오류 형식

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

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

많은 오류 응답은 details 객체도 포함합니다 — validation_failed에는 details.fields(위반한 필드 이름의 배열), 422 invalid_transition에는 details.allowed(from/to와 함께). 그것들을 사용하세요.

페이지네이션

목록 엔드포인트는 limit과 cursor를 받습니다. cursor는 불투명합니다. 이전 응답의 next_cursor를 전달하세요. 계산이 저렴한 경우 응답 헤더는 전체 개수를 위한 X-Tracker-Pagination-Total도 포함합니다.

다음은 무엇인가

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