Documentazione dell'API utente di Loomio

/api/b2 è l'API orientata agli utenti per le integrazioni con Loomio. Usa la chiave API di un account utente e ogni azione viene eseguita come quell'utente.

Le operazioni sui gruppi usano le iscrizioni e i permessi nei gruppi dell'utente titolare della chiave API. Il ruolo di amministratore dell'istanza non amplia l'accesso di una chiave API ai gruppi o ai contenuti; usa l'API server per l'amministrazione a livello di istanza.

Usa la chiave API dell'account utente Loomio che eseguirà le azioni. Un account bot dedicato è utile quando un'integrazione non deve essere invitata ai sondaggi o ricevere notifiche.

Gli utenti che hanno effettuato l'accesso possono trovare la propria chiave API e gli ID dei gruppi nella pagina di accesso API.

Invia la chiave API in un'intestazione Authorization: Bearer. Le chiavi API nelle stringhe di query vengono rifiutate perché gli URL possono essere registrati dai proxy e nei log di accesso.

Modifica dell'autenticazione

In precedenza, la chiave API veniva accettata come parametro URL api_key. Le richieste che usano ?api_key=YOUR_API_KEY non funzionano più. Usa invece l'intestazione HTTP Authorization:

Authorization: Bearer YOUR_API_KEY

Gli esempi usano YOUR_API_KEY, l'ID gruppo 123 e https://www.loomio.com/. Sostituiscili con la tua chiave API, l'ID del tuo gruppo e l'URL della tua installazione di Loomio.

Dimensione delle risposte e record correlati

Le risposte dell'API utente usano un formato composto: i record principali sono accompagnati da record correlati, come topic, gruppi, utenti, sondaggi e reazioni. Questo consente a un client di popolare un archivio locale di record con una sola richiesta, ma può includere più dati di quanti ne servano a una semplice integrazione.

Passa compact=1 per omettere i record correlati voluminosi relativi a topic, gruppi, gruppi principali, iscrizioni, reazioni, tag e traduzioni. I record principali e i record correlati necessari per interpretarne il contenuto restano presenti.

curl -H 'Authorization: Bearer YOUR_API_KEY' 'https://www.loomio.com/api/b2/threads/123/items?compact=1'

Per un controllo diretto, passa exclude_types con i tipi di record al singolare separati da spazi. Ad esempio, exclude_types=group reaction omette i gruppi e le reazioni correlati. I valori comuni sono topic, group, parent, membership, reaction, tag, translation, user, discussion, poll, poll_option, stance, stance_choice, outcome e topic_item. Le esclusioni si applicano ai record correlati, non alla risorsa principale richiesta dall'endpoint.

Le risposte relative a raccolte includono meta.total quando è definita una dimensione esatta della raccolta. Il totale viene calcolato prima di applicare limit e offset. Gli endpoint come quello di ricerca, che restituiscono intenzionalmente un insieme limitato di risultati, omettono meta.total anziché restituire null.

Riepilogo degli endpoint

Gruppi

Elenca i gruppi

Restituisce i gruppi in cui l'utente titolare della chiave API ha un'iscrizione attiva.

GET /api/b2/groups

curl -H 'Authorization: Bearer YOUR_API_KEY' https://www.loomio.com/api/b2/groups

La risposta contiene tutti i record corrispondenti in un array groups senza paginazione. Include gruppi principali e sottogruppi, anche quelli il cui abbonamento non è attualmente attivo. Controlla il campo enabled quando un'integrazione deve operare solo sui gruppi abilitati.

Tra i campi importanti dei gruppi ci sono:

La risposta può includere ulteriori impostazioni del gruppo, record correlati del gruppo principale e le iscrizioni dell'utente API. I client dovrebbero ignorare i campi che non usano.

Recupera un gruppo

Restituisce un gruppo visibile all'utente titolare della chiave API.

GET /api/b2/groups/:id_or_key_or_handle

L'identificatore può essere l'ID numerico, la chiave o l'identificativo leggibile del gruppo.

curl -H 'Authorization: Bearer YOUR_API_KEY' https://www.loomio.com/api/b2/groups/123
curl -H 'Authorization: Bearer YOUR_API_KEY' https://www.loomio.com/api/b2/groups/example-group

La risposta contiene il gruppo nell'array groups e usa gli stessi campi dell'endpoint che elenca i gruppi. Una richiesta per un gruppo a cui l'utente titolare della chiave API non può accedere restituisce un errore di autorizzazione.

Webhook

L'API utente si basa sulle richieste: un'integrazione chiama Loomio quando vuole leggere o modificare dati. Un webhook di gruppo permette invece a Loomio di inviare gli aggiornamenti. Loomio invia gli eventi selezionati del gruppo al tuo endpoint quando si verificano, quindi un'integrazione non deve interrogare periodicamente l'API REST per rilevare le modifiche.

I webhook vengono configurati per ciascun gruppo e richiedono i permessi di amministratore del gruppo. Puoi gestirli tramite l'interfaccia di Loomio:

1. Apri il gruppo.
2. Apri il menu del gruppo e seleziona Integrazioni di chat.
3. Aggiungi l'integrazione corrispondente al formato del payload accettato dal tuo endpoint. Per un endpoint generico, usa il formato Mattermost/Markdown.
4. Inserisci un nome e l'URL di destinazione.
5. Seleziona gli eventi che Loomio deve inviare automaticamente.
6. Salva l'integrazione e usa Test connection per inviare un messaggio di prova.

Usa una destinazione HTTPS con un URL impossibile da indovinare. Loomio richiede che la destinazione si risolva in un indirizzo pubblico e blocca le richieste verso indirizzi di rete locali o privati.

Gli agenti e le altre integrazioni possono invece gestire i webhook tramite gli endpoint chatbot con autenticazione Bearer descritti di seguito. La risorsa si chiama chatbots per compatibilità con le integrazioni di chat di Loomio, ma rappresenta anche webhook generici in uscita.

Elenca i webhook

Restituisce le integrazioni di chat configurate per un gruppo. L'utente titolare della chiave API deve essere un amministratore di quel gruppo. La risposta include gli URL di destinazione, quindi non deve essere resa accessibile ai membri ordinari del gruppo.

GET /api/b2/chatbots?group_id=123

curl -H 'Authorization: Bearer YOUR_API_KEY' 'https://www.loomio.com/api/b2/chatbots?group_id=123'

La risposta contiene un array chatbots con questi campi:

Crea un webhook

POST /api/b2/chatbots

curl -X POST \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "group_id": 123,
    "name": "Planning system",
    "kind": "webhook",
    "webhook_kind": "markdown",
    "server": "https://hooks.example.org/loomio/unguessable-token",
    "event_kinds": ["new_discussion", "new_comment", "poll_created", "outcome_created"],
    "notification_only": false
  }' \
  https://www.loomio.com/api/b2/chatbots

L'utente titolare della chiave API deve essere un amministratore del gruppo indicato da group_id. Prima del salvataggio, viene verificato che la destinazione sia un URL pubblico.

Aggiorna un webhook

PATCH /api/b2/chatbots/:id

Invia tutti i campi da modificare. Non puoi trasferire il webhook a un altro gruppo modificando group_id.

curl -X PATCH \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Planning events","event_kinds":["new_discussion","outcome_created"]}' \
  https://www.loomio.com/api/b2/chatbots/456

Verifica una destinazione webhook

Invia un messaggio di prova compatibile con Markdown a una destinazione prima o dopo averne salvato la configurazione.

POST /api/b2/chatbots/check

curl -X POST \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"group_id":123,"server":"https://hooks.example.org/loomio/unguessable-token"}' \
  https://www.loomio.com/api/b2/chatbots/check

Elimina un webhook

DELETE /api/b2/chatbots/:id

curl -X DELETE -H 'Authorization: Bearer YOUR_API_KEY' https://www.loomio.com/api/b2/chatbots/456

L'eliminazione della configurazione interrompe gli invii futuri. Non elimina alcun contenuto del gruppo Loomio.

Tipi di evento

Un webhook può iscriversi a questi tipi di evento:

Il webhook appartiene a un gruppo e riceve da quel gruppo gli eventi a cui è iscritto. Le persone possono anche selezionare esplicitamente l'integrazione quando condividono contenuti o inviano alcune notifiche, anche quando l'evento automatico corrispondente non è selezionato.

Invio HTTP

Loomio invia una richiesta HTTP POST asincrona all'URL configurato con questa intestazione:

Content-Type: application/json; charset=utf-8

Il timeout della richiesta è di cinque secondi. Una risposta 2xx, inclusa 204 No Content, viene considerata riuscita. I servizi che ricevono i webhook dovrebbero rispondere rapidamente, elaborare le operazioni più lunghe in modo asincrono e gestire invii duplicati o fuori ordine.

Al momento Loomio non aggiunge una firma del webhook, un'intestazione con un segreto condiviso, un ID evento o un ID invio. Tratta l'URL di destinazione completo come una credenziale, non esporlo pubblicamente e includi nell'URL un token impossibile da indovinare quando il servizio ricevente lo supporta. Se ti serve uno schema degli eventi stabile e leggibile da software o un invio firmato, usa il webhook come notifica di modifica e recupera i record aggiornati tramite l'API utente autenticata.

Formati del payload

I payload dei webhook sono messaggi destinati ai servizi di chat e pensati per la visualizzazione. Non sono record Loomio serializzati completi. I link nel messaggio identificano il contenuto Loomio interessato; un'integrazione può recuperare ulteriori informazioni tramite l'API utente quando le serve lo stato attuale in forma strutturata.

Ad esempio, il formato Markdown generico invia un corpo con questa struttura:

{
  "text": "Ada started a discussion: [Quarterly planning](https://example.loomio.org/d/example)",
  "icon_url": "https://example.loomio.org/path/to/group-logo.png",
  "username": "Loomio"
}

Il testo esatto del messaggio dipende dall'evento, dalle impostazioni locali del gruppo, dall'impostazione che limita i messaggi alla sola notifica e dalla versione di Loomio. I servizi riceventi dovrebbero basarsi sui campi di primo livello documentati del formato selezionato, anziché analizzare la formulazione delle frasi.

Ricerca

Cerca discussioni, commenti, sondaggi, voti e conclusioni visibili all'utente della chiave API. I risultati includono i contenuti pubblici anche quando l'utente non è membro del relativo gruppo; i contenuti privati restano soggetti alle normali regole di visibilità delle conversazioni.

GET /api/b2/search

Parametri

curl -H 'Authorization: Bearer YOUR_API_KEY' 'https://www.loomio.com/api/b2/search?query=quarterly+planning&type=Discussion'

La risposta contiene un array search_results. Ogni risultato identifica il record corrispondente e il suo contesto visibile con campi che includono searchable_type, searchable_id, highlight, group_id, group_name, discussion_key, poll_key, author_id, author_name, authored_at e tags. I campi non applicabili a un risultato sono null.

Report sulla partecipazione

Restituisce gli stessi dati aggregati sulla partecipazione usati dal report sulla partecipazione di Loomio.

GET /api/b2/reports

Parametri

Una persona è un delegato quando è membro attivo con il ruolo di delegato in almeno uno dei gruppi selezionati. I suoi conteggi vengono aggregati su tutti i gruppi selezionati. Le righe dei delegati vengono restituite anche quando tutti i conteggi delle attività sono pari a zero. I conteggi riguardano conversazioni, commenti, sondaggi, voti, conclusioni e reazioni; non sono tassi di partecipazione al voto. Le righe degli utenti includono anche le schede di voto identificato assegnate, compilate e non compilate. I sondaggi anonimi sono esclusi da tutti i conteggi dei voti per persona. all_votes_cast è true solo quando è stata assegnata almeno una scheda di voto e tutte le schede assegnate sono state compilate.

L'API applica le stesse regole di visibilità dei gruppi del report nell'applicazione. Una chiave API utente non può esporre dati del report relativi a gruppi a cui quell'utente non può accedere.

Esempio

curl -H 'Authorization: Bearer YOUR_API_KEY' 'https://www.loomio.com/api/b2/reports?section=users&group_scope=custom&group_ids=123&member_type=delegate&start_month=2026-01&end_month=2026-09'

L'array users contiene righe complete sulle attività:

{
  "users": [
    {
      "id": 456,
      "name": "Ada Lovelace",
      "country": "NZ",
      "delegate": true,
      "threads": 2,
      "comments": 8,
      "polls": 1,
      "votes": 5,
      "votes_cast": 5,
      "votes_issued": 6,
      "votes_missed": 1,
      "all_votes_cast": false,
      "outcomes": 1,
      "reactions": 4
    }
  ]
}

Crea una discussione

Crea una discussione come utente della chiave API.

POST /api/b2/discussions

Parametri

Esempio

curl -H 'Authorization: Bearer YOUR_API_KEY' -X POST -H 'Content-Type: application/json' -d '{"group_id": 123, "title":"example thread", "recipient_emails":["person@example.com"]}' https://www.loomio.com/api/b2/discussions

Visualizza una discussione

Recupera una discussione usando il suo ID, un numero intero, oppure la sua chiave, una stringa.

GET /api/b2/discussions/:id

Esempio

curl -H 'Authorization: Bearer YOUR_API_KEY' https://www.loomio.com/api/b2/discussions/abc123

Elenca le discussioni

Elenca le discussioni di un gruppo visibili all'utente della chiave API. Per un gruppo visibile pubblicamente, anche chi non ne è membro può elencare le discussioni pubbliche; le discussioni private restano accessibili solo agli utenti che possono leggerle in Loomio.

GET /api/b2/discussions

Parametri

Compatibilità con le versioni precedenti: per e from sono accettati come alias di limit e offset e continueranno a funzionare.

Esempio

curl -H 'Authorization: Bearer YOUR_API_KEY' 'https://www.loomio.com/api/b2/discussions?group_id=123'

Elenca le conversazioni

Elenca le conversazioni delle discussioni e dei sondaggi visibili all'utente della chiave API, ordinate per attività più recente. L'ID di una conversazione è il suo topic_id.

GET /api/b2/threads

Parametri

Esempio

curl -H 'Authorization: Bearer YOUR_API_KEY' 'https://www.loomio.com/api/b2/threads?limit=50&offset=0'

Leggi una conversazione

Leggi una conversazione, la sua sequenza ordinata di eventi oppure il suo documento Markdown completo con tutti i contenuti visibili.

GET /api/b2/threads/:topic_id

GET /api/b2/threads/:topic_id/items

GET /api/b2/threads/:topic_id/markdown

Esempio

GET https://www.loomio.com/api/b2/threads/<topic_id>
GET https://www.loomio.com/api/b2/threads/<topic_id>/items
GET https://www.loomio.com/api/b2/threads/<topic_id>/markdown

L'endpoint items restituisce la sequenza ordinata di eventi, inclusi commenti, sondaggi, voti e conclusioni visibili. L'endpoint markdown restituisce l'intera conversazione visibile in un unico documento Markdown. I motivi dei voti sono inclusi solo quando sono visibili all'utente della chiave API.

Tutti gli endpoint delle conversazioni applicano gli stessi permessi dell'interfaccia di Loomio. La chiave API non concede l'accesso a una conversazione che l'utente non può normalmente aprire.

Modifica una discussione

Modifica una discussione come utente della chiave API. Si applicano gli stessi permessi di Loomio: l'utente deve essere autorizzato a modificare quella discussione.

PATCH /api/b2/discussions/:id

Parametri

Esempio

curl -H 'Authorization: Bearer YOUR_API_KEY' -X PATCH -H 'Content-Type: application/json' -d '{"title":"updated thread title", "description":"updated context", "description_format":"md"}' https://www.loomio.com/api/b2/discussions/123

Elimina una discussione senza cancellarne il record

Elimina una discussione come utente titolare della chiave API. La discussione viene rimossa, ma il suo record viene conservato.

DELETE /api/b2/discussions/:id

Esempio

curl -H 'Authorization: Bearer YOUR_API_KEY' -X DELETE https://www.loomio.com/api/b2/discussions/123

Crea un commento

Crea un commento in una discussione come utente titolare della chiave API.

POST /api/b2/comments

Parametri

Esempio

curl -H 'Authorization: Bearer YOUR_API_KEY' -X POST -H 'Content-Type: application/json' -d '{"discussion_id": 123, "body":"example comment", "body_format":"md"}' https://www.loomio.com/api/b2/comments

Modifica un commento

Modifica un commento come utente titolare della chiave API. Si applicano gli stessi permessi di Loomio: l'utente deve essere autorizzato a modificare quel commento.

PATCH /api/b2/comments/:id

Parametri

Esempio

curl -H 'Authorization: Bearer YOUR_API_KEY' -X PATCH -H 'Content-Type: application/json' -d '{"body":"updated comment", "body_format":"md"}' https://www.loomio.com/api/b2/comments/123

Elimina un commento senza cancellarne il record

Elimina un commento come utente titolare della chiave API. Il commento viene rimosso e il suo testo viene nascosto, ma il suo record viene conservato.

DELETE /api/b2/comments/:id

Esempio

curl -H 'Authorization: Bearer YOUR_API_KEY' -X DELETE https://www.loomio.com/api/b2/comments/123

Crea un sondaggio

Crea un sondaggio come utente titolare della chiave API.

POST /api/b2/polls

Parametri

Esempio

curl -H 'Authorization: Bearer YOUR_API_KEY' -X POST -H 'Content-Type: application/json' -d '{"group_id": 123, "title":"example poll", "poll_type": "proposal", "options": ["agree", "disagree"], "closing_at": "2026-09-01T12:00:00Z", "recipient_emails":["person@example.com"]}' https://www.loomio.com/api/b2/polls

Mostra un sondaggio

Recupera un sondaggio usando il suo ID, un intero, oppure la sua chiave, una stringa.

GET /api/b2/polls/:id

Esempio

curl -H 'Authorization: Bearer YOUR_API_KEY' https://www.loomio.com/api/b2/polls/abc123

Elenca i sondaggi

Elenca i sondaggi di un gruppo visibili all'utente della chiave API. Se il gruppo è visibile pubblicamente, anche chi non è membro può elencarne i sondaggi pubblici; i sondaggi privati restano accessibili solo agli utenti che possono leggerli in Loomio. La risposta include la conclusione attuale di ogni sondaggio visibile, quindi puoi usare status=closed per elencare le proposte su cui è stata presa una decisione.

GET /api/b2/polls

Parametri

Compatibilità con le versioni precedenti: per e from sono accettati come alias di limit e offset e continueranno a funzionare.

Esempio

curl -H 'Authorization: Bearer YOUR_API_KEY' 'https://www.loomio.com/api/b2/polls?group_id=123'

Modifica un sondaggio

Modifica un sondaggio come utente della chiave API. Si applicano gli stessi permessi di Loomio: l'utente deve essere autorizzato a modificare quel sondaggio.

PATCH /api/b2/polls/:id

Parametri

Esempio

curl -H 'Authorization: Bearer YOUR_API_KEY' -X PATCH -H 'Content-Type: application/json' -d '{"title":"updated poll title", "details":"updated details", "details_format":"md"}' https://www.loomio.com/api/b2/polls/123

Elimina logicamente un sondaggio

Elimina logicamente un sondaggio come utente della chiave API. Questa operazione rimuove il sondaggio mantenendo il suo record nel database.

DELETE /api/b2/polls/:id

Esempio

curl -H 'Authorization: Bearer YOUR_API_KEY' -X DELETE https://www.loomio.com/api/b2/polls/123

Elenca le iscrizioni

Elenca le iscrizioni visibili all'utente della chiave API. I membri del gruppo possono leggere nomi, ID, titoli e ruoli dei membri. Gli indirizzi email sono inclusi solo per l'account dell'utente della chiave API o quando questo utente è un amministratore del gruppo.

GET /api/b2/memberships

Parametri

Esempio

curl -H 'Authorization: Bearer YOUR_API_KEY' 'https://www.loomio.com/api/b2/memberships?group_id=123'

Gestisci le iscrizioni

Invia un elenco di indirizzi email. Verrà inviato un invito al gruppo a tutti i nuovi indirizzi email. A differenza dell'elenco delle iscrizioni, questa operazione richiede i permessi di amministratore del gruppo.

POST /api/b2/memberships

Parametri

Esempio

curl -H 'Authorization: Bearer YOUR_API_KEY' -X POST -H 'Content-Type: application/json' -d '{"group_id": 123, "emails":["person@example.com"]}' https://www.loomio.com/api/b2/memberships

Se passi remove_absent=1, tutti i membri del gruppo non inclusi nell'elenco verranno rimossi dal gruppo. Fai attenzione: potresti rimuovere tutti i membri del tuo gruppo.

curl -H 'Authorization: Bearer YOUR_API_KEY' -X POST -H 'Content-Type: application/json' -d '{"group_id": 123, "emails":["person@example.com"], "remove_absent": 1}' https://www.loomio.com/api/b2/memberships

La risposta restituisce un oggetto con {added_emails: ["person@added.com"], removed_emails: ["person@removed.com"]}.