---
title: "Update community"
method: PUT
path: "/v1/communities/{communityId}"
tags: ["Communities"]
---

# Update community

`PUT /v1/communities/{communityId}`

## Request

- Base URL: `https://api.subo.ai`
- URL: `https://api.subo.ai/v1/communities/{communityId}`
- Auth: API key in header `X-API-Key`

Update any combination of community identity fields and settings groups in a single call. Admin role required. Only provided fields are written; omitted fields are left unchanged. All groups (general, defaults, rewards, experience, platforms) are optional.

## Path parameters

- `communityId` string, required

## Request body

- object
  - `name` string: Display name of the community
  - `icon_url` string: URL of the community icon image
  - `locale` string: BCP 47 locale code, e.g. en-US, fr-FR
  - `general` object: General community settings
    - `text_analysis` boolean: Enable AI text analysis for open-ended responses. The default for every project in the community: a project (`settings.text_analysis`) or an `open_text` block (`text_analysis`) can override it either way.
    - `allow_network_projects` boolean: Allow projects to be pushed via the Subo network
    - `topics` string[]: Community topic tags
  - `defaults` object: Default settings applied to new projects
    - `privacy_mode` 'transparent' | 'semi-private' | 'anonymous': Default privacy mode applied to new projects. `transparent`: all members see who answered what. `semi-private`: only creator and admins see individual responses; others see aggregated results only if shared. `anonymous`: respondent identity hidden from everyone including admins (pseudo-anonymous — answers recorded without user ID unless volunteered). Caveat: XP and achievements can still be granted, so participation is not fully hidden.
    - `project_closing` integer: Default interval before a project closes, in seconds
    - `invite_message` string: Default invitation message text
    - `change_vote_enabled` boolean: Allow participants to change their vote
    - `poll_results_mode` 'public' | 'votersonly' | 'hidden': Who can see poll results
    - `answer_style` 'buttons_full' | 'buttons_emoji' | 'select_menu': Default display style for multiple-choice answers
    - `final_reveal` boolean: Show final results to respondents after closing
  - `rewards` object: XP and achievement settings
    - `use_xp` boolean
    - `xp_name` string: Display name for XP points (e.g. Points, Coins). Requires a paid plan.
    - `xp_per_question` integer: XP awarded per question answered. Requires a paid plan.
    - `xp_per_poll` integer: XP awarded per poll completed. Requires a paid plan.
    - `xp_completion_bonus` integer: XP multiplier awarded for completing a full project. Requires a paid plan.
    - `use_leader_board` boolean
    - `xp_achievement_announcement` string: Where achievement and role notices go. Empty string: off. `-1`: a DM, falling back to the member's own private thread with Subo when their DMs are closed. `-2`: that private thread. A Discord channel id: that public channel, naming the member with a mention.
    - `xp_stack_achievements` boolean: Stack multiple XP achievement role rewards
    - `achievements` object[]: Patch list of achievements to update (by id)
      - `id` integer, required
      - `type` string
      - `name` string
      - `badge` string: Image URL
      - `description` string
      - `discord_role_id` string
  - `experience` object: Messaging and presentation customization
    - `enable_advertising` boolean: Include Subo promotion in buttons or messages. Disabling requires a paid plan.
    - `closing_message_type` 'default' | 'formstandard' | 'custom': Style of the closing message. `custom` requires a paid plan.
    - `closing_message` string: Message displayed at the end of a convo. Use a `# Heading` markdown line as the first line to set a title.
    - `closing_embed_color` string: 6-digit hex color without '#' (e.g. `ff5733`). A leading '#' is accepted and removed.
    - `closing_message_image_url` string: URL of an image to render with the custom closing message (Discord embed image / web large image)
    - `closing_message_thumbnail_url` string: URL of a thumbnail to render with the custom closing message (Discord embed thumbnail / web small image)
    - `invite_footer` string: Footer appended after the project invitation message
    - `analysis_footer` string: Footer appended to analysis/export outputs
    - `closing_message_footer` string: Footer appended after the closing message
    - `xp_closing_message` string: Closing message shown when the respondent earns XP. Use `# Heading` on the first line for a title. Variables: [xp_points], [earned_xp], [month_total_xp], [xp_name], [xp_to_next_level], [next_xp_level], [xp_to_next_monthly_level], [next_monthly_xp_level].
    - `xp_closing_embed_color` string: 6-digit hex color without '#' for the XP closing embed. A leading '#' is accepted and removed.
    - `xp_closing_message_image_url` string: URL of an image to render with the XP closing message
    - `xp_closing_message_thumbnail_url` string: URL of a thumbnail to render with the XP closing message
  - `platforms` object: Platform-specific settings
    - `discord` object: Discord-specific channel and role configuration
      - `participant_channel_id` string: Main participant channel Discord snowflake ID
      - `creator_channel_id` string: Creator channel Discord snowflake ID. Must be a text channel in this community, public or private: Subo opens a private thread there for each admin or creator (/settings, /edit, /export, /results, tests), and voice, announcement, forum and category channels cannot host them. Anything else is rejected with 400 invalid_request.
      - `analysis_channel_id` string: Channel where analysis/results are posted
      - `new_response_notifications_channel_id` string: Channel for new response notifications
      - `enable_new_response_notifications` boolean
      - `participants_category_id` string: Deprecated: accepted and ignored. Subo no longer creates temporary channels, so there is no category to place them in.
      - `new_response_notifications_in_threads` boolean: Send new response notifications in Discord threads

## Response `200`

Updated

- object
  - `data` Community
    - `id` string
    - `name` string
    - `platform` 'discord'
    - `tier` 'basic' | 'premium' | 'vip' | 'custom'
    - `bot_credits` integer
    - `locale` string, nullable
    - `icon_url` string, nullable
    - `created_date` string, date-time, nullable
    - `total_project_count` integer: Total number of projects ever created
    - `active_project_count` integer: Number of currently active (live or pending) projects
    - `topics` string[]: Community topic tags
    - `user_setup_id` string, nullable: Internal Subo user ID of the member who last completed the community bot setup wizard. Read-only. Null if setup has not been run.

## Other responses

- `400`: Bad request
- `401`: Invalid or missing API key
- `402`: One or more fields require a paid plan
- `403`: Forbidden — the key or user lacks permission for this resource or operation
- `404`: Resource not found
- `429`: Rate limit exceeded — wait `retry_after` seconds before retrying. The same value appears in the `Retry-After` header.

---

[API](https://skmtc.dev/subo/apis/subo-api.md) · [All operations](https://skmtc.dev/subo/apis/subo-api/llms.txt) · [OpenAPI document](https://skmtc.dev/subo/apis/subo-api/revisions/12eab2ae4505?raw)