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 만, AI 워커의 실제 작업 큐. review 는 사람 차례, rejected 는 사람 판단) / open (completed/canceled 만 제외) / all / pending / in_progress / review / completed / rejected / canceled
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

6. AI 워커 시나리오 (예시)

1. GET /tasks?scope=assigned&status=todo       — 내가 처리할 일감 큐 (pending + in_progress)
2. GET /tasks/{id}                              — 요청사항 + 히스토리 확인
3. GET /tasks/{id}/attachments/{aid}/download   — 첨부파일 받기
4. (외부에서 처리 수행)
5. POST /tasks/{id}/comments                   — 처리 결과 보고
6. PATCH /tasks/{id}/status (to=review)         — 검토 요청
                                                  ↑ 종결은 사람이 직접

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 채널이 켜져 있는지 확인하세요. 본인이 본인을 멘션하면 알림이 발송되지 않습니다.