Skip to main content

​
Community Governance API

Admin-only proposal creation and community voting for claimed token holders. Governance proposals are surfaced in the community program response.

​
Create proposal

POST /api/community/governance
Creates a new governance proposal. Requires admin session authentication.

​
Request body

FieldTypeRequiredDescription
titlestringYesProposal title (max 120 characters)
summarystringYesShort summary (max 280 characters)
detailsstringNoExtended description (max 4000 characters)
endsAtstringNoISO 8601 end date. Omit for open-ended proposals.

​
Example request

{
  "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

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

​
Response fields

FieldTypeDescription
successbooleantrue when the proposal was created
proposal.idstringUnique proposal identifier (prefixed with cgp_)
proposal.slugstringURL-safe slug derived from the title

​
Errors

CodeDescription
400Missing required title or summary
403Forbidden — admin session required

​
Vote on proposal

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

ParameterTypeDescription
proposalIdstringThe proposal identifier to vote on

​
Request body

FieldTypeRequiredDescription
choicestringYesVote choice: yes, no, or abstain

​
Example request

{
  "choice": "yes"
}

​
Response

{
  "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

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