# Upvote

> The Upvote space module, in the Community tab. A board where members propose topics, vote (one vote per person, retractable) and comment, and the staff approves, changes the state, merges duplicates, archives with a reason and reopens. Sorting, filters, columns, public reading, limits, e-mail notices, and the same actions through the assistant and the API.

**Upvote** is a board where members say what they want: each person proposes **topics** (an idea, a request, an improvement), everyone votes for the ones they back, and the most voted rise. The staff answers by changing each topic's state (**Planned**, **In progress**, **Done** or **Archived**, with the reason), and whoever voted is notified.

It is a [space module](/conceitos/modulos) in the **Community** tab of **Add Space**. **One space is one board**: for separate boards (product, events, content), create several spaces. Who creates the space: owner or admin.

## Upvote, Poll or Survey?

| | [Poll](/espacos/enquetes) | [Survey](/espacos/pesquisas) | **Upvote** |
|---|---|---|---|
| Who asks | The staff | The staff | **Members** propose |
| Options | Fixed, written by the staff | A questionnaire in sections | An open list that grows every day |
| Where it lives | In a Feed or Content post | Its own space and a public link | Its own space |
| Vote | Pick an option; only the staff sees who voted for what | Identified or anonymous answer | One vote per topic, on as many topics as you like; retractable |
| End | Closes at a deadline | A period, with results and NPS | Never closes; each topic has its own outcome |
| What for | Decide among a few options now | Measure satisfaction and climate | Find out what the community wants and show what was done |

**Rule of thumb:** the staff wants to know between A, B or C → Poll; wants to measure → Survey; wants members to say what they want and show what it did with that → Upvote.

## Who can do what

| Action | Who |
|---|---|
| Read the board, topics and comments | Whoever opens the space; in a **public** space, also a visitor without login |
| Vote, take the vote back and comment | Whoever opens the space, signed in |
| Propose a topic | Whoever the space's **Who can post** allows |
| Edit and delete your own topic | The author, until someone else votes on it |
| Approve, edit, change the state, merge, archive, reopen, see who voted and delete | The **staff**: owner, admin and moderator. Finance isn't part of it |
| Turn on prior approval | Owner and admin |

## How it works

### The board

Each topic shows in a card with the **vote button on the left** (the arrow and the number, filled when you voted), the title, a snippet of the description, the author, the comments and the state badge.

- **Sort by:** **Most voted** (the default; on a tie, the newest), **Newest** and **Trending** (the most voted in the last 7 days, updated every hour).
- **Filters:** **All** (everything but archived), **Open**, **Planned**, **In progress**, **Done**, **Archived**, **My topics** and **Voted**.
- **View:** **List** or **Columns** (Open, Planned, In progress and Done, each by most voted). On a phone, the columns become tabs by state, one at a time.

The list gets a single line with the states and compact menus, **Sort** and **Filter** (including **All topics**), and the columns stop repeating the state on every card. On a topic, the bar keeps **Edit** and **Change state**, and the rest goes to **More actions**.

### The vote

Each person has **one vote per topic** and votes on as many topics as they like. Clicking again takes the vote back. Whoever proposes already starts voting on their own topic (and can take it back).

Everyone sees the count; **who voted, only the staff sees**, in **Who voted**, with the date each person joined the community (it helps spot duplicate accounts).

Voting and taking the vote back only work on **Open**, **Planned** or **In progress** topics. In **Done** and **Archived**, voting freezes: you can neither vote nor take the vote back.

### The states

| State | What it means | Vote | Comment |
|---|---|---|---|
| **Open** | Taking votes | Yes | Yes |
| **Planned** | The staff will do it | Yes | Yes |
| **In progress** | The staff is doing it | Yes | Yes |
| **Done** | Ready | Frozen | Yes |
| **Archived** | Won't go ahead, with the reason visible to everyone | Frozen | No |

Only the staff changes the state. Each change takes a **Note for voters** (*"shipped in the March release"*); archiving requires the **Reason**. **Reopen** takes a Done or Archived topic back to Open. The votes always stay.

### Is there something similar already?

When proposing, from the third word of the title up to 5 topics from the same board that share words with it show up under **Is there something similar already?**. If one of them is what you want, **Vote for this** gives it your vote instead of creating another.

### Merge duplicates

When two topics ask for the same thing, the staff uses **Merge into…** on the repeated one and picks the original, which must be Open, Planned or In progress, on the same board. The repeated one is archived as *"Duplicate of <title>"*, with the link; the votes move to the original **without counting twice** whoever voted on both; the comments stay on the repeated one. **A merged topic doesn't reopen.**

### Comments

Whoever opens the space comments and replies (one level of replies), up to 2,000 characters. The comment's author and the staff delete; deleting a comment takes its replies along. An archived topic takes no more comments.

### Prior approval

With **Prior approval** on, members' topics only show on the board after the staff approves. Until then, the topic is **Awaiting approval**, visible only to the author (in **My topics**) and the staff, and takes no votes or comments. If the author edits the text of an already approved topic, it goes back to approval. Staff topics go straight in.

The staff sees the **Manage board** bar, with how many topics are waiting and the **Approval queue** button, which lists the pending ones with **Approve** and **Reject** (a rejected topic stays visible only to the author and the staff). Pending topics also show in [moderation](/membros/moderacao).

### Public reading

In a space with **Public** visibility, a visitor without login reads everything (the board, topics, count, states and comments) except who voted. Voting, commenting or proposing opens *"Sign in to vote for what you back"* (or *"Sign in to comment"*, *"Sign in to propose a topic"*), with **Sign in** and **Create account**; afterwards, the person comes back to the board. In a space that isn't public, only whoever opens the space reads.

### Limits

| Limit | Value |
|---|---|
| New topics | 5 per person per day (the staff has no limit; pending and deleted ones count) |
| Votes | 120 per person per hour |
| Title | 140 characters |
| Description | 5,000 characters |
| Photos | Up to 4 per topic (JPG, PNG or WebP) |
| Note or reason | 500 characters |

### E-mail notices

| Who gets it | When |
|---|---|
| The author and whoever voted | The topic moves to **Planned**, **In progress**, **Done** or **Archived** (with the note or the reason), is **reopened** or is **merged** into another |
| The staff | A new topic is proposed |

Members **don't** get an e-mail for every new topic. The notices also arrive in the bell. Only whoever **still has access to the space** at the time of the notice gets it. You can turn it off with the **Upvote: topics you support** category in [E-mails from this community](/notificacoes/emails-desta-comunidade), or with the footer link.

## Step by step

### Create a board

*Role: owner or admin.*

1. In the menu, under **Add Space**, open the **Community** tab and choose **Upvote**.
2. Give it a name, a description, the visibility (**Public** lets anyone read) and **Who can post**. Turn on **Prior approval** if you want to approve each topic.
3. Create it. Later, **Configure**, in the **Manage board** bar, turns prior approval on and off.

### Propose a topic

1. On the board, click **New topic** (on a phone, in the footer: *"Got an idea? Propose it."*).
2. Type the **Title** and check **Is there something similar already?**: if a topic is what you want, **Vote for this**.
3. Type the **Description** and, if you like, **Add photos** (up to 4).
4. Click **Publish topic**.

### Manage a topic

*Role: owner, admin or moderator.*

Open the topic. The **Manage topic** bar shows the votes, the state and the actions:

- **Approve**: when the topic is awaiting approval.
- **Edit**: title, description and photos.
- **Change state**: pick the state and, if you like, the note for voters. **Save state** notifies the author and whoever voted.
- **Merge into…**: pick the original topic and confirm.
- **Archive**: with the reason, required.
- **Reopen**: from Done or Archived to Open.
- **Who voted**: the list, with each person's join date.
- **Delete**: the topic leaves the board with its votes, comments and photos. If the idea still matters, archiving with a reason keeps the history.

## Examples

**An online school's suggestion board.** A **Public** space "What do you want to learn", **Who can post = Anyone**. Students propose courses; *"Advanced Excel"* reaches 80 votes, the staff moves it to **Planned** with the note *"Recording in November"*, and the 80 get the notice.

**Coworking improvements.** A members-only space with **Prior approval**. A resident proposes *"More sockets in room 2"*; the staff approves it, it gets votes, becomes **In progress** and then **Done**. A second identical request is merged into the first, taking its votes along.

## Common errors and how to fix them

| Situation | What to do |
|---|---|
| **New topic** doesn't show up | The space's **Who can post** doesn't include your role |
| You can't vote | The topic is Done, Archived or awaiting approval; or you aren't signed in (visitor) |
| You can't edit your own topic | Someone else has already voted on it; now only the staff edits |
| You can't comment | The topic is archived or awaiting approval |
| Limit of 5 topics a day | Wait for 24 hours to pass since the first topic |
| You can't reopen | The topic was merged into another: the votes are already there |
| Archiving doesn't save | Fill in the reason, required |

## Frequently asked questions

**Do members know what I voted for?**
No. Only the staff sees who voted.

**Does someone who leaves the community lose their vote?**
No. The votes stay in the count; the notices stop, because the person no longer has access.

**Can I vote without an account?**
No. On a public board, a visitor reads; to vote, they sign in or create an account.

## Through the assistant

The assistant proposes, votes on and manages topics with the same rules as whoever connected it. See [Tools · Content](/mcp/ferramentas-conteudo#upvote).

- **Reading:** `get_upvote_board`, `list_upvote_topics` (with sorting and state), `get_upvote_topic` and `find_similar_upvote_topics`.
- **For whoever opens the space:** `vote_upvote_topic`, `unvote_upvote_topic` and `create_upvote_comment`, with no confirmation; `create_upvote_topic` asks for confirmation; `update_upvote_topic` and `delete_upvote_topic` (with confirmation), the author until someone else votes.
- **Staff:** `set_upvote_topic_status` (archiving included), `reopen_upvote_topic` and `merge_upvote_topics`, all with confirmation, showing the reason and how many people will be notified; `merge_upvote_topics` can't be undone. `list_upvote_voters`, read only.
- **Owner and admin:** `update_upvote_board`, which turns prior approval on or off.

Ask like this: *"Check whether there's already a topic similar to 'dark mode in the app' before creating one; if there is, vote for it."* See the [recipe](/mcp/receitas#91-check-for-a-similar-topic-before-creating-one).

## In the API

The routes live under `/api/upvotes`, with `X-CommunityId`; the path doesn't carry the community. Reads work without login in a public space.

| Route | What it does | Who |
|---|---|---|
| `GET /api/upvotes/spaces/{spaceId}` | The board: whether the person can propose and manage, and the limits | Whoever reads |
| `PUT /api/upvotes/spaces/{spaceId}` | Turns `requireApproval` on or off | Owner and admin |
| `GET` · `POST /api/upvotes/spaces/{spaceId}/topics` | Lists (`sort` = `top`, `new` or `trending`; `status`; `mine`; `voted`; `cursor`) · proposes | Whoever reads · whoever can post |
| `GET /api/upvotes/spaces/{spaceId}/similar?title=` | Up to 5 similar topics | Whoever reads |
| `GET` · `PATCH` · `DELETE /api/upvotes/topics/{id}` | Detail · edits · deletes | Whoever reads · author (until another vote) or staff |
| `PUT` · `DELETE /api/upvotes/topics/{id}/vote` | Votes · takes the vote back | Whoever opens the space |
| `GET /api/upvotes/topics/{id}/voters` | Who voted | Staff |
| `GET` · `POST /api/upvotes/topics/{id}/comments` · `DELETE /api/upvotes/comments/{id}` | Comments | Whoever reads · whoever opens the space · author or staff |
| `POST /api/upvotes/topics/{id}/status` · `…/reopen` · `…/merge` | Changes the state (`status`, `note`) · reopens · merges (`targetId`) | Staff |

Errors: `400` (archiving without a reason, empty or too long text), `403` (no permission), `404` (a topic from another board or community), `409` (voting on Done, Archived or pending; commenting on archived; reopening a merged topic), `429` (5 topics a day, 120 votes an hour). An API key uses the `upvotes` module (see [Authentication](/api/autenticacao#the-scope)). See [Upvotes](/api/referencia/upvotes).

## Related

- [Polls](/espacos/enquetes)
- [Surveys](/espacos/pesquisas)
- [Moderation](/membros/moderacao)
- [Modules](/conceitos/modulos)
- [E-mails from this community](/notificacoes/emails-desta-comunidade)
- [Tools · Content](/mcp/ferramentas-conteudo#upvote)