개발자

# Welley로 만들기

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

[실시간 Swagger UI 열기](https://welley.social/q/swagger-ui/) [OpenAPI JSON 내려받기](https://welley.social/q/openapi?format=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` | 현재 사용자의 알림 목록을 가져와요. | 토큰 필요 |

### 미디어, 검색, 번역

미디어를 업로드하고, 볼 수 있는 콘텐츠를 검색하고, 텍스트 번역을 요청할 수 있어요.

| 메서드 | 경로 | 작업 | 접근 |
| --- | --- | --- | --- |
| POST | `/api/v1/uploads` | 업로드 항목을 만든 다음, 응답으로 받은 업로드 URL에 파일 내용을 PUT으로 보내세요. | 토큰 필요 |
| GET | `/api/v1/search` | 호출한 쪽이 볼 수 있는 콘텐츠를 검색하거나, 지원되는 URL을 확인해요. | 공개 또는 선택적 토큰 |
| POST | `/api/v1/translate/text` | 텍스트를 요청한 언어로 번역해요. | 토큰 필요 |

### 웹훅과 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로 내용을 보내세요.
-   각 작업의 오류 응답과 한도를 확인하세요. 문서에 나온 작업이라도 역할, 서버 설정, 외부 제공자가 필요할 수 있어요.