개발자 문서

외부 시스템(CI, 배치 작업, 사내 도구)을 GoalTrack 에 연결하는 방법은 두 방향입니다.

방향	무엇을 하나	문서
내 시스템 → GoalTrack	이슈·위키 문서 읽기·만들기·고치기, 댓글 읽기·달기, 프로젝트·이니셔티브·검색 읽기, 지표 읽기	API Key
AI 에이전트 → GoalTrack	맡은 이슈 읽기·상태 바꾸기·댓글 남기기(에이전트 이름으로)	AI 에이전트 키
내 시스템 → GoalTrack	지표 값 적재(예: 매달 MRR)	지표 값 적재
GoalTrack → 내 시스템	이슈·코멘트·프로젝트 변경을 webhook 으로 받기	Webhook 수신 검증

공통 규약

• 기본 주소는 https://goaltrack.dyld.kr/api/v1 입니다.
• 요청과 응답 본문은 JSON 입니다. 성공하면 데이터를 그대로 돌려주고, 실패하면 { "error": { "code": "…", "message": "…" } } 를 돌려줍니다. 분기는 message 가 아니라 code 로 하세요 — 에러 코드.
• 인증은 API Key 를 Authorization: Bearer gtk_… 헤더에 담아 보냅니다. Key 로 열린 요청만 받고, 나머지 요청은 Key 로 부르면 401 입니다. AI 에이전트는 자기 키를 Authorization: Bearer gtag_… 로 보냅니다 — AI 에이전트 키.

MCP

MCP 서버(도구 69개)는 로컬·자체 운영 환경에서 AI 에이전트를 연결할 때 씁니다. 호스팅 GoalTrack(goaltrack.dyld.kr)에서는 AI 에이전트 키로 연결합니다.

MCP 서버는 stdio 로 실행되고 데이터베이스에 직접 연결하므로, GoalTrack 서버를 운영하는 쪽만 띄울 수 있습니다. 호스팅 GoalTrack 에서는 에이전트에게 AI 에이전트 키를, 내 시스템에는 API Key를 쓰세요.