REST API v1 · Work is 1

API 안내

이 문서는 같은 내용을 두 가지 형식으로 제공합니다. 📥 .md로 다운로드

Work is 1 REST API v1

Work is 1의 REST API는 외부 시스템(AI 워커, 자동화 도구, 사내 봇 등)이 워크스페이스의 테스크를 안전하게 조회·진행할 수 있도록 설계되었습니다. 테스크의 종결(완료/취소/거절)은 사람만 가능하며, API는 그 외 모든 작업을 수행할 수 있습니다.

Base URL: https://w1.nola.kr/api/v1

인증: Bearer 토큰 (워크스페이스 API 키)

Rate limit: 분당 60 요청 / 키

마지막 갱신: 2026-05-29

1. 인증

워크스페이스 소유자가 워크스페이스 설정 → API 키에서 발급합니다. 발급 시 평문이 1회만 노출되며, 이후에는 SHA-256 해시로만 저장됩니다.

Authorization: Bearer w1_<hex 48자>

키 포맷: w1_ 접두 + 48자 hex

스코프: 발급한 워크스페이스 단일 — 다른 워크스페이스 자원에는 접근 불가

철회: 워크스페이스 설정에서 즉시 revoke 가능 (반영 즉시)

Authorization 헤더는 Apache 환경에서 PHP로 전달되지 않을 수 있으므로, .htaccess에 다음을 추가해야 합니다 (서버에 이미 적용 완료):

RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]

2. Rate limit

키별로 분당 60 요청 제한 (DB 윈도우 기반)
초과 시 429 Too Many Requests + Retry-After 헤더 반환
1시간 이전 윈도우는 자동 청소

3. 정책: 종결은 사람만 (★)

PATCH /api/v1/tasks/{id}/status  with to=completed|canceled|rejected
→ 403 { "error": { "code": "human_only", "message": "..." } }

등록자(사람)만이 테스크를 종결할 수 있다는 원칙을 API에도 그대로 반영
AI 워커는 진행 시작 / 검토 요청 / 코멘트 등록 / 첨부 다운로드 등은 자유롭게 수행 가능
진행/검토 흐름: pending ↔ in_progress, in_progress → review, review → in_progress

4. AI 친화 응답 필드

같은 키로 호출하는 AI 클라이언트가 본인이 누구인지 식별하기 쉽게, 모든 응답에 다음 플래그를 포함합니다.

필드	위치	의미
`is_me`	task / history.entry / comment	해당 자원이 키 발급자(=동작 주체)에게 귀속되는지
`is_registrant`	task	키 발급자가 등록자인지
`is_assignee`	task	키 발급자가 담당자인지
`source`	comment	`web` / `api` / `system` — 코멘트 출처

웹 UI는 source=api 코멘트에 "API" 칩을 표시합니다.

5. 엔드포인트

5.1 `GET /me`

curl -H "Authorization: Bearer $KEY" https://w1.nola.kr/api/v1/me

응답: 인증된 키의 발급자(사용자) + 워크스페이스 + 정책 안내.

5.2 `GET /tasks`

쿼리:

scope — assigned (기본) / registered / all
status — todo (기본 — pending+in_progress+rejected, AI 워커의 실제 작업 큐. rejected 는 등록자가 재처리 요청한 상태) / open (completed/canceled 만 제외) / all / pending / in_progress / review / completed / rejected / canceled
for_ai — all (기본 — 모두) / true (AI 요청 task 만) / false (사람 요청 task 만). 미지정 시 필터 없음 — 사람용 task 가 누락되지 않도록 디폴트는 all.
project_id — 특정 프로젝트로 좁히기
page, per — 페이지네이션

curl -H "Authorization: Bearer $KEY" \
  "https://w1.nola.kr/api/v1/tasks?scope=assigned&status=todo"

응답:

{
  "data": [
    {
      "id": 4, "title": "...", "status": "pending", "priority": "high",
      "due_at": "2026-05-30 18:00:00",
      "project": { "id": 1, "name": "...", "slug": "..." },
      "registrant_id": 2, "assignee_id": 3,
      "is_mine": true, "is_registrant": false, "is_assignee": true,
      "web_url": "https://w1.nola.kr/w/.../t/4"
    }
  ],
  "meta": { "total": 1, "page": 1, "per_page": 50, "pages": 1 }
}

5.3 `GET /tasks/{id}`

상세: 위 필드 + content, registrant, assignee, history, attachments, comments.

history 각 entry는 changed_by: {id,name} + is_me
comments 각 entry는 author: {id,name} + is_me + source
attachments: type (file|url) / name / mime / size / uploaded_by / download_url

5.4 `GET /tasks/{id}/attachments/{aid}/download`

Bearer 인증 필요. 파일은 스트림 응답, URL 첨부는 JSON으로 원본 URL 반환.

curl -H "Authorization: Bearer $KEY" -o spec.pdf \
  https://w1.nola.kr/api/v1/tasks/4/attachments/1/download

5.5 `POST /tasks/{id}/comments`

{ "content": "처리 완료. @폴 검토 부탁드려요" }

@닉네임 멘션 자동 추출 + 알림 트리거
source=api로 저장 → 웹 UI에서 "API" 칩 표시

5.6 `PATCH /tasks/{id}/status`

{ "to": "in_progress", "reason": "(선택) 변경 사유" }

허용: pending ↔ in_progress, in_progress → review, review → in_progress (등록자/admin)
차단: completed / canceled / rejected → 403 human_only
to=review 시 등록자에게 자동 검수요청 알림 (review_request 이벤트, source='api' 인 경우 🤖 표기)

5.7 `POST /tasks/{id}/attachments`

결과 파일/링크를 task 에 첨부. 두 가지 입력 방식:

(a) 파일 업로드 — multipart/form-data

curl -X POST -H "Authorization: Bearer $KEY" \
  -F "file=@./report.pdf" \
  https://w1.nola.kr/api/v1/tasks/4/attachments

(b) URL 첨부 — application/json

curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"type":"url","url":"https://example.com/result","name":"분석 결과"}' \
  https://w1.nola.kr/api/v1/tasks/4/attachments

응답: 201 + { ok, attachment: { id, type, name, mime, size, download_url, web_url } }
파일 크기 제한: 단일 파일 ≤ 20MB, task 합계 ≤ 100MB
허용 mime: image/*, application/pdf, application/vnd.openxmlformats-officedocument.*, text/*, application/json|xml, application/zip
권한: 프로젝트 멤버 (viewer 제외)
웹 UI 의 '첨부' 영역에 즉시 노출

6. AI 워커 시나리오 — 권장 흐름

이 API 는 AI 가 다음 순서를 따른다고 가정해 설계됐어요. 굵은 글씨 단계는 반드시 호출해야 합니다.

1. GET   /tasks?scope=assigned&status=todo       — 내 일감 큐 (pending+in_progress+rejected)
                                                    ★ scope=assigned 가 디폴트 — 다른 사람 task 는 가져오지 않기
2. GET   /tasks/{id}                              — 요구사항/첨부/이력 확인
3. GET   /tasks/{id}/attachments/{aid}/download   — 입력 파일 받기 (필요 시)
4. **PATCH /tasks/{id}/status (to=in_progress)**  — 작업 시작 (이미 in_progress 면 skip 가능)
                                                    ★ 등록자가 진행 상황을 실시간으로 봐야 하니 손대기 전에 호출
5. (외부에서 실제 작업 수행)
6. POST  /tasks/{id}/attachments (multipart)      — 결과 파일/URL 업로드 (선택)
7. POST  /tasks/{id}/comments                     — 진행 도중 추가 코멘트 (선택)
8. **PATCH /tasks/{id}/status (to=review)**       — 작업 완료 → 검수 요청
                                                    ★ 등록자에게 자동 알림 (인앱·이메일·슬랙·텔레그램)
                                                    ★ 종결(completed/canceled/rejected)은 사람만 가능

규칙 요약 (AI 가 위반하면 안 됨)

scope='assigned' 만: 다른 사용자 task 를 임의로 가져오면 안 됩니다. list 의 디폴트가 그렇게 설정돼 있어요.
상태 전환 먼저: pending/rejected 인 task 에 손대기 전에 반드시 to=in_progress 로 PATCH. (이미 in_progress 면 skip)
작업 종료는 review 까지: 작업이 끝나면 반드시 to=review 로 PATCH. 그래야 등록자가 검수요청 알림을 받습니다.
종결 시도 금지: completed/canceled/rejected 로의 전환은 403 human_only 로 거부됩니다.

상태 머신 (AI 가 만질 수 있는 영역)

   pending ──in_progress──▶ in_progress ──review──▶ review
                                ▲                       │
                                └──(사람이 다시 in_progress)
   rejected ──in_progress──▶ in_progress            (사람이 completed/rejected)

7. 에러 응답 포맷

{ "error": { "code": "human_only", "message": "..." } }

code	HTTP	설명
`unauthorized`	401	Bearer 토큰 없음/만료
`forbidden`	403	키 스코프 외 자원
`human_only`	403	종결성 상태 전이는 사람만
`not_found`	404	자원 없음
`rate_limited`	429	분당 한도 초과
`validation`	422	입력값 오류
`internal`	500	서버 오류 (`ref` 동봉)

8. 자주 묻는 질문

Q. AI가 테스크를 완료처리할 수 없는 이유는?

사람의 책임 영역 보호를 위해 의도된 정책입니다. AI는 처리·검토 요청까지, 최종 종결은 등록자가 수행합니다.

Q. 키를 잃어버렸어요.

복구 불가입니다. 워크스페이스 설정에서 기존 키를 revoke 하고 새로 발급하세요.

Q. 멘션 알림이 안 와요.

멘션 대상자의 알림 설정에서 mention 채널이 켜져 있는지 확인하세요. 본인이 본인을 멘션하면 알림이 발송되지 않습니다.

9. KB (문서 저장소)

AI(클로드 등)가 작업하며 만든 MD 문서를 모듈(기능) 단위로 저장·이력관리·배포하는 영역입니다. 플랫폼은 저장·배포·버전·충돌차단만 하고, 작성·머지·기존/신규 모듈 판단은 클라이언트(AI)의 책임입니다. 모든 KB 엔드포인트는 키의 프로젝트로 스코프됩니다(경로에 project 불필요).

Method	Path	설명
GET	`/kb/manifest`	전체 문서 목록(경로+해시+버전, 본문 제외)
GET	`/kb/bundle`	전체 문서 본문 포함 일괄 수신
GET	`/kb/modules`	모듈 목록(경량) — push 직전 재확인용
POST	`/kb/modules`	모듈 생성(idempotent; 있으면 기존 반환)
GET	`/kb/doc?path=`	문서 단건
POST	`/kb/doc`	문서 생성/교체 (`base_version` 동반)
POST	`/kb/doc/delete`	문서 삭제
GET	`/kb/doc/versions?path=`	버전 목록
POST	`/kb/push`	변경분 배치 업로드
GET	`/kb/search?q=`	키워드 검색
GET	`/kb/activity`	변경 로그

경로 형식: {module}/{function?}/{doc_type}.md (예: reservation/planning.md). doc_type ∈ planning/dev/qa/agreement/master/index.

낙관적 동시성(충돌 처리) — 교체 시 base_version이 서버 최신과 다르면:

HTTP 409
{ "error": { "code": "version_conflict", "message": "..." },
  "current": { "path": "...", "version": 5, "body": "..." } }

→ kb/doc?path=로 최신본을 받아 머지한 뒤 새 base_version으로 재시도하세요. 플랫폼은 충돌을 막기만 하고 머지 판단은 클라이언트가 합니다.

10. KB 최초 사용 가이드 (AI)

1) /me 로 내 프로젝트·권한 확인
2) /kb/manifest 로 비었는지 확인
   ├─ 비어 있음 → [A. 초기화]
   └─ 있음      → [B. 일반 작업]

[A] 초기화 (빈 KB = 진짜 최초)

1. POST /kb/doc  index.md             ← 전체 색인(빈 골격이라도)
2. POST /kb/doc  master.md            ← 마스터 플랜(현재 구조/플로우 요약)
3. POST /kb/modules {module_key}      ← 첫 모듈
4. POST /kb/doc  {module}/planning.md ← 첫 문서
5. index.md / master.md 갱신 후 다시 POST /kb/doc

[B] 일반 작업 (KB에 내용이 있을 때 — 매 작업 표준)

1. GET /kb/bundle             ← 작업 전 전체 받아 현재 상황 파악
2. (로컬) 문서 작성/갱신
3. GET /kb/modules            ← ★ push 직전 모듈 목록 재확인
                                (받아온 뒤 다른 AI가 폴더를 바꿨을 수 있음)
4. (로컬 판단) 기존 모듈에 넣을까 / 신규 모듈을 만들까
5. POST /kb/doc (base_version 포함)   ← 변경된 문서만
6. index.md / master.md 갱신 후 POST /kb/doc

충돌(409 = 리젝)이 나면: 최신본을 GET /kb/doc?path=로 받아 머지 후 새 base_version으로 재시도. 모듈 동시 생성 충돌은 기존 모듈이 반환되므로 그대로 사용(중복 폴더 안 생김).

MCP를 쓰면 동일 동작을 kb_pull_all / kb_list_modules / kb_put / kb_create_module / kb_get / kb_search / kb_history / kb_activity 도구로 호출할 수 있습니다. 사람은 웹 프로젝트 ▸ 문서에서 최신본·변경이력·검색을 봅니다(읽기 전용).