Documentazione dell'API utente di Loomio

/api/b2 è l'API utente per le integrazioni con Loomio. Usa la chiave API di un account utente ed esegue ogni azione a nome di quell'utente.

Le operazioni sui gruppi rispettano le partecipazioni e i permessi dell'utente a cui appartiene la chiave API. Il ruolo di amministratore dell'istanza non amplia l'accesso della chiave API ai gruppi o ai contenuti; per amministrare l'istanza, usa la Server API.

Usa la chiave API dell'account Loomio che eseguirà le azioni. Un account bot dedicato è utile se l'integrazione non deve ricevere inviti ai sondaggi o notifiche.

Se hai effettuato l'accesso, trovi la tua chiave API e gli ID dei gruppi nella pagina di accesso API.

Invia la chiave API nell'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 poteva essere passata 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 di gruppo 123 e https://www.loomio.com/. Sostituiscili con la tua chiave API, l'ID del gruppo e l'URL della tua installazione di Loomio.

Dimensioni delle risposte e record correlati

Le risposte dell'API utente hanno un formato composito: 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 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 più voluminosi: topic, gruppi, gruppi principali, partecipazioni, reazioni, tag e traduzioni. I record principali e quelli 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 controllare direttamente le esclusioni, passa exclude_types con i tipi di record al singolare separati da spazi. Per 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 che contengono raccolte includono meta.total quando è definita la dimensione esatta della raccolta. Il totale viene calcolato prima di applicare limit e offset. Gli endpoint come la ricerca, che restituiscono intenzionalmente un insieme limitato di risultati, omettono meta.total invece di restituire null.

Riepilogo degli endpoint

Gruppi

Elencare i gruppi

Restituisce i gruppi di cui l'utente a cui appartiene la chiave API è membro attivo.

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 se il loro abbonamento non è attualmente attivo. Controlla il campo enabled se l'integrazione deve operare solo sui gruppi abilitati.

I principali campi dei gruppi sono:

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

Recuperare un gruppo

Restituisce un gruppo visibile all'utente a cui appartiene la chiave API.

GET /api/b2/groups/:id_or_key_or_handle

Puoi identificare il gruppo tramite il suo ID numerico, la chiave o l'identificativo.

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 a cui appartiene la chiave API non può accedere restituisce un errore di autorizzazione.

Webhook

L'API utente funziona tramite richieste: un'integrazione chiama Loomio quando vuole leggere o modificare dati. Un webhook di gruppo consente il flusso nella direzione opposta. Loomio invia al tuo endpoint gli eventi del gruppo selezionati quando si verificano, quindi l'integrazione non deve interrogare periodicamente l'API REST per rilevare le modifiche.

I webhook si configurano per singolo gruppo e richiedono i permessi di amministratore del gruppo. Puoi gestirli dall'interfaccia di Loomio:

1. Apri il gruppo.
2. Apri il menu del gruppo e seleziona Integrazioni di chat.
3. Aggiungi l'integrazione con il 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 difficile da indovinare. Loomio richiede che la destinazione corrisponda a un indirizzo pubblico e blocca le richieste verso indirizzi di reti locali o private.

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

Elencare i webhook

Restituisce le integrazioni di chat configurate per un gruppo. L'utente a cui appartiene la chiave API deve essere amministratore di quel gruppo. La risposta include gli URL di destinazione, quindi non deve essere resa accessibile ai normali membri 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:

Creare 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 a cui appartiene la chiave API deve essere amministratore di group_id. Prima del salvataggio, Loomio verifica che la destinazione sia un URL pubblico.

Aggiornare un webhook

PATCH /api/b2/chatbots/:id

Invia 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

Verificare la destinazione di un webhook

Invia un messaggio di prova compatibile con Markdown alla 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

Eliminare un webhook

DELETE /api/b2/chatbots/:id

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

Eliminando la configurazione interrompi gli invii futuri. I contenuti del gruppo Loomio restano disponibili.

Tipi di evento

Un webhook può ricevere questi tipi di evento:

Il webhook appartiene a un solo 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 se 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, incluso 204 No Content, è considerata riuscita. Il servizio che riceve il webhook dovrebbe rispondere rapidamente, elaborare in modo asincrono le operazioni più lunghe e gestire invii duplicati o fuori ordine.

Attualmente Loomio non aggiunge una firma del webhook, un'intestazione con un segreto condiviso, un ID evento o un ID invio. Tratta l'URL completo di destinazione come una credenziale: non renderlo pubblico e includi nell'URL un token difficile da indovinare se 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 delle modifiche e recupera i dati aggiornati tramite l'API utente autenticata.

Formati dei payload

I payload dei webhook sono messaggi pensati per essere mostrati nei servizi di chat. Non contengono tutti i dati dei record Loomio. I link nel messaggio identificano i contenuti Loomio interessati; un'integrazione può usare l'API utente per ottenere i dati strutturati aggiornati.

Per esempio, il formato Markdown generico invia un corpo di questo tipo:

{
  "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, dalla lingua del gruppo, dall'impostazione che limita il messaggio alla notifica e dalla versione di Loomio. I servizi riceventi dovrebbero usare i campi principali documentati per il formato selezionato, senza interpretare il testo delle frasi.

Ricerca

Cerca discussioni, commenti, sondaggi, voti e conclusioni visibili all'utente a cui appartiene la chiave API. I risultati includono contenuti pubblici anche se l'utente non è membro del gruppo; i contenuti privati seguono le normali regole di visibilità dell'argomento.

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 trovato e il suo contesto visibile tramite campi tra cui searchable_type, searchable_id, highlight, group_id, group_name, discussion_key, poll_key, author_id, author_name, authored_at e tags. I campi non pertinenti a un risultato hanno valore null.

Report sulla partecipazione

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

GET /api/b2/reports

Parametri

Una persona è delegata se ha un'adesione attiva come delegata in almeno uno dei gruppi selezionati. I suoi conteggi sono aggregati per tutti i gruppi selezionati. Le righe dei delegati vengono restituite anche quando tutti i conteggi delle attività sono pari a zero. I conteggi riguardano discussioni, commenti, sondaggi, voti, conclusioni e reazioni; non sono tassi di partecipazione al voto. Le righe degli utenti includono anche il numero di schede di voto nominative assegnate, compilate e non compilate. I sondaggi anonimi sono esclusi da tutti i conteggi dei voti per persona. all_votes_cast è true solo se è 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 in Loomio. La chiave API di un utente non può esporre i dati dei report relativi a gruppi a cui quell'utente non ha accesso.

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 con tutti i dati delle 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
    }
  ]
}

Creare una discussione

Crea una discussione usando l'account associato alla 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

Visualizzare una discussione

Recupera una discussione tramite il suo ID numerico o la sua chiave testuale.

GET /api/b2/discussions/:id

Esempio

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

Elencare le discussioni

Elenca le discussioni di un gruppo visibili all'utente associato alla chiave API. Se il gruppo è visibile pubblicamente, anche chi non ne fa parte può elencare le sue discussioni pubbliche. Le discussioni private restano accessibili solo agli utenti che possono leggerle in Loomio.

GET /api/b2/discussions

Parametri

Per compatibilità, 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'

Elencare i thread

Elenca i thread delle discussioni e dei sondaggi visibili all'utente associato alla chiave API, ordinati per attività più recente. L'ID di un thread è 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'

Leggere un thread

Leggi un thread, la sua sequenza ordinata di eventi o il documento Markdown completo dei 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 degli eventi, inclusi commenti, sondaggi, voti e conclusioni visibili. L'endpoint markdown restituisce l'intero thread visibile come un unico documento Markdown. Le motivazioni dei voti sono incluse solo se sono visibili all'utente associato alla chiave API.

Tutti gli endpoint dei thread applicano gli stessi permessi dell'interfaccia di Loomio. La chiave API non consente di accedere a un thread che l'utente normalmente non può aprire.

Modificare una discussione

Modifica una discussione usando l'account associato alla chiave API. Si applicano gli stessi permessi di Loomio: l'utente deve essere autorizzato a modificare la 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

Eliminare una discussione senza rimuoverne il record

Elimina una discussione usando l'account associato alla chiave API. La discussione viene scartata, 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

Creare un commento

Crea un commento in una discussione usando l'account associato alla 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

Modificare un commento

Modifica un commento usando l'account associato alla chiave API. Si applicano gli stessi permessi di Loomio: l'utente deve essere autorizzato a modificare il 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

Eliminare un commento senza rimuoverne il record

Elimina un commento usando l'account associato alla chiave API. Il commento viene scartato e il suo testo nascosto, ma il 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 usando l'account associato alla 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

Visualizza un sondaggio

Recupera un sondaggio tramite il suo ID numerico o la sua chiave, che è 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 associato alla chiave API. Se il gruppo è visibile pubblicamente, anche chi non ne è membro può elencare i sondaggi pubblici. I sondaggi privati restano accessibili solo a chi può leggerli in Loomio. La risposta include la conclusione corrente di ogni sondaggio visibile: puoi quindi usare status=closed per elencare le proposte su cui è stata presa una decisione.

GET /api/b2/polls

Parametri

Per compatibilità, 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 usando l'account associato alla chiave API. Si applicano gli stessi permessi di Loomio: devi poter 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 un sondaggio senza cancellarne il record

Elimina un sondaggio usando l'account associato alla chiave API. Il sondaggio viene scartato, ma il suo record resta nel sistema.

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 associato alla chiave API. I membri del gruppo possono leggere nomi, ID, titoli e ruoli degli altri membri. Gli indirizzi email sono inclusi solo per l'account associato alla chiave API o se quell'utente è 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. I nuovi indirizzi riceveranno un invito a unirsi al gruppo. 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 saranno rimossi. 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 è un oggetto con {added_emails: ["person@added.com"], removed_emails: ["person@removed.com"]}.