Vanilla Forums Collections API

openapi: 3.2.0
info:
  description: API access to your community.
  title: Vanilla Addons Collections API
  version: '2.0'
servers:
- url: https://open.vanillaforums.com/api/v2
tags:
- name: Collections
paths:
  /collections:
    get:
      summary: List collections.
      parameters:
      - name: collectionID
        description: Filter by one or more collection IDs.
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/RangeExpression'
      - name: name
        description: Filter by collection name
        in: query
        required: false
        schema:
          type: string
          minLength: 1
          maxLength: 255
      - name: dateUpdated
        description: Filter by updated date. See [date filters](https://docs.vanillaforums.com/help/apiv2/date-filters/).
        in: query
        schema:
          format: date-filter
          type: string
      - $ref: '#/components/parameters/Page'
      - name: limit
        description: Desired number of collections per page.
        in: query
        schema:
          type: integer
          default: 20
          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/FullCollectionSchema'
                type: array
          description: Success
        '401':
          $ref: '#/components/responses/PermissionError'
      tags:
      - Collections
      x-addon: vanilla
    post:
      summary: Create new collection
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CollectionPostSchema'
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FullCollectionSchema'
          description: Success.
        '401':
          $ref: '#/components/responses/PermissionError'
        '404':
          $ref: '#/components/responses/NotFound'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
      tags:
      - Collections
      x-addon: vanilla
  /collections/by-resource:
    get:
      summary: List the collections a given record belongs to.
      parameters:
      - description: The id of the record.
        in: query
        name: recordID
        required: true
        schema:
          type: integer
      - description: The type of the record.
        in: query
        name: recordType
        required: true
        schema:
          type: string
      - 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:
                type: array
                items:
                  $ref: '#/components/schemas/Collection'
          description: Success
        '401':
          $ref: '#/components/responses/PermissionError'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
      - Collections
      x-addon: vanilla
    put:
      summary: Add a record to one or more collections.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                collectionIDs:
                  description: The collections to add the record to.
                  type: array
                  items:
                    type: integer
                record:
                  description: The record to add.
                  type: object
                  properties:
                    recordID:
                      type: integer
                    recordType:
                      type: string
                    sort:
                      type:
                      - integer
                      - 'null'
                  required:
                  - recordID
                  - recordType
              required:
              - collectionsIDs
              - record
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionContentSchema'
          description: Success
        '401':
          $ref: '#/components/responses/PermissionError'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
      - Collections
      x-addon: vanilla
  /collections/contents/{locale}:
    get:
      summary: List collections & contents.
      parameters:
      - name: locale
        description: Filter the records by their locale.
        in: path
        required: true
        schema:
          type: string
      - name: collectionID
        description: Filter by one or more collection IDs.
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/RangeExpression'
      - name: dateAddedToCollection
        description: Filter by date a record has been added to collection. See [date filters](https://docs.vanillaforums.com/help/apiv2/date-filters/).
        in: query
        schema:
          format: date-filter
          type: string
      - name: expand
        description: 'Expand associated records using one or more valid field names. A value of "all" will expand all expandable fields.

          '
        in: query
        schema:
          type: array
          items:
            type: string
            enum:
            - all
            - collection
      - $ref: '#/components/parameters/Page'
      - name: limit
        description: Desired number of collections per page.
        in: query
        schema:
          type: integer
          default: 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/CollectionRecordContentSchema'
                type: array
          description: Success
        '401':
          $ref: '#/components/responses/PermissionError'
      tags:
      - Collections
      x-addon: vanilla
  /collections/{id}:
    parameters:
    - description: The collection id
      in: path
      name: id
      required: true
      schema:
        type: integer
      x-addon: vanilla
    get:
      summary: Get a single collection.
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FullCollectionSchema'
          description: Success
        '401':
          $ref: '#/components/responses/PermissionError'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
      - Collections
      x-addon: vanilla
      parameters:
      - 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
    patch:
      summary: Update a collection
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Collection'
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FullCollectionSchema'
        '401':
          $ref: '#/components/responses/PermissionError'
        '404':
          $ref: '#/components/responses/NotFound'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
      tags:
      - Collections
      x-addon: vanilla
    delete:
      summary: Delete a collection.
      responses:
        '204':
          description: Success.
        '401':
          $ref: '#/components/responses/PermissionError'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
      - Collections
      x-addon: vanilla
  /collections/{id}/content/{locale}:
    get:
      summary: List collection with the each record expanded
      parameters:
      - name: id
        description: The collection id
        in: path
        required: true
        schema:
          type: integer
      - name: locale
        description: Filter the records by their locale.
        in: path
        required: true
        schema:
          type: string
      - name: fields
        in: query
        style: form
        description: Only return fields with these keys from the output. Use dot notation for nested fields.
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionContentSchema'
          description: Success
        '401':
          $ref: '#/components/responses/PermissionError'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
      - Collections
      x-addon: vanilla
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
    CategoryFragment:
      properties:
        categoryID:
          description: The ID of the category.
          type: integer
        name:
          description: The name of the category.
          minLength: 1
          type: string
        url:
          description: Full URL to the category.
          minLength: 1
          type: string
      required:
      - categoryID
      - name
      - url
      type: object
      x-addon: vanilla
    FullCollectionSchema:
      allOf:
      - type: object
        properties:
          collectionID:
            description: The Id of the collection.
            type: integer
            readOnly: true
          records:
            description: An array of records that belongs to the collection.
            items:
              $ref: '#/components/schemas/CollectionRecord'
            type: array
            maxItems: 30
        required:
        - collectionID
        - records
      - $ref: '#/components/schemas/Collection'
      x-addon: vanilla
    Collection:
      description: A collection of multiple  resources
      type: object
      properties:
        name:
          description: Name for the collection
          minLength: 1
          maxLength: 255
          type: string
        dateInserted:
          description: When the collection was created.
          format: date-time
          type: string
        dateUpdated:
          description: When the collection was last updated.
          format: date-time
          type:
          - string
          - 'null'
        insertUserID:
          description: The unique ID of the user that created this collection.
          type: integer
        updateUserID:
          description: The unique ID of the user who updated this collection.
          type:
          - integer
          - 'null'
        records:
          description: An array of records that belongs to the collection.
          items:
            $ref: '#/components/schemas/PostCollectionRecord'
          type: array
          maxItems: 30
      required:
      - name
      x-addon: vanilla
    CategorySchema:
      properties:
        categoryID:
          description: The ID of the category.
          type: integer
        countAllComments:
          description: Total of all comments in a category and its children.
          type: integer
        countAllDiscussions:
          description: Total of all discussions in a category and its children.
          type: integer
        countCategories:
          description: Total number of child categories.
          type: integer
        countComments:
          description: Total comments in the category.
          type: integer
        countDiscussions:
          description: Total discussions in the category.
          type: integer
        countFollowers:
          description: Total followers in the category.
          type: integer
        customPermissions:
          description: Are custom permissions set for this category?
          type: boolean
        description:
          description: The description of the category.
          minLength: 0
          type:
          - string
          - 'null'
        displayAs:
          type: string
          default: discussions
          description: The display style of the category.
          enum:
          - categories
          - discussions
          - flat
          - heading
          minLength: 1
        followed:
          description: Is the category being followed by the current user?
          type: boolean
        isArchived:
          description: The archived state of this category.
          type: boolean
        name:
          description: The name of the category.
          minLength: 1
          type: string
        parentCategoryID:
          description: Parent category ID.
          type:
          - integer
          - 'null'
        url:
          description: The URL to the category.
          minLength: 1
          type: string
        urlcode:
          description: The URL code of the category.
          minLength: 1
          type: string
        ideationType:
          description: Voting type used for ideation posts.
          enum:
          - up
          - up-down
          - false
          x-addon: ideation
        permissions:
          $ref: '#/components/schemas/DiscussionPermissions'
        defaultStatusID:
          description: The default status ID of the category.
          type: integer
      required:
      - categoryID
      - name
      - description
      - parentCategoryID
      - customPermissions
      - isArchived
      - urlcode
      - url
      - displayAs
      - countCategories
      - countDiscussions
      - countComments
      - countFollowers
      - countAllDiscussions
      - countAllComments
      type: object
      x-addon: vanilla
    BasicError:
      type: object
      properties:
        message:
          description: Verbose description of the error.
          type: string
        status:
          description: Response status code.
          type: integer
      required:
      - message
      - status
      x-addon: dashboard
    CollectionRecordContentSchema:
      allOf:
      - $ref: '#/components/schemas/CollectionRecord'
      - type: object
        properties:
          collectionID:
            description: The Id of the collection.
            type: integer
            readOnly: true
          record:
            description: The expanded data of the specific record
            type: object
            anyOf:
            - $ref: '#/components/schemas/Article'
            - $ref: '#/components/schemas/Discussion'
            - $ref: '#/components/schemas/CategorySchema'
            - $ref: '#/components/schemas/Group'
            - $ref: '#/components/schemas/FullEvent'
            - $ref: '#/components/schemas/FullKnowledgeBaseSchema'
          collection:
            description: The collection that the record belongs to
            type: object
            properties:
              collectionID:
                description: The Id of the collection.
                type: integer
                readOnly: true
              name:
                description: Name for the collection
                type: string
      x-addon: vanilla
    StatusFragment:
      type: object
      description: Describes a status currently applied to a discussion. Expandable with `status` and `status.log` expands.
      properties:
        statusID:
          description: Record status ID of the discussion status.
          type: integer
        name:
          description: The name of the status.
          type: string
        recordType:
          description: Type of the discussion status.
          type: string
          enum:
          - discussion
        recordSubType:
          description: Some statuses may only apply to a specific subtype of record.
          type: string
        state:
          description: States are used to group statuses together.
          type: string
          enum:
          - open
          - closed
        dateUpdated:
          type: string
          format: date-time
          description: When the discussion was updated with the status.
        log:
          type: object
          description: Information about when the status was applied.
          required:
          - dateUpdated
          - updateUser
          properties:
            reasonUpdated:
              description: Reason for status change
              type:
              - string
              - 'null'
            updateUser:
              $ref: '#/components/schemas/UserFragment'
            dateUpdated:
              description: When the discussion was last updated.
              format: date-time
              type: string
      required:
      - statusID
      - name
      - recordType
      - state
      x-addon: vanilla
    PostFragment:
      properties:
        discussionID:
          description: The discussion ID of the post.
          type: integer
        commentID:
          description: The comment ID of the post, if any.
          type: integer
        name:
          description: The title of the post.
          minLength: 1
          type: string
        body:
          description: The HTML formatted body of the post.
          type: string
        url:
          description: The URL of the post.
          minLength: 1
          type: string
        dateInserted:
          description: The date of the post.
          format: date-time
          type: string
        insertUser:
          $ref: '#/components/schemas/UserFragment'
        insertUserID:
          description: The author of the post.
          type: integer
      required:
      - name
      - url
      - dateInserted
      - insertUserID
      type: object
      x-addon: vanilla
    Discussion:
      properties:
        attributes:
          properties:
            idea:
              properties:
                status:
                  properties:
                    name:
                      description: Label for the status.
                      minLength: 1
                      type: string
                    state:
                      description: The open/closed state of an idea.
                      enum:
                      - open
                      - closed
                      minLength: 1
                      type: string
                  required:
                  - name
                  - state
                  type: object
                statusID:
                  description: Unique numeric ID of a status.
                  type: integer
                statusNotes:
                  description: Status update notes.
                  minLength: 1
                  type:
                  - string
                  - 'null'
                type:
                  description: 'Voting type for this idea: up-only or up and down.'
                  enum:
                  - up
                  - up-down
                  minLength: 1
                  type: string
              required:
              - statusNotes
              - statusID
              - status
              - type
              type: object
              x-addon: ideation
          type: object
        body:
          description: The body of the discussion.
          minLength: 1
          type: string
        bookmarked:
          description: Whether or not the discussion is bookmarked by the current user.
          type: boolean
        muted:
          description: Whether or not the discussion is muted by the current user.
          type: boolean
        category:
          $ref: '#/components/schemas/CategoryFragment'
        categoryID:
          description: The category the discussion is in.
          type: integer
        closed:
          description: Whether the discussion is closed or open.
          type: boolean
        isLivePost:
          description: true if this post is live.
          type: boolean
        countComments:
          description: The number of comments on the discussion.
          type: integer
        countUnread:
          description: The number of unread comments.
          type: integer
        countViews:
          description: The number of views on the discussion.
          type: integer
        dateInserted:
          description: When the discussion was created.
          format: date-time
          type: string
        dateUpdated:
          description: When the discussion was last updated.
          format: date-time
          type:
          - string
          - 'null'
        dateLastComment:
          description: The date of the last comment or the original discussion date if it has no comments.
          type: string
          format: date-time
        discussionID:
          description: The ID of the discussion.
          type: integer
        image:
          $ref: '#/components/schemas/Image'
        images:
          description: List of all images in the post.
          items:
            $ref: '#/components/schemas/Image'
        insertUser:
          $ref: '#/components/schemas/UserFragment'
        insertUserID:
          description: The user that created the discussion.
          type: integer
        lastPost:
          $ref: '#/components/schemas/PostFragment'
        lastUserID:
          type: integer
          description: The last user to post in the discussion.
        lastUser:
          $ref: '#/components/schemas/UserFragment'
        name:
          description: The title of the discussion.
          minLength: 1
          type: string
        pinLocation:
          description: The location for the discussion, if pinned. "category" are pinned to their own category. "recent" are pinned to the recent discussions list, as well as their own category.
          enum:
          - category
          - recent
          minLength: 1
          type:
          - string
          - 'null'
        pinned:
          description: Whether or not the discussion has been pinned.
          type: boolean
        publishedSilently:
          description: Whether or not the discussion was published silently.
          type: boolean
        contentLocale:
          description: The locale from which the discussion name/body were last updated.
          type: string
        score:
          description: Total points associated with this post.
          type:
          - integer
          - 'null'
        announce:
          description: Whether or not the discussion has been announced.
          type: boolean
        sink:
          description: Whether or not the discussion has been sunk.
          type: boolean
        unread:
          description: Whether or not the discussion should have an unread indicator.
          type: boolean
        url:
          description: The full URL to the discussion.
          type: string
        statusID:
          type: integer
          description: The statusID current applied to the discussion.
        status:
          $ref: '#/components/schemas/StatusFragment'
        showSuggestions:
          type: boolean
          description: Whether the discussion has visible suggestions
          x-feature: Feature.AISuggestions.Enabled
        reportMeta:
          $ref: '#/components/schemas/ReportMeta'
        type:
          description: The base post type of the discussion.
          minLength: 1
          type: string
          enum:
          - discussion
          - idea
          - question
        postTypeID:
          description: The discussions postType.
          type: string
        postMeta:
          $ref: '#/components/schemas/PostMeta'
        suggestions:
          type: array
          items:
            properties:
              format:
                type: string
                description: Source of the suggestion
              sourceIcon:
                type: string
                description: Icon of the suggestion source
              type:
                type: string
                description: Type of suggestion discussion/comment
              id:
                type: integer
                description: Index of the suggestion
              url:
                type: string
                description: URL of the suggestion
              title:
                type: string
                description: Title of the suggestion
              summary:
                type: string
                description: Summary of the suggestion
              hidden:
                type: boolean
                description: Whether the suggestion is dismissed
              commentID:
                type: integer
                description: Comment ID of the suggestion
            type: object
          x-feature: Feature.AISuggestions.Enabled
        permissions:
          $ref: '#/components/schemas/DiscussionPermissions'
      required:
      - discussionID
      - type
      - name
      - body
      - categoryID
      - dateInserted
      - dateUpdated
      - insertUserID
      - pinLocation
      - closed
      - sink
      - countComments
      - countViews
      - score
      - bookmarked
      - muted
      - unread
      - attributes
      type: object
      x-addon: vanilla
    PostCollectionRecord:
      properties:
        recordID:
          description: The ID of the corresponding record
          type: integer
        recordType:
          description: The type of the record.
          enum:
          - article
          - category
          - discussion
          - event
          - groups
          - knowledgeBase
          type: string
        sort:
          description: Manual sort order for the group
          type:
          - integer
          - 'null'
      required:
      - recordID
      - recordType
      type: object
      x-addon: vanilla
    ReportReasonFragment:
      type: object
      properties:
        reportReasonID:
          type: string
        name:
          type: string
        description:
          type: string
        sort:
          type: integer
        reportID:
          type: integer
        deleted:
          type: boolean
      required:
      - reportReasonID
      - name
      - description
      - sort
      - deleted
      x-addon: vanilla
    Image:
      description: An image, pulled from content.
      type: object
      properties:
        url:
          description: The original image URL.
          type: string
        urlSrcSet:
          $ref: '#/components/schemas/SrcSet'
        alt:
          description: The image's alternative text.
          type: string
      x-addon: dashboard
    CollectionRecord:
      allOf:
      - type: object
        properties:
          dateAddedToCollection:
            description: When the record was added to collection.
            format: date-time
            type: string
      - $ref: '#/components/schemas/PostCollectionRecord'
      x-addon: vanilla
    ReportMeta:
      type: object
      properties:
        reportsReasons:
          type: array
          description: Report reasons.
          items:
            $ref: '#/components/schemas/ReportReasonFragment'
        reportUserIDs:
          description: User IDs that have reported this post.
          type: array
          items:
            type: integer
        reportUsers:
          description: Users that have reported this post.
          type: array
          items:
            $ref: '#/components/schemas/UserFragment'
        countReportUsers:
          description: The number of users that have reported this post.
          type: number
        reportGuestUsers:
          description: Guest reporters, with email and name.
          type: array
          items:
            type: object
            properties:
              reporterEmail:
                type: string
                description: The guest reporter's email address.
              reporterName:
                type: string
                description: The guest reporter's display name.
            required:
            - reporterEmail
        dateLastReport:
          description: The date of the last report on the post.
          type: string
          format: date-time
        countReports:
          type: integer
          default: 0
          description: The number of reports on the post.
      x-addon: vanilla
    PostMeta:
      type: object
      description: Custom post fields. This is an object keyed by postFieldID.
      example:
        my-field: value1
        my-arrayField:
        - arrVal1
        - arrVal2
      x-addon: vanilla
    RangeExpression:
      description: Specify a range or CSV of values.
      type: string
      format: range-expression
      externalDocs:
        url: https://success.vanillaforums.com/kb/articles/308-range-expressions
      x-addon: dashboard
    DiscussionPermissions:
      type: object
      description: Permissions for the current user related to discussions. Applied when expanded..
      example:
        discussions.view: true
        discussions.add: true
        discussions.edit: false
        discussions.delete: false
        discussions.sink: false
        comments.add: true
        comments.edit: false
        comments.delete: false
      x-addon: vanilla
    SrcSet:
      description: An image's srcset for various sizes.
      type: object
      properties:
        '10':
          description: 10px large Image url.
          type: string
        '300':
          description: 300px large Image url.
          type: string
        '800':
          description: 800px large Image url.
          type: string
        '1200':
          description: 1200px large Image url.
          type: string
      x-addon: dashboard
    CollectionContentSchema:
      description: A collection resource with records expanded
      type: object
      properties:
        collectionID:
          description: The Id of the collection.
          type: integer
          readOnly: true
        name:
          description: Name for the collection
          minLength: 1
          maxLength: 255
          type: string
        records:
          description: An array of records that belongs to t

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