LoomioユーザーAPIのドキュメント

/api/b2 は、Loomioとの連携に使うユーザー向けAPIです。ユーザーアカウントのAPIキーを使用し、すべての操作はそのユーザーとして実行されます。

グループに対する操作には、APIキーのユーザーのメンバーシップとグループ権限が適用されます。インスタンス管理者であっても、APIキーでアクセスできるグループやコンテンツは増えません。インスタンス全体の管理にはサーバーAPIを使用してください。

操作を実行するLoomioユーザーアカウントのAPIキーを使用してください。連携用アカウントを投票に招待したり、そのアカウントに通知を送ったりしたくない場合は、専用のボットアカウントが役立ちます。

ログイン中のユーザーは、APIアクセスページでAPIキーとグループIDを確認できます。

APIキーは Authorization: Bearer ヘッダーで送信してください。URLはプロキシやアクセスログに記録される可能性があるため、クエリ文字列に含めたAPIキーは受け付けられません。

認証方法の変更

以前はURLパラメーター api_key でAPIキーを指定できました。現在、?api_key=YOUR_API_KEY を使ったリクエストは機能しません。代わりにHTTPの Authorization ヘッダーを使用してください。

Authorization: Bearer YOUR_API_KEY

例では YOUR_API_KEY、グループID 123、https://www.loomio.com/ を使用します。それぞれ実際のAPIキー、グループID、Loomioのインストール先URLに置き換えてください。

レスポンスのサイズと関連レコード

ユーザーAPIのレスポンスは複合形式です。主要なレコードに加え、トピック、グループ、ユーザー、投票、リアクションなどの関連レコードが含まれます。クライアントは1回のリクエストでローカルのレコードストアを構築できますが、単純な連携には不要なデータも含まれる場合があります。

compact=1 を指定すると、サイズの大きい関連レコードであるトピック、グループ、親グループ、メンバーシップ、リアクション、タグ、翻訳が省略されます。主要なレコードと、その内容を解釈するために必要な関連レコードは残ります。

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

省略する種類を直接指定するには、単数形のレコード種別をスペースで区切って exclude_types に渡します。たとえば exclude_types=group reaction は、関連するグループとリアクションを省略します。主な値は topic、group、parent、membership、reaction、tag、translation、user、discussion、poll、poll_option、stance、stance_choice、outcome、topic_item です。省略の対象は関連レコードであり、エンドポイントで要求した主要なリソースではありません。

正確な件数が定義されているコレクションのレスポンスには meta.total が含まれます。この件数は limit と offset を適用する前に計算されます。検索など、結果数に上限を設けているエンドポイントでは、null を返す代わりに meta.total を省略します。

エンドポイント一覧

グループ

グループの一覧表示

APIキーのユーザーが有効なメンバーシップを持つグループを返します。

GET /api/b2/groups

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

レスポンスには、条件に一致するすべてのレコードが、ページ分割されていない groups 配列に含まれます。現在サブスクリプションが有効でないグループも含め、親グループとサブグループが対象です。有効なグループだけを連携の対象にする場合は、enabled フィールドを確認してください。

主なグループのフィールドは次のとおりです。

レスポンスには、グループの追加設定、関連する親グループのレコード、APIユーザーのメンバーシップが含まれる場合があります。クライアントでは使用しないフィールドを無視してください。

グループの取得

APIキーのユーザーが閲覧できるグループを1件返します。

GET /api/b2/groups/:id_or_key_or_handle

識別子には、グループの数値ID、キー、ハンドルを指定できます。

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

レスポンスの groups 配列にグループが含まれ、一覧表示のエンドポイントと同じフィールドが使われます。APIキーのユーザーがアクセスできないグループを要求すると、権限エラーが返されます。

Webhook

ユーザーAPIはリクエスト方式です。連携システムがデータを読み取る、または変更するときにLoomioを呼び出します。グループのWebhookは逆方向の通知を担います。選択したグループのイベントが発生すると、Loomioが指定先のエンドポイントに送信するため、連携システムが変更を確認するためにREST APIを定期的に呼び出す必要はありません。

Webhookはグループごとに設定し、グループ管理者の権限が必要です。Loomioの画面から次の手順で管理できます。

1. グループを開きます。
2. グループメニューを開き、チャット連携を選択します。
3. 送信先のエンドポイントが受け付けるペイロード形式に合う連携を追加します。汎用のエンドポイントにはMattermost/Markdown形式を使用します。
4. 名前と送信先URLを入力します。
5. Loomioから自動送信するイベントを選択します。
6. 連携を保存し、テスト接続でテストメッセージを送信します。

推測されにくいURLを持つHTTPSの送信先を使用してください。Loomioは送信先が公開アドレスに解決されることを要求し、ローカルまたはプライベートネットワークのアドレスへのリクエストをブロックします。

エージェントやその他の連携システムは、以下で説明するBearer認証付きのチャットボット用エンドポイントからWebhookを管理することもできます。リソース名の chatbots はLoomioのチャット連携との互換性のために使われますが、一般的な送信Webhookも表します。

Webhookの一覧表示

グループに設定されているチャット連携を返します。APIキーのユーザーは、そのグループの管理者でなければなりません。レスポンスには送信先URLが含まれるため、一般のグループメンバーには公開しないでください。

GET /api/b2/chatbots?group_id=123

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

レスポンスには、次のフィールドを持つ chatbots 配列が含まれます。

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

API キーのユーザーは、group_id で指定したグループの管理者である必要があります。保存前に、送信先が公開 URL かどうか検証されます。

Webhook を更新する

PATCH /api/b2/chatbots/:id

変更するフィールドを送信します。group_id を変更しても、Webhook を別のグループに移すことはできません。

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

Webhook の送信先をテストする

設定の保存前または保存後に、Markdown に対応したテストメッセージを送信先へ送れます。

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

Webhook を削除する

DELETE /api/b2/chatbots/:id

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

設定を削除すると、以後の送信は停止します。Loomio のグループ内のコンテンツは削除されません。

イベントの種類

Webhook では、次の種類のイベントを受信対象にできます。

Webhook は 1 つのグループに属し、そのグループで受信対象に設定したイベントを受け取ります。対応する自動送信イベントが選択されていなくても、一部の通知を共有または送信するときに連携を明示的に選択できます。

HTTP による送信

Loomio は、次のヘッダーを付けた非同期の HTTP POST を設定済みの URL に送信します。

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

リクエストのタイムアウトは 5 秒です。204 No Content を含む 2xx 応答は成功として扱われます。Webhook の受信側は速やかに応答し、時間のかかる処理は非同期で行ってください。重複した送信や順序の前後にも対応してください。

現在、Loomio は Webhook の署名、共有シークレットのヘッダー、イベント ID、送信 ID を付けません。送信先 URL 全体を認証情報として扱い、公開しないでください。受信サービスが対応している場合は、推測されにくいトークンを URL に含めてください。安定した機械可読のイベント形式や署名付きの送信が必要な場合は、Webhook を変更通知として使い、認証済みのユーザー API から最新のレコードを取得してください。

ペイロード形式

Webhook のペイロードは、チャットサービス向けの表示用メッセージです。Loomio のレコード全体をシリアライズしたものではありません。メッセージ内のリンクは、対象となる Loomio のコンテンツを示します。構造化された最新の状態が必要な場合は、ユーザー API で取得できます。

たとえば、一般的な Markdown 形式では、次のような本文を送信します。

{
  "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"
}

メッセージの正確な文面は、イベント、グループの言語設定、通知のみの設定、Loomio のバージョンによって異なります。受信側では文章を解析せず、選択した形式で定義されている最上位のフィールドを使用してください。

検索

API キーのユーザーに表示できるディスカッション、コメント、投票、票、結論を検索します。グループのメンバーでなくても、公開コンテンツは結果に含まれます。非公開コンテンツには、通常のトピックの閲覧権限が適用されます。

GET /api/b2/search

パラメータ

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

応答には search_results 配列が含まれます。各結果には、一致したレコードと閲覧可能な関連情報を示す searchable_type、searchable_id、highlight、group_id、group_name、discussion_key、poll_key、author_id、author_name、authored_at、tags などのフィールドがあります。結果に該当しないフィールドは null になります。

参加レポート

Loomio の参加レポートと同じ集計データを返します。

GET /api/b2/reports

パラメータ

選択したグループのいずれかで有効な代表者メンバーシップを持つ人が、代表者です。活動件数は、選択したすべてのグループを通じて集計されます。すべての活動件数がゼロでも、代表者の行は返されます。件数にはスレッド、コメント、投票、票、結論、リアクションが含まれますが、投票参加率ではありません。ユーザーの行には、記名投票で割り当てられた投票機会、投じられた票、投じられなかった票の数も含まれます。匿名投票は、個人ごとの投票件数からすべて除外されます。all_votes_cast が true になるのは、少なくとも 1 件の投票機会が割り当てられ、そのすべてで票が投じられた場合だけです。

この API には、Loomio 内のレポートと同じグループ閲覧ルールが適用されます。ユーザー API キーでは、そのユーザーがアクセスできないグループのレポートデータは取得できません。

例

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'

users 配列には、活動データの各項目を含む行が入ります。

{
  "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
    }
  ]
}

ディスカッションを作成する

APIキーのユーザーとしてディスカッションを作成します。

POST /api/b2/discussions

パラメータ

例

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

ディスカッションを取得する

整数のディスカッションID、または文字列のキーを指定して、ディスカッションを取得します。

GET /api/b2/discussions/:id

例

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

ディスカッションの一覧を取得する

グループ内でAPIキーのユーザーに表示されるディスカッションの一覧を取得します。公開グループでは、メンバー以外も公開ディスカッションの一覧を取得できます。非公開ディスカッションは、Loomioで閲覧権限のあるユーザーにのみ表示されます。

GET /api/b2/discussions

パラメータ

従来の指定方法: per と from は、それぞれ limit と offset の別名として引き続き使用できます。

例

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

スレッドの一覧を取得する

APIキーのユーザーに表示されるディスカッションと投票のスレッドを、最近のアクティビティ順に取得します。スレッドIDは topic_id です。

GET /api/b2/threads

パラメータ

例

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

スレッドを読む

スレッド、時系列に並んだイベント、または表示可能な内容をまとめたMarkdown文書を取得します。

GET /api/b2/threads/:topic_id

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

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

例

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

items エンドポイントは、表示可能なコメント、投票、投票内容、結論を含むイベントを時系列順に返します。markdown エンドポイントは、表示可能なスレッド全体を1つのMarkdown文書として返します。投票理由は、APIキーのユーザーに表示される場合にのみ含まれます。

すべてのスレッドエンドポイントには、Loomioの画面と同じ権限が適用されます。APIキーを使っても、通常は開けないスレッドにはアクセスできません。

ディスカッションを編集する

APIキーのユーザーとしてディスカッションを編集します。Loomioと同じ権限が適用され、そのディスカッションの編集権限が必要です。

PATCH /api/b2/discussions/:id

パラメータ

例

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

ディスカッションをソフト削除する

APIキーのユーザーとしてディスカッションをソフト削除します。ディスカッションは削除済みとして扱われますが、レコードは残ります。

DELETE /api/b2/discussions/:id

例

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

コメントを作成する

APIキーのユーザーとしてディスカッションにコメントを作成します。

POST /api/b2/comments

パラメータ

例

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

コメントを編集する

APIキーのユーザーとしてコメントを編集します。Loomioと同じ権限が適用され、そのコメントの編集権限が必要です。

PATCH /api/b2/comments/:id

パラメータ

例

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

コメントをソフト削除する

APIキーのユーザーとしてコメントをソフト削除します。コメントは削除済みとして扱われ、本文は非表示になりますが、レコードは残ります。

DELETE /api/b2/comments/:id

例

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

投票を作成する

API キーのユーザーとして投票を作成します。

POST /api/b2/polls

パラメータ

例

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

投票を取得する

整数の投票 ID または文字列のキーを使って投票を取得します。

GET /api/b2/polls/:id

例

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

投票の一覧を取得する

グループ内で API キーのユーザーに表示できる投票を一覧表示します。公開グループでは、メンバー以外も公開投票を一覧表示できます。非公開の投票は、Loomio で閲覧権限があるユーザーに限られます。レスポンスには表示可能な各投票の現在の結論も含まれます。status=closed を使うと、決定済みの提案を一覧表示できます。

GET /api/b2/polls

パラメータ

従来の指定方法: per と from は、それぞれ limit と offset の別名として引き続き使用できます。

例

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

投票を編集する

API キーのユーザーとして投票を編集します。Loomio と同じ権限が適用され、その投票の編集権限が必要です。

PATCH /api/b2/polls/:id

パラメータ

例

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

投票を論理削除する

API キーのユーザーとして投票を論理削除します。投票は破棄されますが、レコードは残ります。

DELETE /api/b2/polls/:id

例

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

メンバーシップの一覧を取得する

API キーのユーザーに表示できるメンバーシップを一覧表示します。グループのメンバーは、メンバーの名前、ID、肩書き、役割を閲覧できます。メールアドレスが含まれるのは、API キーのユーザー自身のアカウントか、そのユーザーがグループ管理者の場合だけです。

GET /api/b2/memberships

パラメータ

例

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

メンバーシップを管理する

メールアドレスの一覧を送信すると、新しいメールアドレスの人をグループに招待します。メンバーシップの一覧取得とは異なり、この操作にはグループ管理者の権限が必要です。

POST /api/b2/memberships

パラメータ

例

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

remove_absent=1 を指定すると、一覧に含まれないグループのメンバーが削除されます。グループの全員が削除される可能性があるため、注意してください。

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

レスポンスは {added_emails: ["person@added.com"], removed_emails: ["person@removed.com"]} を含むオブジェクトです。