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から連携システムへデータを送信できます。選択したグループのイベントが発生すると、Loomioが指定のエンドポイントに送信するため、連携システムが変更を確認するためにREST APIを繰り返し呼び出す必要はありません。

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

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

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

エージェントやその他の連携システムでは、代わりに、以下で説明するBearer認証のチャットボットエンドポイントを通じてWebhookを管理できます。このリソースは、Loomioのチャット連携との互換性のためにchatbotsという名前になっていますが、一般的な送信用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は、次のヘッダーを付けて、設定されたURLに非同期のHTTP POSTを送信します。

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には、アプリ内のレポートと同じグループの閲覧権限が適用されます。ユーザー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キーのユーザー自身のアカウントの場合、または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"]}を含むオブジェクトを返します。