openapi: 3.0.3
info:
  title: HipChat REST API v2
  version: '2.0'
  summary: Historical OpenAPI for Atlassian's discontinued HipChat team chat platform.
  description: |
    The HipChat REST API v2 powered Atlassian's HipChat team chat platform. This OpenAPI document
    is a historical reconstruction based on the Atlassian developer documentation (developer.atlassian.com/server/hipchat)
    and the official client libraries published under github.com/hipchat. It is preserved for archival
    and migration research only.

    **Status: DISCONTINUED on February 15, 2019.** Slack acquired the HipChat and Stride IP from
    Atlassian on July 26, 2018 and the four products (HipChat Cloud, Stride, HipChat Server, HipChat Data
    Center) were sunset together. No production endpoints remain reachable.
  termsOfService: https://www.atlassian.com/legal/customer-agreement
  contact:
    name: Atlassian (historical)
    url: https://www.atlassian.com/migration/move-from-hipchat-to-slack
  license:
    name: Documentation reused under Atlassian Developer Terms
    url: https://developer.atlassian.com/platform/marketplace/atlassian-developer-terms/
  x-status: sunset
  x-lifecycle: discontinued
  x-sunset-date: '2019-02-15'
  x-end-of-sale: '2018-07-26'
  x-replacement: https://slack.com
servers:
- url: https://api.hipchat.com/v2
  description: HipChat Cloud (historical; no longer reachable)
- url: https://{hipchat-server-host}/v2
  description: HipChat Server / Data Center (historical; self-hosted, no longer supported)
  variables:
    hipchat-server-host:
      default: hipchat.example.com
security:
- BearerAuth: []
- QueryToken: []
tags:
- name: Rooms
  description: Create, read, update, archive, and notify chat rooms.
- name: Users
  description: Manage HipChat users and look up profile information.
- name: Messages
  description: Send and retrieve room messages and private messages.
- name: Webhooks
  description: Register and manage room webhooks.
- name: Emoticons
  description: Read and manage the emoticon catalog.
- name: Sessions
  description: Active XMPP / web sessions.
- name: OAuth Sessions
  description: OAuth 2 client credentials and add-on session management.
- name: Capabilities
  description: HipChat Connect add-on capability discovery.
- name: Add-ons
  description: Install, configure, and uninstall HipChat Connect add-ons.
paths:
  /capabilities:
    get:
      tags: [Capabilities]
      summary: Get HipChat Capabilities Descriptor
      description: Returns the capabilities document describing the API surface and OAuth endpoints of the
        HipChat installation. Used by HipChat Connect add-ons during installation.
      operationId: getCapabilities
      responses:
        '200':
          description: Capabilities descriptor.
          content:
            application/json:
              schema:
                type: object
  /oauth/token:
    post:
      tags: [OAuth Sessions]
      summary: Generate OAuth Access Token
      description: Exchange client credentials (or an authorization code) for a bearer access token. Used
        by HipChat Connect add-ons after installation.
      operationId: generateToken
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required: [grant_type]
              properties:
                grant_type:
                  type: string
                  enum: [client_credentials, authorization_code, password, refresh_token]
                username:
                  type: string
                password:
                  type: string
                scope:
                  type: string
                  description: Space-separated list of scopes.
      responses:
        '200':
          description: Access token issued.
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token: {type: string}
                  expires_in: {type: integer}
                  group_id: {type: integer}
                  group_name: {type: string}
                  scope: {type: string}
                  token_type: {type: string, enum: [bearer]}
  /room:
    get:
      tags: [Rooms]
      summary: Get All Rooms
      description: List all rooms in the HipChat group.
      operationId: getAllRooms
      parameters:
      - $ref: '#/components/parameters/StartIndex'
      - $ref: '#/components/parameters/MaxResults'
      - name: include-private
        in: query
        schema: {type: boolean, default: false}
      - name: include-archived
        in: query
        schema: {type: boolean, default: false}
      responses:
        '200':
          description: Page of rooms.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoomCollection'
    post:
      tags: [Rooms]
      summary: Create Room
      description: Create a new HipChat room owned by the authenticated user.
      operationId: createRoom
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RoomCreateRequest'
      responses:
        '201':
          description: Room created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoomReference'
  /room/{id_or_name}:
    parameters:
    - $ref: '#/components/parameters/RoomIdOrName'
    get:
      tags: [Rooms]
      summary: Get Room Details
      description: Returns room metadata, owner, privacy, topic, and integration settings.
      operationId: getRoom
      responses:
        '200':
          description: Room details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Room'
    put:
      tags: [Rooms]
      summary: Update Room
      description: Update mutable room fields (name, topic, privacy, owner, archived).
      operationId: updateRoom
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RoomUpdateRequest'
      responses:
        '204':
          description: Room updated.
    delete:
      tags: [Rooms]
      summary: Delete Room
      description: Permanently delete a room.
      operationId: deleteRoom
      responses:
        '204':
          description: Room deleted.
  /room/{id_or_name}/notification:
    parameters:
    - $ref: '#/components/parameters/RoomIdOrName'
    post:
      tags: [Rooms, Messages]
      summary: Send Room Notification
      description: |
        Send a notification message to a room. Subject to a separate flood-control rate limit of
        30 messages per minute per room (see `X-FloodControl-Limit` response headers).
      operationId: sendRoomNotification
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationRequest'
      responses:
        '204':
          description: Notification accepted.
  /room/{id_or_name}/message:
    parameters:
    - $ref: '#/components/parameters/RoomIdOrName'
    post:
      tags: [Rooms, Messages]
      summary: Send Room Message
      description: Send a message authored by the authenticated user to a room.
      operationId: sendRoomMessage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [message]
              properties:
                message: {type: string, maxLength: 10000}
      responses:
        '200':
          description: Message accepted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id: {type: string}
                  timestamp: {type: string, format: date-time}
  /room/{id_or_name}/history:
    parameters:
    - $ref: '#/components/parameters/RoomIdOrName'
    get:
      tags: [Rooms, Messages]
      summary: View Room History
      description: Returns the history of messages for the room.
      operationId: getRoomHistory
      parameters:
      - name: date
        in: query
        schema: {type: string, format: date-time}
      - name: timezone
        in: query
        schema: {type: string, default: UTC}
      - $ref: '#/components/parameters/StartIndex'
      - $ref: '#/components/parameters/MaxResults'
      - name: reverse
        in: query
        schema: {type: boolean, default: true}
      responses:
        '200':
          description: Message history page.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageCollection'
  /room/{id_or_name}/history/latest:
    parameters:
    - $ref: '#/components/parameters/RoomIdOrName'
    get:
      tags: [Rooms, Messages]
      summary: View Recent Room History
      description: Returns the most recent messages from a room with optional not-before filtering.
      operationId: getLatestRoomHistory
      parameters:
      - name: not-before
        in: query
        schema: {type: string}
      - name: timezone
        in: query
        schema: {type: string, default: UTC}
      - $ref: '#/components/parameters/MaxResults'
      responses:
        '200':
          description: Recent messages.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageCollection'
  /room/{id_or_name}/webhook:
    parameters:
    - $ref: '#/components/parameters/RoomIdOrName'
    get:
      tags: [Webhooks]
      summary: Get All Room Webhooks
      description: List webhooks registered against the room.
      operationId: getAllRoomWebhooks
      responses:
        '200':
          description: Webhook collection.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookCollection'
    post:
      tags: [Webhooks]
      summary: Create Room Webhook
      description: Register a webhook against a room for a specified event.
      operationId: createRoomWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookCreateRequest'
      responses:
        '201':
          description: Webhook created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
  /room/{id_or_name}/webhook/{webhook_id}:
    parameters:
    - $ref: '#/components/parameters/RoomIdOrName'
    - name: webhook_id
      in: path
      required: true
      schema: {type: string}
    get:
      tags: [Webhooks]
      summary: Get Room Webhook
      operationId: getRoomWebhook
      responses:
        '200':
          description: Webhook details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
    delete:
      tags: [Webhooks]
      summary: Delete Room Webhook
      operationId: deleteRoomWebhook
      responses:
        '204':
          description: Webhook deleted.
  /user:
    get:
      tags: [Users]
      summary: Get All Users
      description: List all users in the HipChat group.
      operationId: getAllUsers
      parameters:
      - $ref: '#/components/parameters/StartIndex'
      - $ref: '#/components/parameters/MaxResults'
      - name: include-guests
        in: query
        schema: {type: boolean, default: false}
      - name: include-deleted
        in: query
        schema: {type: boolean, default: false}
      responses:
        '200':
          description: User collection.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserCollection'
  /user/{id_or_email}:
    parameters:
    - name: id_or_email
      in: path
      required: true
      schema: {type: string}
    get:
      tags: [Users]
      summary: Get User Details
      operationId: getUser
      responses:
        '200':
          description: User profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
    put:
      tags: [Users]
      summary: Update User
      operationId: updateUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserUpdateRequest'
      responses:
        '204':
          description: User updated.
    delete:
      tags: [Users]
      summary: Delete User
      operationId: deleteUser
      responses:
        '204':
          description: User deleted.
  /user/{id_or_email}/message:
    parameters:
    - name: id_or_email
      in: path
      required: true
      schema: {type: string}
    post:
      tags: [Users, Messages]
      summary: Send Private Message To User
      description: Send a one-to-one private message. Requires the `send_message` scope.
      operationId: sendPrivateMessage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [message]
              properties:
                message: {type: string, maxLength: 10000}
                notify: {type: boolean, default: false}
                message_format: {type: string, enum: [text, html], default: html}
      responses:
        '204':
          description: Message accepted.
  /emoticon:
    get:
      tags: [Emoticons]
      summary: Get All Emoticons
      operationId: getAllEmoticons
      parameters:
      - $ref: '#/components/parameters/StartIndex'
      - $ref: '#/components/parameters/MaxResults'
      - name: type
        in: query
        schema: {type: string, enum: [group, global, all], default: all}
      responses:
        '200':
          description: Emoticon collection.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmoticonCollection'
  /emoticon/{emoticon_id_or_shortcut}:
    parameters:
    - name: emoticon_id_or_shortcut
      in: path
      required: true
      schema: {type: string}
    get:
      tags: [Emoticons]
      summary: Get Emoticon Details
      operationId: getEmoticon
      responses:
        '200':
          description: Emoticon details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Emoticon'
  /addon:
    post:
      tags: [Add-ons]
      summary: Install Add-on
      description: Register a HipChat Connect add-on by submitting its descriptor URL.
      operationId: installAddon
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [url]
              properties:
                url: {type: string, format: uri}
      responses:
        '201':
          description: Add-on installed.
  /addon/{addon_key_or_id}/installable/{installable_id}:
    parameters:
    - name: addon_key_or_id
      in: path
      required: true
      schema: {type: string}
    - name: installable_id
      in: path
      required: true
      schema: {type: string}
    delete:
      tags: [Add-ons]
      summary: Uninstall Add-on Installation
      operationId: uninstallAddon
      responses:
        '204':
          description: Add-on installation removed.
  /session:
    get:
      tags: [Sessions]
      summary: Get Active Sessions
      operationId: getActiveSessions
      responses:
        '200':
          description: Active sessions list.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items: {type: object}
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Pass the token as `Authorization: Bearer {token}`. Supports add-on, user, personal access,
        and room notification tokens.
    QueryToken:
      type: apiKey
      in: query
      name: auth_token
      description: Pass the token as the `auth_token` query parameter (legacy compatibility).
  parameters:
    RoomIdOrName:
      name: id_or_name
      in: path
      required: true
      description: Numeric room id or URL-encoded room name.
      schema: {type: string}
    StartIndex:
      name: start-index
      in: query
      schema: {type: integer, minimum: 0, default: 0}
    MaxResults:
      name: max-results
      in: query
      schema: {type: integer, minimum: 0, maximum: 1000, default: 100}
  schemas:
    RoomReference:
      type: object
      properties:
        id: {type: integer}
        name: {type: string}
        links:
          type: object
          properties:
            self: {type: string, format: uri}
    Room:
      allOf:
      - $ref: '#/components/schemas/RoomReference'
      - type: object
        properties:
          xmpp_jid: {type: string}
          statistics:
            type: object
            properties:
              messages_sent: {type: integer}
              last_active: {type: string, format: date-time}
          created: {type: string, format: date-time}
          is_archived: {type: boolean}
          privacy: {type: string, enum: [public, private]}
          is_guest_accessible: {type: boolean}
          topic: {type: string}
          participants:
            type: array
            items: {$ref: '#/components/schemas/UserReference'}
          owner:
            $ref: '#/components/schemas/UserReference'
          guest_access_url: {type: string, format: uri, nullable: true}
    RoomCollection:
      type: object
      properties:
        items:
          type: array
          items: {$ref: '#/components/schemas/RoomReference'}
        startIndex: {type: integer}
        maxResults: {type: integer}
        links:
          type: object
          properties:
            self: {type: string}
            next: {type: string}
    RoomCreateRequest:
      type: object
      required: [name]
      properties:
        name: {type: string, maxLength: 50}
        topic: {type: string, maxLength: 250}
        guest_access: {type: boolean, default: false}
        privacy: {type: string, enum: [public, private], default: public}
        owner_user_id: {type: string}
    RoomUpdateRequest:
      type: object
      properties:
        name: {type: string}
        topic: {type: string}
        is_archived: {type: boolean}
        privacy: {type: string, enum: [public, private]}
        owner:
          type: object
          properties:
            id: {type: string}
    NotificationRequest:
      type: object
      required: [message]
      properties:
        message: {type: string, maxLength: 10000}
        color: {type: string, enum: [yellow, green, red, purple, gray, random], default: yellow}
        notify: {type: boolean, default: false}
        message_format: {type: string, enum: [html, text], default: html}
        from: {type: string, maxLength: 64}
        attach_to: {type: string}
        card:
          type: object
          description: Optional rich-card payload (HipChat Cards).
    Message:
      type: object
      properties:
        id: {type: string}
        from:
          oneOf:
          - {$ref: '#/components/schemas/UserReference'}
          - type: object
            properties:
              name: {type: string}
        message: {type: string}
        date: {type: string, format: date-time}
        type: {type: string, enum: [message, notification, guest_access, topic]}
        color: {type: string}
        message_format: {type: string, enum: [html, text]}
        mentions:
          type: array
          items: {$ref: '#/components/schemas/UserReference'}
        file:
          type: object
          nullable: true
    MessageCollection:
      type: object
      properties:
        items:
          type: array
          items: {$ref: '#/components/schemas/Message'}
        startIndex: {type: integer}
        maxResults: {type: integer}
    UserReference:
      type: object
      properties:
        id: {type: integer}
        mention_name: {type: string}
        name: {type: string}
        links:
          type: object
          properties:
            self: {type: string, format: uri}
    User:
      allOf:
      - $ref: '#/components/schemas/UserReference'
      - type: object
        properties:
          email: {type: string, format: email}
          title: {type: string}
          presence:
            type: object
            properties:
              status: {type: string, enum: [chat, away, xa, dnd]}
              show: {type: string}
              idle: {type: integer}
              client:
                type: object
                properties:
                  type: {type: string}
                  version: {type: string}
          xmpp_jid: {type: string}
          is_group_admin: {type: boolean}
          is_guest: {type: boolean}
          is_deleted: {type: boolean}
          timezone: {type: string}
          last_active: {type: string, format: date-time}
          created: {type: string, format: date-time}
          photo_url: {type: string, format: uri}
    UserCollection:
      type: object
      properties:
        items:
          type: array
          items: {$ref: '#/components/schemas/UserReference'}
        startIndex: {type: integer}
        maxResults: {type: integer}
    UserUpdateRequest:
      type: object
      properties:
        name: {type: string}
        title: {type: string}
        mention_name: {type: string}
        is_group_admin: {type: boolean}
        timezone: {type: string}
        email: {type: string, format: email}
    Webhook:
      type: object
      properties:
        id: {type: string}
        name: {type: string}
        url: {type: string, format: uri}
        event:
          type: string
          enum: [room_message, room_notification, room_enter, room_exit, room_topic_change, room_archived,
            room_unarchived, room_deleted, room_created, room_file_upload]
        pattern: {type: string}
        authentication: {type: string, enum: [none, jwt], default: jwt}
        links:
          type: object
          properties:
            self: {type: string, format: uri}
    WebhookCreateRequest:
      type: object
      required: [url, event]
      properties:
        url: {type: string, format: uri}
        event: {type: string}
        pattern: {type: string}
        name: {type: string}
        authentication: {type: string, enum: [none, jwt], default: jwt}
    WebhookCollection:
      type: object
      properties:
        items:
          type: array
          items: {$ref: '#/components/schemas/Webhook'}
        startIndex: {type: integer}
        maxResults: {type: integer}
    Emoticon:
      type: object
      properties:
        id: {type: integer}
        shortcut: {type: string}
        url: {type: string, format: uri}
        creator:
          $ref: '#/components/schemas/UserReference'
        audio:
          type: array
          items:
            type: object
        height: {type: integer}
        width: {type: integer}
    EmoticonCollection:
      type: object
      properties:
        items:
          type: array
          items: {$ref: '#/components/schemas/Emoticon'}
        startIndex: {type: integer}
        maxResults: {type: integer}