Vanilla Forums Discussions API

openapi: 3.0.3
info:
  description: API access to your community.
  title: Vanilla Addons Discussions API
  version: '2.0'
servers:
- url: https://open.vanillaforums.com/api/v2
tags:
- name: Discussions
paths:
  /comments/list:
    delete:
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: An array of comment IDs.
              properties:
                commentIDs:
                  type: array
                  items:
                    type: integer
                  example:
                  - 2452
                  - 14253
                  - 14124
                deleteMethod:
                  enum:
                  - full
                  - tombstone
                  type: string
      responses:
        '202':
          $ref: '#/components/responses/TrackingSlipResponse'
        '204':
          description: Success
        '403':
          $ref: '#/components/responses/PermissionError'
        '408':
          $ref: '#/components/responses/LongRunnerResponse'
      tags:
      - Discussions
      summary: Delete a list of comments.
      x-addon: vanilla
  /discussions:
    get:
      parameters:
      - name: discussionID
        description: Filter by a range or CSV of discussion IDs.
        in: query
        schema:
          $ref: '#/components/schemas/RangeExpression'
      - name: categoryID
        description: Filter by a category.
        in: query
        schema:
          type: integer
      - $ref: '#/components/parameters/DateInserted'
      - $ref: '#/components/parameters/DateUpdated'
      - $ref: '#/components/parameters/DateLastComment'
      - name: slotType
        description: Filter to discussions created within a certain timeframe. Daily, Weekly, Monthly, Yearly, or all time.
        in: query
        schema:
          type: string
          enum:
          - d
          - w
          - m
          - y
          - a
      - name: siteSectionID
        description: 'Filter discussions by site section ID (ex. subcommunity).

          The subcommunity ID or folder can be used if you use [smart IDs](https://success.vanillaforums.com/kb/articles/46-smart-ids).

          The query looks like:


          ```

          siteSectionID=$subcommunityID:{id|folder}

          ```'
        in: query
        schema:
          type: string
      - name: tagID
        description: Filter discussion by a range of tag IDs.
        in: query
        schema:
          $ref: '#/components/schemas/RangeExpression'
      - name: tagOperator
        description: Either 'and' or 'or'. 'or' logic means a post only needs 1 of the provided tags. 'and' means it needs all of them.
        in: query
        schema:
          type: string
          enum:
          - and
          - or
          default: or
      - name: type
        description: Filter by discussion type, or comma separated list.
        in: query
        schema:
          type: string
        x-filter:
          field: d.Type
      - name: postTypeID
        description: Filter by one or more postTypeIDs.
        in: query
        schema:
          type: string
      - name: status
        description: Filter questions by status (accepted, answered, unanswered).
        in: query
        schema:
          type: string
        x-filter:
          field: d.QnA
      - name: excludeHiddenCategories
        description: Exclude discussions from categories that has the `HideAllDiscussions` option set to true.
        in: query
        required: false
        schema:
          default: false
          type: boolean
      - name: followed
        description: 'Only fetch discussions from followed categories. Pinned discussions are mixed in.

          '
        in: query
        required: false
        schema:
          default: false
          type: boolean
      - name: userFollowed
        description: 'Only fetch discussions from users the current user is following. Requires authentication. Returns empty array for guest users or users who follow no one.

          '
        in: query
        required: false
        schema:
          default: false
          type: boolean
      - name: score
        description: Filter by score.
        in: query
        schema:
          type: integer
      - name: pinned
        description: 'Whether or not to include pinned discussions. If true, only return pinned discussions. Cannot be used with the pinOrder parameter.

          '
        in: query
        schema:
          type: boolean
      - name: pinOrder
        description: 'If including pinned posts, in what order should they be integrated? When "first", discussions pinned to a specific category will only be affected if the discussion''s category is passed as the categoryID parameter. Cannot be used with the pinned parameter.

          Must be one of: "first", "mixed".

          '
        in: query
        schema:
          type: string
          default: first
          enum:
          - first
          - mixed
      - name: hasComments
        description: Optionally only include discussions that have/doesn't have comments.
        in: query
        required: false
        schema:
          type: boolean
      - $ref: '#/components/parameters/Page'
      - name: limit
        description: 'Desired number of items per page. **Note that you may not get the exact number of records back as specified with the limit unless you also specify pinOrder=mixed**. This is an optimization for pinned (i.e. announcement) discussion handling.

          '
        in: query
        schema:
          type: integer
          default: 30
          maximum: 100
          minimum: 1
      - name: sort
        description: Sort the results.
        in: query
        schema:
          type: string
          enum:
          - dateLastComment
          - dateInserted
          - discussionID
          - -dateLastComment
          - -dateInserted
          - -discussionID
      - name: insertUserID
        description: 'Filter by author.

          '
        in: query
        schema:
          type: integer
        x-filter:
          field: d.InsertUserID
      - name: insertUserRoleID
        description: Filter by author role. One or more roleIDs can be passed in a CSV.
        in: query
        schema:
          type: string
      - name: insertUserRankID
        description: Filter by author rank. One or more rankIDs can be passed in a CSV.
        in: query
        x-addon: ranks
        schema:
          type: string
      - $ref: '#/components/parameters/discussionExpand'
      - name: resolved
        description: Filter by resolved status.
        in: query
        schema:
          type: boolean
        x-filter:
          field: d.Resolved
      - name: bookmarkUserID
        description: Bookmarked by the UserID.
        in: query
        schema:
          type: integer
        allowEmptyValue: false
      - name: participatedUserID
        description: Commented (participated) on by the UserID.
        in: query
        schema:
          type: integer
        allowEmptyValue: false
      - name: reactionType
        description: Discussions for which the user has given the specified reaction.
        in: query
        schema:
          type: string
      - name: statusID
        description: List of statusIDs to filter discussion by.
        in: query
        schema:
          type: array
          items:
            type: integer
      - name: internalStatusID
        description: List of internalStatusIDs to filter discussion by.
        in: query
        schema:
          type: array
          items:
            type: integer
      - name: suggested
        description: Filter discussion list based on user interests.
        in: query
        schema:
          type: boolean
        x-feature: suggestedContent.enabled
      - name: excerptLength
        description: Length of excerpts.
        in: query
        schema:
          type: integer
      - name: excludedCategoryIDs
        description: Category IDs to exclude.
        in: query
        schema:
          type: array
          items:
            type: integer
      - $ref: '#/components/parameters/PostFieldFilters'
      - name: fields
        in: query
        style: form
        description: Only return fields with these keys from the output. Use dot notation for nested fields.
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/Discussion'
                type: array
          description: Success
      tags:
      - Discussions
      summary: List discussions.
      x-addon: vanilla
    post:
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Discussion'
          description: Success
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostPremoderation'
          description: Premoderation
      tags:
      - Discussions
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DiscussionPost'
        required: true
      summary: Add a discussion.
      x-addon: vanilla
  /discussions/bookmarked:
    get:
      parameters:
      - $ref: '#/components/parameters/Page'
      - description: 'Desired number of items per page.

          '
        in: query
        name: limit
        schema:
          type: integer
          default: 30
          maximum: 100
          minimum: 1
      - $ref: '#/components/parameters/discussionExpand'
      - name: fields
        in: query
        style: form
        description: Only return fields with these keys from the output. Use dot notation for nested fields.
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/Discussion'
                type: array
          description: Success
      tags:
      - Discussions
      summary: Get a list of the current user's bookmarked discussions.
      x-addon: vanilla
  /discussions/close:
    patch:
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: An array of discussion IDs.
              properties:
                discussionIDs:
                  type: array
                  items:
                    type: integer
                closed:
                  description: Whether to close (true) or open (false) this set of discussions.
                  type: boolean
      responses:
        '200':
          description: Success
        '202':
          $ref: '#/components/responses/TrackingSlipResponse'
        '403':
          $ref: '#/components/responses/PermissionError'
        '408':
          $ref: '#/components/responses/LongRunnerResponse'
      tags:
      - Discussions
      summary: Close/open a list of discussions.
      x-addon: vanilla
  /discussions/idea:
    x-addon: ideation
    post:
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Discussion'
          description: Success
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostPremoderation'
          description: Premoderation
      tags:
      - Discussions
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DiscussionPost'
        required: true
      summary: Add an idea.
      x-addon: vanilla
  /discussions/list:
    delete:
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: An array of discussion IDs.
              properties:
                discussionIDs:
                  type: array
                  items:
                    type: integer
                  example:
                  - 2452
                  - 14253
                  - 14124
      responses:
        '202':
          $ref: '#/components/responses/TrackingSlipResponse'
        '204':
          description: Success
        '403':
          $ref: '#/components/responses/PermissionError'
        '408':
          $ref: '#/components/responses/LongRunnerResponse'
      tags:
      - Discussions
      summary: Delete a list of discussions.
      x-addon: vanilla
  /discussions/merge:
    patch:
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                discussionIDs:
                  description: An array of discussion IDs to merge together.
                  type: array
                  items:
                    type: integer
                  example:
                  - 2052
                  - 2053
                  - 5602
                destinationDiscussionID:
                  description: The discussionID that everything will be merged into.
                  type: integer
                  example: 2052
                addRedirects:
                  description: If a redirect discussion needs to be created.
                  type: boolean
                  example: true
      responses:
        '200':
          description: Success
        '202':
          $ref: '#/components/responses/TrackingSlipResponse'
        '403':
          $ref: '#/components/responses/PermissionError'
        '408':
          $ref: '#/components/responses/LongRunnerResponse'
      tags:
      - Discussions
      summary: Merge discussions.
      x-addon: vanilla
  /discussions/move:
    patch:
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: An array of discussion IDs.
              properties:
                discussionIDs:
                  type: array
                  items:
                    type: integer
                categoryID:
                  description: The category ID to move discussions into.
                  type: integer
                addRedirects:
                  description: If a redirect discussion needs to be created.
                  type: boolean
                postTypeID:
                  description: The post type ID to associate with the moved discussion.
                  type: string
      responses:
        '200':
          description: Success
        '202':
          $ref: '#/components/responses/TrackingSlipResponse'
        '403':
          $ref: '#/components/responses/PermissionError'
        '408':
          $ref: '#/components/responses/LongRunnerResponse'
      tags:
      - Discussions
      summary: Move a list of discussions.
      x-addon: vanilla
  /discussions/muted:
    get:
      parameters:
      - $ref: '#/components/parameters/Page'
      - description: 'Desired number of items per page.

          '
        in: query
        name: limit
        schema:
          type: integer
          default: 30
          maximum: 100
          minimum: 1
      - $ref: '#/components/parameters/discussionExpand'
      - name: fields
        in: query
        style: form
        description: Only return fields with these keys from the output. Use dot notation for nested fields.
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/Discussion'
                type: array
          description: Success
      tags:
      - Discussions
      summary: Get a list of the current user's muted discussions.
      x-addon: vanilla
  /discussions/poll:
    x-addon: polls
    post:
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Discussion'
          description: Success
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostPremoderation'
          description: Premoderation
      tags:
      - Discussions
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DiscussionPost'
        required: true
      summary: Add a poll.
      x-addon: vanilla
  /discussions/question:
    x-addon: qna
    post:
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Discussion'
          description: Success
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostPremoderation'
          description: Premoderation
      tags:
      - Discussions
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DiscussionPost'
        required: true
      summary: Add a discussion.
      x-addon: vanilla
  /discussions/resolve-bulk:
    post:
      summary: Mark all discussions you can triage as resolved.
      responses:
        '201':
          description: Success
      tags:
      - Discussions
      x-addon: vanilla
  /discussions/search:
    get:
      parameters:
      - description: 'The numeric ID of a category to limit search results to.

          '
        in: query
        name: categoryID
        schema:
          type: integer
      - description: 'Limit results to those in followed categories. Cannot be used with the categoryID parameter.

          '
        in: query
        name: followed
        schema:
          type: boolean
      - description: 'Search terms.

          '
        in: query
        name: query
        required: true
        schema:
          minLength: 1
          type: string
      - $ref: '#/components/parameters/Page'
      - description: 'Desired number of items per page.

          '
        in: query
        name: limit
        schema:
          type: integer
          default: 30
          maximum: 100
          minimum: 1
      - description: 'Expand associated records.

          '
        in: query
        name: expand
        schema:
          default: false
          type: boolean
      - name: fields
        in: query
        style: form
        description: Only return fields with these keys from the output. Use dot notation for nested fields.
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/Discussion'
                type: array
          description: Success
      tags:
      - Discussions
      summary: Search discussions.
      x-addon: vanilla
  /discussions/split:
    post:
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                newPost:
                  type: object
                  description: Date about new discussion to create.
                  properties:
                    name:
                      description: Name of the new discussion.
                      type: string
                    body:
                      description: The body of the discussion.
                      type: string
                    format:
                      $ref: '#/components/schemas/Format'
                    categoryID:
                      description: Category ID for the new discussion.
                      type: integer
                    postType:
                      description: Post type of the discussion.
                      type: string
                    authorType:
                      description: Author of the new discussion.
                      type: string
                      enum:
                      - me
                      - System
                  required:
                  - name
                  - categoryID
                  - postType
                  - authorType
                commentIDs:
                  description: Comment IDs to split out into its own discussion.
                  type: array
                  items:
                    type: integer
              required:
              - commentIDs
              - newPost
      responses:
        '200':
          description: Success
        '202':
          $ref: '#/components/responses/TrackingSlipResponse'
        '403':
          $ref: '#/components/responses/PermissionError'
        '408':
          $ref: '#/components/responses/LongRunnerResponse'
      tags:
      - Discussions
      summary: Split comments out into a discussion.
      x-addon: vanilla
  /discussions/{id}:
    delete:
      parameters:
      - description: 'The discussion ID.

          '
        in: path
        name: id
        required: true
        schema:
          type: integer
      - $ref: '#/components/parameters/discussionExpand'
      responses:
        '202':
          $ref: '#/components/responses/TrackingSlipResponse'
        '204':
          description: Success
        '403':
          $ref: '#/components/responses/PermissionError'
        '408':
          $ref: '#/components/responses/LongRunnerResponse'
      tags:
      - Discussions
      summary: Delete a discussion.
      x-addon: vanilla
    get:
      parameters:
      - description: 'The discussion ID.

          '
        in: path
        name: id
        required: true
        schema:
          type: integer
      - $ref: '#/components/parameters/discussionExpand'
      - name: fields
        in: query
        style: form
        description: Only return fields with these keys from the output. Use dot notation for nested fields.
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Discussion'
          description: Success
      tags:
      - Discussions
      summary: Get a discussion.
      x-addon: vanilla
    patch:
      parameters:
      - description: The discussion ID.
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Discussion'
          description: Success
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostPremoderation'
          description: Premoderation
      tags:
      - Discussions
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DiscussionPatch'
        required: true
      summary: Update a discussion.
      x-addon: vanilla
  /discussions/{id}/bookmark:
    put:
      parameters:
      - description: The discussion ID.
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  bookmarked:
                    description: The current bookmark value.
                    type: boolean
                required:
                - bookmarked
                type: object
          description: Success
      tags:
      - Discussions
      requestBody:
        content:
          application/json:
            schema:
              properties:
                bookmarked:
                  description: Pass true to bookmark or false to remove bookmark.
                  type: boolean
              required:
              - bookmarked
              type: object
        required: true
      summary: Bookmark a discussion.
      x-addon: vanilla
  /discussions/{id}/bump:
    patch:
      summary: Bump a discussion higher in the list by updating the DateLastComment field.
      tags:
      - Discussions
      parameters:
      - description: The discussion ID.
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Discussion'
          description: Success
        '404':
          description: Not Found
        '400':
          description: Bad Request
      x-addon: vanilla
  /discussions/{id}/canonical-url:
    put:
      parameters:
      - description: The discussion ID.
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Discussion'
          description: Success
        '404':
          description: Not Found
        '400':
          description: Bad Request
      tags:
      - Discussions
      requestBody:
        content:
          application/json:
            schema:
              properties:
                canonicalUrl:
                  description: Canonical url for discussion.
                  type: string
              required:
              - canonicalUrl
              type: object
        required: true
      summary: Set custom canonical url for a discussion.
      x-addon: vanilla
    delete:
      parameters:
      - description: The discussion ID.
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '204':
          description: Success
        '404':
          description: Not Found
      tags:
      - Discussions
      summary: Remove custom canonical url for a discussion.
      x-addon: vanilla
  /discussions/{id}/dismiss:
    put:
      parameters:
      - description: The discussion ID.
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  dismissed:
                    description: The current dismiss value.
                    default: true
                    type: boolean
                type: object
          description: Success
      tags:
      - Discussions
      requestBody:
        content:
          application/json:
            schema:
              properties:
                dismissed:
                  description: Pass true to dismiss the announcement or false to remove the dismissal.
                  type: boolean
              type: object
        required: true
      summary: Dismiss an announcement.
      x-addon: vanilla
  /discussions/{id}/edit:
    get:
      parameters:
      - description: 'The discussion ID.

          '
        in: path
        name: id
        required: true
        schema:
          type: integer
      - $ref: '#/components/parameters/discussionExpand'
      - name: fields
        in: query
        style: form
        description: Only return fields with these keys from the output. Use dot notation for nested fields.
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscussionGetEdit'
          description: Success
      tags:
      - Discussions
      summary: Get a discussion for editing.
      x-addon: vanilla
  /discussions/{id}/idea:
    x-addon: ideation
    patch:
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  statusID:
                    description: Idea status ID.
                    type: integer
                  statusNotes:
                    description: Notes on a status change. Notes will persist until overwritten.
                    minLength: 1
                    nullable: true
                    type: string
                required:
                - statusID
                - statusNotes
                type: object
          description: Success
      tags:
      - Discussions
      requestBody:
        content:
          application/json:
            schema:
              properties:
                statusID:
                  description: Idea status ID.
                  type: integer
                statusNotes:
                  description: Notes on a status change. Notes will persist until overwritten.
                  minLength: 1
                  nullable: true
                  type: string
              required:
              - statusID
              - statusNotes
              type: object
        required: true
      summary: Update idea metadata on a discussion.
      x-addon: vanilla
  /discussions/{id}/mute:
    put:
      parameters:
      - description: The discussion ID.
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  muted:
                    description: The current muted value.
                    type: boolean
                required:
                - muted
                type: object
          description: Success
      tags:
      - Discussions
      requestBody:
        content:
          application/json:
            schema:
              properties:
                muted:
                  description: Pass true to mute or false to unmute a discussion.
                  type: boolean
              required:
              - muted
              type: object
        required: true
      x-addon: vanilla
  /discussions/{id}/poll:
    x-addon: polls
    get:
      parameters:
      - description: 'The Discussion ID.

          '
        in: path
        name: id
        required: true
        schema:
          type: integer
      - name: fields
        in: query
        style: form
        description: Only return fields with these keys from the output. Use dot notation for nested fields.
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Discussion'
                properties:
                  countOptions:
                    description: The number of options to choose from.
                    type: integer
                  countVotes:
                    description: The number of votes.
                    type: integer
                  dateInserted:
                    description: When the poll was created.
                    format: date-time
                    type: string
                  dateUpdated:
                    description: When the poll was updated.
                    format: date-time
                    nullable: true
                    type: string
                  discussionID:
                    description: The discussion the poll is displayed in.
                    type: integer
                  insertUser:
                    $ref: '#/components/schemas/UserFragment'
                  insertUserID:
                    description: The unique ID of the user who created this poll.
                    type: integer
                  name:
                    description: The name of the poll.
                    minLength: 1
                    type: string
                  pollID:
                    description: The unique ID of the poll.
                    type: integer
                  updateUser:
                    $ref: '#/components/schemas/UserFragment'
                  updateUserID:
                    description: The u

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