W1 Work is 1
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-10-12

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" 칩을 표시합니다.

4.1 태스크 번호는 두 가지 — id 와 display_no

Work is 1 의 태스크에는 번호가 두 개 있습니다. 화면 빵부스러기에 보이는 번호(예: P6C07B-229)와 주소·API 가 쓰는 번호(예: 4093)는 서로 다른 값입니다.

번호 예시 어디에 보이나 쓰임새
id 4093 주소창(/w/.../t/4093), 화면 제목 아래 #4093 칩, 모든 API 응답, 경로의 {id} 기계가 지목할 때 — 조회·수정·코멘트·상태 변경 등 모든 API 호출
display_no P6C07B-229 화면 상단 빵부스러기 사람에게 말할 때 — 프로젝트 접두어(project.task_key) + - + 프로젝트 내 순번
  • display_no 만으로 태스크를 지목하지 마세요. 이 번호는 프로젝트별로 매겨집니다(프로젝트마다 순번이 따로 올라갑니다). 프로젝트 접두어는 설정에서 바뀔 수 있고, 번호가 매겨지기 전의 과거 태스크는 WB- + id (예: WB-4093) 로 내려옵니다. 조회·수정 API 는 display_no 를 받지 않습니다.
  • 조회·수정은 항상 id 로 하세요. GET /tasks/{id} 등 경로의 {id} 자리에는 4093 처럼 숫자만 넣습니다. P6C07B-229 를 넣으면 안 됩니다.
  • 사람에게는 display_no, 기계에게는 id. 응답에 둘 다 들어 있으므로, 사람에게 보고할 때는 P6C07B-229 (#4093) 처럼 함께 적는 것이 가장 안전합니다.
  • id 와 web_url 의 값·형식은 그대로입니다. display_no 와 project.task_key 는 기존 필드를 바꾸지 않고 덧붙인 필드라서, 기존 연동은 수정 없이 동작합니다.

5. 엔드포인트

경로의 {id} 는 항상 URL 고유번호(id)입니다. 화면 빵부스러기의 내부관리번호(display_no)가 아닙니다 — 4.1 참고.

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, "display_no": "WORK-2", "title": "...", "status": "pending", "priority": "high",
      "due_at": "2026-05-30 18:00:00",
      "project": { "id": 1, "name": "...", "slug": "...", "task_key": "WORK" },
      "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}

상세: 위 필드(id·display_no·project.task_key 포함) + content, registrant, assignee, history, attachments, comments, customer_memos, customer_memo_ai_allowed, extra_requests, decision_requests.

  • 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
  • customer_memos: 고객 접수 건이면 고객 포털 메모(고객 작성 + 담당자 전달) 배열. 각 entry author_type(customer|staff) / author / source(web|api — API 로 등록한 담당자 메모는 api, 고객 포털에는 AI 표기가 없고 내부 화면에서만 구분) / content / attachments / created_at. 고객 접수 건이 아니면 빈 배열.
  • customer_memo_ai_allowed: boolean. 프로젝트 설정 "접수 기본값 > AI 고객사 전달 등록 허용" 값. false 면 POST /tasks/{id}/customer-memos 가 403 ai_customer_memo_disabled 로 거부됩니다. (필드가 없는 구버전 서버에서는 생략)
  • extra_requests: 고객이 보낸 "추가작업 요청"(검토요청/완료/종결/반려 상태에서 사용하는 공식 채널) 누적 배열 — 상태 컬럼 없음(읽음/처리 개념 없음, 항상 전체 누적). 각 entry id / customer / content / created_at. 없으면 빈 배열.

  { "id": 12, "customer": "tt", "content": "배너 1개만 더 부탁드립니다.", "created_at": "2026-08-28 14:38:50" }
  

  • decision_requests: 고객 "확인요청/답변". 미응답(open) + 응답완료(answered)만 포함, 취소(canceled)는 제외. 없으면 빈 배열.

각 entry id / type(choice|file|text) / status(open|answered) / title / body / options(type=choice 일 때만, 그 외 []) / due_at / requested_by: {id,name} / request_attachments / answer(미응답이면 null).

answer: by(응답한 고객명) / at / choice_index(0-based, options 배열 인덱스와 동일) / choice_label(options 매핑, 못 찾으면 null) / text / attachments.

  {
    "id": 7, "type": "choice", "status": "answered",
    "title": "디자인 방향 확인", "body": "A안과 B안 중 어느 쪽으로 할까요?",
    "options": ["A안", "B안"], "due_at": null,
    "requested_by": {"id": 1, "name": "폴"},
    "request_attachments": [],
    "answer": {
      "by": "tt", "at": "2026-08-28 15:10:00",
      "choice_index": 1, "choice_label": "B안",
      "text": "B안으로 진행해주세요", "attachments": []
    }
  }
  

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 POST /tasks/{id}/customer-memos

고객 접수 건에 고객사 전달(고객 포털에 보이는 담당자 메모)을 등록합니다. 내부 기록용 코멘트(POST /tasks/{id}/comments)와 다릅니다.

{ "content": "요청하신 배너 수정을 완료했습니다. 확인 부탁드립니다.", "attachment_ids": [31, 32] }

  • content: 필수, 1~10000자
  • attachment_ids: 선택, 최대 10개. 이 테스크에 이미 올라간 첨부여야 합니다 (먼저 5.8 POST /tasks/{id}/attachments 로 업로드 후 반환된 id 사용). 첨부한 파일은 이 전달 시점부터 고객이 내려받을 수 있게 됩니다. POST /tasks/{id}/attachments 로 올린 파일은 이렇게 전달하기 전까지 고객에게 보이지 않습니다(내부용). 고객에게 보고서를 전달할 때는 코드·경로·내부 메모를 뺀 고객용 버전을 따로 만들어 첨부하세요.

curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"content":"요청하신 배너 수정을 완료했습니다.","attachment_ids":[31]}' \
  https://w1.nola.kr/api/v1/tasks/4/customer-memos

응답 201:

{
  "ok": true,
  "memo": {
    "id": 55, "content": "요청하신 배너 수정을 완료했습니다.", "source": "api",
    "attachments": [
      { "id": 31, "type": "file", "name": "banner.png", "mime": "image/png", "size": 20480,
        "download_url": "/api/v1/tasks/4/attachments/31/download" }
    ],
    "created_at": "2026-10-26 10:00:00"
  },
  "portal_visible": true,
  "customer_notified": true
}

주의 (★)

  • 즉시 노출: 등록 즉시 고객 포털에 '담당자' 이름으로 보이고 고객에게 알림이 발송됩니다. 승인·임시저장 단계가 없으며, 고객이 읽은 뒤에는 되돌릴 수 없습니다. 포털에는 AI 가 등록했다는 표시가 없습니다(source=api 는 내부 화면·API 에서만 구분).
  • 프로젝트 설정: 프로젝트 설정 > 접수 기본값 > "AI 고객사 전달 등록 허용" 이 켜져 있어야 합니다. 꺼져 있으면 403 ai_customer_memo_disabled — 사람에게 켜달라고 요청하세요. 켜져 있는지는 GET /tasks/{id} 의 customer_memo_ai_allowed 로 확인합니다.
  • 고객 접수 건만: 고객 접수 건이 아니면 422 not_customer_task.
  • 내용 규칙: 고객이 이해할 수 있는 쉬운 존댓말로 작성하고, 내부 정보(소스 코드·파일 경로·키/비밀값·내부 논의·다른 고객 정보)는 넣지 마세요.
  • 권한: 프로젝트 멤버 (viewer 제외)
code HTTP 설명
ai_customer_memo_disabled 403 프로젝트 설정에서 AI 고객사 전달 등록이 꺼져 있음
not_customer_task 422 고객 접수 건이 아님
forbidden 403 프로젝트 멤버가 아님
read_only 403 뷰어(viewer) 권한 키 — 조회만 가능
scope_project_mismatch 403 키의 프로젝트 스코프와 테스크의 프로젝트가 다름
invalid_content 422 content 가 비었거나 형식 오류
content_too_long 422 content 가 10000자 초과
invalid_attachment 422 attachment_ids 가 이 테스크의 첨부가 아니거나 10개 초과
not_found 404 테스크 없음

5.7 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.8 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 의 '첨부' 영역에 즉시 노출 (직원용). 고객 포털에는 보이지 않습니다 — 고객에게 보이려면 POST /tasks/{id}/customer-memos 의 attachment_ids 로 전달하세요.

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                     — 진행 도중 추가 코멘트 (선택)
   POST  /tasks/{id}/customer-memos                — 고객 접수 건에서 고객에게 알릴 내용 전달 (선택, 즉시 노출·프로젝트 설정 필요)
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 키 스코프 외 자원
ai_customer_memo_disabled 403 프로젝트 설정에서 AI 고객사 전달 등록이 꺼져 있음 (5.6)
not_customer_task 422 고객 접수 건이 아님 (5.6)
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 도구로 호출할 수 있습니다. 사람은 웹 프로젝트 ▸ 문서에서 최신본·변경이력·검색을 봅니다(읽기 전용).

© 2026 Work is 1 · 본 문서는 /docs/api(HTML) 및 /docs/api.md(MD 다운로드)에서 동일 내용을 제공합니다.