Vývojári

# Vytvárajte s Welley

Pomocou Welley API môžete vytvárať klientov, skripty, nástroje pre komunity a integrácie. Živá referencia Swagger popisuje operácie a schémy, ktoré môžete použiť.

[Otvoriť živé Swagger UI](https://welley.social/q/swagger-ui/) [Stiahnuť OpenAPI JSON](https://welley.social/q/openapi?format=json)

V budúcnosti plánujeme vydať Welley ako open source. Dátum vydania ani licencia zatiaľ neboli oznámené.

## Začnite verejnou požiadavkou

API beží cez HTTPS a väčšina operácií prijíma a vracia JSON. Verejné operácie čítania môžu fungovať bez účtu.

### Prečítajte informácie o serveri

Táto požiadavka vráti verejné metadáta o serveri. Nemení žiadne údaje servera.

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

### Vyhľadajte operáciu vo Swagger

Skôr než napíšete klienta, skontrolujte parametre operácie, schému požiadavky, schému odpovede a oprávnenia.

## Overenie integrácie

Chránené operácie potrebujú platný token v hlavičke Authorization. Náš oficiálny CLI posiela token s predponou Bearer.

### Prečítajte si svoje efektívne oprávnenia na serveri

Nastavte WELLEY\_TOKEN na vlastný platný token, tak ako zvyčajne narábate s tajnými údajmi. Tento príklad údaje iba číta.

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

-   Pre integráciu vytvorte osobný prístupový token v nastaveniach účtu.
-   Určite mu názov a čas vypršania. API prijíma aj expiresInDays=0 pre token bez uloženého času vypršania.
-   Obmedzte, ktoré globálne oprávnenia, oprávnenia skupín a ktoré skupiny môže token používať.
-   Ak necháte zoznam povolených prázdny, toto pole je obmedzené iba vaším aktuálnym prístupom. Token nemôže dať práva, ktoré nemáte vy.
-   Tajný kľúč tokenu uvidíte iba raz. Uložte si ho skôr, než zatvoríte výsledok vytvorenia.
-   Na správu tokenov potrebujete prihlasovaciu reláciu účtu. Osobný prístupový token nemôže tokeny vytvárať, zobrazovať, kopírovať ani rušiť.

## Skontrolujte oprávnenia a rozsah

Overenie povie API, kto volá. Oprávnenia rolí určujú, ktoré operácie môže tento volajúci používať.

-   API vráti 401, keď chránená požiadavka nemá platné overenie.
-   API vráti 403, keď volajúci nemá požadované oprávnenie.
-   Názvy oprávnení majú tvar Resource.Action, napríklad GroupSettings.Manage.
-   Pri operáciách webhookov a oprávnení s rozsahom vynechajte scope, ak chcete použiť rozsah servera. Pre rozsah skupiny zadajte TypeId skupiny.
-   Prečítajte si popis každej operácie. Niektoré endpointy namiesto tokenu účtu používajú podpisy HTTP alebo iný protokol.

## Vyberte oblasť API

Referencia pokrýva sociálne funkcie, integrácie a správu servera. Tu uvedené príklady sú len malou časťou API.

### Účty a profily

Čítajte profily, spravujte identity účtu a používajte operácie exportu alebo presunu účtu.

| Metóda | Cesta | Operácia | Prístup |
| --- | --- | --- | --- |
| GET | `/api/v1/users` | Prečítajte lokálny alebo vzdialený profil podľa používateľského mena. | Verejný prístup alebo voliteľný token |
| POST | `/api/v1/users` | Pridajte k aktuálnemu účtu ďalší profil, najviac do limitu servera. | Vyžaduje token |

### Príspevky a feedy

Čítajte feedy a vytvárajte príspevky. Ďalšie operácie zvládajú odpovede, ankety, reakcie, koncepty a uložené príspevky.

| Metóda | Cesta | Operácia | Prístup |
| --- | --- | --- | --- |
| GET | `/api/v1/posts` | Čítajte verejné príspevky ako hosť alebo prispôsobený feed, keď ste overený. | Verejný prístup alebo voliteľný token |
| POST | `/api/v1/posts` | Vytvorte príspevok s jeho obsahom a nastavením, kto ho môže vidieť. | Vyžaduje token |

### Skupiny a udalosti

Vytvárajte nástroje pre komunity pomocou skupín, členstva, kanálov, moderovania a udalostí.

| Metóda | Cesta | Operácia | Prístup |
| --- | --- | --- | --- |
| POST | `/api/v1/groups` | Vytvorte skupinu s oprávneniami overeného používateľa. | Vyžaduje token |
| GET | `/api/v1/events` | Zobrazte verejné udalosti alebo udalosti, ktoré overený používateľ vidí. | Verejný prístup alebo voliteľný token |
| POST | `/api/v1/events` | Vytvorte udalosť. Udalosť skupiny vyžaduje GroupEvents.Create. | Vyžaduje token |

### Konverzácie a upozornenia

Čítajte konverzačné miestnosti a ich správy. Čítajte zbierky upozornení a aktualizujte ich stav prečítania.

| Metóda | Cesta | Operácia | Prístup |
| --- | --- | --- | --- |
| GET | `/api/v1/rooms` | Zobrazte miestnosti aktuálneho používateľa. Na pokračovanie v zozname použite nextCursor z tela odpovede. | Vyžaduje token |
| GET | `/api/v1/user-notifications` | Zobrazte upozornenia aktuálneho používateľa. | Vyžaduje token |

### Médiá, vyhľadávanie a preklad

Nahrávajte médiá, hľadajte v obsahu, ktorý vidíte, a žiadajte o preklady textov.

| Metóda | Cesta | Operácia | Prístup |
| --- | --- | --- | --- |
| POST | `/api/v1/uploads` | Vytvorte záznam nahrávania a potom pošlite obsah súboru metódou PUT na URL nahrávania, ktoré vráti. | Vyžaduje token |
| GET | `/api/v1/search` | Hľadajte v obsahu, ktorý volajúci vidí, alebo vyhľadajte podporované URL. | Verejný prístup alebo voliteľný token |
| POST | `/api/v1/translate/text` | Preložte text do požadovaného jazyka. | Vyžaduje token |

### Webhooky a AI agenti

Pripájajte externé služby cez webhooky. AI agentov nastavíte cez API agentov.

| Metóda | Cesta | Operácia | Prístup |
| --- | --- | --- | --- |
| GET | `/api/v1/webhooks/events` | Získajte zoznam podporovaných typov udalostí webhookov. | Vyžaduje token |
| POST | `/api/v1/webhooks` | Vytvorte webhook v rozsahu servera alebo skupiny, na ktorý máte oprávnenie. Tajný kľúč na podpisovanie HTTP sa zobrazí iba raz. | Vyžaduje token |
| GET | `/api/v1/ai-agents` | Zobrazte AI agentov, ktorých volajúci vidí. | Vyžaduje token |

### Správa servera a skupín

API použite na nastavenia, hlásenia, moderovanie, ovládanie federácie, kvóty a správu nasadenia.

| Metóda | Cesta | Operácia | Prístup |
| --- | --- | --- | --- |
| GET | `/api/v1/rbac/permissions` | Prečítajte efektívne oprávnenia pre aktuálneho používateľa a rozsah. | Vyžaduje token |
| GET | `/api/v1/settings` | Prečítajte nastavenia platformy, ak má účet požadované oprávnenia. | Verejný prístup alebo voliteľný token |

## Práca s odpoveďami a médiami

Riaďte sa stránkovaním a postupom nahrávania, ktoré platia pre každú operáciu.

-   Pri feedoch s kurzorom sledujte odkazy na stránkovanie, ktoré server vráti. Kurzory nevytvárajte z odhadov o ID.
-   Miestnosti vracajú v tele odpovede nepriehľadný nextCursor. Keď v zozname pokračujete, ponechajte rovnaké filtre.
-   Ak chcete nahrať médiá, vytvorte záznam nahrávania a potom pošlite obsah na URL, ktoré vráti.
-   Skontrolujte chybové odpovede a limity každej operácie. Aj zdokumentovaná operácia môže vyžadovať rolu, konfiguráciu servera alebo externého poskytovateľa.