Vanilla Forums Reports & Escalations API

openapi: 3.2.0
info:
  description: API access to your community.
  title: Vanilla Addons Reports & Escalations API
  version: '2.0'
servers:
- url: https://open.vanillaforums.com/api/v2
tags:
- name: Reports & Escalations
paths:
  /escalations:
    post:
      tags:
      - Reports & Escalations
      summary: Create an Escalation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EscalationInsert'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Escalation'
      x-addon: vanilla
    get:
      tags:
      - Reports & Escalations
      summary: Get a list of escalations
      parameters:
      - name: escalationID
        description: Filter by a range or CSV of discussion escalationIDs.
        in: query
        schema:
          $ref: '#/components/schemas/RangeExpression'
      - name: recordType
        in: query
        schema:
          type: string
          enum:
          - discussion
          - comment
          - premoderated
      - name: recordID
        description: Filter by a range or CSV of discussion recordIDs.
        in: query
        schema:
          $ref: '#/components/schemas/RangeExpression'
      - name: placeRecordType
        in: query
        schema:
          type: string
          enum:
          - category
      - name: placeRecordID
        description: Filter by a range or CSV of category placeRecordIDs.
        in: query
        schema:
          $ref: '#/components/schemas/RangeExpression'
      - name: status
        description: Filter by one or more statuses (CSV & array supported).
        in: query
        schema:
          type: array
          items:
            type: string
            enum:
            - open
            - in-progress
            - on-hold
            - external-zendesk
            - done
      - name: assignedUserID
        description: Filter by a range or CSV of assigned userIDs.
        in: query
        schema:
          $ref: '#/components/schemas/RangeExpression'
      - name: removedUserID
        description: Filter by a range or CSV of userIDs who removed the record.
        in: query
        schema:
          $ref: '#/components/schemas/RangeExpression'
      - name: recordUserID
        description: Filter by a range or CSV of users who created the content that was escalated.
        in: query
        schema:
          $ref: '#/components/schemas/RangeExpression'
      - name: recordUserRoleID
        description: Filter by a range or CSV of users' roles who created the content that was escalated.
        in: query
        schema:
          $ref: '#/components/schemas/RangeExpression'
      - name: reportReasonID
        description: Filter by a report reason. Multiple reasonIDs can be passed in a CSV or array.
        in: query
        schema:
          type: string
      - $ref: '#/components/parameters/Page'
      - description: 'Desired number of items per page.

          '
        in: query
        name: limit
        schema:
          type: integer
          default: 100
          maximum: 500
          minimum: 1
      - name: escalationID
        description: Filter by a range or CSV of escalationIDs.
        in: query
        schema:
          $ref: '#/components/schemas/RangeExpression'
      - $ref: '#/components/parameters/DateInserted'
      - name: dateRemoved
        in: query
        description: 'Filter by removed date. See [date filters](https://docs.vanillaforums.com/help/apiv2/date-filters/).

          '
        schema:
          format: date-filter
          type: string
      - name: recordIsLive
        description: Whether the record still exists.
        in: query
        schema:
          type: boolean
      - name: hasAssociatedAppeal
        description: Whether the escalation has an associated appeal.
        in: query
        schema:
          type: boolean
      - name: appealStatus
        description: Filter by appeal status. Multiple statuses can be passed as CSV or array.
        in: query
        schema:
          type: array
          items:
            type: string
            enum:
            - pending
            - in-review
            - approved
            - rejected
      - 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':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Escalation'
      x-addon: vanilla
  /escalations/:escalationID:
    get:
      tags:
      - Reports & Escalations
      summary: Get an escalation
      parameters:
      - name: escalationID
        in: path
        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':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Escalation'
      x-addon: vanilla
    patch:
      tags:
      - Reports & Escalations
      summary: Update an escalation
      parameters:
      - name: escalationID
        in: path
        required: true
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EscalationPatch'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Escalation'
      x-addon: vanilla
  /escalations/log:
    get:
      tags:
      - Reports & Escalations
      summary: Get a list of escalation Logs
      parameters:
      - name: escalationID
        description: Filter by a range or CSV of discussion escalationIDs.
        in: query
        schema:
          $ref: '#/components/schemas/RangeExpression'
      - name: recordType
        in: query
        schema:
          type: string
          enum:
          - discussion
          - comment
          - premoderated
      - name: recordID
        description: Filter by a range or CSV of discussion recordIDs.
        in: query
        schema:
          $ref: '#/components/schemas/RangeExpression'
      - name: action
        description: Filter by one or more action (CSV & array supported).
        in: query
        schema:
          type: array
          items:
            type: string
            enum:
            - removed
            - escalated
            - restored
      - name: insertUserID
        description: Filter by a user performing the action
        in: query
        schema:
          $ref: '#/components/schemas/RangeExpression'
      - name: recordUserID
        description: Filter by a range or CSV of users who created the content that was acted upon.
        in: query
        schema:
          $ref: '#/components/schemas/RangeExpression'
      - name: recordUserRoleID
        description: Filter by a range or CSV of users' roles who created the content that was escalated.
        in: query
        schema:
          $ref: '#/components/schemas/RangeExpression'
      - description: 'Desired number of items per page.

          '
        in: query
        name: limit
        schema:
          type: integer
          default: 100
          maximum: 500
          minimum: 1
      - name: escalationID
        description: Filter by a range or CSV of escalationIDs.
        in: query
        schema:
          $ref: '#/components/schemas/RangeExpression'
      - $ref: '#/components/parameters/DateInserted'
      - name: recordIsLive
        description: Whether the record still exists.
        in: query
        schema:
          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':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EscalationLog'
      x-addon: vanilla
  /escalations/log/:escalationLogID:
    get:
      tags:
      - Reports & Escalations
      summary: Get an escalation Log
      description: 'Retrieve a specific escalation log entry. Moderators can access any log entry.

        Non-moderators can only access logs where they are the record owner (e.g., for appealing content removal).

        '
      parameters:
      - name: escalationLogID
        in: path
        required: true
        schema:
          type: integer
      - name: expand
        in: query
        description: Expand additional data. Options are appeal (submitted appeal), record (removed content), or all.
        schema:
          oneOf:
          - type: string
            enum:
            - appeal
            - record
            - all
          - type: array
            items:
              type: string
              enum:
              - appeal
              - record
              - all
      - 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':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EscalationLog'
      x-addon: vanilla
  /escalations/lookup-assignee:
    get:
      summary: Search for users that could be assigned to an escalation by full or partial name matching.
      parameters:
      - name: escalationID
        description: If passed will filter to potential assignees for this specific escalation.
        in: query
        required: true
        schema:
          type: integer
      - description: 'Filter for username. Supports full or partial matching with appended wildcard (e.g. User*).

          '
        in: query
        name: name
        required: true
        schema:
          minLength: 1
          type: string
      - description: 'Page number. See [Pagination](https://docs.vanillaforums.com/apiv2/#pagination).

          '
        in: query
        name: page
        schema:
          type: integer
          default: 1
          minimum: 1
      - description: 'Desired number of items per page.

          '
        in: query
        name: limit
        schema:
          type: integer
          default: 30
          maximum: 100
          minimum: 1
      - 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/UserFragment'
                type: array
          description: Success
      tags:
      - Reports & Escalations
      x-addon: vanilla
  /report-reasons:
    get:
      tags:
      - Reports & Escalations
      summary: Get a list of report reasons for the current sessioned user. `community.manage` permission grants permission to all reasons.
      parameters:
      - name: includeDeleted
        description: Allow selecting deleted reports. Requires `moderation.manage` permission.
        in: query
        schema:
          type: boolean
          default: false
      - 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':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ReportReason'
      x-addon: vanilla
    post:
      tags:
      - Reports & Escalations
      summary: Create a report reason
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReportReasonPost'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportReason'
        '409':
          description: Conflict. Returned if the reportReasonID already exists.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Report reason already exists.
                  code:
                    type: number
                    example: 409
                  conflictingReason:
                    $ref: '#/components/schemas/ReportReason'
      x-addon: vanilla
  /report-reasons/:reportReasonID:
    get:
      tags:
      - Reports & Escalations
      summary: Get a report reason if you have permission for it.
      parameters:
      - name: reportReasonID
        in: path
        required: true
        schema:
          type: integer
      - name: includeDeleted
        description: Allow selecting deleted reports. Requires `moderation.manage` permission.
        in: query
        schema:
          type: boolean
          default: false
      - 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':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportReason'
        '404':
          description: Not Found. Also returned if there is no permission to not leak reasonIDs.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Report reason not found.
      x-addon: vanilla
    patch:
      tags:
      - Reports & Escalations
      summary: Update a report reason
      parameters:
      - name: reportReasonID
        in: path
        required: true
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReportReasonPost'
      responses:
        '201':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportReason'
      x-addon: vanilla
    delete:
      tags:
      - Reports & Escalations
      summary: Delete a report reason. If the report has already been used, the reason will be marked as deleted but still exist in the underyling system for usage when viewing existing reports.
      parameters:
      - name: reportID
        in: path
        required: true
        schema:
          type: integer
      responses:
        '204':
          description: No Content
      x-addon: vanilla
  /report-reasons/sorts:
    put:
      tags:
      - Reports & Escalations
      summary: Update the sort order of report reasons
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Mapping of reportReasonID to new sorts.
              example:
                spam: 1
                abuse: 2
                sexual-content: 3
      responses:
        '204':
          description: No Content
      x-addon: vanilla
  /reports:
    post:
      tags:
      - Reports & Escalations
      summary: Create a report
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReportInsert'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Report'
      x-addon: vanilla
    get:
      tags:
      - Reports & Escalations
      summary: Get a list of reports
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Report'
      parameters:
      - name: recordType
        in: query
        schema:
          type: string
          enum:
          - discussion
          - comment
      - name: reportReasonID
        description: Filter by a report reason. Multiple reasonIDs can be passed in a CSV or array.
        in: query
        schema:
          type: string
      - name: recordID
        description: Filter by a range or CSV of discussion recordIDs.
        in: query
        schema:
          $ref: '#/components/schemas/RangeExpression'
      - name: placeRecordType
        in: query
        schema:
          type: string
          enum:
          - category
      - name: placeRecordID
        description: Filter by a range or CSV of category placeRecordIDs.
        in: query
        schema:
          $ref: '#/components/schemas/RangeExpression'
      - name: insertUserID
        description: Filter by a range or CSV of users that made the report.
        in: query
        schema:
          $ref: '#/components/schemas/RangeExpression'
      - name: insertUserRoleID
        description: Filter by a range or CSV of users' roles that made the report.
        in: query
        schema:
          $ref: '#/components/schemas/RangeExpression'
      - name: removedUserID
        description: Filter by a range or CSV of userIDs who removed the record.
        in: query
        schema:
          $ref: '#/components/schemas/RangeExpression'
      - name: recordUserID
        description: Filter by a range or CSV of users who's content was reported.
        in: query
        schema:
          $ref: '#/components/schemas/RangeExpression'
      - name: status
        description: Filter by one or more statuses (CSV & array supported).
        in: query
        schema:
          type: array
          default:
          - new
          items:
            type: string
            enum:
            - new
            - escalated
            - dismissed
      - $ref: '#/components/parameters/Page'
      - description: 'Desired number of items per page.

          '
        in: query
        name: limit
        schema:
          type: integer
          default: 100
          maximum: 500
          minimum: 1
      - name: reportID
        description: Filter by a range or CSV of recordIDs.
        in: query
        schema:
          $ref: '#/components/schemas/RangeExpression'
      - $ref: '#/components/parameters/DateInserted'
      - name: dateRemoved
        in: query
        description: 'Filter by removed date. See [date filters](https://docs.vanillaforums.com/help/apiv2/date-filters/).

          '
        schema:
          format: date-filter
          type: string
      - name: reporterEmail
        description: Filter by guest reporter email address.
        in: query
        schema:
          type: string
          format: email
      - name: recordIsLive
        description: Whether the record still exists.
        in: query
        schema:
          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
      x-addon: vanilla
  /reports/:reportID:
    get:
      tags:
      - Reports & Escalations
      summary: Get a report
      parameters:
      - name: reportID
        in: path
        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':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Report'
      x-addon: vanilla
  /reports/:reportID/approve-record:
    parameters:
    - name: reportID
      in: path
      required: true
      schema:
        type: integer
      x-addon: vanilla
    patch:
      tags:
      - Reports & Escalations
      summary: Approve a pending or removed post that was premoderated.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                verifyRecordUser:
                  type: boolean
                  description: If true mark the user as verified.
                premoderatedRecord:
                  type: object
                  description: Optional mod edits to make to the post before being approved.
                  properties:
                    body:
                      type: string
                      description: Body content formatted in rich.
                    name:
                      type: string
                      description: Name/Title content in plain text.
                  required:
                  - body
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Report'
      x-addon: vanilla
  /reports/:reportID/dismiss:
    parameters:
    - name: reportID
      in: path
      required: true
      schema:
        type: integer
      x-addon: vanilla
    post:
      tags:
      - Reports & Escalations
      summary: Dismiss a user's report.
      responses:
        '204':
          description: No Content
      x-addon: vanilla
  /reports/:reportID/reject-record:
    parameters:
    - name: reportID
      in: path
      required: true
      schema:
        type: integer
      x-addon: vanilla
    patch:
      tags:
      - Reports & Escalations
      summary: Reject a pending or live post that was premoderated and ensure it is deleted.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Report'
      x-addon: vanilla
  /reports/automation:
    get:
      tags:
      - Reports & Escalations
      summary: List of Posts that where reported set number of times.
      parameters:
      - name: countReports
        in: query
        required: true
        schema:
          type: integer
          default: 1
      - name: reportReasonID
        in: query
        required: false
        schema:
          type: string
      - name: placeRecordID
        description: Filter by a range or CSV of category placeRecordIDs.
        in: query
        schema:
          $ref: '#/components/schemas/RangeExpression'
      - name: includeSubcategories
        description: Include reports from subcategories.
        in: query
        schema:
          type: boolean
          default: false
      - $ref: '#/components/parameters/Page'
      - description: 'Desired number of items per page.

          '
        in: query
        name: limit
        schema:
          type: integer
          default: 100
          maximum: 500
          minimum: 1
      - 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':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ReportCounter'
      x-addon: vanilla
components:
  schemas:
    Appeal:
      type: object
      properties:
        appealID:
          type: integer
          description: The unique ID of the appeal.
        type:
          type: string
          description: The type of appeal.
          enum:
          - ban
          - content-removal
        status:
          type: string
          description: The current status of the appeal.
          enum:
          - pending
          - approved
          - rejected
          - in-review
        insertUserID:
          type: integer
          description: The ID of the user who created the appeal record.
        assignedUserID:
          type:
          - integer
          - 'null'
          description: The ID of the moderator assigned to review the appeal.
        appealingUserID:
          type: integer
          description: The ID of the user making the appeal.
        escalationID:
          type:
          - integer
          - 'null'
          description: The escalation ID for content-removal appeals.
        escalationLogID:
          type:
          - integer
          - 'null'
          description: The escalation log ID for content-removal appeals.
        dateInserted:
          type: string
          format: date-time
          description: When the appeal was created.
        dateUpdated:
          type:
          - string
          - 'null'
          format: date-time
          description: When the appeal was last updated.
        appealText:
          type: string
          description: The user's appeal message.
        appealingUserInfo:
          type: object
          description: Information about the user making the appeal.
          properties:
            userID:
              type: integer
              description: The user ID.
            name:
              type: string
              description: The username.
            email:
              type:
              - string
              - 'null'
              description: The user's email address.
          required:
          - userID
          - name
        appealEventInfo:
          type: object
          description: 'Information about the moderation event being appealed.

            Fields vary based on appeal type (ban vs content-removal).

            '
          properties:
            userNoteID:
              type:
              - integer
              - 'null'
              description: The ID of the user note (for ban appeals).
            moderatorUserID:
              type:
              - integer
              - 'null'
              description: The ID of the moderator who made the decision.
            moderatorName:
              type:
              - string
              - 'null'
              description: The name of the moderator who made the decision.
            reasons:
              type:
              - array
              - 'null'
              description: The reasons given for the ban or content removal.
              items:
                type: string
            moderatorMessage:
              type:
              - string
              - 'null'
              description: The message from the moderator at time of ban/removal.
            dateOfEvent:
              type:
              - string
              - 'null'
              format: date-time
              description: When the ban or content removal occurred.
            recordType:
              type:
              - string
              - 'null'
              description: The type of record (for content-removal appeals).
              enum:
              - discussion
              - comment
            recordID:
              type:
              - integer
              - 'null'
              description: The ID of the record that was removed (for content-removal appeals).
            decisionMessage:
              type:
              - string
              - 'null'
              description: The decision message added when resolving the appeal.
      required:
      - appealID
      - type
      - status
      - insertUserID
      - appealingUserID
      - dateInserted
      - appealText
      - appealingUserInfo
      - appealEventInfo
      x-addon: dashboard
    Report:
      type: object
      properties:
        reportID:
          type: integer
        recordType:
          description: Type of record being reported.
          type: string
          enum:
          - discussion
          - comment
        recordID:
          description: ID of the record being reported.
          type: integer
        recordName:
          description: Name of the record being reported.
          type: string
        recordHtml:
          description: Rendered HTML contents of the reported record.
          type: string
        recordExcerpt:
          description: Excerpt of the reported record.
          type: string
        recordUrl:
          description: URL of the record being reported.
          type: string
        recordIsLive:
          description: Whether the record still exists.
          type: boolean
        recordWasEdited:
          description: Whether the record was edited after the report was made.
          type: boolean
        placeRecordType:
          description: Type of record the reported record is placed in.
          type: string
          enum:
          - category
        placeRecordID:
          description: ID of the record the reported record is placed in.
          type: integer
        placeRecordName:
          description: Name of the record the reported record is placed in.
          type: string
        placeRecordUrl:
          description: URL of the record the reported record is placed in.
          type: string
          format: uri
        recordUserID:
          description: ID of the user who made the reported record.
          type: integer
        recordUser:
          $ref: '#/components/schemas/UserFragment'
        recordDateInserted:
          type: string
          format: date-time
        recordDateUpdated:
          type: string
          format: date-time
        isPending:
          description: Whether the reported content is a pending post (Eg. premoderation report).
          type: boolean
        isPendingUpdate:
          description: Whether the reported content is a pending update for a post that was live.
          type: boolean
        reportReasons:
          description: Full report reasons
          type: array
          items:
            $ref: '#/components/schemas/ReportReasonFragment'
        noteHtml:
          type: string
          description: Additional information about the report in HTML format.
        insertUserID:
          description: ID of the user making the report. 0 for guest reporters.
          type: integer
        insertUser:
          $ref: '#/components/schemas/UserFragment'
        reporterEmail:
          description: Email address of the guest reporter. Only present when insertUserID is 0.
          type:
          - string
          - 'null'
        reporterName:
          description: Display name of the guest reporter. Only present when insertUserID is 0.
          type:
          - string
          - 'null'
        reportedUserID:
          description: ID of the user being reported.
          type: integer
        reportedUser:
          $ref: '#/components/schemas/UserFragment'
        updateUserID:
          description: ID of the user who last updated the report.
          type: integer
        updateUser:
          $ref: '#/components/schemas/UserFragment'
        dateInserted:
          description: Date the report was made.
      

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