Vanilla Forums Reports & Escalations API

openapi: 3.0.3
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:
    ReportInsert:
      type: object
      properties:
        recordType:
          description: Type of record being reported.
          type: string
          enum:
          - discussion
          - comment
        recordID:
          description: ID of the record being reported.
          type: integer
        reportReasonIDs:
          description: One or more reasons for the report.
          type: array
          items:
            type: string
          example:
          - spam
          - abuse
        noteBody:
          description: Additional information about the report.
          type: string
        noteFormat:
          description: Format of the note field.
          type: string
        reporterEmail:
          description: Email address of the guest reporter. Required when the reporter is not logged in.
          type: string
          format: email
        reporterName:
          description: Display name of the guest reporter (plain text only).
          type: string
      required:
      - recordType
      - recordID
      - reportReasonIDs
      - noteBody
      - noteFormat
      x-addon: vanilla
    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
          nullable: true
        reporterName:
          description: Display name of the guest reporter. Only present when insertUserID is 0.
          type: string
          nullable: true
        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.
          type: string
          format: date-time
        dateUpdated:
          description: Date the report was last updated.
          type: string
          format: date-time
      required:
      - reportID
      - recordType
      - recordID
      - recordName
      - recordHtml
      - recordUrl
      - recordIsLive
      - recordWasEdited
      - recordUserID
      - recordDateInserted
      - placeRecordType
      - placeRecordID
      - reportReasonIDs
      - insertUserID
      - reportedUserID
      - updateUserID
      - dateInserted
      - dateUpdated
      - noteHtml
      x-addon: vanilla
    ReportReason:
      type: object
      properties:
        reportReasonID:
          type: string
        name:
          type: string
        description:
          type: string
        dateInserted:
          type: string
          format: date-time
        dateUpdated:
          type: string
          format: date-time
        insertUserID:
          type: integer
        updateUserID:
          type: integer
        sort:
          type: integer
        roleIDs:
          type: array
          items:
            type: integer
        roles:
          type: array
          items:
            type: object
            properties:
              roleID:
                type: integer
              name:
                type: string
        deleted:
          type: boolean
        countReports:
          type: integer
          description: The number of reports that have used this reason. Only available with `community.manage` permission.
      required:
      - reportReasonID
      - name
      - description
      - dateInserted
      - insertUserID
      - sort
      - deleted
      x-addon: vanilla
    EscalationLog:
      type: object
      properties:
        escalationLogID:
          description: Primary ID of the log.
          type: integer
        authorNotificationMessage:
          description: Message to the user.
          type: string
        action:
          type: string
          description: Status of the escalation.
          enum:
          - removed
          - escalated
          - restored
        insertUserID:
          description: ID of the user triggered the action.
          type: integer
        dateInserted:
          description: The date log creation.
          type: string
          format: date-time
        recordType:
          description: Type of record being reported.
          type: string
          enum:
          - discussion
          - comment
          - premoderated
        recordID:
          description: ID of the record being reported.
          type: integer
        recordUserID:
          description: ID of the user who created the record being reported.
          type: integer
        reasons:
          description: Reasons for action.
          type: array
          items:
            $ref: '#/components/schemas/ReportReasonFragment'
        insertUser:
          $ref: '#/components/schemas/UserFragment'
        recordUser:
          $ref: '#/components/schem

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