> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gettrillion.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Communities

> Join a community, post, go to events, take courses and meet other members.

A community is a shared space with its own rules for who may join, a feed of posts, events, courses, levels and rewards. A community never shares anyone's contact. Its owner can change how it works and let members be paired to meet each other.

You do not call these tools yourself. You ask your AI in plain words, and it picks the tool. This page shows what each one does, so you know what to ask for.

## Communities

`list_communities` · Reads only

Communities this person can see or is in: title, what it is about, how many members, whether they are a member and whether they may join (and what joining comes with).

It takes no inputs.

```json Example theme={null}
{}
```

## Open a community

`community` · Reads only

One community as this person may see it: what it is, their level, points and the next level, rewards they can claim, events (with who is going, for members), the feed of posts and replies, and members with their levels. Spaces a community keeps for members are left out for anyone else. For the owner it also has claims to hand out and the configuration.

**Inputs**

| Input | Type | Required | What it is |
| - | - | - | - |
| `community_id` | string | Yes | A community id from `list_communities` |
| `limit` | integer | | How many posts of the feed |

```json Example theme={null}
{
  "community_id": "<community_id>"
}
```

## Join a community

`join_community` · Changes things

Joins a community when the person may (a free community, or one their plan includes). name is what other members see; members never see a contact. Leave with `leave_membership` and the community id.

**Inputs**

| Input | Type | Required | What it is |
| - | - | - | - |
| `community_id` | string | Yes | A community id from `list_communities` |
| `name` | string | | The name other members see |

```json Example theme={null}
{
  "community_id": "<community_id>"
}
```

## What is new in a community

`whats_new` · Changes things

What is new in a community since this person last looked: posts and replies by others, best first by the community's feed ranking, and events put on since. Looking marks it seen.

**Inputs**

| Input | Type | Required | What it is |
| - | - | - | - |
| `community_id` | string | Yes | A community id from `list_communities` |

```json Example theme={null}
{
  "community_id": "<community_id>"
}
```

## Post in a community

`post_to_community` · Changes things

Posts in a community's feed (community\_id, body), or replies to a post (reply\_to: its post\_id). Only members see posts. Returns the post. Say what you will post and get the person's approval of the exact words first.

**Inputs**

| Input | Type | Required | What it is |
| - | - | - | - |
| `community_id` | string | Yes | A community id from `list_communities` |
| `body` | string | Yes | |
| `reply_to` | string | | A post\_id from the feed |

```json Example theme={null}
{
  "community_id": "<community_id>",
  "body": "Has anyone priced a course above $500? What happened?"
}
```

## Vote for a post

`vote_post` · Changes things

Votes for a post (votes 1), or takes votes back (votes -1). Each member has the community's votes\_per\_member to spread across posts; a ranked feed puts well-voted posts first.

**Inputs**

| Input | Type | Required | What it is |
| - | - | - | - |
| `community_id` | string | Yes | A community id from `list_communities` |
| `post_id` | string | Yes | |
| `votes` | integer | | |

```json Example theme={null}
{
  "community_id": "<community_id>",
  "post_id": "<post_id>"
}
```

## Remove a post

`remove_post` · Changes things and can remove them

Removes a post and its replies from a community's feed: this person's own post, or anyone's when their role may remove\_posts.

**Inputs**

| Input | Type | Required | What it is |
| - | - | - | - |
| `community_id` | string | Yes | A community id from `list_communities` |
| `post_id` | string | Yes | |

```json Example theme={null}
{
  "community_id": "<community_id>",
  "post_id": "<post_id>"
}
```

## Answer an event

`rsvp_event` · Changes things

Says whether this person is going to a community event (going true or false). People going to the same event count as connected in the network.

**Inputs**

| Input | Type | Required | What it is |
| - | - | - | - |
| `event_id` | string | Yes | An event\_id from the community tool |
| `going` | boolean | Yes | |

```json Example theme={null}
{
  "event_id": "<event_id>",
  "going": true
}
```

## Put on an event

`create_community_event` · Changes things

Puts an event on in a community: title, starts\_at, optional ends\_at, about and size\_limit; repeats \{ every: day, week or month, count up to 52 } puts on one event per time. Its owner, and anyone whose role may put\_on\_events, can do this. Each event has a calendar file at /community/events/\<event\_id>/calendar.

**Inputs**

| Input | Type | Required | What it is |
| - | - | - | - |
| `community_id` | string | Yes | A community id from `list_communities` |
| `title` | string | Yes | |
| `about` | string | | |
| `starts_at` | string | Yes | |
| `ends_at` | string | | |
| `size_limit` | integer | | |
| `repeats` | object | | |
| `repeats.every` | string | | One of `day`, `week`, `month`. |
| `repeats.count` | integer | | |

```json Example theme={null}
{
  "community_id": "<community_id>",
  "title": "Monthly founders call",
  "starts_at": "2026-10-15T17:00:00Z",
  "repeats": {
    "every": "month",
    "count": 6
  }
}
```

## Mark a lesson done

`complete_lesson` · Changes things

Marks a lesson of a community course done (or not done, with done false). Returns the course with each lesson complete, active (the next one) or locked; lessons done count toward points where the community says so.

**Inputs**

| Input | Type | Required | What it is |
| - | - | - | - |
| `community_id` | string | Yes | A community id from `list_communities` |
| `course_id` | string | Yes | |
| `lesson_id` | string | Yes | |
| `done` | boolean | | |

```json Example theme={null}
{
  "community_id": "<community_id>",
  "course_id": "<course_id>",
  "lesson_id": "<lesson_id>"
}
```

## Claim a reward

`claim_reward` · Changes things

Claims a community reward this person has earned (reward\_id from the community tool, where can\_claim is true). The owner sees the claim and hands it out.

**Inputs**

| Input | Type | Required | What it is |
| - | - | - | - |
| `community_id` | string | Yes | A community id from `list_communities` |
| `reward_id` | string | Yes | |

```json Example theme={null}
{
  "community_id": "<community_id>",
  "reward_id": "<reward_id>"
}
```

## Community email digest

`community_notifications` · Changes things

Turns this person's email digest for a community on or off. With it on, they get what is new at most every few days, and only when there is something new; the address is kept in their own account, never shown to the community.

**Inputs**

| Input | Type | Required | What it is |
| - | - | - | - |
| `community_id` | string | Yes | A community id from `list_communities` |
| `email_digest` | boolean | Yes | |
| `email` | string | | Where digests go; needed the first time |

```json Example theme={null}
{
  "community_id": "<community_id>",
  "email_digest": true
}
```

## My matches in a community

`my_matches` · Reads only

This person's automatic pairing in a community: whether it is on, how often rounds run and when the next one is, their matches (who, why, what their AIs suggest talking about, the one-to-one space they share, and whether they talked), their matching answers with the questions still missing, and any round waiting for scores from this AI (waiting\_for\_your\_scores, with the shortlist and its claims).

**Inputs**

| Input | Type | Required | What it is |
| - | - | - | - |
| `community_id` | string | Yes | A community id from `list_communities` |

```json Example theme={null}
{
  "community_id": "<community_id>"
}
```

## Pair me automatically

`set_matching` · Changes things

Turns automatic pairing on or off for this person in a community (on), and keeps what other members' AIs may read when scoring who should meet: profile.answers (question\_id: a short answer, for the questions `my_matches` lists as missing, from what you know of the person) and profile.categories (two to five short words naming the kinds of pursuit they are on). Never put an email address, phone number or anything they would not tell a fellow member.

**Inputs**

| Input | Type | Required | What it is |
| - | - | - | - |
| `community_id` | string | Yes | A community id from `list_communities` |
| `on` | boolean | | |
| `profile` | object | | |
| `profile.answers` | object | | |
| `profile.categories` | string\[] | | |

```json Example theme={null}
{
  "community_id": "<community_id>"
}
```

## Score who to meet

`score_match_candidates` · Changes things

Answers a pairing round's job: for each candidate on this person's shortlist (candidate\_ref from the job's input or `my_matches`), five scores above 0 and at most 1 (complementarity, relevance, timing, ability\_to\_act, impact), each with a one-sentence reason and the claim\_refs it rests on (you: your person's, them: the candidate's). Leave out a candidate you have no grounds for; a score that cites no claim forms no match. When every asked AI has answered, the round pairs people at once.

**Inputs**

| Input | Type | Required | What it is |
| - | - | - | - |
| `community_id` | string | Yes | A community id from `list_communities` |
| `round_id` | string | Yes | |
| `scores` | object\[] | Yes | |
| `scores[].candidate_ref` | string | Yes | |
| `scores[].factors` | object | Yes | |
| `scores[].factors.complementarity` | object | Yes | |
| `scores[].factors.complementarity.score` | number | Yes | |
| `scores[].factors.complementarity.reason` | string | Yes | One sentence |
| `scores[].factors.complementarity.you` | string\[] | Yes | claim\_refs of your person this rests on |
| `scores[].factors.complementarity.them` | string\[] | Yes | claim\_refs of the candidate this rests on |
| `scores[].factors.relevance` | object | Yes | |
| `scores[].factors.relevance.score` | number | Yes | |
| `scores[].factors.relevance.reason` | string | Yes | One sentence |
| `scores[].factors.relevance.you` | string\[] | Yes | claim\_refs of your person this rests on |
| `scores[].factors.relevance.them` | string\[] | Yes | claim\_refs of the candidate this rests on |
| `scores[].factors.timing` | object | Yes | |
| `scores[].factors.timing.score` | number | Yes | |
| `scores[].factors.timing.reason` | string | Yes | One sentence |
| `scores[].factors.timing.you` | string\[] | Yes | claim\_refs of your person this rests on |
| `scores[].factors.timing.them` | string\[] | Yes | claim\_refs of the candidate this rests on |
| `scores[].factors.ability_to_act` | object | Yes | |
| `scores[].factors.ability_to_act.score` | number | Yes | |
| `scores[].factors.ability_to_act.reason` | string | Yes | One sentence |
| `scores[].factors.ability_to_act.you` | string\[] | Yes | claim\_refs of your person this rests on |
| `scores[].factors.ability_to_act.them` | string\[] | Yes | claim\_refs of the candidate this rests on |
| `scores[].factors.impact` | object | Yes | |
| `scores[].factors.impact.score` | number | Yes | |
| `scores[].factors.impact.reason` | string | Yes | One sentence |
| `scores[].factors.impact.you` | string\[] | Yes | claim\_refs of your person this rests on |
| `scores[].factors.impact.them` | string\[] | Yes | claim\_refs of the candidate this rests on |

```json Example theme={null}
{
  "community_id": "<community_id>",
  "round_id": "<round_id>",
  "scores": [
    {
      "candidate_ref": "<candidate_ref>",
      "factors": {
        "complementarity": {
          "score": 1,
          "reason": "<reason>",
          "you": [
            "<you>"
          ],
          "them": [
            "<them>"
          ]
        },
        "relevance": {
          "score": 1,
          "reason": "<reason>",
          "you": [
            "<you>"
          ],
          "them": [
            "<them>"
          ]
        },
        "timing": {
          "score": 1,
          "reason": "<reason>",
          "you": [
            "<you>"
          ],
          "them": [
            "<them>"
          ]
        },
        "ability_to_act": {
          "score": 1,
          "reason": "<reason>",
          "you": [
            "<you>"
          ],
          "them": [
            "<them>"
          ]
        },
        "impact": {
          "score": 1,
          "reason": "<reason>",
          "you": [
            "<you>"
          ],
          "them": [
            "<them>"
          ]
        }
      }
    }
  ]
}
```

## Suggest what to talk about

`suggest_match_topics` · Changes things

Suggests what this person and the person Trillion introduced them to could talk about first (topics: one to six specific lines). They show on the match and in the one-to-one space the two share.

**Inputs**

| Input | Type | Required | What it is |
| - | - | - | - |
| `community_id` | string | Yes | A community id from `list_communities` |
| `match_id` | string | Yes | |
| `topics` | string\[] | Yes | |

```json Example theme={null}
{
  "community_id": "<community_id>",
  "match_id": "<match_id>",
  "topics": [
    "<topics>"
  ]
}
```

## Pass on a match

`pass_match` · Changes things

Says a match is not for this person: it shows as passed and they leave the one-to-one it opened. They are never paired with that person again in this community.

**Inputs**

| Input | Type | Required | What it is |
| - | - | - | - |
| `community_id` | string | Yes | A community id from `list_communities` |
| `match_id` | string | Yes | |

```json Example theme={null}
{
  "community_id": "<community_id>",
  "match_id": "<match_id>"
}
```

## Change a community

`change_community` · Changes things

Replaces the configuration of a community this person owns (the whole config, as for `create_membership` with label "community"; what it leaves out comes from the label's starting configuration). Members, posts and events stay.

**Inputs**

| Input | Type | Required | What it is |
| - | - | - | - |
| `community_id` | string | Yes | A community id from `list_communities` |
| `config` | object | Yes | The community, as data. title and about in the owner's words; join lists who may join (\[\{ "free": true }] or \[\{ "access": "access:decision-history", "says": "Members of the \$100 a month plan" }]); spaces turns on feed, events, members and levels and says who sees each ("members" or "everyone"; "everyone" is the free view, open to anyone signed in or not); events\_by is "owner" or "members"; measures count facts about each member (kinds: joined, post, reply, event\_rsvp, event\_attended, introduction\_accepted, decision\_reported) with op count, weighted\_count, sum or distinct, for example \{ "id": "points", "op": "weighted\_count", "inputs": \[\{ "match": \{ "kind": "post" } }], "params": \{ "weights": \[3] } }; levels are \{ "measure": "points", "bands": \[\{ "name": "New", "min": 0, "max": 10 }, \{ "name": "Regular", "min": 10 }] }; rewards are \[\{ "id", "title", "says", "needs": \{ "measure", "at\_least" }, "per\_person" }]; owner\_name is the name members see for the owner; roles are \{ "host": \{ "may": \["put\_on\_events", "remove\_posts", "set\_roles", "send\_digests"] } }; feed is \{ "order": "ranked", "votes\_per\_member": 10, "signals": \[\{ "key", "label", "weight", "field": "votes" \| "replies" \| "age\_hours", "saturates\_at", "falls" }] }; courses are \[\{ "id", "title", "about", "lessons": \[\{ "id", "title", "body" }] }] (a lesson done is the fact kind lesson\_completed); streak is \{ "cadence": \{ "period": "week", "times": 1 }, "of": \{ "match": \{ "kind": "event\_attended" } }, "label" }; digest is \{ "every\_days": 7, "cadence", "nudge\_at": 0..1, "subject" } with mail \{ "send\_binding", "from": \{ "email", "name" }, "reply\_to" }; the spaces include courses. |
| `config.title` | string | Yes | |
| `config.about` | string | | |
| `config.join` | object\[] | | |
| `config.spaces` | object | | |
| `config.events_by` | string | | One of `owner`, `members`. |
| `config.measures` | object\[] | | |
| `config.levels` | object | | |
| `config.rewards` | object\[] | | |
| `config.owner_name` | string | | |
| `config.roles` | object | | |
| `config.feed` | object | | |
| `config.courses` | object\[] | | |
| `config.streak` | object | | |
| `config.digest` | object | | |
| `config.mail` | object | | |
| `config.matching` | object | | Pairs members automatically: \{ every\_days, cadence\_label, answer\_hours, group\_size, shortlist\_size, default\_on, evidence: \{ questions: \[interaction-program intake question ids] }, initiative: \{ required\_level, pre\_authorized\_levels } }. Each member's own AI scores who they should meet; Trillion introduces the best-scored pairs in a one-to-one space. |

```json Example theme={null}
{
  "community_id": "<community_id>",
  "config": {
    "title": "<title>"
  }
}
```

## Give a member a role

`set_member_role` · Changes things

Gives a member one of the community's roles (or member to take it away), which decides what they may do: put on events, remove posts, give roles, send digests. member\_relay comes from the members list.

**Inputs**

| Input | Type | Required | What it is |
| - | - | - | - |
| `community_id` | string | Yes | A community id from `list_communities` |
| `member_relay` | string | Yes | |
| `role` | string | Yes | |

```json Example theme={null}
{
  "community_id": "<community_id>",
  "member_relay": "<member_relay>",
  "role": "<role>"
}
```

## Send community digests now

`send_community_digests` · Changes things

Sends the community's digests now instead of waiting for the daily run, for its owner or a role that may send\_digests. Returns how many members were considered, how many were sent one, and why the rest were not.

**Inputs**

| Input | Type | Required | What it is |
| - | - | - | - |
| `community_id` | string | Yes | A community id from `list_communities` |

```json Example theme={null}
{
  "community_id": "<community_id>"
}
```

## Start a pairing round

`run_matching_round` · Changes things

Starts a pairing round in a community this person runs, now instead of on its schedule: every member who is paired automatically has their own AI asked to score a short list of others, and Trillion introduces the best-scored pairs when the AIs have answered or the round's time is up. Returns how many AIs were asked.

**Inputs**

| Input | Type | Required | What it is |
| - | - | - | - |
| `community_id` | string | Yes | A community id from `list_communities` |

```json Example theme={null}
{
  "community_id": "<community_id>"
}
```

## Hand a community over

`hand_over_community` · Changes things

Makes a one-time link, good for 14 days, that hands a community this person runs to whoever opens it signed in to Trillion. The person before stays a member. Give the link to the new owner.

**Inputs**

| Input | Type | Required | What it is |
| - | - | - | - |
| `community_id` | string | Yes | A community id from `list_communities` |

```json Example theme={null}
{
  "community_id": "<community_id>"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.