Kehittäjät

# Rakenna Welleyllä

Welley API:n avulla voit rakentaa asiakasohjelmia, skriptejä, yhteisötyökaluja ja integraatioita. Ajantasainen Swagger-referenssi kuvaa käytettävissä olevat operaatiot ja skeemat.

[Avaa ajantasainen Swagger UI](https://welley.social/q/swagger-ui/) [Lataa OpenAPI-JSON](https://welley.social/q/openapi?format=json)

Aiomme julkaista Welleyn avoimena lähdekoodina tulevaisuudessa. Julkaisupäivää tai lisenssiä ei ole vielä ilmoitettu.

## Aloita julkisella pyynnöllä

API toimii HTTPS-yhteyden yli, ja useimmat operaatiot ottavat vastaan ja palauttavat JSONia. Julkiset lukuoperaatiot voivat toimia ilman tiliä.

### Lue palvelimen tiedot

Tämä pyyntö palauttaa palvelimen julkiset metatiedot. Se ei muuta mitään palvelimen tietoja.

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

### Etsi operaatio Swaggerista

Tarkista operaation parametrit, pyyntöskeema, vastausskeema ja oikeudet ennen kuin kirjoitat asiakasohjelman.

## Todenna integraatio

Suojatut operaatiot tarvitsevat voimassa olevan tokenin Authorization-otsakkeessa. Virallinen CLI lähettää tokenin Bearer-etuliitteellä.

### Lue voimassa olevat palvelinoikeutesi

Aseta WELLEY\_TOKEN omaksi voimassa olevaksi tokeniksesi tavalla, jolla yleensä käsittelet salaisuuksia. Tämä esimerkki vain lukee tietoja.

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

-   Luo integraatiota varten henkilökohtainen käyttöoikeustoken tilisi asetuksissa.
-   Anna sille nimi ja vanhenemisaika. API hyväksyy myös arvon expiresInDays=0 tokenille, jolla ei ole tallennettua vanhenemisaikaa.
-   Rajaa, mitä yleisiä oikeuksia, ryhmäoikeuksia ja ryhmiä token voi käyttää.
-   Jos jätät sallittujen luettelon tyhjäksi, kenttää rajoittavat vain nykyiset oikeutesi. Token ei voi antaa oikeuksia, joita sinulla ei ole.
-   Näet tokenin salaisen arvon vain kerran. Tallenna se, ennen kuin suljet luontituloksen.
-   Tokenien hallintaan tarvitset tilin kirjautumisistunnon. Henkilökohtaisella käyttöoikeustokenilla ei voi luoda, listata, kopioida tai mitätöidä tokeneita.

## Tarkista oikeudet ja laajuus

Todennus kertoo API:lle, kuka kutsuu. Roolioikeudet määräävät, mitä operaatioita kutsuja voi käyttää.

-   API palauttaa 401, kun suojatussa pyynnössä ei ole voimassa olevaa todennusta.
-   API palauttaa 403, kun kutsujalla ei ole vaadittua oikeutta.
-   Oikeuksien nimet noudattavat muotoa Resource.Action, esimerkiksi GroupSettings.Manage.
-   Laajuuteen sidotuissa webhook- ja oikeusoperaatioissa jätä scope pois, jos haluat käyttää palvelimen laajuutta. Ryhmän laajuutta varten anna ryhmän TypeId.
-   Lue jokaisen operaation kuvaus. Jotkin päätepisteet käyttävät HTTP-allekirjoituksia tai muuta protokollaa tilin tokenin sijaan.

## Valitse API-alue

Referenssi kattaa sosiaaliset toiminnot, integraatiot ja palvelimen ylläpidon. Tässä olevat esimerkit ovat vain pieni osa API:a.

### Tilit ja profiilit

Lue profiileja, hallitse tilin identiteettejä ja käytä tilin vienti- tai siirto-operaatioita.

| Metodi | Polku | Toiminto | Käyttöoikeus |
| --- | --- | --- | --- |
| GET | `/api/v1/users` | Lue paikallinen tai etäprofiili käyttäjänimen perusteella. | Julkinen tai valinnainen token |
| POST | `/api/v1/users` | Lisää nykyiselle tilille uusi profiili palvelimen rajaan asti. | Token vaaditaan |

### Julkaisut ja syötteet

Lue syötteitä ja luo julkaisuja. Muut operaatiot käsittelevät vastauksia, kyselyjä, reaktioita, luonnoksia ja tallennettuja julkaisuja.

| Metodi | Polku | Toiminto | Käyttöoikeus |
| --- | --- | --- | --- |
| GET | `/api/v1/posts` | Lue julkisia julkaisuja vieraana tai mukautettua syötettä, kun olet tunnistautunut. | Julkinen tai valinnainen token |
| POST | `/api/v1/posts` | Luo julkaisu ja määritä sen sisältö ja se, kuka sen näkee. | Token vaaditaan |

### Ryhmät ja tapahtumat

Rakenna yhteisötyökaluja ryhmien, jäsenyyden, kanavien, moderoinnin ja tapahtumien avulla.

| Metodi | Polku | Toiminto | Käyttöoikeus |
| --- | --- | --- | --- |
| POST | `/api/v1/groups` | Luo ryhmä todennetun käyttäjän oikeuksilla. | Token vaaditaan |
| GET | `/api/v1/events` | Listaa julkiset tapahtumat tai tapahtumat, jotka todennettu käyttäjä näkee. | Julkinen tai valinnainen token |
| POST | `/api/v1/events` | Luo tapahtuma. Ryhmän tapahtuma vaatii oikeuden GroupEvents.Create. | Token vaaditaan |

### Keskustelut ja ilmoitukset

Lue keskusteluhuoneita ja niiden viestejä. Lue ilmoituskokoelmia ja päivitä niiden lukutila.

| Metodi | Polku | Toiminto | Käyttöoikeus |
| --- | --- | --- | --- |
| GET | `/api/v1/rooms` | Listaa nykyisen käyttäjän huoneet. Jatka listaa käyttämällä vastauksen rungon nextCursor-arvoa. | Token vaaditaan |
| GET | `/api/v1/user-notifications` | Listaa nykyisen käyttäjän ilmoitukset. | Token vaaditaan |

### Media, haku ja kääntäminen

Lataa mediaa, hae näkemääsi sisältöä ja pyydä tekstien käännöksiä.

| Metodi | Polku | Toiminto | Käyttöoikeus |
| --- | --- | --- | --- |
| POST | `/api/v1/uploads` | Luo latausmerkintä ja lähetä sitten tiedoston sisältö PUT-pyynnöllä sen palauttamaan latausosoitteeseen. | Token vaaditaan |
| GET | `/api/v1/search` | Hae sisältöä, jonka kutsuja näkee, tai selvitä tuetut URL-osoitteet. | Julkinen tai valinnainen token |
| POST | `/api/v1/translate/text` | Käännä teksti pyydetylle kielelle. | Token vaaditaan |

### Webhookit ja tekoälyagentit

Yhdistä ulkopuolisia palveluita webhookeilla. Määritä tekoälyagentit agenttirajapintojen kautta.

| Metodi | Polku | Toiminto | Käyttöoikeus |
| --- | --- | --- | --- |
| GET | `/api/v1/webhooks/events` | Hae luettelo tuetuista webhook-tapahtumatyypeistä. | Token vaaditaan |
| POST | `/api/v1/webhooks` | Luo webhook palvelimen tai ryhmän laajuudessa, johon sinulla on oikeus. HTTP-allekirjoituksen salaisuus näytetään vain kerran. | Token vaaditaan |
| GET | `/api/v1/ai-agents` | Listaa tekoälyagentit, jotka kutsuja näkee. | Token vaaditaan |

### Palvelimen ja ryhmien ylläpito

Käytä API:a asetuksiin, raportteihin, moderointiin, federoinnin hallintaan, kiintiöihin ja käyttöönoton ylläpitoon.

| Metodi | Polku | Toiminto | Käyttöoikeus |
| --- | --- | --- | --- |
| GET | `/api/v1/rbac/permissions` | Lue nykyisen käyttäjän ja laajuuden voimassa olevat oikeudet. | Token vaaditaan |
| GET | `/api/v1/settings` | Lue alustan asetukset, jos tilillä on vaaditut oikeudet. | Julkinen tai valinnainen token |

## Käsittele vastauksia ja mediaa

Noudata jokaisen operaation omaa sivutusta ja latauskulkua.

-   Kursorisyötteissä seuraa palvelimen palauttamia sivutuslinkkejä. Älä muodosta kursoreita arvaamalla ID-arvoja.
-   Huoneet palauttavat vastauksen rungossa läpinäkymättömän nextCursor-arvon. Kun jatkat listaa, pidä samat suodattimet.
-   Jos haluat ladata mediaa, luo latausmerkintä ja lähetä sisältö sen palauttamaan URL-osoitteeseen.
-   Tarkista jokaisen operaation virhevastaukset ja rajat. Myös dokumentoitu operaatio voi vaatia roolin, palvelimen asetuksen tai ulkoisen palveluntarjoajan.