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

# Community Governance API

> Create governance proposals and vote on community decisions

# Community Governance API

Admin-only proposal creation and community voting for claimed token holders. Governance proposals are surfaced in the [community program](/api-reference/community-program) response.

## Create proposal

```http theme={"dark"}
POST /api/community/governance
```

Creates a new governance proposal. Requires admin session authentication.

### Request body

| Field     | Type   | Required | Description                                       |
| --------- | ------ | -------- | ------------------------------------------------- |
| `title`   | string | Yes      | Proposal title (max 120 characters)               |
| `summary` | string | Yes      | Short summary (max 280 characters)                |
| `details` | string | No       | Extended description (max 4000 characters)        |
| `endsAt`  | string | No       | ISO 8601 end date. Omit for open-ended proposals. |

### Example request

```json theme={"dark"}
{
  "title": "Expand baseFM access to Holder tier",
  "summary": "Should all claimed holders get baseFM streaming, not just Builder and Whale?",
  "details": "Currently only Builder and Whale tiers unlock the baseFM guest pass...",
  "endsAt": "2026-04-20T00:00:00.000Z"
}
```

### Response

```json theme={"dark"}
{
  "success": true,
  "proposal": {
    "id": "cgp_a1b2c3d4-...",
    "slug": "expand-basefm-access-to-holder-tier-abc123"
  }
}
```

### Response fields

| Field           | Type    | Description                                       |
| --------------- | ------- | ------------------------------------------------- |
| `success`       | boolean | `true` when the proposal was created              |
| `proposal.id`   | string  | Unique proposal identifier (prefixed with `cgp_`) |
| `proposal.slug` | string  | URL-safe slug derived from the title              |

### Errors

| Code | Description                           |
| ---- | ------------------------------------- |
| 400  | Missing required `title` or `summary` |
| 403  | Forbidden — admin session required    |

***

## Vote on proposal

```http theme={"dark"}
POST /api/community/governance/{proposalId}/vote
```

Submits or updates a vote on an active governance proposal. Requires session authentication and a claimed holder status.

### Path parameters

| Parameter    | Type   | Description                        |
| ------------ | ------ | ---------------------------------- |
| `proposalId` | string | The proposal identifier to vote on |

### Request body

| Field    | Type   | Required | Description                            |
| -------- | ------ | -------- | -------------------------------------- |
| `choice` | string | Yes      | Vote choice: `yes`, `no`, or `abstain` |

### Example request

```json theme={"dark"}
{
  "choice": "yes"
}
```

### Response

```json theme={"dark"}
{
  "success": true
}
```

### Voting rules

* Only users who have claimed community rewards can vote.
* Voting power is determined by the voter's tier: Whale (10), Builder (3), Holder (1).
* Submitting a new vote on the same proposal replaces the previous vote.
* Only proposals with `active` status accept votes.

### Errors

| Code | Description                                                     |
| ---- | --------------------------------------------------------------- |
| 400  | Missing or invalid `choice`. Must be `yes`, `no`, or `abstain`. |
| 401  | Unauthorized — no valid session                                 |
| 403  | Claimed holder status required to vote                          |
| 404  | Proposal not found or not open for voting                       |