Programiści

# Twórz z Welley

Możesz użyć API Welley, żeby tworzyć klienty, skrypty, narzędzia dla społeczności i integracje. Aktualna dokumentacja Swagger opisuje operacje i schematy, z których możesz korzystać.

[Otwórz aktualny Swagger UI](https://welley.social/q/swagger-ui/) [Pobierz OpenAPI JSON](https://welley.social/q/openapi?format=json)

Planujemy w przyszłości udostępnić Welley jako oprogramowanie open source. Nie ogłosiliśmy jeszcze daty wydania ani licencji.

## Zacznij od publicznego żądania

API działa przez HTTPS, a większość operacji przyjmuje i zwraca JSON. Publiczne operacje odczytu mogą działać bez konta.

### Odczytaj informacje o serwerze

To żądanie zwraca publiczne metadane o serwerze. Nie zmienia żadnych danych serwera.

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

### Sprawdź operację w Swagger

Zanim napiszesz klienta, sprawdź parametry operacji, schemat żądania, schemat odpowiedzi i uprawnienia.

## Uwierzytelnianie integracji

Chronione operacje wymagają prawidłowego tokenu w nagłówku Authorization. Nasze oficjalne CLI wysyła token z prefiksem Bearer.

### Odczytaj swoje efektywne uprawnienia na serwerze

Ustaw WELLEY\_TOKEN na swój ważny token, tak jak zwykle obsługujesz sekrety. Ten przykład tylko odczytuje dane.

```
curl --fail --silent --show-error \ -H "Authorization: Bearer $WELLEY_TOKEN" \ "https://welley.social/api/v1/rbac/permissions"
```

-   Dla integracji utwórz osobisty token dostępu w ustawieniach konta.
-   Nadaj mu nazwę i termin ważności. API przyjmuje też expiresInDays=0 dla tokenu bez zapisanego terminu ważności.
-   Ogranicz, z których uprawnień globalnych, uprawnień grupowych i grup może korzystać token.
-   Jeśli zostawisz listę dozwolonych pustą, to pole jest ograniczone tylko twoim bieżącym dostępem. Token nie może dać uprawnień, których sam nie masz.
-   Sekret tokenu zobaczysz tylko raz. Zapisz go, zanim zamkniesz wynik tworzenia.
-   Do zarządzania tokenami potrzebujesz sesji zalogowanego konta. Osobisty token dostępu nie może tworzyć, wyświetlać, kopiować ani unieważniać tokenów.

## Sprawdź uprawnienia i zakres

Uwierzytelnianie mówi API, kto wywołuje. Uprawnienia roli decydują, z których operacji ten wywołujący może korzystać.

-   API zwraca 401, gdy chronione żądanie nie ma prawidłowego uwierzytelnienia.
-   API zwraca 403, gdy wywołujący nie ma wymaganego uprawnienia.
-   Nazwy uprawnień mają postać Resource.Action, na przykład GroupSettings.Manage.
-   W operacjach webhooków i uprawnień z zakresem pomiń scope, żeby użyć zakresu serwera. Dla zakresu grupy podaj TypeId grupy.
-   Przeczytaj opis każdej operacji. Niektóre endpointy używają podpisów HTTP lub innego protokołu zamiast tokenu konta.

## Wybierz obszar API

Dokumentacja obejmuje funkcje społecznościowe, integracje i administrację serwerem. Przykłady tutaj to tylko niewielka część API.

### Konta i profile

Odczytuj profile, zarządzaj tożsamościami konta i korzystaj z operacji eksportu lub przeniesienia konta.

| Metoda | Ścieżka | Operacja | Dostęp |
| --- | --- | --- | --- |
| GET | `/api/v1/users` | Odczytaj profil lokalny lub zdalny według nazwy użytkownika. | Publiczny lub opcjonalny token |
| POST | `/api/v1/users` | Dodaj kolejny profil do bieżącego konta, do limitu serwera. | Wymagany token |

### Wpisy i aktualności

Odczytuj aktualności i twórz wpisy. Inne operacje obsługują odpowiedzi, ankiety, reakcje, wersje robocze i zapisane wpisy.

| Metoda | Ścieżka | Operacja | Dostęp |
| --- | --- | --- | --- |
| GET | `/api/v1/posts` | Odczytaj publiczne wpisy jako gość albo spersonalizowane aktualności po uwierzytelnieniu. | Publiczny lub opcjonalny token |
| POST | `/api/v1/posts` | Utwórz wpis z jego treścią i informacją, kto może go zobaczyć. | Wymagany token |

### Grupy i wydarzenia

Twórz narzędzia dla społeczności z użyciem grup, członkostwa, kanałów, moderacji i wydarzeń.

| Metoda | Ścieżka | Operacja | Dostęp |
| --- | --- | --- | --- |
| POST | `/api/v1/groups` | Utwórz grupę, korzystając z uprawnień uwierzytelnionego użytkownika. | Wymagany token |
| GET | `/api/v1/events` | Wyświetl publiczne wydarzenia albo wydarzenia, które widzi uwierzytelniony użytkownik. | Publiczny lub opcjonalny token |
| POST | `/api/v1/events` | Utwórz wydarzenie. Wydarzenie grupy wymaga GroupEvents.Create. | Wymagany token |

### Rozmowy i powiadomienia

Odczytuj pokoje rozmów i ich wiadomości. Odczytuj kolekcje powiadomień i aktualizuj informację, czy zostały przeczytane.

| Metoda | Ścieżka | Operacja | Dostęp |
| --- | --- | --- | --- |
| GET | `/api/v1/rooms` | Wyświetl pokoje bieżącego użytkownika. Aby kontynuować listę, użyj nextCursor z treści odpowiedzi. | Wymagany token |
| GET | `/api/v1/user-notifications` | Wyświetl powiadomienia bieżącego użytkownika. | Wymagany token |

### Multimedia, wyszukiwanie i tłumaczenie

Przesyłaj multimedia, przeszukuj widoczne dla ciebie treści i proś o tłumaczenia tekstu.

| Metoda | Ścieżka | Operacja | Dostęp |
| --- | --- | --- | --- |
| POST | `/api/v1/uploads` | Utwórz rekord przesyłania, a potem wyślij zawartość pliku metodą PUT na zwrócony adres URL przesyłania. | Wymagany token |
| GET | `/api/v1/search` | Przeszukaj treści widoczne dla wywołującego albo rozwiąż obsługiwane adresy URL. | Publiczny lub opcjonalny token |
| POST | `/api/v1/translate/text` | Przetłumacz tekst na żądany język. | Wymagany token |

### Webhooki i agenci AI

Połącz zewnętrzne usługi przez webhooki. Konfiguruj agentów AI przez API agentów.

| Metoda | Ścieżka | Operacja | Dostęp |
| --- | --- | --- | --- |
| GET | `/api/v1/webhooks/events` | Pobierz listę obsługiwanych typów zdarzeń webhooków. | Wymagany token |
| POST | `/api/v1/webhooks` | Utwórz webhook w zakresie serwera lub grupy, do którego masz uprawnienia. Sekret podpisu HTTP jest pokazywany tylko raz. | Wymagany token |
| GET | `/api/v1/ai-agents` | Wyświetl agentów AI, których widzi wywołujący. | Wymagany token |

### Administracja serwerem i grupami

Używaj API do ustawień, zgłoszeń, moderacji, kontroli federacji, limitów i administrowania wdrożeniem.

| Metoda | Ścieżka | Operacja | Dostęp |
| --- | --- | --- | --- |
| GET | `/api/v1/rbac/permissions` | Odczytaj efektywne uprawnienia bieżącego użytkownika w danym zakresie. | Wymagany token |
| GET | `/api/v1/settings` | Odczytaj ustawienia platformy, jeśli konto ma wymagane uprawnienia. | Publiczny lub opcjonalny token |

## Obsługa odpowiedzi i multimediów

W każdej operacji stosuj jej własny sposób stronicowania i przesyłania plików.

-   W aktualnościach z kursorem korzystaj z linków stronicowania zwracanych przez serwer. Nie buduj kursorów na podstawie domysłów o identyfikatorach.
-   Pokoje zwracają nieprzejrzysty nextCursor w treści odpowiedzi. Gdy kontynuujesz listę, zachowaj te same filtry.
-   Aby przesłać multimedia, utwórz rekord przesyłania, a potem wyślij zawartość na zwrócony adres URL.
-   Sprawdź odpowiedzi błędów i limity każdej operacji. Nawet udokumentowana operacja może wymagać roli, konfiguracji serwera lub zewnętrznego dostawcy.