openapi: 3.1.0
info:
  title: Sendbird Platform API
  description: >-
    The Sendbird Platform API provides server-side access to manage users, channels,
    messages, and moderation for in-app chat applications built on Sendbird. Supports
    group channels, open channels, direct messages, push notifications, and webhooks
    for real-time communication features.
  version: 3.0.0
  termsOfService: https://sendbird.com/terms-of-service/
  contact:
    name: Sendbird Support
    url: https://sendbird.com/contact-us/
  license:
    name: Proprietary
    url: https://sendbird.com/terms-of-service/

servers:
  - url: https://api-{application_id}.sendbird.com/v3
    description: Sendbird Platform API (replace {application_id} with your app ID)
    variables:
      application_id:
        default: YOUR_APP_ID
        description: Your Sendbird application ID

security:
  - apiTokenAuth: []

tags:
  - name: Users
    description: Operations for managing Sendbird users.
  - name: Channels
    description: Operations for managing group and open channels.
  - name: Messages
    description: Operations for sending and managing messages.
  - name: Moderation
    description: Operations for content moderation and user management.

paths:
  /users:
    get:
      operationId: listUsers
      summary: List Users
      description: >-
        Retrieves a list of users registered in the Sendbird application.
        Supports pagination and filtering by nickname.
      tags:
        - Users
      parameters:
        - name: token
          in: query
          description: Pagination token for the next page.
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of users to return (1-100).
          schema:
            type: integer
            default: 10
            minimum: 1
            maximum: 100
        - name: active_mode
          in: query
          description: Filter by user active mode.
          schema:
            type: string
            enum:
              - activated
              - deactivated
              - all
            default: all
        - name: show_bot
          in: query
          description: Whether to include bot users in results.
          schema:
            type: boolean
            default: false
        - name: user_ids
          in: query
          description: Comma-separated list of user IDs to filter.
          schema:
            type: string
        - name: nickname
          in: query
          description: Filter users by nickname (partial match).
          schema:
            type: string
        - name: nickname_startswith
          in: query
          description: Filter users whose nickname starts with this value.
          schema:
            type: string
      responses:
        '200':
          description: A list of users.
          content:
            application/json:
              schema:
                type: object
                properties:
                  users:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  next:
                    type: string
                    description: Pagination token for the next page.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createUser
      summary: Create a User
      description: >-
        Creates a new user in the Sendbird application. The user_id must be unique
        within the application.
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - user_id
                - nickname
                - profile_url
              properties:
                user_id:
                  type: string
                  description: Unique user ID.
                nickname:
                  type: string
                  description: Display nickname of the user.
                profile_url:
                  type: string
                  description: URL of the user profile image.
                issue_access_token:
                  type: boolean
                  description: Whether to generate an access token for the user.
                  default: false
                metadata:
                  type: object
                  description: Custom metadata key-value pairs.
                  additionalProperties:
                    type: string
      responses:
        '200':
          description: User created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /users/{user_id}:
    get:
      operationId: getUser
      summary: Get a User
      description: Retrieves information about a specific user.
      tags:
        - Users
      parameters:
        - $ref: '#/components/parameters/user_id'
      responses:
        '200':
          description: User details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateUser
      summary: Update a User
      description: Updates information of a specific user.
      tags:
        - Users
      parameters:
        - $ref: '#/components/parameters/user_id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                nickname:
                  type: string
                  description: Updated nickname.
                profile_url:
                  type: string
                  description: Updated profile image URL.
                metadata:
                  type: object
                  description: Updated metadata.
                  additionalProperties:
                    type: string
      responses:
        '200':
          description: User updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteUser
      summary: Delete a User
      description: Deletes a specific user from the Sendbird application.
      tags:
        - Users
      parameters:
        - $ref: '#/components/parameters/user_id'
      responses:
        '200':
          description: User deleted successfully.
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /group_channels:
    get:
      operationId: listGroupChannels
      summary: List Group Channels
      description: Retrieves a list of group channels in the Sendbird application.
      tags:
        - Channels
      parameters:
        - name: token
          in: query
          description: Pagination token.
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of channels to return.
          schema:
            type: integer
            default: 10
            maximum: 100
        - name: channel_url
          in: query
          description: Filter by specific channel URL.
          schema:
            type: string
        - name: members_include_in
          in: query
          description: Filter channels that include specific user IDs.
          schema:
            type: string
      responses:
        '200':
          description: A list of group channels.
          content:
            application/json:
              schema:
                type: object
                properties:
                  channels:
                    type: array
                    items:
                      $ref: '#/components/schemas/GroupChannel'
                  next:
                    type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createGroupChannel
      summary: Create a Group Channel
      description: Creates a new group channel for messaging between users.
      tags:
        - Channels
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                user_ids:
                  type: array
                  items:
                    type: string
                  description: List of user IDs to add to the channel.
                name:
                  type: string
                  description: Name of the group channel.
                channel_url:
                  type: string
                  description: Custom URL for the channel.
                cover_url:
                  type: string
                  description: URL for the channel cover image.
                is_distinct:
                  type: boolean
                  description: Whether to create a distinct channel for the user set.
                  default: false
                data:
                  type: string
                  description: Custom data string for the channel.
      responses:
        '200':
          description: Group channel created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupChannel'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /group_channels/{channel_url}:
    get:
      operationId: getGroupChannel
      summary: Get a Group Channel
      description: Retrieves details of a specific group channel.
      tags:
        - Channels
      parameters:
        - $ref: '#/components/parameters/channel_url'
      responses:
        '200':
          description: Group channel details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupChannel'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteGroupChannel
      summary: Delete a Group Channel
      description: Deletes a specific group channel.
      tags:
        - Channels
      parameters:
        - $ref: '#/components/parameters/channel_url'
      responses:
        '200':
          description: Group channel deleted successfully.
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'

  /group_channels/{channel_url}/messages:
    get:
      operationId: listMessages
      summary: List Messages
      description: Retrieves messages from a specific group channel.
      tags:
        - Messages
      parameters:
        - $ref: '#/components/parameters/channel_url'
        - name: message_ts
          in: query
          description: Unix timestamp to fetch messages around.
          schema:
            type: integer
        - name: prev_limit
          in: query
          description: Number of messages to retrieve before message_ts.
          schema:
            type: integer
            default: 15
            maximum: 200
        - name: next_limit
          in: query
          description: Number of messages to retrieve after message_ts.
          schema:
            type: integer
            default: 0
            maximum: 200
        - name: include
          in: query
          description: Whether to include the message at message_ts.
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: A list of messages.
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      $ref: '#/components/schemas/Message'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: sendMessage
      summary: Send a Message
      description: Sends a message to a specific group channel.
      tags:
        - Messages
      parameters:
        - $ref: '#/components/parameters/channel_url'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - message_type
                - user_id
              properties:
                message_type:
                  type: string
                  description: Type of message.
                  enum:
                    - MESG
                    - FILE
                    - ADMM
                user_id:
                  type: string
                  description: ID of the user sending the message.
                message:
                  type: string
                  description: Text content of the message.
                data:
                  type: string
                  description: Custom data string.
                custom_type:
                  type: string
                  description: Custom type for message categorization.
                mention_type:
                  type: string
                  enum:
                    - users
                    - channel
                  description: Type of mention.
                mentioned_user_ids:
                  type: array
                  items:
                    type: string
                  description: IDs of mentioned users.
      responses:
        '200':
          description: Message sent successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /users/{user_id}/ban:
    post:
      operationId: banUser
      summary: Ban a User from a Channel
      description: Bans a user from a specific channel for moderation purposes.
      tags:
        - Moderation
      parameters:
        - $ref: '#/components/parameters/user_id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - channel_url
              properties:
                channel_url:
                  type: string
                  description: URL of the channel to ban the user from.
                seconds:
                  type: integer
                  description: Duration of the ban in seconds. -1 for permanent ban.
                  default: -1
                description:
                  type: string
                  description: Reason for the ban.
      responses:
        '200':
          description: User banned successfully.
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /users/{user_id}/mute:
    post:
      operationId: muteUser
      summary: Mute a User in a Channel
      description: Mutes a user in a specific channel, preventing them from sending messages.
      tags:
        - Moderation
      parameters:
        - $ref: '#/components/parameters/user_id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - channel_url
              properties:
                channel_url:
                  type: string
                  description: URL of the channel to mute the user in.
                seconds:
                  type: integer
                  description: Duration of the mute in seconds.
                  default: -1
                description:
                  type: string
                  description: Reason for the mute.
      responses:
        '200':
          description: User muted successfully.
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

components:
  securitySchemes:
    apiTokenAuth:
      type: apiKey
      in: header
      name: Api-Token
      description: Sendbird API token obtained from the Sendbird Dashboard.

  parameters:
    user_id:
      name: user_id
      in: path
      required: true
      description: Unique identifier of the user.
      schema:
        type: string
    channel_url:
      name: channel_url
      in: path
      required: true
      description: URL of the channel.
      schema:
        type: string

  schemas:
    User:
      type: object
      properties:
        user_id:
          type: string
          description: Unique identifier of the user.
        nickname:
          type: string
          description: Display nickname.
        profile_url:
          type: string
          description: Profile image URL.
        is_online:
          type: boolean
          description: Whether the user is currently online.
        is_active:
          type: boolean
          description: Whether the user account is active.
        last_seen_at:
          type: integer
          description: Unix timestamp of last activity.
        access_token:
          type: string
          description: Access token for the user (returned when issue_access_token is true).
        metadata:
          type: object
          description: Custom metadata.
          additionalProperties:
            type: string
        created_at:
          type: integer
          description: Unix timestamp when the user was created.

    GroupChannel:
      type: object
      properties:
        channel_url:
          type: string
          description: Unique URL of the channel.
        name:
          type: string
          description: Name of the channel.
        cover_url:
          type: string
          description: Cover image URL.
        member_count:
          type: integer
          description: Number of members in the channel.
        joined_member_count:
          type: integer
          description: Number of joined members.
        unread_message_count:
          type: integer
          description: Number of unread messages.
        last_message:
          $ref: '#/components/schemas/Message'
        is_distinct:
          type: boolean
          description: Whether this is a distinct channel.
        created_at:
          type: integer
          description: Unix timestamp when the channel was created.
        data:
          type: string
          description: Custom data string.

    Message:
      type: object
      properties:
        message_id:
          type: integer
          description: Unique ID of the message.
        type:
          type: string
          description: Message type.
          enum:
            - MESG
            - FILE
            - ADMM
        message:
          type: string
          description: Text content of the message.
        user:
          $ref: '#/components/schemas/User'
        channel_url:
          type: string
          description: URL of the channel containing this message.
        created_at:
          type: integer
          description: Unix timestamp when the message was created.
        updated_at:
          type: integer
          description: Unix timestamp when the message was last updated.
        custom_type:
          type: string
          description: Custom type for message categorization.
        data:
          type: string
          description: Custom data string.
        mention_type:
          type: string
          description: Mention type.
        mentioned_users:
          type: array
          items:
            $ref: '#/components/schemas/User'
          description: Mentioned users.

    Error:
      type: object
      properties:
        error:
          type: boolean
          description: Indicates an error occurred.
        code:
          type: integer
          description: Sendbird error code.
        message:
          type: string
          description: Human-readable error message.

  responses:
    BadRequest:
      description: Bad request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized. API token is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Not found. The requested resource does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'