Stream Chat Users API

openapi: 3.0.3
info:
  title: Stream Chat API (Server-side REST)
  description: >-
    Server-side REST API for Stream (GetStream.io) Chat. This is a curated subset
    of Stream's published Chat protocol (https://getstream.github.io/protocol),
    grounding the endpoints modeled in the API Evangelist catalog against the real
    base URL and paths. The Chat API is addressed at https://chat.stream-io-api.com.
    Every request carries the application `api_key` as a query parameter and is
    authenticated with a JWT sent in the `Authorization` header together with a
    `Stream-Auth-Type: jwt` header. Server-side tokens (no `user_id` claim) are
    used for the operations in this document; client tokens are used to open the
    real-time WebSocket connection modeled in the companion AsyncAPI document.

    Path and method choices here are taken from Stream's official
    chat-openapi.yaml (github.com/GetStream/protocol). Request and response bodies
    are represented generically; consult the linked protocol reference for the full
    schemas.
  version: '1.0'
  contact:
    name: API Evangelist
    url: https://apievangelist.com
    email: kin@apievangelist.com
  license:
    name: API documentation - Stream Terms
    url: https://getstream.io/legal/terms/
servers:
  - url: https://chat.stream-io-api.com
    description: Stream Chat API (edge, global)
security:
  - JWT: []
    ApiKey: []
tags:
  - name: Channels
    description: Query, create, update, truncate, and delete chat channels.
  - name: Messages
    description: Send, retrieve, update, delete, and search messages and replies.
  - name: Members
    description: Query and partially update channel members.
  - name: Reactions
    description: Add and remove emoji reactions on messages.
  - name: Threads
    description: Query and retrieve message threads.
  - name: Users
    description: Upsert, query, update, deactivate, and reactivate users.
  - name: Devices
    description: Register and manage push notification devices.
  - name: Moderation
    description: Ban, flag, and mute users, messages, and channels.
  - name: Permissions
    description: Inspect application permissions.
  - name: Roles
    description: List, create, and delete custom roles.
  - name: Campaigns
    description: Create and control bulk messaging campaigns.
  - name: Application
    description: Application-level utilities such as rate limits and search.
paths:
  /channels:
    post:
      operationId: QueryChannels
      tags:
        - Channels
      summary: Query channels
      description: >-
        Query the channels a user has access to, using a filter, sort, and
        pagination. Returns channel state including members, messages, reads,
        and channel configuration.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryChannelsRequest'
      responses:
        '200':
          description: A list of channels with their state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChannelsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /channels/{type}/{id}:
    parameters:
      - $ref: '#/components/parameters/ChannelType'
      - $ref: '#/components/parameters/ChannelId'
    post:
      operationId: UpdateChannel
      tags:
        - Channels
      summary: Update a channel (overwrite)
      description: Overwrite a channel's custom data and, optionally, its member set.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          $ref: '#/components/responses/Channel'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    patch:
      operationId: UpdateChannelPartial
      tags:
        - Channels
      summary: Partially update a channel
      description: Set or unset individual fields of a channel's custom data.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                set:
                  type: object
                unset:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          $ref: '#/components/responses/Channel'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    delete:
      operationId: DeleteChannel
      tags:
        - Channels
      summary: Delete a channel
      description: Delete a channel and all of its messages (soft or hard delete).
      parameters:
        - name: hard_delete
          in: query
          schema:
            type: boolean
      responses:
        '200':
          $ref: '#/components/responses/Channel'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /channels/{type}/{id}/query:
    parameters:
      - $ref: '#/components/parameters/ChannelType'
      - $ref: '#/components/parameters/ChannelId'
    post:
      operationId: GetOrCreateChannel
      tags:
        - Channels
      summary: Get or create a channel
      description: >-
        Fetch a channel's full state, creating it if it does not yet exist, and
        optionally start watching it. This is the primary way to load a channel.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                watch:
                  type: boolean
                state:
                  type: boolean
                presence:
                  type: boolean
                data:
                  type: object
      responses:
        '200':
          $ref: '#/components/responses/Channel'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /channels/{type}/{id}/message:
    parameters:
      - $ref: '#/components/parameters/ChannelType'
      - $ref: '#/components/parameters/ChannelId'
    post:
      operationId: SendMessage
      tags:
        - Messages
      summary: Send a message
      description: >-
        Send a new message to a channel. Emits a `message.new` event over the
        WebSocket to watchers of the channel.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendMessageRequest'
      responses:
        '201':
          $ref: '#/components/responses/Message'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /channels/{type}/{id}/member:
    parameters:
      - $ref: '#/components/parameters/ChannelType'
      - $ref: '#/components/parameters/ChannelId'
    patch:
      operationId: UpdateMemberPartial
      tags:
        - Members
      summary: Partially update a channel member
      description: >-
        Set or unset channel-scoped attributes for a member, such as
        notifications muted, pinned, or archived state.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                set:
                  type: object
                unset:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: The updated channel member.
          content:
            application/json:
              schema:
                type: object
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /channels/{type}/{id}/truncate:
    parameters:
      - $ref: '#/components/parameters/ChannelType'
      - $ref: '#/components/parameters/ChannelId'
    post:
      operationId: TruncateChannel
      tags:
        - Channels
      summary: Truncate a channel
      description: Remove all messages from a channel while keeping the channel itself.
      responses:
        '200':
          $ref: '#/components/responses/Channel'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /channels/{type}/{id}/read:
    parameters:
      - $ref: '#/components/parameters/ChannelType'
      - $ref: '#/components/parameters/ChannelId'
    post:
      operationId: MarkRead
      tags:
        - Channels
      summary: Mark a channel read
      description: >-
        Mark messages in a channel as read for a user, updating unread counts and
        emitting a `message.read` event.
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Read state updated.
          content:
            application/json:
              schema:
                type: object
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /members:
    get:
      operationId: QueryMembers
      tags:
        - Members
      summary: Query members
      description: Query channel members across the application with filtering and sorting.
      parameters:
        - name: payload
          in: query
          description: URL-encoded JSON query (filter_conditions, sort, limit, offset).
          schema:
            type: string
      responses:
        '200':
          description: A list of members.
          content:
            application/json:
              schema:
                type: object
                properties:
                  members:
                    type: array
                    items:
                      type: object
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /messages/{id}:
    parameters:
      - $ref: '#/components/parameters/MessageId'
    get:
      operationId: GetMessage
      tags:
        - Messages
      summary: Get a message
      responses:
        '200':
          $ref: '#/components/responses/Message'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: UpdateMessage
      tags:
        - Messages
      summary: Update a message (overwrite)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          $ref: '#/components/responses/Message'
    put:
      operationId: UpdateMessagePartial
      tags:
        - Messages
      summary: Partially update a message
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                set:
                  type: object
                unset:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          $ref: '#/components/responses/Message'
    delete:
      operationId: DeleteMessage
      tags:
        - Messages
      summary: Delete a message
      parameters:
        - name: hard
          in: query
          schema:
            type: boolean
      responses:
        '200':
          $ref: '#/components/responses/Message'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /messages/{id}/reaction:
    parameters:
      - $ref: '#/components/parameters/MessageId'
    post:
      operationId: SendReaction
      tags:
        - Reactions
      summary: Send a reaction
      description: Add an emoji reaction to a message, emitting a `reaction.new` event.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                reaction:
                  type: object
                  properties:
                    type:
                      type: string
                      example: like
                    score:
                      type: integer
      responses:
        '201':
          $ref: '#/components/responses/Message'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /messages/{id}/reaction/{type}:
    parameters:
      - $ref: '#/components/parameters/MessageId'
      - name: type
        in: path
        required: true
        description: The reaction type to remove (e.g. like).
        schema:
          type: string
    delete:
      operationId: DeleteReaction
      tags:
        - Reactions
      summary: Delete a reaction
      description: Remove a user's reaction of a given type from a message.
      responses:
        '200':
          $ref: '#/components/responses/Message'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /messages/{parent_id}/replies:
    parameters:
      - name: parent_id
        in: path
        required: true
        description: The id of the parent message whose thread replies to fetch.
        schema:
          type: string
    get:
      operationId: GetReplies
      tags:
        - Messages
      summary: Get thread replies
      description: Paginate the replies under a parent (thread) message.
      responses:
        '200':
          description: A list of reply messages.
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      $ref: '#/components/schemas/Message'
  /threads:
    post:
      operationId: QueryThreads
      tags:
        - Threads
      summary: Query threads
      description: Query the threads a user participates in.
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: A list of threads.
          content:
            application/json:
              schema:
                type: object
                properties:
                  threads:
                    type: array
                    items:
                      type: object
  /threads/{message_id}:
    parameters:
      - name: message_id
        in: path
        required: true
        description: The parent message id identifying the thread.
        schema:
          type: string
    get:
      operationId: GetThread
      tags:
        - Threads
      summary: Get a thread
      responses:
        '200':
          description: The thread and its metadata.
          content:
            application/json:
              schema:
                type: object
    patch:
      operationId: UpdateThreadPartial
      tags:
        - Threads
      summary: Partially update a thread
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: The updated thread.
          content:
            application/json:
              schema:
                type: object
  /users:
    get:
      operationId: QueryUsers
      tags:
        - Users
      summary: Query users
      description: Query users with filtering, sorting, and pagination.
      parameters:
        - name: payload
          in: query
          description: URL-encoded JSON query (filter_conditions, sort, limit, offset).
          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'
    post:
      operationId: UpsertUsers
      tags:
        - Users
      summary: Upsert users
      description: Create or update a batch of users by id.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                users:
                  type: object
                  additionalProperties:
                    $ref: '#/components/schemas/User'
      responses:
        '201':
          description: The upserted users keyed by id.
          content:
            application/json:
              schema:
                type: object
        '429':
          $ref: '#/components/responses/TooManyRequests'
    patch:
      operationId: UpdateUsersPartial
      tags:
        - Users
      summary: Partially update users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                users:
                  type: array
                  items:
                    type: object
      responses:
        '200':
          description: The updated users.
          content:
            application/json:
              schema:
                type: object
  /users/{user_id}/deactivate:
    parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
    post:
      operationId: DeactivateUser
      tags:
        - Users
      summary: Deactivate a user
      description: Deactivate a user, preventing them from connecting or sending messages.
      responses:
        '200':
          description: The deactivated user.
          content:
            application/json:
              schema:
                type: object
  /devices:
    get:
      operationId: ListDevices
      tags:
        - Devices
      summary: List devices
      description: List the push devices registered for a user.
      parameters:
        - name: user_id
          in: query
          schema:
            type: string
      responses:
        '200':
          description: A list of devices.
          content:
            application/json:
              schema:
                type: object
                properties:
                  devices:
                    type: array
                    items:
                      $ref: '#/components/schemas/Device'
    post:
      operationId: CreateDevice
      tags:
        - Devices
      summary: Register a device
      description: Register a push device (APNs or Firebase) for a user.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Device'
      responses:
        '201':
          description: Device registered.
          content:
            application/json:
              schema:
                type: object
    delete:
      operationId: DeleteDevice
      tags:
        - Devices
      summary: Remove a device
      parameters:
        - name: id
          in: query
          required: true
          schema:
            type: string
        - name: user_id
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Device removed.
          content:
            application/json:
              schema:
                type: object
  /moderation/ban:
    post:
      operationId: Ban
      tags:
        - Moderation
      summary: Ban a user
      description: Ban a user globally or within a specific channel, optionally with a timeout.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                target_user_id:
                  type: string
                timeout:
                  type: integer
                reason:
                  type: string
                type:
                  type: string
                id:
                  type: string
      responses:
        '200':
          description: User banned.
          content:
            application/json:
              schema:
                type: object
    delete:
      operationId: Unban
      tags:
        - Moderation
      summary: Unban a user
      parameters:
        - name: target_user_id
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: User unbanned.
          content:
            application/json:
              schema:
                type: object
  /moderation/flag:
    post:
      operationId: Flag
      tags:
        - Moderation
      summary: Flag a message or user
      description: Flag a message or user for moderation review.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                target_message_id:
                  type: string
                target_user_id:
                  type: string
                reason:
                  type: string
      responses:
        '200':
          description: Flag created.
          content:
            application/json:
              schema:
                type: object
  /moderation/mute:
    post:
      operationId: MuteUser
      tags:
        - Moderation
      summary: Mute a user
      description: Mute one or more target users for the requesting user.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                target_ids:
                  type: array
                  items:
                    type: string
                timeout:
                  type: integer
      responses:
        '200':
          description: User(s) muted.
          content:
            application/json:
              schema:
                type: object
  /permissions:
    get:
      operationId: ListPermissions
      tags:
        - Permissions
      summary: List permissions
      description: List all permissions available in the application.
      responses:
        '200':
          description: A list of permissions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  permissions:
                    type: array
                    items:
                      type: object
  /permissions/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: GetPermission
      tags:
        - Permissions
      summary: Get a permission
      responses:
        '200':
          description: A single permission.
          content:
            application/json:
              schema:
                type: object
  /roles:
    get:
      operationId: ListRoles
      tags:
        - Roles
      summary: List roles
      description: List all roles defined in the application.
      responses:
        '200':
          description: A list of roles.
          content:
            application/json:
              schema:
                type: object
                properties:
                  roles:
                    type: array
                    items:
                      type: object
    post:
      operationId: CreateRole
      tags:
        - Roles
      summary: Create a role
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
      responses:
        '201':
          description: Role created.
          content:
            application/json:
              schema:
                type: object
  /roles/{name}:
    parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
    delete:
      operationId: DeleteRole
      tags:
        - Roles
      summary: Delete a role
      responses:
        '200':
          description: Role deleted.
          content:
            application/json:
              schema:
                type: object
  /campaigns:
    post:
      operationId: CreateCampaign
      tags:
        - Campaigns
      summary: Create a campaign
      description: Create a bulk messaging campaign targeting a user segment.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Campaign created.
          content:
            application/json:
              schema:
                type: object
  /campaigns/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: GetCampaign
      tags:
        - Campaigns
      summary: Get a campaign
      responses:
        '200':
          description: A single campaign.
          content:
            application/json:
              schema:
                type: object
    put:
      operationId: UpdateCampaign
      tags:
        - Campaigns
      summary: Update a campaign
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Campaign updated.
          content:
            application/json:
              schema:
                type: object
    delete:
      operationId: DeleteCampaign
      tags:
        - Campaigns
      summary: Delete a campaign
      responses:
        '200':
          description: Campaign deleted.
          content:
            application/json:
              schema:
                type: object
  /campaigns/{id}/start:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    post:
      operationId: StartCampaign
      tags:
        - Campaigns
      summary: Start a campaign
      responses:
        '200':
          description: Campaign started.
          content:
            application/json:
              schema:
                type: object
  /campaigns/{id}/stop:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    post:
      operationId: StopCampaign
      tags:
        - Campaigns
      summary: Stop a campaign
      responses:
        '200':
          description: Campaign stopped.
          content:
            application/json:
              schema:
                type: object
  /search:
    get:
      operationId: Search
      tags:
        - Application
      summary: Search messages
      description: Full-text search of messages across an application's channels.
      parameters:
        - name: payload
          in: query
          description: URL-encoded JSON search request (filter_conditions, query, sort, limit).
          schema:
            type: string
      responses:
        '200':
          description: Search results.
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
  /rate_limits:
    get:
      operationId: GetRateLimits
      tags:
        - Application
      summary: Get rate limits
      description: >-
        Return the rate limit quotas and current usage for the application,
        optionally filtered by platform and endpoint.
      parameters:
        - name: server_side
          in: query
          schema:
            type: boolean
        - name: android
          in: query
          schema:
            type: boolean
        - name: ios
          in: query
          schema:
            type: boolean
        - name: web
          in: query
          schema:
            type: boolean
        - name: endpoints
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Rate limit quotas per platform and endpoint.
          content:
            application/json:
              schema:
                type: object
components:
  securitySchemes:
    JWT:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        A Stream JWT sent in the `Authorization` header. Server-side tokens omit
        the `user_id` claim; a `Stream-Auth-Type: jwt` header must accompany the
        request.
    ApiKey:
      type: apiKey
      in: query
      name: api_key
      description: The application API key, sent as the `api_key` query parameter on every request.
  parameters:
    ChannelType:
      name: type
      in: path
      required: true
      description: The channel type, e.g. messaging, livestream, team, gaming, commerce.
      schema:
        type: string
    ChannelId:
      name: id
      in: path
      required: true
      description: The channel id, unique within the channel type.
      schema:
        type: string
    MessageId:
      name: id
      in: path
      required: true
      description: The unique id of the message.
      schema:
        type: string
  responses:
    Channel:
      description: A channel and its state.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ChannelStateResponse'
    Message:
      description: A message wrapped in a response envelope.
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                $ref: '#/components/schemas/Message'
              duration:
                type: string
    BadRequest:
      description: The request was malformed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIError'
    Unauthorized:
      description: Missing or invalid authentication.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIError'
    NotFound:
      description: The requested resource does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIError'
    TooManyRequests:
      description: >-
        Rate limit exceeded for this app, platform, and endpoint. Inspect the
        X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.
      headers:
        X-RateLimit-Limit:
          schema:
            type: integer
        X-RateLimit-Remaining:
          schema:
            type: integer
        X-RateLimit-Reset:
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIError'
  schemas:
    QueryChannelsRequest:
      type: object
      properties:
        filter_conditions:
          type: object
          description: MongoDB-style filter over channel fields.
        sort:
          type: array
          items:
            type: object
        limit:
          type: integer
        offset:
          type: integer
        watch:
          type: boolean
        state:
          type: boolean
        presence:
          type: boolean
    ChannelsResponse:
      type: object
      properties:
        channels:
          type: array
          items:
            $ref: '#/components/schemas/ChannelStateResponse'
        duration:
          type: string
    ChannelStateResponse:
      type: object
      properties:
        channel:
          $ref: '#/components/schemas/Channel'
        messages:
          type: array
          items:
            $ref: '#/components/schemas/Message'
        members:
          type: array
          items:
            type: object
        read:
          type: array
          items:
            type: object
        duration:
          type: string
    Channel:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
        cid:
          type: string
          description: The composite channel id, "{type}:{id}".
        member_count:
          type: integer
        created_by:
          $ref: '#/components/schemas/User'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    SendMessageRequest:
      type: object
      required:
        - message
      properties:
        message:
          type: object
          properties:
            text:
              type: string
            attachments:
              type

# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/getstream/refs/heads/main/openapi/getstream-openapi.yml