Vanilla Forums Search API

openapi: 3.2.0
info:
  description: API access to your community.
  title: Vanilla Addons Search API
  version: '2.0'
servers:
- url: https://open.vanillaforums.com/api/v2
tags:
- name: Search
paths:
  /search:
    get:
      parameters:
      - description: 'Filter the records using the supplied terms.

          '
        in: query
        name: query
        schema:
          type: string
        x-search-filter: true
      - description: 'Restrict the search to the specified main type(s) of records.

          '
        in: query
        name: recordTypes
        schema:
          items:
            enum:
            - article
            - discussion
            - comment
            - group
            - user
            - customPage
            type: string
          type: array
        style: form
      - description: 'Restrict the search to the specified type(s) of records.

          '
        in: query
        name: types
        schema:
          items:
            enum:
            - article
            - discussion
            - comment
            - question
            - answer
            - group
            - poll
            - customPage
            type: string
          type: array
        style: form
      - description: 'Set the scope of the search to the comments of a discussion. Incompatible with recordType and type.

          '
        in: query
        name: discussionID
        schema:
          type: integer
        x-search-scope: true
      - description: 'Set the scope of the search to a specific category (includes results from the social group category).

          '
        in: query
        name: categoryID
        schema:
          type: integer
        x-search-scope: true
      - description: 'Set the scope of the search to specific categories.

          '
        in: query
        name: categoryIDs
        schema:
          type: array
          items:
            type: integer
        x-search-scope: true
      - description: 'Set the scope of the search to followed categories only.

          '
        in: query
        name: followedCategories
        schema:
          default: false
          type: boolean
        x-search-scope: true
      - description: 'Search the specified category''s subtree. Works with categoryID

          '
        in: query
        name: includeChildCategories
        schema:
          default: false
          type: boolean
      - description: 'Allow search in archived categories.

          '
        in: query
        name: includeArchivedCategories
        schema:
          default: false
          type: boolean
      - description: 'Filter the records by KnowledgeBase ID

          '
        in: query
        name: knowledgeBaseID
        schema:
          type: integer
        x-search-scope: true
      - description: 'Filter the records by KnowledgeCategory ID

          '
        in: query
        name: knowledgeCategoryIDs
        schema:
          items:
            type: integer
          type: array
        x-search-scope: true
      - description: 'Filter the records by matching part of their name.

          '
        in: query
        name: name
        schema:
          type: string
        x-search-filter: true
      - description: 'Filter the records by their featured status.

          '
        in: query
        name: featured
        schema:
          type: boolean
        x-search-filter: true
      - description: 'Filter the records by their locale.

          '
        in: query
        name: locale
        schema:
          type: string
        x-search-filter: true
      - description: 'Filter the records by their site-section-group.

          '
        in: query
        name: siteSiteSectionGroup
        schema:
          type: string
        x-search-filter: true
      - $ref: '#/components/parameters/SiteSectionFilters'
      - description: 'Filter the records by inserted user names.

          '
        in: query
        name: insertUserNames
        schema:
          items:
            type: string
          type: array
        style: form
        x-search-filter: true
      - description: 'Filter the records by inserted userIDs.

          '
        in: query
        name: insertUserIDs
        schema:
          items:
            type: integer
          type: array
        style: form
        x-search-filter: true
      - $ref: '#/components/parameters/DateInserted'
      - description: 'Filter discussions by matching tags.

          '
        in: query
        name: tags
        schema:
          items:
            type: string
          type: array
        style: form
        x-search-filter: true
      - description: 'Tags search condition.

          Must be one of: "and", "or".

          '
        in: query
        name: tagOperator
        schema:
          type: string
          default: or
          enum:
          - and
          - or
      - description: 'Set the default search type.

          '
        in: query
        name: queryOperator
        schema:
          type: string
          default: and
          enum:
          - and
          - or
      - $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 the results to include a rendered body field.

          '
        in: query
        name: expandBody
        schema:
          type: boolean
          default: true
      - description: 'Expand associated records using one or more valid field names. A value of "all" will expand all expandable fields.

          '
        in: query
        name: expand
        schema:
          items:
            enum:
            - insertUser
            - breadcrumbs
            - excerpt
            - image
            - insertUser.ssoID
            - insertUser.roles
            - insertUser.profileFields
            - insertUser.extended
            type: string
          type: array
        style: form
      - $ref: '#/components/parameters/ProfileFieldFilters'
      - name: includeTypeaheads
        in: query
        schema:
          type: boolean
        description: 'BETA: Include typeahead results in the search response.

          '
      - name: includeResults
        in: query
        schema:
          type: boolean
        description: 'BETA: Include search results in the search response.

          '
      - in: query
        name: matchMode
        schema:
          type: string
          enum:
          - fulltext
          - fulltext_extended
          - wildcard
          - vectorized
          description: 'Enforce a specific method to do the search.

            '
      - description: Filter the records statusID
        in: query
        name: statusID
        schema:
          items:
            type: integer
          type: array
        style: form
      - description: Filter answer-type comments by answer statusID. Be sure it add a `types` filter if you only want answers.
        in: query
        name: answerStatusID
        schema:
          items:
            type: string
            enum:
            - accepted
            - rejected
            - pending
          type: array
        style: form
      - description: Filter the records postTypeID
        in: query
        name: postTypeID
        schema:
          items:
            type: string
          type: array
        style: form
      - $ref: '#/components/parameters/PostMetaSearchFilters'
      - 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/SearchResult'
                type: array
          description: Success
      tags:
      - Search
      summary: Search for records matching specific criteria.
      x-addon: dashboard
components:
  schemas:
    UserFragment:
      oneOf:
      - type: object
        properties:
          userID:
            description: The ID of the user.
            type: integer
          name:
            description: The username of the user.
            minLength: 1
            type: string
          url:
            description: The URL of the user's profile.
            type: string
            format: uri
          photoUrl:
            description: The URL of the user's avatar picture.
            type: string
            format: uri
          dateLastActive:
            description: Time the user was last active.
            format: date-time
            type:
            - string
            - 'null'
          ssoID:
            description: The unique ID of the user from the source site, if using SSO.
            type: string
          label:
            description: The label of the user as plaintext.
            type: string
          labelHtml:
            description: The label of the user in HTML format.
            type: string
          private:
            description: Whether the user profile is private or not.
            type: boolean
        required:
        - userID
        - name
        - photoUrl
        - dateLastActive
      - type: object
        description: A user fragment when only expanding by ssoID.
        properties:
          ssoID:
            description: The unique ID of the user from the source site, if using SSO.
            type: string
        required:
        - ssoID
      x-addon: dashboard
    SearchResult:
      properties:
        url:
          description: The URL of the record.
          type: string
        body:
          description: The content of the record.
          minLength: 1
          type:
          - string
          - 'null'
        excerpt:
          description: An excerpt of the record.
          type: string
        categoryID:
          description: The category containing the record.
          type: integer
        commentID:
          description: The id of the comment.
          type: integer
        dateInserted:
          description: When the record was created.
          format: date-time
          type: string
        dateUpdated:
          description: When the user was updated.
          format: date-time
          type:
          - string
          - 'null'
        discussionID:
          description: The id of the discussion.
          type: integer
        groupID:
          description: The id of the group or the id of the group containing the record.
          type:
          - integer
          - 'null'
        insertUserID:
          description: The user that created the record.
          type: integer
        insertUser:
          $ref: '#/components/schemas/UserFragment'
        name:
          description: 'The title of the record. A comment would be "RE: {DiscussionTitle}".'
          minLength: 1
          type: string
        recordID:
          description: The identifier of the record.
          type: integer
        recordType:
          description: The main type of record.
          enum:
          - discussion
          - comment
          - group
          minLength: 1
          type: string
        score:
          description: Score of the record.
          type: integer
        type:
          description: Sub-type of the discussion.
          enum:
          - discussion
          - comment
          - question
          - group
          minLength: 1
          type: string
        updateUserID:
          description: The user that updated the record.
          type:
          - integer
          - 'null'
        image:
          description: The url of the first image in the record.
          type: string
        breadcrumbs:
          description: 'List of breadcrumbs objects. Only returned if: expand = breadcrumbs.'
          items:
            properties:
              name:
                description: Breadcrumb element name.
                minLength: 1
                type: string
                example: User Feedback
              url:
                description: Breadcrumb element url.
                minLength: 1
                type: string
                example: https://vanilla.com/forum/user-feedback/
            type: object
          type: array
      required:
      - recordID
      - recordType
      - type
      - name
      - body
      - score
      - insertUserID
      - dateInserted
      - updateUserID
      - dateUpdated
      type: object
      x-addon: dashboard
  parameters:
    DateInserted:
      name: dateInserted
      in: query
      description: 'Filter by insert date. See [date filters](https://docs.vanillaforums.com/help/apiv2/date-filters/).

        '
      schema:
        format: date-filter
        type: string
      x-addon: dashboard
    Page:
      name: page
      in: query
      description: 'Page number. See [Pagination](https://docs.vanillaforums.com/apiv2/#pagination).

        '
      schema:
        type: integer
        default: 1
        minimum: 1
      x-addon: dashboard
    PostMetaSearchFilters:
      name: postMeta
      description: Post meta values to filter posts
      in: query
      style: form
      schema:
        type: object
        properties:
          internal-data:
            type: string
          private-data:
            type: string
          public-data:
            type: string
      x-addon: dashboard
x-resourceEvents:
  emailTemplates:
    x-feature: Feature.emailTemplates.Enabled
    name: Email Template
    type: emailTemplate
  notification:
    x-addon: dashboard
    name: Notification
    type: notification
  reaction:
    name: Reaction
    type: reaction
  user:
    x-addon: dashboard
    name: User
    type: user
  comment:
    x-addon: vanilla
    name: Comment
    type: comment
  discussion:
    x-addon: vanilla
    name: Discussion
    type: discussion
  escalation:
    x-addon: vanilla
    name: Escalation
    type: cmdEscalation
  report:
    x-addon: vanilla
    name: Report
    type: report
  userNote:
    x-addon: warnings2
    name: User Note
    type: userNote
x-aliases:
  AssetOut:
    type:
      description: The type of the asset.
      type: string
    url:
      type: string
      description: Absolute URL of the asset.
    content-type:
      description: The content-type of the asset.
      type: string
      example: application/json
  StringAssetOut:
    type:
      description: The type of the asset.
      type: string
    url:
      type: string
      description: Absolute URL of the asset.
    content-type:
      description: The content-type of the asset.
      type: string
      example: application/json
    data:
      type: string
      description: Contents of the asset. May require an expand parameter to retreive.
    '200':
      content:
        application/json:
          schema:
            description: Contents of an asset.
            type: object
            properties:
              type:
                description: The type of the asset.
                type: string
                example: html
                enum:
                - html
                - css
                - js
              data:
                type: string
                example: <header>Hello Footer<footer />
                description: Contents of the asset. May require an expand parameter to retreive.
              content-type:
                description: The content-type of the asset.
                type: string
                example: text/html
              url:
                type: string
                description: Absolute URL of the resource.
                example: https://site.com/api/v2/themes/:themeID/assets/:assetName.ext?v=faasdf42d
      description: Success
  ThemeSlug:
    description: Unique theme slug.
    in: path
    name: themeID
    required: true
    schema:
      type: string
  AssetNotFound:
    description: JavaScript could not be found.
    content:
      application/json:
        schema:
          type: object
          properties:
            description:
              description: Verbose description of the error.
              type:
              - string
              - 'null'
            message:
              description: Short description of the error.
              type: string
            status:
              description: Status code of the error response.
              type: integer
          required:
          - description
          - message
          - status
  ThemeIDParam:
    description: Unique themeID.
    in: path
    name: themeID
    required: true
    schema:
      type: integer
  StringAssetIn:
    description: An asset to be inserted.
    type: object
    properties:
      type:
        description: The type of the asset.
        type: string
        example: html
        enum:
        - html
        - css
        - js
      data:
        type: string
        example: <header>Hello Footer<footer />
        description: Contents of the asset. May require an expand parameter to retreive.
  JsonAssetIn:
    description: An asset to be inserted.
    type: object
    properties:
      type:
        type: string
        example: json
      data:
        type: object
        description: JSON content of the asset.
        example:
          global:
            mainColors:
              primary: '#5cc530'
  JsonAssetOut:
    '200':
      content:
        application/json:
          schema:
            type: object
            properties:
              type:
                type: string
                example: json
              data:
                type: object
                description: JSON content of the asset.
                example:
                  global:
                    mainColors:
                      primary: '#5cc530'
              content-type:
                description: The content-type of the asset.
                type: string
                example: application/json
              url:
                type: string
                description: Absolute URL of the resource.
                example: https://site.com/api/v2/themes/:themeID/assets/:assetName.ext?v=faasdf42d
      description: Success
  DeleteAsset:
    parameters:
    - description: Unique themeID.
      in: path
      name: themeID
      required: true
      schema:
        type: integer
    responses:
      '204':
        description: Success
    tags:
    - Theme Assets
    summary: Delete theme asset.
  StringPutAsset:
    parameters:
    - description: Unique themeID.
      in: path
      name: themeID
      required: true
      schema:
        type: integer
    requestBody:
      required: true
      content:
        application/json:
          schema:
            description: An asset to be inserted.
            type: object
            properties:
              type:
                description: The type of the asset.
                type: string
                example: html
                enum:
                - html
                - css
                - js
              data:
                type: string
                example: <header>Hello Footer<footer />
                description: Contents of the asset. May require an expand parameter to retreive.
    responses:
      '200':
        content:
          application/json:
            schema:
              description: Contents of an asset.
              type: object
              properties:
                type:
                  description: The type of the asset.
                  type: string
                  example: html
                  enum:
                  - html
                  - css
                  - js
                data:
                  type: string
                  example: <header>Hello Footer<footer />
                  description: Contents of the asset. May require an expand parameter to retreive.
                content-type:
                  description: The content-type of the asset.
                  type: string
                  example: text/html
                url:
                  type: string
                  description: Absolute URL of the resource.
                  example: https://site.com/api/v2/themes/:themeID/assets/:assetName.ext?v=faasdf42d
        description: Success
    tags:
    - Theme Assets
    summary: Set theme asset or replace if already exists.
  HtmlPutAssetContentType:
    parameters:
    - description: Unique themeID.
      in: path
      name: themeID
      required: true
      schema:
        type: integer
    requestBody:
      required: true
      content:
        text/html:
          schema:
            type: string
            description: HTML contents.
            example: <div>Hello HTML Asset!</div>
    responses:
      '200':
        content:
          text/html:
            schema:
              type: string
              description: HTML contents.
              example: <div>Hello HTML Asset!</div>
        description: Success
    tags:
    - Theme Assets
    summary: Set theme asset or replace if already exists.
  JsPutAssetContentType:
    parameters:
    - description: Unique themeID.
      in: path
      name: themeID
      required: true
      schema:
        type: integer
    requestBody:
      required: true
      content:
        application/javascript:
          schema:
            type: string
            description: HTML contents.
            example: console.log('Hello Javascript')
    responses:
      '200':
        content:
          application/javascript:
            schema:
              type: string
              description: HTML contents.
              example: console.log('Hello Javascript')
        description: Success
    tags:
    - Theme Assets
    summary: Set theme asset or replace if already exists.
  CssPutAssetContentType:
    parameters:
    - description: Unique themeID.
      in: path
      name: themeID
      required: true
      schema:
        type: integer
    requestBody:
      required: true
      content:
        text/css:
          schema:
            type: string
            description: HTML contents.
            example: ".class {\n   color: orange;\n}\n"
    responses:
      '200':
        content:
          text/css:
            schema:
              type: string
              description: HTML contents.
              example: ".class {\n   color: orange;\n}\n"
        description: Success
    tags:
    - Theme Assets
    summary: Set theme asset or replace if already exists.
  JsonPutAsset:
    parameters:
    - description: Unique themeID.
      in: path
      name: themeID
      required: true
      schema:
        type: integer
    requestBody:
      required: true
      content:
        application/json:
          schema:
            description: An asset to be inserted.
            type: object
            properties:
              type:
                type: string
                example: json
              data:
                type: object
                description: JSON content of the asset.
                example:
                  global:
                    mainColors:
                      primary: '#5cc530'
    responses:
      '200':
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  example: json
                data:
                  type: object
                  description: JSON content of the asset.
                  example:
                    global:
                      mainColors:
                        primary: '#5cc530'
                content-type:
                  description: The content-type of the asset.
                  type: string
                  example: application/json
                url:
                  type: string
                  description: Absolute URL of the resource.
                  example: https://site.com/api/v2/themes/:themeID/assets/:assetName.ext?v=faasdf42d
        description: Success
    tags:
    - Theme Assets
    summary: Set theme asset or replace if already exists.
  JsonPutAssetContentType:
    parameters:
    - description: Unique themeID.
      in: path
      name: themeID
      required: true
      schema:
        type: integer
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            description: JSON contents of the asset.
            example:
              hello:
                json:
                  asset: true
    responses:
      '200':
        content:
          application/json:
            schema:
              type: object
              description: JSON contents of the asset.
              example:
                hello:
                  json:
                    asset: true
        description: Success
    tags:
    - Theme Assets
    summary: Set theme asset or replace if already exists.