Vanilla Forums Search API
The Search API from Vanilla Forums — 1 operation(s) for search.
OpenAPI Specification
openapi: 3.0.3
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:
SearchResult:
properties:
url:
description: The URL of the record.
type: string
body:
description: The content of the record.
minLength: 1
nullable: true
type: string
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
nullable: true
type: string
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.
nullable: true
type: integer
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.
nullable: true
type: integer
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
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
nullable: true
type: string
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
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
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
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
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.
nullable: true
type: string
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.