openapi: 3.0.0
info:
  title: Social Service API
  version: 1.0.0
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  description: |
    ## Overview

    The Social Service API powers social interactions and community features within the Decentraland metaverse platform. This API enables users to create and manage communities, connect with friends, participate in voice chats, and engage in social activities.

    ### Key Features

    ### 🏘️ Communities
    - **Create and manage communities** with customizable privacy settings (public/private) and visibility (listed/unlisted)
    - **Member management** with role-based permissions (owner, moderator, member)
    - **Community posts** for sharing updates and announcements
    - **Place associations** to link communities with specific Decentraland locations
    - **Ban management** for community moderation
    - **Invitations and join requests** workflow for private communities

    ### 🎙️ Community Voice Chats
    - Real-time voice chat sessions within communities
    - Role-based participation (speakers and listeners)
    - Active voice chat discovery across communities
    - Location tracking for voice chat participants

    ### 🎁 Referral System
    - Track user referrals and invitations
    - Monitor referral progress and rewards
    - Email association for referral campaigns

    ### 👥 Social Features
    - **Friendship management** (via RPC/gRPC - not covered in this REST API)
    - **Blocking and privacy controls** (via RPC/gRPC)
    - **User profiles** with claimed names and avatars
    - **Online status tracking** for community members

    ## Authentication

    This API uses two authentication methods:

    ### Signed Fetch (Primary)
    Most endpoints use **Signed Fetch authentication** (ADR-44), which cryptographically signs requests using the user's Ethereum wallet. This ensures that requests are genuinely from the wallet owner without requiring traditional API keys.

    - **Header**: `Authorization: <signed-fetch-token>`
    - **Required for**: All user-facing endpoints
    - **Optional on**: Public read endpoints (returns additional data when authenticated)
    - **Security**: Prevents scene-based requests for additional security

    ### Bearer Token (Admin)
    Administrative endpoints use **Bearer token authentication** for system-level operations.

    - **Header**: `Authorization: Bearer <API_ADMIN_TOKEN>`
    - **Required for**: Admin and moderation endpoints
    - **Used by**: Backend services and authorized administrators   

    ### Key Concepts

    ### Community Privacy
    - **Public**: Anyone can view and join
    - **Private**: Requires invitation or approval to join

    ### Community Visibility
    - **All** (listed): Appears in public community listings
    - **Unlisted**: Only accessible via direct link, not shown in listings

    ### Community Roles
    - **owner**: Full control over the community
    - **moderator**: Can manage members, posts, and settings
    - **member**: Regular community member
    - **none**: Not a member of the community

    ### Request Types
    - **invite**: An invitation sent to a user to join a community
    - **request_to_join**: A request from a user to join a private community
servers:
  - url: https://social-api.decentraland.org
    description: Production server
  - url: https://social-api.decentraland.zone
    description: Development server
security:
  - SignedFetch: []
paths:
  /v1/communities:
    get:
      operationId: listCommunities
      summary: List communities
      description: |
        Lists all communities with full details, or performs a fast community search with minimal data.
        This endpoint has optional Signed Fetch authentication.
        When signed, it includes properties related to the authenticated user in its response.
        This endpoint excludes unlisted communities from results. Use direct community access (GET `/v1/communities/{id}`) to retrieve unlisted communities.

        **Minimal Mode (minimal=true):**
        When `minimal=true` is set, authentication is required and only the `search` parameter is used:
        - Returns community `id`, `name`, `membersCount`, and `privacy` for fast lookups
        - Requires `search` parameter with minimum 3 characters
        - Maximum 50 results per request
        - Supports pagination with `limit` and `offset` parameters
        - Other filter parameters are ignored

        **Visibility Rules (Minimal Mode):**
        - Public and Private communities: searchable by anyone
        - Unlisted communities: only searchable by their members

        **Search Behavior (Minimal Mode):**
        - Matches community names starting with the search term
        - Also matches words in the middle of the name (after a space)
      security:
        - SignedFetch: []
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
          description: Number of communities per page. When `minimal=true`, max is 50.
        - name: offset
          in: query
          required: false
          schema:
            type: integer
          description: Number of communities to skip.
        - name: search
          in: query
          required: false
          schema:
            type: string
          description: Search term to filter communities by name. Required when `minimal=true` (minimum 3 characters).
        - name: minimal
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: |
            When `true`, returns community `id`, `name`, `membersCount`, and `privacy` for fast lookups.
            Requires authentication and `search` parameter with minimum 3 characters.
            Supports pagination with `limit` (max 50) and `offset` parameters.
            Other filter parameters (`onlyMemberOf`, `onlyWithActiveVoiceChat`, `roles`) are ignored.
        - name: onlyMemberOf
          in: query
          required: false
          schema:
            type: boolean
          description: Filter communities where the authenticated user is a member. Ignored when `minimal=true`.
        - name: onlyWithActiveVoiceChat
          in: query
          required: false
          schema:
            type: boolean
          description: Filter to show only communities with active voice chats. Ignored when `minimal=true`.
        - name: roles
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
              enum:
                - owner
                - moderator
                - member
                - none
          description: Filter communities by the authenticated user's role (can specify multiple roles). Ignored when `minimal=true`.
      responses:
        '200':
          description: Communities found
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    required: &ref_6
                      - data
                    properties: &ref_7
                      data:
                        allOf:
                          - type: object
                            required: &ref_0
                              - results
                              - total
                              - limit
                              - offset
                            properties: &ref_1
                              results:
                                type: array
                                items:
                                  type: object
                              total:
                                type: integer
                                description: Total number of items
                              limit:
                                type: integer
                                description: Number of items per page
                              offset:
                                type: integer
                                description: Number of items skipped
                              page:
                                type: integer
                                description: Current page number (1-indexed)
                              pages:
                                type: integer
                                description: Total number of pages
                          - type: object
                            properties:
                              results:
                                type: array
                                items:
                                  type: object
                                  required:
                                    - id
                                    - name
                                    - description
                                    - ownerAddress
                                    - privacy
                                    - visibility
                                    - active
                                    - membersCount
                                  properties:
                                    id:
                                      type: string
                                    name:
                                      type: string
                                    description:
                                      type: string
                                    ownerAddress:
                                      type: string
                                    ownerName:
                                      type: string
                                      description: Display name of the community owner
                                    privacy:
                                      type: string
                                      enum:
                                        - public
                                        - private
                                    visibility:
                                      type: string
                                      enum:
                                        - all
                                        - unlisted
                                      description: Community visibility setting (all = listed, unlisted = hidden from general listings)
                                    active:
                                      type: boolean
                                    membersCount:
                                      type: integer
                                    thumbnails:
                                      type: object
                                      additionalProperties:
                                        type: string
                                      description: Map of thumbnail URLs by size/type
                                    friends:
                                      type: array
                                      items:
                                        type: object
                                        description: Friend profile information including address and name
                                      description: |
                                        Array of friends who are members of this community.
                                        This is only present when the user is signed in.
                                    role:
                                      type: string
                                      enum:
                                        - owner
                                        - moderator
                                        - member
                                        - none
                                      description: |
                                        The role of the user in the community.
                                        This is only present when the user is signed in.
                                    voiceChatStatus:
                                      type: object
                                      nullable: true
                                      properties:
                                        isActive:
                                          type: boolean
                                        participantCount:
                                          type: integer
                                        moderatorCount:
                                          type: integer
                                      description: Voice chat status for the community (null if no active voice chat)
                  - type: object
                    required: &ref_8
                      - data
                    properties: &ref_9
                      data:
                        allOf:
                          - type: object
                            required: *ref_0
                            properties: *ref_1
                          - type: object
                            properties:
                              results:
                                type: array
                                items:
                                  type: object
                                  required:
                                    - id
                                    - name
                                    - membersCount
                                    - privacy
                                  properties:
                                    id:
                                      type: string
                                      format: uuid
                                      description: Unique identifier of the community
                                    name:
                                      type: string
                                      description: Name of the community
                                    membersCount:
                                      type: integer
                                      description: Number of members in the community
                                    privacy:
                                      type: string
                                      enum:
                                        - public
                                        - private
                                      description: Community privacy setting
                                description: List of communities matching the search query with minimal data
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                required: &ref_2
                  - message
                  - error
                properties: &ref_3
                  message:
                    type: string
                    description: A message describing the error
                  error:
                    type: string
                    description: Error code (e.g. Not Found, Invalid Request, Unauthorized, etc.)
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
      tags:
        - Communities
    post:
      operationId: createCommunity
      summary: Create a new community
      description: |
        Creates a new community with the provided details.
        This endpoint requires Signed Fetch authentication.
      security:
        - SignedFetch: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - name
                - description
              properties:
                name:
                  type: string
                description:
                  type: string
                placeIds:
                  type: string
                  description: JSON array of place IDs to add to the community
                privacy:
                  type: string
                  enum:
                    - public
                    - private
                  description: Community privacy setting
                visibility:
                  type: string
                  enum:
                    - all
                    - unlisted
                  description: Community visibility setting
                thumbnail:
                  type: string
                  format: binary
                  description: Community thumbnail image
      responses:
        '201':
          description: Community created successfully
          content:
            application/json:
              schema:
                type: object
                required: &ref_10
                  - data
                properties: &ref_11
                  data:
                    type: object
                    required:
                      - id
                      - name
                      - description
                      - ownerAddress
                      - privacy
                      - visibility
                      - active
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      description:
                        type: string
                      ownerAddress:
                        type: string
                      privacy:
                        type: string
                        enum:
                          - public
                          - private
                      visibility:
                        type: string
                        enum:
                          - all
                          - unlisted
                      active:
                        type: boolean
                      thumbnails:
                        type: object
                        additionalProperties:
                          type: string
                        description: A map of thumbnail types to URLs. The key is the thumbnail type (e.g. "raw") and the value is the URL.
        '401':
          description: Unauthorized - Signed Fetch required
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
      tags:
        - Communities
  /v1/communities/{id}:
    get:
      operationId: getCommunityById
      summary: Get a community by ID
      description: |
        Retrieves detailed information about a specific community by its unique ID.
        This endpoint requires Signed Fetch authentication and returns the authenticated user's role in the community.
        Returns both public and private communities if the user has access.
        Includes voice chat status, member count, and community metadata.
      security:
        - SignedFetch: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the community.
      responses:
        '200':
          description: Community found
          content:
            application/json:
              schema:
                type: object
                required: &ref_12
                  - data
                properties: &ref_13
                  data:
                    type: object
                    required:
                      - id
                      - name
                      - description
                      - ownerAddress
                      - ownerName
                      - privacy
                      - visibility
                      - active
                      - membersCount
                      - role
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      description:
                        type: string
                      ownerAddress:
                        type: string
                        description: ETH Address of the community owner
                      ownerName:
                        type: string
                        description: Display name of the community owner
                      privacy:
                        type: string
                        enum:
                          - public
                          - private
                      visibility:
                        type: string
                        enum:
                          - all
                          - unlisted
                      active:
                        type: boolean
                        description: Whether the community is active or it was logically deleted
                      membersCount:
                        type: integer
                        description: Number of members in the community
                      role:
                        type: string
                        enum:
                          - owner
                          - moderator
                          - member
                          - none
                        description: Role of the authenticated user in this community
                      thumbnails:
                        type: object
                        additionalProperties:
                          type: string
                        description: Map of thumbnail URLs by size/type
                      voiceChatStatus:
                        type: object
                        nullable: true
                        properties:
                          isActive:
                            type: boolean
                          participantCount:
                            type: integer
                          moderatorCount:
                            type: integer
                        description: Voice chat status for the community (null if no active voice chat)
        '401':
          description: Unauthorized - Signed Fetch required
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '404':
          description: Community not found
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
      tags:
        - Communities
    put:
      operationId: updateCommunity
      summary: Update a community
      description: |
        Updates a community's details including name, description, privacy settings, unlisted status, and thumbnail.
        This endpoint requires Signed Fetch authentication and only community owners can update.
      security:
        - SignedFetch: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the community.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Community name
                description:
                  type: string
                  description: Community description
                placeIds:
                  type: string
                  description: JSON array of place IDs to replace all current community places
                privacy:
                  type: string
                  enum:
                    - public
                    - private
                  description: Community privacy setting
                visibility:
                  type: string
                  enum:
                    - all
                    - unlisted
                  description: Community visibility setting
                thumbnail:
                  type: string
                  format: binary
                  description: Community thumbnail image
      responses:
        '200':
          description: Community updated successfully
          content:
            application/json:
              schema:
                type: object
                required: &ref_14
                  - message
                  - data
                properties: &ref_15
                  message:
                    type: string
                    description: A message describing the result
                  data:
                    type: object
                    required:
                      - id
                      - name
                      - description
                      - ownerAddress
                      - privacy
                      - visibility
                      - active
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      description:
                        type: string
                      ownerAddress:
                        type: string
                      privacy:
                        type: string
                        enum:
                          - public
                          - private
                      visibility:
                        type: string
                        enum:
                          - all
                          - unlisted
                      active:
                        type: boolean
                      thumbnails:
                        type: object
                        additionalProperties:
                          type: string
                        description: A map of thumbnail types to URLs. The key is the thumbnail type (e.g. "raw") and the value is the URL.
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '401':
          description: Unauthorized - Signed Fetch required or not owner
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '404':
          description: Community not found
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
      tags:
        - Communities
    patch:
      operationId: patchCommunity
      summary: Update a community partially
      description: |
        Partially updates a community's properties. Currently supports updating the Editor's Choice flag.
        This endpoint requires Signed Fetch authentication and only global moderators can update Editor's Choice.
      security:
        - SignedFetch: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the community.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - editorsChoice
              properties:
                editorsChoice:
                  type: boolean
                  description: Whether the community should be marked as Editor's Choice. Only global moderators can update this field.
      responses:
        '204':
          description: Community updated successfully
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '401':
          description: Unauthorized - Signed Fetch required or insufficient permissions (only global moderators can update Editor's Choice)
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '404':
          description: Community not found
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
      tags:
        - Communities
    delete:
      operationId: deleteCommunity
      summary: Delete a community
      description: |
        Deletes a community.
        This endpoint requires Signed Fetch authentication.
      security:
        - SignedFetch: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the community.
      responses:
        '204':
          description: Community deleted successfully
        '401':
          description: Unauthorized - Signed Fetch required
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '404':
          description: Community not found
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
      tags:
        - Communities
  /v1/communities/{id}/members:
    get:
      operationId: listCommunityMembers
      summary: List community members
      description: |
        Lists all members of a specific community with their profiles and roles.
        This endpoint has optional Signed Fetch authentication.
        When not signed, it only returns members of public communities.
        When signed, it returns all members if the user has access to the community, including friendship status with each member.
        Can be filtered to show only online members.
      security:
        - SignedFetch: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the community.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
          description: Number of members per page.
        - name: offset
          in: query
          required: false
          schema:
            type: integer
          description: Number of members to skip.
        - name: onlyOnline
          in: query
          required: false
          schema:
            type: boolean
          description: Filter to show only online members.
      responses:
        '200':
          description: Members found
          content:
            application/json:
              schema:
                type: object
                required: &ref_16
                  - data
                properties: &ref_17
                  data:
                    allOf:
                      - type: object
                        required: *ref_0
                        properties: *ref_1
                      - type: object
                        properties:
                          results:
                            type: array
                            items:
                              type: object
                              required:
                                - address
                                - role
                                - joinedAt
                                - name
                                - hasClaimedName
                                - profilePictureUrl
                                - friendshipStatus
                              properties:
                                address:
                                  type: string
                                  description: ETH Address of the member
                                role:
                                  type: string
                                  enum:
                                    - owner
                                    - moderator
                                    - member
                                  description: Role of the member in the community
                                joinedAt:
                                  type: string
                                  format: date-time
                                  description: When the member joined the community
                                name:
                                  type: string
                                  description: Display name of the member
                                hasClaimedName:
                                  type: boolean
                                  description: Whether the member has claimed their name
                                profilePictureUrl:
                                  type: string
                                  description: URL of the member profile picture
                                friendshipStatus:
                                  type: integer
                                  description: Friendship status code between the authenticated user and the member
        '401':
          description: Unauthorized - Signed Fetch required
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '404':
          description: Community not found
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
      tags:
        - Communities
    post:
      operationId: addCommunityMember
      summary: Add a member to a community
      description: |
        Adds a member to a community.
        This endpoint requires Signed Fetch authentication.
      security:
        - SignedFetch: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the community.
      responses:
        '204':
          description: Member added successfully
        '401':
          description: Unauthorized - Signed Fetch required
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '404':
          description: Community not found
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
      tags:
        - Communities
  /v1/communities/{id}/members/{memberAddress}:
    delete:
      operationId: removeCommunityMember
      summary: Remove a member from a community
      description: |
        Removes a member from a community.
        This endpoint requires Signed Fetch authentication.
      security:
        - SignedFetch: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the community.
        - name: memberAddress
          in: path
          required: true
          schema:
            type: string
          description: ETH address of the member to remove.
      responses:
        '204':
          description: Member removed successfully
        '401':
          description: Unauthorized - Signed Fetch required
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '404':
          description: Community or member not found
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
      tags:
        - Communities
    patch:
      operationId: updateMemberRole
      summary: Update member role
      description: |
        Updates the role of a member in a community.
        This endpoint requires Signed Fetch authentication.
      security:
        - SignedFetch: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the community.
        - name: memberAddress
          in: path
          required: true
          schema:
            type: string
          description: ETH address of the member to update.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - role
              properties:
                role:
                  type: string
                  enum:
                    - owner
                    - moderator
                    - member
                  description: New role for the member
      responses:
        '204':
          description: Member role updated successfully
        '401':
          description: Unauthorized - Signed Fetch required
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '404':
          description: Community or member not found
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
      tags:
        - Communities
  /v1/members/{address}/communities:
    get:
      operationId: getMemberCommunities
      summary: List communities for a member
      description: |
        Lists all communities a member belongs to.
        This endpoint requires Signed Fetch authentication.
      security:
        - SignedFetch: []
      parameters:
        - name: address
          in: path
          required: true
          schema:
            type: string
          description: ETH address of the member.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
          description: Number of communities per page.
        - name: offset
          in: query
          required: false
          schema:
            type: integer
          description: Number of communities to skip.
      responses:
        '200':
          description: Communities found
          content:
            application/json:
              schema:
                type: object
                required: &ref_18
                  - data
                properties: &ref_19
                  data:
                    allOf:
                      - type: object
                        required: *ref_0
                        properties: *ref_1
                      - type: object
                        properties:
                          results:
                            type: array
                            items:
                              type: object
                              required:
                                - id
                                - name
                                - ownerAddress
                                - active
                                - role
                              properties:
                                id:
                                  type: string
                                name:
                                  type: string
                                ownerAddress:
                                  type: string
                                active:
                                  type: boolean
                                role:
                                  type: string
                                  enum:
                                    - owner
                                    - moderator
                                    - member
                                thumbnails:
                                  type: object
                                  additionalProperties:
                                    type: string
                                  description: Map of thumbnail URLs by size/type
        '401':
          description: Unauthorized - Signed Fetch required
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
      tags:
        - Communities
    post:
      operationId: getMemberCommunitiesByIds
      summary: Get member communities by IDs
      description: |
        Validates a batch of community IDs and returns only those that exist and are visible to a user.
        This endpoint is used by other services (like worlds-content-server) to validate community IDs
        when storing access settings.

        **Authentication:**
        This endpoint requires Bearer token authentication (admin token).

        **Visibility Rules:**
        - Public communities are always visible
        - Private communities are only visible to their members
        - Banned users cannot see communities they are banned from

        **Usage:**
        - Caller provides a list of community IDs to validate
        - Response contains only the valid and visible communities
        - Caller should check that all requested IDs are present in the response

        **Limits:**
        - Maximum 50 community IDs per request
      security:
        - BearerAuth: []
      parameters:
        - name: address
          in: path
          required: true
          schema:
            type: string
          description: ETH address of the member to check visibility for.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: &ref_20
                - communityIds
              properties: &ref_21
                communityIds:
                  type: array
                  items:
                    type: string
                    format: uuid
                  minItems: 1
                  maxItems: 50
                  description: List of community IDs to validate (max 50)
      responses:
        '200':
          description: Valid and visible communities
          content:
            application/json:
              schema:
                type: object
                required: &ref_22
                  - data
                properties: &ref_23
                  data:
                    type: object
                    required:
                      - communities
                    properties:
                      communities:
                        type: array
                        items:
                          type: object
                          required:
                            - id
                          properties:
                            id:
                              type: string
                              format: uuid
                              description: Unique identifier of a valid and visible community
                        description: List of communities that exist and are visible to the user
        '400':
          description: Invalid request - malformed community IDs or exceeds limit
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '401':
          description: Unauthorized - Bearer token required
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
      tags:
        - Communities
  /v1/communities/{id}/bans:
    get:
      operationId: listBannedMembers
      summary: List banned members of a community
      description: |
        Lists all banned members of a specific community.
        This endpoint requires Signed Fetch authentication.
      security:
        - SignedFetch: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the community.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
          description: Number of banned members per page.
        - name: offset
          in: query
          required: false
          schema:
            type: integer
          description: Number of banned members to skip.
      responses:
        '200':
          description: Banned members found
          content:
            application/json:
              schema:
                type: object
                required: &ref_24
                  - data
                properties: &ref_25
                  data:
                    allOf:
                      - type: object
                        required: *ref_0
                        properties: *ref_1
                      - type: object
                        properties:
                          results:
                            type: array
                            items:
                              type: object
                              required:
                                - address
                                - bannedAt
                              properties:
                                address:
                                  type: string
                                  description: ETH Address of the banned member
                                bannedAt:
                                  type: string
                                  format: date-time
                                  description: When the member was banned
        '401':
          description: Unauthorized - Signed Fetch required
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '404':
          description: Community not found
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
      tags:
        - Communities
  /v1/communities/{id}/members/{memberAddress}/bans:
    post:
      operationId: banCommunityMember
      summary: Ban a member from a community
      description: |
        Bans a member from a community.
        This endpoint requires Signed Fetch authentication.
      security:
        - SignedFetch: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the community.
        - name: memberAddress
          in: path
          required: true
          schema:
            type: string
          description: ETH address of the member to ban.
      responses:
        '204':
          description: Member banned successfully
        '401':
          description: Unauthorized - Signed Fetch required
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '404':
          description: Community or member not found
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
      tags:
        - Communities
    delete:
      operationId: unbanCommunityMember
      summary: Unban a member from a community
      description: |
        Unbans a member from a community.
        This endpoint requires Signed Fetch authentication.
      security:
        - SignedFetch: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the community.
        - name: memberAddress
          in: path
          required: true
          schema:
            type: string
          description: ETH address of the member to unban.
      responses:
        '204':
          description: Member unbanned successfully
        '401':
          description: Unauthorized - Signed Fetch required
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '404':
          description: Community or member not found
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
      tags:
        - Communities
  /v1/communities/{id}/places:
    get:
      operationId: getCommunityPlaces
      summary: Get community places
      description: |
        Lists all places (Decentraland world locations) associated with a specific community.
        This endpoint has optional Signed Fetch authentication.
        When not signed, it only returns places of public communities.
        When signed, it returns all places if the user has access to the community or the community is public.
        Places are identified by their unique place IDs (UUIDs).
      security:
        - SignedFetch: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the community.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
          description: Number of places per page.
        - name: offset
          in: query
          required: false
          schema:
            type: integer
          description: Number of places to skip.
      responses:
        '200':
          description: Places found
          content:
            application/json:
              schema:
                type: object
                required: &ref_28
                  - data
                properties: &ref_29
                  data:
                    allOf:
                      - type: object
                        required: *ref_0
                        properties: *ref_1
                      - type: object
                        properties:
                          results:
                            type: array
                            items:
                              type: object
                              required: &ref_26
                                - id
                              properties: &ref_27
                                id:
                                  type: string
                                  format: uuid
                                  description: Unique identifier of the place
        '401':
          description: Unauthorized - Signed Fetch required
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '404':
          description: Community not found
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
      tags:
        - Communities
    post:
      operationId: addCommunityPlaces
      summary: Add places to community
      description: |
        Adds one or more places to a community.
        This endpoint requires Signed Fetch authentication.
        Duplicate places are ignored.
      security:
        - SignedFetch: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the community.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - placeIds
              properties:
                placeIds:
                  type: array
                  items:
                    type: string
                    format: uuid
                  description: Array of place IDs to add to the community
      responses:
        '204':
          description: Places added successfully
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '401':
          description: Unauthorized - Signed Fetch required
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '404':
          description: Community not found
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
      tags:
        - Communities
  /v1/communities/{id}/places/{placeId}:
    delete:
      operationId: removeCommunityPlace
      summary: Remove place from community
      description: |
        Removes a place from a community.
        This endpoint requires Signed Fetch authentication.
      security:
        - SignedFetch: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the community.
        - name: placeId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: The unique identifier of the place to remove.
      responses:
        '204':
          description: Place removed successfully
        '401':
          description: Unauthorized - Signed Fetch required
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '404':
          description: Community or place not found
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
      tags:
        - Communities
  /v1/communities/{address}/managed:
    get:
      operationId: getManagedCommunities
      summary: Get managed communities for an address
      description: |
        Lists all communities where the specified address is an owner or moderator.
        This endpoint requires admin authentication.
      security:
        - BearerAuth: []
      parameters:
        - name: address
          in: path
          required: true
          schema:
            type: string
          description: ETH address of the user to get managed communities for.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
          description: Number of communities per page.
        - name: offset
          in: query
          required: false
          schema:
            type: integer
          description: Number of communities to skip.
      responses:
        '200':
          description: Managed communities found
          content:
            application/json:
              schema:
                type: object
                required: &ref_30
                  - data
                properties: &ref_31
                  data:
                    allOf:
                      - type: object
                        required: *ref_0
                        properties: *ref_1
                      - type: object
                        properties:
                          results:
                            type: array
                            items:
                              type: object
                              required:
                                - id
                                - name
                                - ownerAddress
                                - active
                                - role
                              properties:
                                id:
                                  type: string
                                name:
                                  type: string
                                ownerAddress:
                                  type: string
                                active:
                                  type: boolean
                                role:
                                  type: string
                                  enum:
                                    - owner
                                    - moderator
        '401':
          description: Unauthorized - Admin token required
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
      tags:
        - Communities
  /v1/referral-progress:
    post:
      operationId: createReferralProgress
      summary: Create referral progress
      description: |
        Creates a referral relationship between a referrer and an invited user.
        This endpoint requires Signed Fetch authentication.
        The authenticated user becomes the "invited" user, and the referrer address is provided in the request body.
        This should be called when a user follows a referral link.
      security:
        - SignedFetch: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - referrer
              properties:
                referrer:
                  type: string
                  description: ETH address of the referrer
      responses:
        '204':
          description: Referral progress created successfully
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '401':
          description: Unauthorized - Signed Fetch required
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
      tags:
        - Referrals
    patch:
      operationId: updateReferralStatus
      summary: Update referral signed up status
      description: |
        Updates the referral progress status to signed up for the authenticated user.
        This endpoint requires Signed Fetch authentication.
      security:
        - SignedFetch: []
      responses:
        '204':
          description: Referral status updated successfully
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '401':
          description: Unauthorized - Signed Fetch required
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '404':
          description: Referral not found
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
      tags:
        - Referrals
    get:
      operationId: getReferralStats
      summary: Get invited users accepted stats
      description: |
        Retrieves the current users invited by a referral and the ones from the last time they were fetched, along with reward images containing the tier and URL information. This allows comparing the previously seen data with the current one.
        This endpoint requires Signed Fetch authentication.
      security:
        - SignedFetch: []
      responses:
        '200':
          description: Referral statistics found
          content:
            application/json:
              schema:
                type: object
                required: &ref_32
                  - invitedUsersAccepted
                  - invitedUsersAcceptedViewed
                  - rewardImages
                properties: &ref_33
                  invitedUsersAccepted:
                    type: integer
                    description: Current total number of users invited by the referral
                  invitedUsersAcceptedViewed:
                    type: integer
                    description: Total number of invited users recorded in the previous fetch
                  rewardImages:
                    type: array
                    description: Images url for each tier reached
                    items:
                      type: object
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '401':
          description: Unauthorized - Signed Fetch required
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
      tags:
        - Referrals
  /v1/referral-email:
    post:
      operationId: addReferralEmail
      summary: Add referral email
      description: |
        Associates an email address with a referral for the authenticated user.
        This endpoint requires Signed Fetch authentication.
      security:
        - SignedFetch: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
              properties:
                email:
                  type: string
                  format: email
                  description: Email address to associate with the referral
      responses:
        '204':
          description: Referral email added successfully
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '401':
          description: Unauthorized - Signed Fetch required
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
      tags:
        - Referrals
  /v1/communities/{id}/requests:
    get:
      operationId: getCommunityRequests
      summary: Get community requests
      description: |
        Lists all pending requests (invites and join requests) for a specific community.
        This endpoint requires Signed Fetch authentication and only community owners or moderators can access it.
        Returns detailed information about each request including the member's profile, friendship status with the authenticated user.
        Can be filtered by request type (invite or request_to_join).
      security:
        - SignedFetch: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the community.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
          description: Number of requests per page.
        - name: offset
          in: query
          required: false
          schema:
            type: integer
          description: Number of requests to skip.
        - name: type
          in: query
          required: false
          schema:
            type: string
            enum:
              - invite
              - request_to_join
          description: Filter requests by type (invite or request_to_join).
      responses:
        '200':
          description: Community requests found
          content:
            application/json:
              schema:
                type: object
                required: &ref_34
                  - data
                properties: &ref_35
                  data:
                    allOf:
                      - type: object
                        required: *ref_0
                        properties: *ref_1
                      - type: object
                        properties:
                          results:
                            type: array
                            items:
                              type: object
                              required:
                                - id
                                - communityId
                                - memberAddress
                                - type
                                - status
                                - name
                                - hasClaimedName
                                - profilePictureUrl
                                - friendshipStatus
                              properties:
                                id:
                                  type: string
                                  description: Unique identifier of the community request
                                communityId:
                                  type: string
                                  description: ID of the community
                                memberAddress:
                                  type: string
                                  description: ETH address of the member who made/received the request
                                type:
                                  type: string
                                  enum:
                                    - invite
                                    - request_to_join
                                  description: Type of request
                                status:
                                  type: string
                                  enum:
                                    - pending
                                    - accepted
                                    - rejected
                                    - cancelled
                                  description: Status of the request
                                name:
                                  type: string
                                  description: Display name of the member
                                hasClaimedName:
                                  type: boolean
                                  description: Whether the member has claimed their name
                                profilePictureUrl:
                                  type: string
                                  description: URL of the member profile picture
                                friendshipStatus:
                                  type: integer
                                  description: Friendship status code between the authenticated user and the member
        '401':
          description: Unauthorized - Signed Fetch required or insufficient permissions
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '404':
          description: Community not found
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
      tags:
        - Communities
    post:
      operationId: createCommunityRequest
      summary: Create community request
      description: |
        Creates a community request (invite or join request) for a specific member.
        This endpoint requires Signed Fetch authentication.
      security:
        - SignedFetch: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the community.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - targetedAddress
                - type
              properties:
                targetedAddress:
                  type: string
                  description: ETH address of the member to create the request for
                type:
                  type: string
                  enum:
                    - invite
                    - request_to_join
                  description: Type of request to create
      responses:
        '200':
          description: Community request created successfully
          content:
            application/json:
              schema:
                type: object
                required: &ref_36
                  - data
                properties: &ref_37
                  data:
                    type: object
                    required:
                      - id
                      - communityId
                      - memberAddress
                      - type
                      - status
                    properties:
                      id:
                        type: string
                        description: Unique identifier of the community request
                      communityId:
                        type: string
                        description: ID of the community
                      memberAddress:
                        type: string
                        description: ETH address of the member
                      type:
                        type: string
                        enum:
                          - invite
                          - request_to_join
                        description: Type of request
                      status:
                        type: string
                        enum:
                          - pending
                          - accepted
                          - rejected
                          - cancelled
                        description: Status of the request
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '401':
          description: Unauthorized - Signed Fetch required
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '404':
          description: Community not found
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
      tags:
        - Communities
  /v1/communities/{id}/requests/{requestId}:
    patch:
      operationId: updateCommunityRequestStatus
      summary: Update community request status
      description: |
        Updates the status of a community request (accept, reject, or cancel).
        This endpoint requires Signed Fetch authentication with proper permissions:
        - For invites: Only the invited user can accept/reject, community owners/moderators can cancel
        - For join requests: Only community owners/moderators can accept/reject, the requesting user can cancel
      security:
        - SignedFetch: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the community.
        - name: requestId
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the community request.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: &ref_38
                - intention
              properties: &ref_39
                intention:
                  type: string
                  enum:
                    - accepted
                    - rejected
                    - cancelled
                  description: Action to perform on the community request
      responses:
        '204':
          description: Community request status updated successfully
        '400':
          description: Invalid request or intention
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '401':
          description: Unauthorized - Signed Fetch required or insufficient permissions
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '404':
          description: Community or request not found
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
      tags:
        - Communities
  /v1/members/{address}/requests:
    get:
      operationId: getMemberRequests
      summary: Get member requests
      description: |
        Lists all pending requests (invites received and join requests sent) for a specific member.
        This endpoint requires Signed Fetch authentication and users can only access their own requests.
        Returns detailed community information for each request including voice chat status, member count, and friends in the community.
        Can be filtered by request type (invite or request_to_join).
      security:
        - SignedFetch: []
      parameters:
        - name: address
          in: path
          required: true
          schema:
            type: string
          description: ETH address of the member.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
          description: Number of requests per page.
        - name: offset
          in: query
          required: false
          schema:
            type: integer
          description: Number of requests to skip.
        - name: type
          in: query
          required: false
          schema:
            type: string
            enum:
              - invite
              - request_to_join
          description: Filter requests by type (invite or request_to_join).
      responses:
        '200':
          description: Member requests found
          content:
            application/json:
              schema:
                type: object
                required: &ref_40
                  - data
                properties: &ref_41
                  data:
                    allOf:
                      - type: object
                        required: *ref_0
                        properties: *ref_1
                      - type: object
                        properties:
                          results:
                            type: array
                            items:
                              type: object
                              required:
                                - id
                                - communityId
                                - memberAddress
                                - type
                                - status
                                - name
                                - description
                                - ownerAddress
                                - ownerName
                                - privacy
                                - membersCount
                                - role
                                - active
                                - friends
                                - voiceChatStatus
                              properties:
                                id:
                                  type: string
                                  description: Unique identifier of the community request
                                communityId:
                                  type: string
                                  description: ID of the community
                                memberAddress:
                                  type: string
                                  description: ETH address of the member for whom the request was made
                                type:
                                  type: string
                                  enum:
                                    - invite
                                    - request_to_join
                                  description: Type of request (invite received or join request sent)
                                status:
                                  type: string
                                  enum:
                                    - pending
                                    - accepted
                                    - rejected
                                    - cancelled
                                  description: Status of the request
                                name:
                                  type: string
                                  description: Name of the community
                                description:
                                  type: string
                                  description: Description of the community
                                ownerAddress:
                                  type: string
                                  description: ETH address of the community owner
                                ownerName:
                                  type: string
                                  description: Display name of the community owner
                                privacy:
                                  type: string
                                  enum:
                                    - public
                                    - private
                                  description: Privacy setting of the community
                                membersCount:
                                  type: integer
                                  description: Total number of members in the community
                                role:
                                  type: string
                                  enum:
                                    - none
                                    - Member
                                    - Moderator
                                    - Owner
                                  description: Current role of the user in this community
                                active:
                                  type: boolean
                                  description: Whether the community is active
                                friends:
                                  type: array
                                  items:
                                    type: string
                                  description: List of friends who are members of this community
                                voiceChatStatus:
                                  type: object
                                  required:
                                    - isActive
                                    - participantCount
                                    - moderatorCount
                                  properties:
                                    isActive:
                                      type: boolean
                                      description: Whether there is an active voice chat in the community
                                    participantCount:
                                      type: integer
                                      description: Number of participants in the voice chat
                                    moderatorCount:
                                      type: integer
                                      description: Number of moderators in the voice chat
                                  description: Voice chat status information for the community
        '401':
          description: Unauthorized - Signed Fetch required or accessing another user's requests
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
      tags:
        - Communities
  /v1/members/{address}/invites:
    get:
      operationId: getCommunityInvites
      summary: Get community invites for a user
      description: |
        Lists all communities where the authenticated user (inviter) is a member but the specified address (invitee) is not a member.
        This is used to render a list of potential communities to invite the user to.
        This endpoint requires Signed Fetch authentication.
      security:
        - SignedFetch: []
      parameters:
        - name: address
          in: path
          required: true
          schema:
            type: string
          description: ETH address of the user to check invite possibilities for (invitee).
      responses:
        '200':
          description: Community invites found
          content:
            application/json:
              schema:
                type: object
                required: &ref_42
                  - data
                properties: &ref_43
                  data:
                    type: array
                    items:
                      type: object
                      required:
                        - id
                        - name
                      properties:
                        id:
                          type: string
                          description: Unique identifier of the community
                        name:
                          type: string
                          description: Name of the community
                    description: List of communities where the inviter is a member but the invitee is not
        '400':
          description: Invalid request - Users cannot invite themselves
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '401':
          description: Unauthorized - Signed Fetch required
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
      tags:
        - Communities
  /v1/communities/{id}/posts/{postId}/like:
    post:
      operationId: likeCommunityPost
      summary: Like a community post
      description: |
        Likes a post in a community.
        This endpoint requires Signed Fetch authentication.
        Users can only like posts from communities they are members of.
      security:
        - SignedFetch: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the community.
        - name: postId
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the post.
      responses:
        '201':
          description: Post liked successfully
        '401':
          description: Unauthorized - Signed Fetch required or not a member of the community
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '404':
          description: Community or post not found
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
      tags:
        - Communities
    delete:
      operationId: unlikeCommunityPost
      summary: Unlike a community post
      description: |
        Unlikes a post in a community.
        This endpoint requires Signed Fetch authentication.
        Users can only unlike posts they have previously liked.
      security:
        - SignedFetch: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the community.
        - name: postId
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the post.
      responses:
        '204':
          description: Post unliked successfully
        '401':
          description: Unauthorized - Signed Fetch required
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '404':
          description: Community or post not found
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
      tags:
        - Communities
  /v1/community-voice-chats/active:
    get:
      operationId: getActiveCommunityVoiceChats
      summary: Get active community voice chats
      description: |
        Lists all active community voice chats visible to the authenticated user.
        This endpoint requires Signed Fetch authentication.
        Returns voice chats from communities the user is a member of, including participant counts,
        moderator counts, community information, and location data (positions and worlds).
      security:
        - SignedFetch: []
      responses:
        '200':
          description: Active community voice chats found
          content:
            application/json:
              schema:
                type: object
                required: &ref_44
                  - data
                properties: &ref_45
                  data:
                    type: object
                    required:
                      - activeChats
                      - total
                    properties:
                      activeChats:
                        type: array
                        items:
                          type: object
                          required:
                            - communityId
                            - participantCount
                            - moderatorCount
                            - isMember
                            - communityName
                            - positions
                            - worlds
                          properties:
                            communityId:
                              type: string
                              description: ID of the community
                            participantCount:
                              type: integer
                              description: Number of participants in the voice chat
                            moderatorCount:
                              type: integer
                              description: Number of moderators in the voice chat
                            isMember:
                              type: boolean
                              description: Whether the user is a member of the community
                            communityName:
                              type: string
                              description: Name of the community
                            communityImage:
                              type: string
                              description: URL of the community image
                            positions:
                              type: array
                              items:
                                type: string
                              description: Array of position coordinates
                            worlds:
                              type: array
                              items:
                                type: string
                              description: Array of world identifiers
                      total:
                        type: integer
                        description: Total number of active voice chats
        '401':
          description: Unauthorized - Signed Fetch required
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
      tags:
        - Community Voice Chats
  /v1/moderation/communities:
    get:
      operationId: getCommunitiesForModeration
      summary: Get all communities for moderation
      description: |
        Lists all communities for moderation purposes with detailed information.
        This endpoint requires Signed Fetch authentication and the user must be a global moderator.
        Global moderators are configured via feature flags.
      security:
        - SignedFetch: []
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
          description: Number of communities per page.
        - name: offset
          in: query
          required: false
          schema:
            type: integer
          description: Number of communities to skip.
        - name: search
          in: query
          required: false
          schema:
            type: string
          description: Search term to filter communities by name or description.
      responses:
        '200':
          description: Communities found
          content:
            application/json:
              schema:
                type: object
                required: &ref_46
                  - data
                properties: &ref_47
                  data:
                    allOf:
                      - type: object
                        required: *ref_0
                        properties: *ref_1
                      - type: object
                        properties:
                          results:
                            type: array
                            items:
                              type: object
                              required:
                                - id
                                - name
                                - description
                                - ownerAddress
                                - privacy
                                - visibility
                                - active
                                - membersCount
                              properties:
                                id:
                                  type: string
                                name:
                                  type: string
                                description:
                                  type: string
                                ownerAddress:
                                  type: string
                                privacy:
                                  type: string
                                  enum:
                                    - public
                                    - private
                                visibility:
                                  type: string
                                  enum:
                                    - all
                                    - unlisted
                                active:
                                  type: boolean
                                membersCount:
                                  type: integer
                                thumbnails:
                                  type: object
                                  additionalProperties:
                                    type: string
                                  description: Map of thumbnail URLs by size/type
        '401':
          description: Unauthorized - Signed Fetch required
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '403':
          description: Forbidden - Global moderator privileges required
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
      tags:
        - Communities
  /v1/communities/{id}/posts:
    get:
      operationId: listCommunityPosts
      summary: List community posts
      description: |
        Lists all posts from a specific community with pagination support.
        This endpoint has optional Signed Fetch authentication.
        When not signed, it only returns posts from public communities.
        When signed, it returns all posts if the user has access to the community, including the user's like status for each post.
        Posts are returned in reverse chronological order (newest first).
      security:
        - SignedFetch: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the community.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
          description: Number of posts per page (max 100).
        - name: offset
          in: query
          required: false
          schema:
            type: integer
          description: Number of posts to skip.
      responses:
        '200':
          description: Posts found
          content:
            application/json:
              schema:
                type: object
                required: &ref_48
                  - data
                properties: &ref_49
                  data:
                    type: object
                    required:
                      - posts
                      - total
                    properties:
                      posts:
                        type: array
                        items:
                          type: object
                          required: &ref_4
                            - id
                            - communityId
                            - authorAddress
                            - authorName
                            - authorProfilePictureUrl
                            - authorHasClaimedName
                            - content
                            - createdAt
                            - likesCount
                          properties: &ref_5
                            id:
                              type: string
                              format: uuid
                              description: Unique post identifier
                            communityId:
                              type: string
                              format: uuid
                              description: ID of the community this post belongs to
                            authorAddress:
                              type: string
                              description: Ethereum address of the post author
                            authorName:
                              type: string
                              description: Display name of the post author
                            authorProfilePictureUrl:
                              type: string
                              format: uri
                              description: URL of the author profile picture
                            authorHasClaimedName:
                              type: boolean
                              description: Whether the author has a claimed name
                            content:
                              type: string
                              description: Post content (1-1000 characters)
                            createdAt:
                              type: string
                              format: date-time
                              description: When the post was created
                            likesCount:
                              type: integer
                              description: Number of likes on this post
                            isLikedByUser:
                              type: boolean
                              description: Whether the authenticated user has liked this post (only present when user is authenticated)
                      total:
                        type: integer
                        description: Total number of posts in the community
        '401':
          description: Unauthorized - Signed Fetch required
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '404':
          description: Community not found
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
      tags:
        - Communities
    post:
      operationId: createCommunityPost
      summary: Create a community post
      description: |
        Creates a new post in a community.
        This endpoint requires Signed Fetch authentication and only community owners or moderators can create posts.
        Post content must be between 1 and 1000 characters.
        Returns the created post with author profile information.
      security:
        - SignedFetch: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the community.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: &ref_50
                - content
              properties: &ref_51
                content:
                  type: string
                  minLength: 1
                  maxLength: 1000
                  description: Post content (1-1000 characters)
      responses:
        '201':
          description: Post created successfully
          content:
            application/json:
              schema:
                type: object
                required: &ref_52
                  - data
                properties: &ref_53
                  data:
                    type: object
                    required: *ref_4
                    properties: *ref_5
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '401':
          description: Unauthorized - Signed Fetch required or insufficient permissions
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '404':
          description: Community not found
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
      tags:
        - Communities
  /v1/communities/{id}/posts/{postId}:
    delete:
      operationId: deleteCommunityPost
      summary: Delete a community post
      description: |
        Deletes a post from a community.
        This endpoint requires Signed Fetch authentication and only community owners or moderators can delete posts.
      security:
        - SignedFetch: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the community.
        - name: postId
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the post.
      responses:
        '204':
          description: Post deleted successfully
        '401':
          description: Unauthorized - Signed Fetch required or insufficient permissions
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '404':
          description: Community or post not found
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                required: *ref_2
                properties: *ref_3
      tags:
        - Communities
components:
  securitySchemes:
    SignedFetch:
      type: apiKey
      in: header
      name: Authorization
      description: |
        Signed Fetch authentication.
        See ADR-44 for more details about the authentication mechanism.
    BearerAuth:
      type: http
      scheme: bearer
      description: |
        Bearer token authentication for admin endpoints.
        Requires API_ADMIN_TOKEN.
  schemas:
    PaginatedResponse:
      type: object
      required: *ref_0
      properties: *ref_1
    GetCommunities200OkResponse:
      type: object
      required: *ref_6
      properties: *ref_7
    GetCommunitiesMinimal200OkResponse:
      type: object
      required: *ref_8
      properties: *ref_9
    ErrorResponse:
      type: object
      required: *ref_2
      properties: *ref_3
    CreateCommunity201OkResponse:
      type: object
      required: *ref_10
      properties: *ref_11
    GetCommunityById200OkResponse:
      type: object
      required: *ref_12
      properties: *ref_13
    UpdateCommunity200OkResponse:
      type: object
      required: *ref_14
      properties: *ref_15
    GetCommunityMembers200OkResponse:
      type: object
      required: *ref_16
      properties: *ref_17
    GetMemberCommunities200OkResponse:
      type: object
      required: *ref_18
      properties: *ref_19
    GetMemberCommunitiesByIdsRequest:
      type: object
      required: *ref_20
      properties: *ref_21
    GetMemberCommunitiesByIds200OkResponse:
      type: object
      required: *ref_22
      properties: *ref_23
    GetBannedMembers200OkResponse:
      type: object
      required: *ref_24
      properties: *ref_25
    CommunityPlace:
      type: object
      required: *ref_26
      properties: *ref_27
    GetCommunityPlaces200OkResponse:
      type: object
      required: *ref_28
      properties: *ref_29
    GetManagedCommunities200OkResponse:
      type: object
      required: *ref_30
      properties: *ref_31
    GetReferralStats200OkResponse:
      type: object
      required: *ref_32
      properties: *ref_33
    GetCommunityRequests200OkResponse:
      type: object
      required: *ref_34
      properties: *ref_35
    CreateCommunityRequest200OkResponse:
      type: object
      required: *ref_36
      properties: *ref_37
    UpdateCommunityRequestStatusRequest:
      type: object
      required: *ref_38
      properties: *ref_39
    GetMemberRequests200OkResponse:
      type: object
      required: *ref_40
      properties: *ref_41
    GetCommunityInvites200OkResponse:
      type: object
      required: *ref_42
      properties: *ref_43
    GetActiveCommunityVoiceChats200OkResponse:
      type: object
      required: *ref_44
      properties: *ref_45
    GetCommunitiesForModeration200OkResponse:
      type: object
      required: *ref_46
      properties: *ref_47
    CommunityPost:
      type: object
      required: *ref_4
      properties: *ref_5
    GetCommunityPosts200OkResponse:
      type: object
      required: *ref_48
      properties: *ref_49
    CreatePostRequest:
      type: object
      required: *ref_50
      properties: *ref_51
    CreatePost201OkResponse:
      type: object
      required: *ref_52
      properties: *ref_53
