플랫폼 API (/v1)
플랫폼 API는 Waafir의 버전 관리되는 HTTP 인터페이스입니다. 자체 시스템에서 조직을 조회하고 관리하는 데 사용하세요. 팀(구성원 초대, 역할 변경, 제거), 데이터룸·폴더·파일에 대한 접근 권한 부여, Q&A, 데이터룸 채팅과 에이전트, 활동 및 상대방별 참여도, 포트폴리오 모니터링을 다룹니다.
플랫폼 API는 동일한 플랫폼을 AI 클라이언트에 도구로 제공하는 Waafir의 MCP 서버와는 별개의 인터페이스입니다. 두 가지 모두 같은 개인 액세스 토큰으로 인증합니다.
기본 URL
모든 엔드포인트는 다음 경로 아래에 있습니다.
https://app.waafir.io/api/v1엔드포인트 레퍼런스에는 각 엔드포인트가 전체 경로로 나열되어 있습니다. 예: GET /api/v1/team.
첫 호출
- 토큰을 발급합니다. Waafir에서 추가 기능 → 설정을 열고 개인 액세스 토큰을 발급하세요. 시작하는 데는
read토큰으로 충분합니다.waafir_pat_로 시작하는 값을 복사하세요. 이 값은 한 번만 표시됩니다. - 자신이 누구인지 확인합니다.
GET /api/v1/session은 토큰이 대리하는 신원과 조직을 그대로 반환합니다. 토큰을 기반으로 개발을 시작하기 전에 토큰이 작동하는지 확인하는 데 사용하세요.
curl -s https://app.waafir.io/api/v1/session \
-H "Authorization: Bearer $WAAFIR_TOKEN"{
"orgId": "…",
"userId": "…",
"email": "you@example.com",
"orgRole": "admin",
"authMethod": "pat",
"principalType": "user"
}401은 토큰이 없거나, 잘못 입력되었거나, 만료되었거나, 취소되었음을 의미합니다. 그 밖의 거부에는 보통 기계가 읽을 수 있는 code가 포함되며, 이는 오류 코드 페이지에 설명되어 있습니다. 일부 거부에는 코드가 없으므로 항상 HTTP 상태 코드로 대비 처리하세요.
레퍼런스가 만들어지는 방식
엔드포인트와 오류 코드 페이지는 이 사이트가 게시될 때마다 플랫폼 자체의 라우트 트리에서 생성됩니다. 사람이 직접 작성하지 않습니다. 프로덕션 릴리스는 앱과 같은 커밋에서 이 페이지를 빌드하므로, 해당 릴리스가 제공하는 경로가 각 엔드포인트에 필요한 역할 게이트와 토큰 범위, 허용되는 쿼리 매개변수와 함께 나열됩니다. 오류 목록은 알려진 최소한의 목록일 뿐 전체 목록이 아닙니다. 엔드포인트는 생성기가 볼 수 없는 코드를 반환할 수 있으므로, 목록에 없는 오류는 HTTP 상태 코드로 처리하세요.
버전 관리
/v1은 버전 내에서 추가만 이루어집니다. Waafir는 응답 필드와 선택적 요청 매개변수를 추가할 수 있습니다. /v1 내에서 기존 필드를 제거하거나 타입을 바꾸거나 엔드포인트를 제거하지 않습니다. 호환성을 깨는 변경은 새 버전 접두사로 제공됩니다. 인식하지 못하는 필드는 무시하도록 클라이언트를 작성하세요.
다음으로 볼 내용
- 인증: 토큰, 범위, 역할 상한, 데이터룸 제한 토큰.
- 엔드포인트: 영역별로 그룹화된 모든 엔드포인트.
- 오류 코드: 알려진 거부 유형과 대처 방법.
- 대출 API 레퍼런스와 쿡북: 포트폴리오 모니터링 데이터 수집을 위한 요청 및 응답 규약.