API 사용법

내 Just Do X 를 다른 프로그램(AI 작업자 데몬, 자동화 스크립트, MCP 서버 등)에서 다룰 수 있는 API예요. API 로 바꾼 내용은 내 기기들에 동기화로 15초 안에 반영되고, 배정·코멘트 알림도 앱과 똑같이 갑니다.

1. 키 만들기

앱의 계정 메뉴 → 내 정보 → API 키 → [새 API 키 만들기]. 이름, 할 수 있는 일(권한), 만료를 고르면 키가 한 번만 보입니다. 키는 비밀번호처럼 다루세요 — 새면 바로 [폐기]하세요.

read — 업무·코멘트·작업자 읽기 (늘 포함)
tasks:write — 업무 만들기·고치기·지우기·공유
comments:write — 코멘트 쓰기·고치기·반응, 파일 올리기
workers:write — 작업자 추가·이름 바꾸기

키로는 비밀번호·이메일 변경, 계정 삭제, 키 관리를 할 수 없습니다.

API 키와 MCP 연결은 Pro 플랜에서 쓸 수 있어요. 무료 플랜이면 키를 만들 수 없고, Pro 가 끝나면 있던 키는 남지만 부르면 403 pro_only 로 막혀요 — Pro 로 돌아오면 그 키가 다시 돼요. AI 작업자(justdox 데몬)는 무료에서도 쓸 수 있어요(6절). 요금제

2. 부르기

curl https://justdox.io/api/v1/me \
  -H "Authorization: Bearer jdx_live_xxxxxxxxxxxx_..."

curl -X POST https://justdox.io/api/v1/tasks \
  -H "Authorization: Bearer $JDX_KEY" -H "Content-Type: application/json" \
  -d '{"text":"주간 보고서 쓰기","dueDate":"2026-10-24","dueTime":"18:00","tags":["보고"]}'

curl -X PATCH https://justdox.io/api/v1/tasks/<id> \
  -H "Authorization: Bearer $JDX_KEY" -H "Content-Type: application/json" \
  -d '{"status":"done"}'

응답은 JSON. 오류는 { error, message } 와 상태 코드(400 잘못된 입력, 401 키 없음·틀림·폐기·만료, 403 권한 없음·Pro 아님(pro_only)·무료 플랜 한도(plan_limit — 끝나지 않은 업무 10개·반복 5개), 404 없음, 409 충돌, 429 요청이 너무 많음 — 키마다 분당 120회).

3. 엔드포인트

https://justdox.io/api/v1

메서드	경로	권한	설명
GET	/me	read	키의 주인 계정
GET	/tasks	read	업무 목록 — scope=all\|mine\|received, status=a,b, assigneeId=<id>\|none, tag=, updatedSince=<ISO>
POST	/tasks	tasks:write	업무 만들기 { text, status?, dueDate?, dueTime?, assigneeId? 또는 assignee?(작업자 이름, 'me' = 나 — '나' 줄이 없으면 담당자 없이), tags?, repeatRule?, requireApproval?, expireOnDue?, reminder?, parentId? } — parentId 면 그 업무의 하위 업무(담당자가 있는 업무 아래에도 된다)
GET	/tasks/{id}	read	업무 하나 — 공유받은 업무도(owner: shared, 읽기만)
PATCH	/tasks/{id}	tasks:write	업무 고치기 (같은 칸들). 받은 업무는 status 만. 안 끝난 하위 업무가 있으면 done 은 409(open_subtasks)
DELETE	/tasks/{id}	tasks:write	내 업무 지우기 (하위 업무가 있으면 409)
GET	/tasks/{id}/comments	read	코멘트 목록 (오래된 것부터) — 남의 코멘트엔 by(이름), @ 로 받는 사람을 고른 코멘트엔 to(이름)·toMe
POST	/tasks/{id}/comments	comments:write	코멘트 쓰기 { text, to?, choices? } — 공유받은 업무에도. 상대에게 알림이 간다. to: @ 로 부를 사람 이름(그 사람들에게만 알림). choices: 고를 답 2–6개(화면에 버튼으로, 누른 답이 그 사람의 코멘트가 된다)
GET	/tasks/{id}/attachments	read	첨부 파일 목록 (id, name, mime, size, commentId)
POST	/tasks/{id}/attachments?commentId=	comments:write	파일 올리기 — 본문 = 파일, X-File-Name·Content-Type 헤더. commentId 면 그 코멘트에 붙는다
GET	/attachments?kind=&name=&taskId=&limit=	read	첨부 파일 찾기 — 내 업무·받은 업무·공유받은 업무 전체에서(코멘트에 붙은 것까지), 최근 것부터. kind=pdf\|image\|text\|other, name=이름 일부, taskId=a,b 로 좁히기, limit 1–500(기본 100). 줄마다 id, taskId, name, mime, size, commentId
GET	/attachments/{id}	read	파일 내려받기
GET	/tasks/{id}/shares	read	내 업무를 공유받은 사람(sharedWith)과 공유할 수 있는 사람(candidates)
POST	/tasks/{id}/shares	tasks:write	공유하기 { person, unshare? } — person: candidates 의 이름. 공유받은 사람은 보기·코멘트만. unshare: true 면 풀기
PATCH	/comments/{id}	comments:write	내가 쓴 코멘트 고치기 { text }
POST	/comments/{id}/reactions	comments:write	이모지 반응 { emoji: 👍\|❤️\|😂\|🎉\|🙏\|✅, on?: false 면 빼기 }
GET	/workers	read	작업자 목록
POST	/workers	workers:write	작업자(이름표) 추가 { name }
PATCH	/workers/{id}	workers:write	작업자 이름 바꾸기 { name }
POST	/agent	read	AI 작업자 데몬 전용 — { providers, version } 를 알리고 작업자 설정(모델·권한·한도)을 받는다
POST	/mcp	read	MCP 서버 — AI 앱 연결(5절). 도구는 키의 권한대로
GET	/changes?since=<ISO>	read	그 뒤로 바뀐 업무(지운 것 포함)·코멘트와 다음 since

4. 업무 모양

{
  "id": "uuid",
  "text": "주간 보고서 쓰기",
  "status": "pending | active | hold | review | done | missed",
  "dueDate": "2026-10-24" | null,
  "dueTime": "18:00" | null,
  "repeatRule": "daily | weekly:1,3 | monthly:15 | every:3d" | null,
  "tags": [],
  "assigneeId": "worker uuid" | null,
  "parentId": null,
  "requireApproval": false,
  "expireOnDue": false,
  "reminder": "at | m5 | m10 | m30 | h1 | d1 | sun | none" | null,
  "owner": "me | other | shared",
  "createdAt": "ISO", "updatedAt": "ISO", "completedAt": "ISO" | null
}

status 로 고를 수 있는 값: pending(대기)·active(진행)·hold(보류)·done(완료). review(완료 확인)·missed(못함)는 규칙이 정합니다.
반복 업무를 done 으로 하면 앱과 같이 그 회차를 기록하고 다음 회차로 넘어갑니다.
owner 가 other 인 업무는 남이 나에게 맡긴 업무예요 — status 와 코멘트만 바꿀 수 있고, 완료 확인이 켜져 있으면 done 이 review 가 됩니다.
owner 가 shared 인 업무는 남이 나에게 공유한 업무예요 — 업무 하나·코멘트·첨부 읽기와 첨부 찾기로만 보이고, 코멘트는 남길 수 있어요(업무 목록에는 안 나오고, 업무 자체는 고칠 수 없어요).

5. AI 앱에 연결하기 (MCP)

Claude Code·Claude 데스크톱·Cursor 처럼 MCP 를 쓰는 AI 앱에 Just Do X 를 붙이면, 대화로 내 업무를 보고 만들고 고칠 수 있어요. 주소 하나와 API 키만 있으면 돼요(Pro).

# Claude Code
claude mcp add --transport http justdox https://justdox.io/api/v1/mcp \
  --header "Authorization: Bearer jdx_live_xxxxxxxxxxxx_..."

// Cursor (~/.cursor/mcp.json) 등 주소·헤더를 받는 앱
{ "mcpServers": { "justdox": {
    "url": "https://justdox.io/api/v1/mcp",
    "headers": { "Authorization": "Bearer jdx_live_xxxxxxxxxxxx_..." } } } }

// Claude 데스크톱 (claude_desktop_config.json) — mcp-remote 로 이어 준다
{ "mcpServers": { "justdox": {
    "command": "npx",
    "args": ["mcp-remote", "https://justdox.io/api/v1/mcp", "--header", "Authorization:Bearer ${JDX_KEY}"],
    "env": { "JDX_KEY": "jdx_live_xxxxxxxxxxxx_..." } } } }

도구: list_tasks·get_task·create_task(반복·알림·옵션·하위 업무)·update_task·delete_task·share_task·add_comment(@·선택지)·edit_comment·react_comment·find_attachments(여러 업무에서 첨부 찾기 — PDF·그림·이름)·read_attachment(글·그림·PDF 파일 읽기)·list_workers·add_worker·rename_worker. AI 비서·AI 작업자와 같은 일을 같은 칸으로 해요 — AI 비서는 이 도구들을 그대로 써요(읽기 도구는 바로, 바꾸는 도구는 사용자가 카드를 눌러야 실행).
키의 권한에 맞는 도구만 보여요 — 읽기만 줄 거면 read 만 있는 키를 만드세요. 도구는 위 API 를 그대로 불러서 요청 제한(분당 120회)도 같이 써요.
MCP Streamable HTTP(2025-06-18)로, 세션 없이 JSON 으로 답해요. 키는 AI 앱 설정에 들어가니, 그 앱만 쓰는 키를 따로 만들어 두면 언제든 폐기할 수 있어요.

6. AI 작업자 컴퓨터 연결 (justdox 데몬)

AI 작업자는 연결된 컴퓨터에 설치된 AI 도구(Claude Code·Codex·Antigravity CLI)로 일해요. 그 컴퓨터에서:

curl -fsSL https://justdox.io/install.sh | sh      # macOS · Linux
irm https://justdox.io/install.ps1 | iex           # Windows PowerShell
# Windows 설치 프로그램: https://justdox.io/downloads/JustDoX-Setup.exe
justdox setup --account <email>     # 서버 확인 → 브라우저 로그인 → AI 도구 찾기 → 데몬 시작
justdox status | logs | stop | restart --account <email>
justdox accounts                    # 이 컴퓨터에 연결된 계정들

명령마다 Just Do X 계정(--account, 줄여서 -a)을 붙여요. 없으면 물어봐요. 계정마다 ~/.justdox/accounts/<이메일> 폴더·키·데몬이 따로라, 한 PC 사용자 계정을 여러 사람이 같이 써도 섞이지 않아요.
데몬은 15초마다 신호를 보내고, 서버가 보내는 '일 있음'(SSE)을 받거나 30초마다 확인해 맡겨진 일을 가져가요.
실행 건마다 그 업무 하나만 다룰 수 있는 24시간 키를 받아, AI 도구에 Just Do X MCP 도구로 넘겨요 — AI 가 직접 코멘트·상태를 남겨요. 도구는 위 API 를 그대로 불러요: get_task·add_comment(@·선택지·파일)·set_status·create_task(하위 업무까지)·download_attachment·edit_comment·react_comment, 리더의 업무·작업자 읽기(list_leader_tasks·view_leader_task·list_workers). 업무 고치기·공유·작업자 추가/이름 바꾸기는 request_change 로 리더의 승인을 받아요.
AI 는 그 컴퓨터에서 데몬을 실행한 계정의 권한으로 일해요. 중요한 파일이 있는 PC 라면 AI 전용 사용자 계정이나 가상 PC 에서 실행하세요.

7. 변경 따라가기

GET https://justdox.io/api/v1/changes?since=2026-10-20T00:00:00.000Z
→ { "tasks": [...], "comments": [...], "next": "2026-10-20T03:12:45.120Z" }

처음엔 since 없이 부르고, 그다음부터 돌려받은 next 를 since 로 넘기세요. 경계의 항목이 한 번 더 올 수 있으니 id 로 겹침을 거르세요.