개발자

Welley로 만들기

Welley API로 클라이언트, 스크립트, 커뮤니티 도구, 연동 기능을 만들 수 있어요. 실시간 Swagger 문서에 사용할 수 있는 작업과 스키마가 나와 있어요.

실시간 Swagger UI 열기OpenAPI JSON 내려받기

앞으로 Welley를 오픈 소스로 공개할 계획이에요. 공개 일정과 라이선스는 아직 발표되지 않았어요.

공개 요청으로 시작하기

API는 HTTPS로 동작하고, 대부분의 작업은 JSON을 받고 JSON으로 응답해요. 공개 읽기 작업은 계정 없이도 쓸 수 있어요.

서버 정보 읽기

이 요청은 서버의 공개 메타데이터를 돌려줘요. 서버 데이터는 바꾸지 않아요.

curl --fail --silent --show-error "https://welley.social/api/v1/instance"

Swagger에서 작업 찾아보기

클라이언트를 작성하기 전에 매개변수, 요청 스키마, 응답 스키마, 권한을 확인해 보세요.

연동 인증하기

보호된 작업에는 Authorization 헤더에 유효한 토큰이 필요해요. 공식 CLI는 토큰을 Bearer 접두사와 함께 보내요.

내 서버 유효 권한 읽기

WELLEY_TOKEN을 본인의 유효한 토큰으로 설정하세요. 평소 비밀 값을 다루는 방식대로 하면 돼요. 이 예시는 데이터를 읽기만 해요.

curl --fail --silent --show-error \ -H "Authorization: Bearer $WELLEY_TOKEN" \ "https://welley.social/api/v1/rbac/permissions"
  • 연동을 만들 때는 계정 설정에서 개인 액세스 토큰을 만드세요.
  • 이름과 만료 기간을 정해 주세요. API는 저장된 만료 기간이 없는 토큰을 위해 expiresInDays=0도 받아요.
  • 토큰이 사용할 수 있는 전역 권한, 그룹 권한, 그룹을 제한할 수 있어요.
  • 허용 목록을 비워 두면 해당 항목은 현재 내 접근 권한으로만 제한돼요. 토큰은 내가 가지고 있지 않은 권한을 줄 수 없어요.
  • 토큰 비밀 값은 한 번만 볼 수 있어요. 생성 결과를 닫기 전에 저장해 두세요.
  • 토큰을 관리하려면 계정 로그인 세션이 필요해요. 개인 액세스 토큰으로는 토큰을 만들거나, 목록을 보거나, 복사하거나, 폐기할 수 없어요.

권한과 범위 확인하기

인증은 API에 누가 호출하는지 알려줘요. 호출한 쪽이 어떤 작업을 쓸 수 있는지는 역할 권한이 정해요.

  • 보호된 요청에 유효한 인증이 없으면 API는 401을 반환해요.
  • 호출한 쪽에 필요한 권한이 없으면 API는 403을 반환해요.
  • 권한 이름은 Resource.Action 형식이에요. 예를 들면 GroupSettings.Manage가 있어요.
  • 범위가 있는 웹훅 및 권한 작업에서는 scope를 생략하면 서버 범위가 쓰여요. 그룹 범위를 쓰려면 그룹 TypeId를 전달하세요.
  • 각 작업의 설명을 읽어 보세요. 일부 엔드포인트는 계정 토큰 대신 HTTP 서명이나 다른 프로토콜을 써요.

API 영역 고르기

레퍼런스는 소셜 기능, 연동, 서버 관리를 다뤄요. 여기 나온 예시는 API의 일부일 뿐이에요.

계정과 프로필

프로필을 읽고, 계정의 아이덴티티를 관리하고, 계정 내보내기나 이전 작업을 쓸 수 있어요.

메서드경로작업접근
GET/api/v1/users사용자 이름으로 로컬 또는 원격 프로필을 읽어요.공개 또는 선택적 토큰
POST/api/v1/users현재 계정에 프로필을 하나 더 추가해요. 서버의 한도까지 추가할 수 있어요.토큰 필요

게시물과 피드

피드를 읽고 게시물을 만들 수 있어요. 다른 작업으로 답글, 투표, 반응, 임시 저장, 저장한 게시물을 다뤄요.

메서드경로작업접근
GET/api/v1/posts게스트로는 공개 게시물을 읽고, 인증하면 맞춤 피드를 읽을 수 있어요.공개 또는 선택적 토큰
POST/api/v1/posts내용과 공개 범위를 정해 게시물을 만들어요.토큰 필요

그룹과 이벤트

그룹, 멤버십, 채널, 모더레이션, 이벤트로 커뮤니티 도구를 만들 수 있어요.

메서드경로작업접근
POST/api/v1/groups인증된 사용자의 권한으로 그룹을 만들어요.토큰 필요
GET/api/v1/events공개 이벤트나 인증된 사용자가 볼 수 있는 이벤트의 목록을 가져와요.공개 또는 선택적 토큰
POST/api/v1/events이벤트를 만들어요. 그룹 이벤트에는 GroupEvents.Create가 필요해요.토큰 필요

대화와 알림

대화방과 메시지를 읽어요. 알림 모음을 읽고 읽음 여부를 업데이트해요.

메서드경로작업접근
GET/api/v1/rooms현재 사용자의 대화방 목록을 가져와요. 목록을 이어서 가져오려면 응답 본문의 nextCursor를 사용하세요.토큰 필요
GET/api/v1/user-notifications현재 사용자의 알림 목록을 가져와요.토큰 필요

웹훅과 AI 에이전트

웹훅으로 외부 서비스를 연결해요. 에이전트 API로 AI 에이전트를 설정해요.

메서드경로작업접근
GET/api/v1/webhooks/events지원되는 웹훅 이벤트 유형의 목록을 가져와요.토큰 필요
POST/api/v1/webhooks권한이 있는 서버 또는 그룹 범위에 웹훅을 만들어요. HTTP 서명 비밀 값은 한 번만 표시돼요.토큰 필요
GET/api/v1/ai-agents호출한 쪽이 볼 수 있는 AI 에이전트의 목록을 가져와요.토큰 필요

서버와 그룹 관리

API로 설정, 신고, 모더레이션, 연합 제어, 할당량, 배포 관리를 할 수 있어요.

메서드경로작업접근
GET/api/v1/rbac/permissions현재 사용자와 범위의 유효 권한을 읽어요.토큰 필요
GET/api/v1/settings계정에 필요한 권한이 있으면 플랫폼 설정을 읽어요.공개 또는 선택적 토큰

응답과 미디어 다루기

각 작업에 맞는 페이지 나누기와 업로드 흐름을 따르세요.

  • 커서 방식 피드에서는 서버가 반환하는 페이지 나누기 링크를 따라가세요. ID를 추측해서 커서를 만들지 마세요.
  • 대화방은 응답 본문에 알아볼 수 없는 형태의 nextCursor를 반환해요. 목록을 이어서 가져올 때는 같은 필터를 유지하세요.
  • 미디어를 업로드하려면 업로드 항목을 만든 다음, 반환된 URL로 내용을 보내세요.
  • 각 작업의 오류 응답과 한도를 확인하세요. 문서에 나온 작업이라도 역할, 서버 설정, 외부 제공자가 필요할 수 있어요.