תיעוד ה־API למשתמש של Loomio

/api/b2 הוא ה־API למשתמש עבור אינטגרציות עם Loomio. הוא משתמש במפתח ה־API של חשבון משתמש, וכל פעולה מתבצעת בשם החשבון הזה.

פעולות בקבוצות כפופות לחברויות ולהרשאות הקבוצה של החשבון שמפתח ה־API שייך לו. הרשאת ניהול של המערכת אינה מרחיבה את הגישה של מפתח ה־API לקבוצות או לתוכן. לניהול ברמת המערכת יש להשתמש ב־Server API.

יש להשתמש במפתח ה־API של חשבון Loomio שיבצע את הפעולות. חשבון בוט ייעודי מועיל כאשר אין צורך להזמין את האינטגרציה להשתתף במשאלים או לשלוח לה התראות.

לאחר כניסה לחשבון, ניתן למצוא את מפתח ה־API ואת מזהי הקבוצות בדף הגישה ל־API.

יש לשלוח את מפתח ה־API בכותרת Authorization: Bearer. מפתחות API שנשלחים בפרמטרים של כתובת URL נדחים, משום ששרתי תיווך ויומני גישה עשויים לתעד כתובות URL.

שינוי באופן האימות

בעבר ניתן היה לשלוח את מפתח ה־API בפרמטר הכתובת api_key. בקשות שמשתמשות ב־?api_key=YOUR_API_KEY אינן פועלות עוד. יש להשתמש בכותרת HTTP ‏Authorization במקום זאת:

Authorization: Bearer YOUR_API_KEY

בדוגמאות נעשה שימוש ב־YOUR_API_KEY, במזהה הקבוצה 123 ובכתובת https://www.loomio.com/. יש להחליף אותם במפתח ה־API, במזהה הקבוצה ובכתובת ההתקנה של Loomio.

תגובות ה־API למשתמש משתמשות במבנה משולב: לצד הרשומות הראשיות נשלחות רשומות קשורות, כגון נושאים, קבוצות, משתמשים, משאלים ותגובות רגשיות. כך אפשר למלא מאגר רשומות מקומי בבקשה אחת, אך התגובה עשויה להכיל יותר נתונים מהנדרש לאינטגרציה פשוטה.

ניתן להעביר 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. נקודות קצה כגון חיפוש, שמחזירות בכוונה מספר מוגבל של תוצאות, משמיטות את meta.total במקום להחזיר null.

סיכום נקודות הקצה

שיטה נקודת קצה מטרה
GET /api/b2/groups הצגת הקבוצות של החשבון שמפתח ה־API שייך לו
GET /api/b2/groups/:id_or_key_or_handle קבלת קבוצה שניתן לצפות בה
GET /api/b2/reports הפקת דוח השתתפות
GET /api/b2/search חיפוש בדיונים, בתגובות, במשאלים, בהצבעות ובמסקנות שניתן לצפות בהם
POST /api/b2/discussions יצירת דיון
GET /api/b2/discussions/:id קבלת דיון
GET /api/b2/discussions הצגת דיונים בקבוצה
PATCH /api/b2/discussions/:id עריכת דיון
DELETE /api/b2/discussions/:id מחיקה רכה של דיון
GET /api/b2/threads הצגת שרשורים של דיונים ושל משאלים עצמאיים שניתן לצפות בהם
GET /api/b2/threads/:topic_id קבלת שרשור
GET /api/b2/threads/:topic_id/items קבלת הפריטים בשרשור לפי סדרם
GET /api/b2/threads/:topic_id/markdown קבלת שרשור מלא בפורמט Markdown
POST /api/b2/comments יצירת תגובה או מענה
PATCH /api/b2/comments/:id עריכת תגובה
DELETE /api/b2/comments/:id מחיקה רכה של תגובה
POST /api/b2/polls יצירת משאל
GET /api/b2/polls/:id קבלת משאל
GET /api/b2/polls הצגת משאלים בקבוצה
PATCH /api/b2/polls/:id עריכת משאל
DELETE /api/b2/polls/:id מחיקה רכה של משאל
GET /api/b2/memberships הצגת החברויות בקבוצה
POST /api/b2/memberships הוספת חברים, ואפשרות להסיר חברים שאינם ברשימה
GET /api/b2/chatbots הצגת אינטגרציות הצ'אט וה־webhooks של קבוצה
POST /api/b2/chatbots יצירת אינטגרציית צ'אט או webhook
PATCH /api/b2/chatbots/:id עדכון אינטגרציית צ'אט או webhook
DELETE /api/b2/chatbots/:id מחיקת אינטגרציית צ'אט או webhook
POST /api/b2/chatbots/check שליחת בדיקת חיבור ל־webhook

קבוצות

הצגת קבוצות

מחזיר את הקבוצות שבהן לחשבון שמפתח ה־API שייך לו יש חברות פעילה.

GET /api/b2/groups

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

התגובה מכילה את כל הרשומות המתאימות במערך groups, ללא חלוקה לעמודים. היא כוללת קבוצות הורה ותת־קבוצות, גם כאשר המינוי שלהן אינו פעיל כרגע. כאשר האינטגרציה אמורה לפעול רק בקבוצות פעילות, יש לבדוק את השדה enabled.

שדות חשובים של קבוצה:

שדה תיאור
id מזהה מספרי של הקבוצה, המשמש בנקודות קצה אחרות של ה־API למשתמש
key מפתח קצר וקבוע המשמש בכתובות URL של Loomio
handle מזהה קריא של הקבוצה
name שם הקבוצה
full_name שם הקבוצה, כולל ההקשר של קבוצת ההורה שלה
parent_id המזהה המספרי של קבוצת ההורה של תת־קבוצה, או null אם אין קבוצת הורה
enabled האם הקבוצה והמינוי שלה פעילים
memberships_count מספר החברויות הפעילות והממתינות
accepted_memberships_count מספר החברויות שאושרו
pending_memberships_count מספר ההזמנות הממתינות
admin_memberships_count מספר מנהלי הקבוצה
delegates_count מספר הנציגים
discussions_count מספר הדיונים ישירות בקבוצה
polls_count מספר המשאלים ישירות בקבוצה
subgroups_count מספר תת־הקבוצות

התגובה עשויה לכלול הגדרות קבוצה נוספות, רשומות קשורות של קבוצת ההורה וחברויות של חשבון ה־API. על תוכנות המשתמשות ב־API להתעלם משדות שאינן משתמשות בהם.

קבלת קבוצה

מחזיר קבוצה אחת שהחשבון שמפתח ה־API שייך לו יכול לצפות בה.

GET /api/b2/groups/:id_or_key_or_handle

המזהה יכול להיות המזהה המספרי של הקבוצה, המפתח שלה או המזהה הקריא שלה.

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 שייך לו גישה אליה מחזירה שגיאת הרשאה.

Webhooks

ה־API למשתמש מבוסס על בקשות: אינטגרציה פונה ל־Loomio כאשר היא צריכה לקרוא או לשנות נתונים. Webhook של קבוצה מאפשר לשלוח עדכונים בכיוון ההפוך. Loomio שולח אירועים נבחרים מהקבוצה לנקודת הקצה של האינטגרציה כשהם מתרחשים, כך שאין צורך לבדוק שוב ושוב אם חלו שינויים ב־REST API.

Webhooks מוגדרים לכל קבוצה בנפרד ודורשים הרשאת ניהול בקבוצה. ניתן לנהל אותם דרך הממשק של Loomio:

  1. יש לפתוח את הקבוצה.
  2. יש לפתוח את תפריט הקבוצה ולבחור אינטגרציות צ'אט.
  3. יש להוסיף אינטגרציה שמתאימה לפורמט הנתונים שנקודת הקצה מקבלת. לנקודת קצה כללית, יש להשתמש בפורמט Mattermost/Markdown.
  4. יש להזין שם ואת כתובת ה־URL של היעד.
  5. יש לבחור את האירועים ש־Loomio ישלח אוטומטית.
  6. יש לשמור את האינטגרציה ולהשתמש ב־בדיקת חיבור כדי לשלוח הודעת בדיקה.

יש להשתמש ביעד HTTPS עם כתובת URL שקשה לנחש. Loomio דורש שכתובת היעד תפנה לכתובת ציבורית וחוסם בקשות לכתובות ברשת מקומית או פרטית.

אפשר לנהל webhooks גם באמצעות סוכנים ואינטגרציות אחרות, דרך נקודות הקצה של צ'אטבוטים המאומתות באמצעות Bearer ומתוארות בהמשך. המשאב נקרא chatbots כדי לשמור על תאימות לאינטגרציות הצ'אט של Loomio, והוא משמש גם ל-webhooks יוצאים כלליים.

הצגת webhooks

מחזיר את אינטגרציות הצ'אט שהוגדרו לקבוצה. נדרשת הרשאת ניהול בקבוצה עבור החשבון שמפתח ה־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 עם השדות הבאים:

שדה תיאור
id מזהה האינטגרציה המשמש לעדכון ולמחיקה
group_id הקבוצה שממנה מתקבלים האירועים
name השם של האינטגרציה לצורכי ניהול
kind webhook עבור webhook יוצא או matrix עבור אינטגרציית Matrix
webhook_kind פורמט הנתונים: markdown, slack, discord, microsoft או webex
server כתובת ה-URL של היעד
event_kinds אירועים שנשלחים אוטומטית
notification_only האם ההודעות כוללות רק את כותרת ההתראה

יצירת 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 לסוגי האירועים הבאים:

אירוע מתי הוא נשלח
new_discussion נפתח דיון
discussion_edited דיון נערך
new_comment נוצרה תגובה
poll_created נפתח משאל
poll_edited משאל נערך
poll_closing_soon מועד סגירת המשאל מתקרב
poll_expired הגיע מועד סגירת המשאל
poll_closed_by_user המשאל נסגר ידנית
poll_reopened המשאל נפתח מחדש
outcome_created פורסמה מסקנה
outcome_updated מסקנה עודכנה
outcome_review_due הגיע המועד לבדיקת מסקנה
stance_created הוצבעה הצבעה
stance_updated הצבעה שונתה

ה-webhook שייך לקבוצה אחת ומקבל ממנה את האירועים שנבחרו. ניתן גם לבחור במפורש באינטגרציה בעת שיתוף או שליחה של התראות מסוימות, גם אם האירוע האוטומטי המתאים לא נבחר.

משלוח באמצעות HTTP

Loomio שולחת בקשת HTTP מסוג POST באופן אסינכרוני לכתובת ה-URL שהוגדרה, עם הכותרת הבאה:

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

זמן ההמתנה המרבי לבקשה הוא חמש שניות. תגובת 2xx, כולל 204 No Content, נחשבת להצלחה. שירותים שמקבלים הודעות webhook צריכים להשיב במהירות, לעבד פעולות ממושכות באופן אסינכרוני ולהתמודד עם משלוחים כפולים או משלוחים שמגיעים בסדר שונה.

Loomio אינה מוסיפה כיום חתימת webhook, כותרת עם סוד משותף, מזהה אירוע או מזהה משלוח. יש להתייחס לכתובת ה-URL המלאה של היעד כאל פרט גישה, להימנע מחשיפתה לציבור ולכלול בה אסימון שקשה לנחש אם השירות המקבל תומך בכך. אם נדרשים מבנה אירועים יציב לקריאה ממוחשבת או משלוחים חתומים, ניתן להשתמש ב-webhook כהודעה על שינוי ולאחזר את הרשומות העדכניות דרך ממשק ה-API למשתמשים עם אימות.

פורמטים של הנתונים הנשלחים

הנתונים שנשלחים ב-webhook הם הודעות המיועדות להצגה בשירותי צ'אט. הם אינם רשומות Loomio מלאות בפורמט סדור. הקישורים בהודעה מזהים את התוכן שהושפע ב-Loomio; כשנדרש המצב העדכני במבנה נתונים, ניתן לאחזר אותו דרך ממשק ה-API למשתמשים.

פורמט האינטגרציה שדות JSON עיקריים
Mattermost/Markdown text, icon_url, username
Slack text
Discord content, מוגבל לכ-1,900 תווים
Microsoft Teams @type, @context, themeColor, text, sections
Webex markdown

לדוגמה, הפורמט הכללי של 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

פרמטרים

שם תיאור
query טקסט לחיפוש. נתמכות התאמות מדויקות ומקורבות
group_id הגבלת התוצאות לקבוצה גלויה אחת
org_id הגבלת התוצאות לקבוצת אם גלויה ולתתי-הקבוצות הגלויות שלה. עבור דיונים ישירים יש להשתמש ב-0
type הגבלת התוצאות לסוג אחד: Discussion, Comment, Poll, Stance או Outcome
types רשימת סוגי תוצאות מופרדת בפסיקים
tag הגבלת התוצאות לנושאים עם התג הזה
author_id הגבלת התוצאות לתוכן של מחבר או מחברת מסוימים. ללא query, מוחזרת הפעילות הגלויה האחרונה של אותו חשבון
order יש להגדיר authored_at_desc כדי לסדר תוכן תואם לפי זמן היצירה 
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

פרמטרים

שם תיאור
section חלק בדוח: base, users או countries. עבור פעילות של כל אדם בנפרד יש להשתמש ב-users
group_scope custom או my. הערך הישן all מטופל כמו my, כי מפתחות API למשתמשים אינם מקנים גישה לכל המערכת
group_ids מזהי קבוצות מופרדים בפסיקים כאשר group_scope=custom. מזהים של קבוצות שחשבון ה-API אינו חבר בהן אינם נכללים
start_month החודש הראשון שייכלל בפורמט YYYY-MM; ברירת המחדל היא לפני 12 חודשים
end_month החודש האחרון שייכלל בפורמט YYYY-MM; ברירת המחדל היא החודש הנוכחי
interval מרווח הזמן עבור החלק base: day, week, month או year
member_type כדי להחזיר רק נציגים ונציגות נוכחיים, יש להגדיר delegate יחד עם section=users

אדם נחשב לנציג או לנציגה כאשר יש לו חברות פעילה בתפקיד זה באחת הקבוצות שנבחרו. הספירות מצטברות מכל הקבוצות שנבחרו. שורות של נציגים ונציגות מוחזרות גם כשכל ספירות הפעילות הן אפס. הספירות כוללות שרשורים, תגובות, משאלים, הצבעות, מסקנות ותגובות רגשיות; הן אינן שיעורי השתתפות בהצבעה. שורות המשתמשים כוללות גם פתקי הצבעה מזוהים שהונפקו, שמולאו ושלא מולאו. משאלים אנונימיים אינם נכללים באף ספירת הצבעה אישית. הערך של all_votes_cast הוא true רק אם הונפק לפחות פתק הצבעה אחד וכל הפתקים שהונפקו מולאו.

ממשק ה-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

פרמטרים

שם תיאור
group_id הקבוצה שבה השרשור יופיע
title כותרת השרשור, שדה חובה
description רקע לשרשור, שדה רשות
description_format md או html, שדה רשות. ברירת המחדל היא md
recipient_audience group או null. אם הערך הוא group, תישלח הודעה לכל הקבוצה על השרשור החדש
recipient_user_ids מערך מזהי משתמשים שיש לשלוח להם הודעה או להזמין אותם לשרשור
recipient_emails מערך כתובות דוא״ל של אנשים שיש להזמין לשרשור
recipient_message הודעה שתיכלל בהזמנה בדוא״ל

דוגמה

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

הצגת דיון

אחזור דיון לפי מזהה מספרי או לפי מפתח שהוא מחרוזת.

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

פרמטרים

שם תיאור
group_id מספר שלם, שדה חובה. מזהה הקבוצה שאת הדיונים שלה יש להציג
status מחרוזת, שדה רשות. ברירת המחדל היא open. ערכים אפשריים: open, closed, all
limit מספר שלם, שדה רשות. ברירת המחדל היא 50. גודל העמוד
offset מספר שלם, שדה רשות. ברירת המחדל היא 0. נקודת ההתחלה של העימוד

תאימות לאחור: per ו־from מתקבלים כשמות חלופיים ל־limit ול־offset, וימשיכו לפעול.

דוגמה

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

רשימת שרשורים

הצגת שרשורי הדיונים והסקרים שגלויים לחשבון המשויך למפתח ה־API, לפי מועד הפעילות האחרונה. מזהה השרשור הוא ה־topic_id שלו.

GET /api/b2/threads

פרמטרים

שם תיאור
limit מספר שלם, שדה רשות. ברירת המחדל היא 50. גודל העמוד
offset מספר שלם, שדה רשות. ברירת המחדל היא 0. נקודת ההתחלה של העימוד

דוגמה

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 מחזירה את כל התוכן הגלוי בשרשור כמסמך Markdown אחד. נימוקי הצבעה נכללים רק אם הם גלויים לחשבון המשויך למפתח ה־API.

כל נקודות הקצה של שרשורים אוכפות את אותן הרשאות שחלות בממשק Loomio. מפתח ה־API אינו מעניק גישה לשרשור שאי אפשר לפתוח באמצעות החשבון כרגיל.

עריכת דיון

עריכת דיון בשם החשבון המשויך למפתח ה־API. חלות אותן הרשאות כמו ב־Loomio: לחשבון חייבת להיות הרשאה לערוך את הדיון.

PATCH /api/b2/discussions/:id

פרמטרים

שם תיאור
title כותרת מעודכנת
description רקע מעודכן
description_format md או html, שדה רשות. ברירת המחדל היא md
recipient_audience group או null. אם הערך הוא group, תישלח הודעה לכל הקבוצה על העריכה
recipient_user_ids מערך מזהי משתמשים שיש לשלוח להם הודעה או להזמין אותם לשרשור
recipient_emails מערך כתובות דוא״ל של אנשים שיש להזמין לשרשור
recipient_message הודעה שתיכלל בהזמנה בדוא״ל

דוגמה

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

פרמטרים

שם תיאור
discussion_id מספר שלם, שדה חובה. מזהה הדיון שבו תפורסם התגובה
body תוכן התגובה, שדה חובה אלא אם צורף קובץ
body_format md או html, שדה רשות. ברירת המחדל היא md

דוגמה

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

פרמטרים

שם תיאור
body תוכן התגובה המעודכן
body_format md או html, שדה רשות. ברירת המחדל היא md

דוגמה

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

פרמטרים

שם תיאור
group_id מספר שלם, לא חובה, ברירת המחדל היא null. מזהה הקבוצה של המשאל. אם נשלח discussion_id, המערכת מתעלמת מ-group_id
discussion_id מספר שלם, לא חובה, ברירת המחדל היא null. מזהה שרשור הדיון שאליו יתווסף המשאל
title מחרוזת, חובה. כותרת המשאל
poll_type מחרוזת, חובה. ערכים: proposal, poll, count, score, ranked_choice, meeting, dot_vote
details מחרוזת, לא חובה. תוכן המשאל
details_format מחרוזת, לא חובה, ברירת המחדל היא md. ערכים: md או html
options מערך מחרוזות. אם poll_type הוא proposal, הערכים התקינים הם agree, disagree, abstain, block. אם poll_type הוא meeting, יש לספק תאריך או תאריך ושעה בפורמט ISO 8601. בכל סוגי המשאל האחרים, כל מחרוזת תקינה
closing_at מחרוזת בפורמט ISO 8601 או null, ברירת המחדל היא null. לדוגמה: 2026-09-01T12:00:00Z. אם הערך הוא null, ההצבעה מושבתת והמשאל נחשב לטיוטה
specified_voters_only ערך בוליאני, לא חובה, ברירת המחדל היא false. אם הערך הוא true, רק אנשים שצוינו יכולים להצביע. אם הערך הוא false, כל חברי הקבוצה יוזמנו להצביע
hide_results מחרוזת, לא חובה, ברירת המחדל היא off. ערכים: off, until_vote, until_closed
shuffle_options ערך בוליאני, ברירת המחדל היא false. הצגת האפשרויות למצביעים בסדר אקראי
anonymous ערך בוליאני, לא חובה, ברירת המחדל היא false. הסתרת זהות המצביעים
recipient_audience group או null, לא חובה, ברירת המחדל היא null. אם הערך הוא group, כל הקבוצה תקבל הודעה
notify_on_closing_soon מחרוזת, לא חובה, ברירת המחדל היא nobody. ערכים: nobody, author, undecided_voters, voters
recipient_user_ids מערך מזהי משתמשים שיש להודיע להם או להזמין אותם
recipient_emails מערך כתובות דוא״ל של אנשים שיש להזמין להצביע
recipient_message הודעה שתיכלל בהזמנה בדוא״ל
notify_recipients ערך בוליאני, ברירת המחדל היא false. אם הערך הוא false, אנשים יתווספו בלי לשלוח הודעות. אם הערך הוא true, כל מי שיוזמן בבקשה זו יקבל הודעה בדוא״ל

דוגמה

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

הצגת משאל

אחזור משאל לפי מזהה מספרי או לפי מפתח שהוא מחרוזת.

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

פרמטרים

שם תיאור
group_id מספר שלם, חובה. מזהה הקבוצה שאת המשאלים שלה יש להציג
status מחרוזת, לא חובה, ברירת המחדל היא active. ערכים: active, closed, all
limit מספר שלם, לא חובה, ברירת המחדל היא 50. גודל הדף
offset מספר שלם, לא חובה, ברירת המחדל היא 0. היסט לחלוקה לדפים

תאימות לאחור: 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

פרמטרים

שם תיאור
title כותרת מעודכנת
details פרטי משאל מעודכנים
details_format md או html, לא חובה, ברירת המחדל היא md
options שמות מעודכנים של האפשרויות. שינוי האפשרויות עשוי להשפיע על הצבעות קיימות, בהתאם למצב המשאל
closing_at מחרוזת בפורמט ISO 8601 או null
recipient_audience group או null. אם הערך הוא group, כל הקבוצה תקבל הודעה
recipient_user_ids מערך מזהי משתמשים שיש להודיע להם או להזמין אותם
recipient_emails מערך כתובות דוא״ל של אנשים שיש להזמין להצביע
recipient_message הודעה שתיכלל בהזמנה בדוא״ל

דוגמה

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 יכול לראות. חברי קבוצה יכולים לקרוא את השמות, המזהים, התארים והתפקידים של חברי הקבוצה. כתובות דוא״ל נכללות רק עבור החשבון המשויך למפתח ה-API, או כאשר חשבון זה הוא מנהל קבוצה.

GET /api/b2/memberships

פרמטרים

שם תיאור
group_id מספר שלם, חובה. מזהה הקבוצה שאת החברויות שלה יש להציג

דוגמה

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

ניהול חברויות

יש לשלוח רשימת כתובות דוא״ל. כתובות חדשות ברשימה יקבלו הזמנה לקבוצה. בשונה מהצגת חברויות, פעולה זו דורשת הרשאת מנהל קבוצה.

POST /api/b2/memberships

פרמטרים

שם תיאור
group_id מספר שלם, חובה. מזהה הקבוצה שאת החברויות שלה יש לנהל
emails מערך מחרוזות, חובה. כתובות הדוא״ל של אנשים שיש להזמין לקבוצה
remove_absent ערך בוליאני. אם הערך הוא true, כל מי שכתובת הדוא״ל שלהם אינה מופיעה ברשימה יוסרו מהקבוצה

דוגמה

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