api.yaml

openapi: "3.0.2"
info:
  description: "This is the Scoold API. First, you need to generate an [API key](/admin) in order to access the API."
  version: "1.6.1"
  title: "Scoold API documentation"
externalDocs:
  description: "README"
  url: "https://github.com/Erudika/scoold"
servers:
  - url: {{serverUrl}}{{contextPath}}
tags:
- name: "posts"
- name: "users"
- name: "tags"
- name: "comments"
- name: "reports"
- name: "spaces"
- name: "webhooks"
- name: "search"
- name: "stats"
- name: "backups"
- name: "config"
paths:
  /api:
    get:
      summary: General information and health
      tags:
        - stats
      responses:
        '200':
          description: Server is healthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Health'

        '500':
          description: Server is unhealthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Health'
  /api/posts:
    post:
      summary: Create a new post
      description: To publish the post in the given space, set the `space` field. Otherwise the post will be created in the default space.<br>To change the author, set the `creatorid` field to an existing user.<br>To create an answer, set field `type` to `reply` and specify `parentid` to be the ID of the question post.<br>The `body` of the post can contain GitHub-flavored Markdown and mentions like `@<user_id|John Doe>`.
      tags:
        - posts
      security:
      - scoold_auth: []
      parameters:
        - name: notificationsDisabled
          in: query
          required: false
          description: If set, all notifications for newly created posts will be disabled. This is to prevent spamming users when creating posts in bulk.
          schema:
            type: boolean
      requestBody:
        description: The request entity
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Post'
      responses:
        '201':
          description: A new post object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Post'
        '400':
          description: Bad request - missing or invalid request entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      summary: List questions on the front page
      tags:
        - posts
      security:
      - scoold_auth: []
      parameters:
        - name: sortby
          in: query
          required: false
          description: The `sortby` parameter could be a property name like `votes` or `properties.answercount` or a category like `activity`, `unanswered`, `unapproved` (posts without an approved answer)
          schema:
            type: string
        - name: space
          in: query
          required: false
          schema:
            type: string
        - name: filter
          in: query
          required: false
          description: The `filter` is used to filter results based on tags or location
          schema:
            type: string
            enum: [favtags, local]
        - name: q
          in: query
          required: false
          description: Allows for an additional fine tuned query to be applied to the other filters.
          schema:
            type: string
        - name: includeReplies
          in: query
          required: false
          description: If `true`, answers will be returned embedded inside the `children` array property of each question object.
          schema:
            type: boolean
        - name: favtags
          in: query
          required: false
          description: Used in combination with the `favtags` filter parameter to filter posts based on a set of tags
          schema:
            type: array
            items:
              type: string
        - name: latlng
          in: query
          required: false
          description: Used in combination with the `local` filter parameter to filter posts based on location, for example `42.32,24.53`
          schema:
            type: string
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/sortby'
        - $ref: '#/components/parameters/desc'
      responses:
        '200':
          description: A page of posts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Posts'
  /api/posts/{id}:
    get:
      summary: Returns a specific post along with its children (replies) and similar posts
      description: You can paginate through child objects using the `page` parameter
      tags:
        - posts
      security:
      - scoold_auth: []
      parameters:
        - name: id
          in: path
          required: true
          description: The id of the post to retrieve
          schema:
            type: string
        - name: sortby
          in: query
          required: false
          description: Sort children by field
          schema:
            type: string
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/sortby'
        - $ref: '#/components/parameters/desc'
      responses:
        '200':
          description: A post object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Post'
        '404':
          description: Not found
    patch:
      summary: Update post
      description: To change the user who edited the question, specify `lasteditby` in the request body. Additionally, you can modify the properties `space`, `latlng` and `location` in the request body to change their values.
      tags:
        - posts
      security:
      - scoold_auth: []
      parameters:
        - name: id
          in: path
          required: true
          description: The id of the post to update
          schema:
            type: string
      requestBody:
        description: The request entity
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Post'
      responses:
        '200':
          description: Post was updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Post'
        '400':
          description: Bad request - missing or invalid request entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
    delete:
      summary: Delete post
      tags:
        - posts
      security:
      - scoold_auth: []
      parameters:
        - name: id
          in: path
          required: true
          description: The id of the post to delete
          schema:
            type: string
      responses:
        '200':
          description: Post was deleted
        '404':
          description: Not found
  /api/posts/{id}/tags:
    patch:
      summary: Edit question tags
      description: Add or remove question tags. To change the user who edited the question, specify `lasteditby` in the request body.
      tags:
        - posts
      security:
      - scoold_auth: []
      parameters:
        - name: id
          in: path
          required: true
          description: The id of the post to update
          schema:
            type: string
      requestBody:
        description: The request entity
        required: true
        content:
          application/json:
            schema:
              properties:
                add:
                  description: A list of tags to add to the question
                  type: array
                  items:
                    type: string
                remove:
                  description: A list of tags to remove from the question
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Post was updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Post'
        '400':
          description: Bad request - missing or invalid request entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Post not found
  /api/posts/{id}/approve:
    put:
      summary: Approve a post which awaits approval by a moderator
      description: Only works for posts of type `UnapprovedQuestion` or `UnapprovedReply`
      tags:
        - posts
      security:
      - scoold_auth: []
      parameters:
        - name: id
          in: path
          required: true
          description: The id of the post
          schema:
            type: string
      responses:
        '200':
          description: Post was approved
  /api/posts/{id}/accept/{replyid}:
    put:
      summary: Accept an answer (reply) to post as the best answer
      description: Only works for posts of type `Reply`. This works as a toggle - each subsequent request will undo the previous action.
      tags:
        - posts
      security:
      - scoold_auth: []
      parameters:
        - name: id
          in: path
          required: true
          description: The id of the post
          schema:
            type: string
        - name: replyid
          in: path
          required: true
          description: The id of the `Reply` to accept
          schema:
            type: string
      responses:
        '200':
          description: Post was accepted
  /api/posts/{id}/close:
    put:
      summary: Closes or opens a post - closed posts cannot have any more replies
      description: Only works for posts of type `Question`. This works as a toggle - each subsequent request will undo the previous action.
      tags:
        - posts
      security:
      - scoold_auth: []
      parameters:
        - name: id
          in: path
          required: true
          description: The id of the post
          schema:
            type: string
      responses:
        '200':
          description: Post was closed
  /api/posts/{id}/pin:
    put:
      summary: Pins or unpins a post - pinned posts always stay on top
      description: Only works for posts of type `Question` or `Sticky`. This works as a toggle - each subsequent request will undo the previous action.
      tags:
        - posts
      security:
      - scoold_auth: []
      parameters:
        - name: id
          in: path
          required: true
          description: The id of the post
          schema:
            type: string
      responses:
        '200':
          description: Post was pinned
  /api/posts/{id}/restore/{revisionid}:
    put:
      summary: Restores a revision of a post
      description: Restoring a revision reverts the content of a post to a previous state.
      tags:
        - posts
      security:
      - scoold_auth: []
      parameters:
        - name: id
          in: path
          required: true
          description: The id of the post
          schema:
            type: string
        - name: revisionid
          in: path
          required: true
          description: The id of the revision to restore
          schema:
            type: string
      responses:
        '200':
          description: Revision was restored
  /api/posts/{id}/like:
    put:
      summary: Likes or unlikes a post - liked posts go to a user's favorites list
      description: Only works for posts of type `Question` or `Sticky`. This works as a toggle - each subsequent request will undo the previous action.
      tags:
        - posts
      security:
      - scoold_auth: []
      parameters:
        - name: id
          in: path
          required: true
          description: The id of the post
          schema:
            type: string
      responses:
        '200':
          description: Post was liked
  /api/posts/{id}/voteup:
    put:
      summary: Upvotes a post
      description: Upvotes
      tags:
        - posts
      security:
      - scoold_auth: []
      parameters:
        - name: id
          in: path
          required: true
          description: The id of the post
          schema:
            type: string
        - name: userid
          in: query
          required: true
          description: The id of the user voting
          schema:
            type: string
      responses:
        '200':
          description: vote succeeded
        '400':
          description: vote failed
  /api/posts/{id}/votedown:
    put:
      summary: Downvotes a post
      description: Downvotes
      tags:
        - posts
      security:
      - scoold_auth: []
      parameters:
        - name: id
          in: path
          required: true
          description: The id of the post
          schema:
            type: string
        - name: userid
          in: query
          required: true
          description: The id of the user voting
          schema:
            type: string
      responses:
        '200':
          description: vote succeeded
        '400':
          description: vote failed
  /api/posts/{id}/answers:
    get:
      summary: Returns a page of answers for a given post
      description: You can paginate through answers by setting the parameters `sortby`, `desc`, `limit` and `page`.
      tags:
        - posts
      security:
      - scoold_auth: []
      parameters:
        - name: id
          in: path
          required: true
          description: The id of the parent question
          schema:
            type: string
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/sortby'
        - $ref: '#/components/parameters/desc'
      responses:
        '200':
          description: A list of answers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Posts'
        '404':
          description: Not found
  /api/posts/{id}/comments:
    get:
      summary: Returns a page of comments for a given post
      description: By default, oldest comments are returned first, 5 per page. You can change that by setting the parameters `sortby`, `desc`, `limit` and `page`.
      tags:
        - posts
      security:
      - scoold_auth: []
      parameters:
        - name: id
          in: path
          required: true
          description: The id of the post to retrieve
          schema:
            type: string
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/sortby'
        - $ref: '#/components/parameters/desc'
      responses:
        '200':
          description: A list of comments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Comments'
        '404':
          description: Not found
  /api/posts/{id}/revisions:
    get:
      summary: Returns a page of revisions for a given post
      description: You can paginate through results using the parameters `sortby`, `desc`, `limit` and `page`.
      tags:
        - posts
      security:
      - scoold_auth: []
      parameters:
        - name: id
          in: path
          required: true
          description: The id of the post to retrieve
          schema:
            type: string
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/sortby'
        - $ref: '#/components/parameters/desc'
      responses:
        '200':
          description: A list of revisions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Revisions'
        '404':
          description: Not found
  /api/users:
    post:
      summary: Create a new user
      description: To assign spaces to users, use the `spaces` field. Otherwise the user will be assigned to the default space.<br>The `user` field contains the core Para `User` corresponding to the new `Profile` object.
      tags:
        - users
      security:
      - scoold_auth: []
      requestBody:
        description: The request entity. **Note:** `id` field will be ignored as all user ids are auto-generated by Para.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '201':
          description: A new user object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Profile'
        '400':
          description: Bad request - missing or invalid request entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      summary: List users
      tags:
        - users
      security:
      - scoold_auth: []
      parameters:
        - name: q
          in: query
          required: false
          example: "*"
          description: A query string to find specific users
          schema:
            type: string
        - name: sortby
          in: query
          required: false
          example: "timestamp"
          description: This could be a property name like `votes`, `properties.yearlyVotes`, `properties.quarterlyVotes`, `properties.monthlyVotes`  or `properties.weeklyVotes`.
          schema:
            type: string
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/sortby'
        - $ref: '#/components/parameters/desc'
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Profiles'
  /api/users/{id}:
    get:
      summary: Returns a specific user profile along with its user object
      tags:
        - users
      security:
      - scoold_auth: []
      parameters:
        - name: id
          in: path
          required: true
          description: The id of the user to retrieve
          schema:
            type: string
      responses:
        '200':
          description: A user profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Profile'
        '404':
          description: Not found
    patch:
      summary: Update user
      tags:
        - users
      security:
      - scoold_auth: []
      parameters:
        - name: id
          in: path
          required: true
          description: The id of the user to update
          schema:
            type: string
      requestBody:
        description: The request entity
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Profile'
      responses:
        '200':
          description: Post was updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Profile'
        '404':
          description: Not found
    delete:
      summary: Delete user
      tags:
        - users
      security:
      - scoold_auth: []
      parameters:
        - name: id
          in: path
          required: true
          description: The id of the user to delete
          schema:
            type: string
      responses:
        '200':
          description: Profile and user objects were deleted
        '404':
          description: Not found
  /api/users/{id}/questions:
    get:
      summary: Returns a list of questions created by a user
      tags:
        - users
      security:
      - scoold_auth: []
      parameters:
        - name: id
          in: path
          required: true
          description: The id of the user to retrieve
          schema:
            type: string
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/sortby'
        - $ref: '#/components/parameters/desc'
      responses:
        '200':
          description: A list of posts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Posts'
        '404':
          description: Not found
  /api/users/{id}/replies:
    get:
      summary: Returns a list of replies (answers) created by a user
      tags:
        - users
      security:
      - scoold_auth: []
      parameters:
        - name: id
          in: path
          required: true
          description: The id of the user to retrieve
          schema:
            type: string
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/sortby'
        - $ref: '#/components/parameters/desc'
      responses:
        '200':
          description: A list of posts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Posts'
        '404':
          description: Not found
  /api/users/{id}/favorites:
    get:
      summary: Returns a list of a user's favorite posts
      tags:
        - users
      security:
      - scoold_auth: []
      parameters:
        - name: id
          in: path
          required: true
          description: The id of the user to retrieve
          schema:
            type: string
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/sortby'
        - $ref: '#/components/parameters/desc'
      responses:
        '200':
          description: A list of posts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Posts'
        '404':
          description: Not found
  /api/users/{id}/moderator:
    put:
      summary: Promote or demote user as moderator
      description: This works as a toggle - each subsequent request will undo the previous action.
      tags:
        - users
      security:
      - scoold_auth: []
      parameters:
        - name: id
          in: path
          required: true
          description: The id of the user to promote/demote
          schema:
            type: string
        - name: spaces
          in: query
          required: false
          description: A comma-separated list of spaces in which the user will be promoted/demoted to moderator. Endpoint acts a toggle switch. This parameter is **only required if** `scoold.mods_access_all_spaces = false`.
          schema:
            type: string
      responses:
        '200':
          description: User was promoted or demoted
  /api/users/{id}/ban:
    put:
      summary: Ban or unban user
      description: You can permanently ban a user with `banuntil=-1`
      tags:
        - users
      security:
      - scoold_auth: []
      parameters:
        - name: id
          in: path
          required: true
          description: The id of the user to ban/unban
          schema:
            type: string
        - name: banuntil
          in: query
          required: false
          description: Ban period end date as a future Unix timestamp in milliseconds, use `0` to unban, `-1` to permaban
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: User was banned or unbanned
  /api/users/spaces:
    put:
      summary: Edit spaces in bulk
      description: Map users to spaces
      tags:
        - users
      security:
      - scoold_auth: []
      parameters:
        - name: operation
          in: query
          required: false
          description: The type of operation for adding multiple spaces - `add`, `remove` or `set`.
          schema:
            type: string
      requestBody:
        description: The request entity
        required: true
        content:
          application/json:
            schema:
              properties:
                spaces:
                  description: list of spaces
                  type: array
                  items:
                    type: string
                users:
                  description: list of user ids
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Spaces were updated
  /api/tags:
    post:
      summary: Create a new tag
      tags:
        - tags
      security:
      - scoold_auth: []
      requestBody:
        description: The request entity
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Tag'
      responses:
        '201':
          description: A new tag object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tag'
        '400':
          description: Bad request - missing or invalid request entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      summary: List tags
      description: Returns a page of tags. Use the `page` parameter to paginate through results.
      tags:
        - tags
      security:
      - scoold_auth: []
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/sortby'
        - $ref: '#/components/parameters/desc'
      responses:
        '200':
          description: A page of tags returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tags'
  /api/tags/{id}:
    get:
      summary: Get tag
      tags:
        - tags
      security:
      - scoold_auth: []
      parameters:
        - name: id
          in: path
          required: true
          description: The id of the tag to get
          schema:
            type: string
      responses:
        '200':
          description: Tag object returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tag'
        '404':
          description: Not found
    patch:
      summary: Rename tag
      tags:
        - tags
      security:
      - scoold_auth: []
      parameters:
        - name: id
          in: path
          required: true
          description: The id of the tag to rename
          schema:
            type: string
      requestBody:
        description: The request entity
        required: true
        content:
          application/json:
            schema:
              properties:
                tag:
                  description: The new name of the tag
                  type: string
                  example: new-tag-name
                description:
                  description: The new description of the tag
                  type: string
                  example: some text
      responses:
        '200':
          description: Tag was renamed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tag'
        '404':
          description: Not found
    delete:
      summary: Delete tag
      tags:
        - tags
      security:
      - scoold_auth: []
      parameters:
        - name: id
          in: path
          required: true
          description: The id of the tag to delete
          schema:
            type: string
      responses:
        '200':
          description: Tag was deleted
        '404':
          description: Not found
  /api/tags/{id}/questions:
    get:
      summary: List questions tagged with a specific tag
      tags:
        - tags
      security:
      - scoold_auth: []
      parameters:
        - name: id
          in: path
          required: true
          description: The id of the tag
          schema:
            type: string
      responses:
        '200':
          description: Tag object returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Posts'
  /api/comments:
    post:
      summary: Create a new comment
      tags:
        - comments
      security:
      - scoold_auth: []
      requestBody:
        description: Set `creatorid` to change the author of the comment. Set `parentid` to the id of an existing post.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Comment'
      responses:
        '201':
          description: A new comment object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Comment'
        '400':
          description: Bad request - missing or invalid request entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/comments/{id}:
    get:
      summary: Get comment
      tags:
        - comments
      security:
      - scoold_auth: []
      parameters:
        - name: id
          in: path
          required: true
          description: The id of the comment to get
          schema:
            type: string
      responses:
        '200':
          description: Comment object returned
          content:
            application/json:
                schema:
                  $ref: '#/components/schemas/Comment'
        '404':
          description: Not found
    delete:
      summary: Delete comment
      tags:
        - comments
      security:
      - scoold_auth: []
      parameters:
        - name: id
          in: path
          required: true
          description: The id of the comment to delete
          schema:
            type: string
      responses:
        '200':
          description: Comment was deleted
  /api/reports:
    post:
      summary: Create a new report
      description: You can store any additional properties in the report object - simply pass those as JSON in the request body.
      tags:
        - reports
      security:
      - scoold_auth: []
      requestBody:
        description: Set `creatorid` to change the author of the report.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Report'
      responses:
        '201':
          description: A new report object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Report'
        '400':
          description: Bad request - missing or invalid request entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      summary: List reports
      tags:
        - reports
      security:
      - scoold_auth: []
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/sortby'
        - $ref: '#/components/parameters/desc'
      responses:
        '200':
          description: a page of report objects returned
          content:
            application/json:
                schema:
                  $ref: '#/components/schemas/Reports'
  /api/reports/{id}:
    get:
      summary: Get report
      tags:
        - reports
      security:
      - scoold_auth: []
      parameters:
        - name: id
          in: path
          required: true
          description: The id of the report to get
          schema:
            type: string
      responses:
        '200':
          description: Report object returned
          content:
            application/json:
                schema:
                  $ref: '#/components/schemas/Report'
        '404':
          description: Not found
    delete:
      summary: Delete report
      tags:
        - reports
      security:
      - scoold_auth: []
      parameters:
        - name: id
          in: path
          required: true
          description: The id of the report to delete
          schema:
            type: string
      responses:
        '200':
          description: Report was deleted
  /api/reports/{id}/close:
    put:
      summary: Close report
      tags:
        - reports
      security:
      - scoold_auth: []
      parameters:
        - name: id
          in: path
          required: true
          description: The id of the report to close
          schema:
            type: string
      requestBody:
        description: The request entity
        required: true
        content:
          application/json:
            schema:
              properties:
                solution:
                  description: Actions taken to solve the issue
                  type: string
      responses:
        '200':
          description: Report was closed
  /api/spaces:
    post:
      summary: Create a new space
      tags:
        - spaces
      security:
      - scoold_auth: []
      parameters:
        - name: assigntoall
          in: query
          required: false
          description: If `true`, space will be assigned to all new and existing users
          schema:
            type: boolean
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Space'
      responses:
        '201':
          description: A new space object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Space'
        '400':
          description: Bad request - missing or invalid request entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      summary: List spaces
      tags:
        - spaces
      security:
      - scoold_auth: []
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/sortby'
        - $ref: '#/components/parameters/desc'
      responses:
        '200':
          description: A page of space objects returned
          content:
            application/json:
                schema:
                  $ref: '#/components/schemas/Spaces'
  /api/spaces/{id}:
    get:
      summary: Get space
      tags:
        - spaces
      security:
      - scoold_auth: []
      parameters:
        - name: id
          in: path
          required: true
          description: The id of the space to get
          schema:
            type: string
      responses:
        '200':
          description: Space object returned
          content:
            application/json:
                schema:
                  $ref: '#/components/schemas/Space'
        '404':
          description: Not found
    patch:
      summary: Rename space
      tags:
        - spaces
      security:
      - scoold_auth: []
      parameters:
        - name: id
          in: path
          required: true
          description: The id of an existing space
          schema:
            type: string
        - name: assigntoall
          in: query
          required: false
          description: If `true`, space will be assigned to all new and existing users
          schema:
            type: boolean
        - name: needsapproval
          in: query
          required: false
          description: If `false`, space will not require moderators to approve each post.
          schema:
            type: boolean
      requestBody:
        required: true
        description: The request body must contain the `name` field as the new name for that space.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Space'
      responses:
        '200':
          description: Space was updated, empty response.
    delete:
      summary: Delete space
      tags:
        - spaces
      security:
      - scoold_auth: []
      parameters:
        - name: id
          in: path
          required: true
          description: The id of the space to delete
          schema:
            type: string
      responses:
        '200':
          description: Space was deleted
  /api/webhooks:
    post:
      summary: Create a new webhook
      tags:
        - webhooks
      security:
      - scoold_auth: []
      requestBody:
        description: The request entity
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Webhook'
      responses:
        '201':
          description: A new webhook object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '400':
          description: Bad request - missing or invalid request entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      summary: List webhooks
      description: Returns a page of webhooks. Use the `page` parameter to paginate through results.
      tags:
        - webhooks
      security:
      - scoold_auth: []
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/sortby'
        - $ref: '#/components/parameters/desc'
      responses:
        '200':
          description: A page of webhooks returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhooks'
  /api/webhooks/{id}:
    get:
      summary: Get webhook
      tags:
        - webhooks
      security:
      - scoold_auth: []
      parameters:
        - name: id
          in: path
          required: true
          description: The id of the webhook to get
          schema:
            type: string
      responses:
        '200':
          description: Webhook object returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '404':
          description: Not found
    patch:
      summary: Update webhook
      tags:
        - webhooks
      security:
      - scoold_auth: []
      parameters:
        - name: id
          in: path
          required: true
          description: The id of the webhook to update
          schema:
            type: string
      requestBody:
        description: The request entity
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Webhook'
      responses:
        '200':
          description: Webhook was updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '404':
          description: Not found
    delete:
      summary: Delete webhook
      tags:
        - webhooks
      security:
      - scoold_auth: []
      parameters:
        - name: id
          in: path
          required: true
          description: The id of the webhook to delete
          schema:
            type: string
      responses:
        '200':
          description: Webhook was deleted
        '404':
          description: Not found
  /api/events:
    get:
      summary: List webhook events
      description: The list does not contain the standard `create`, `update`, `delete`, `createAll`, `updateAll`, `deleteAll`. You can subscribe to these events by creating a webhook with a `customEvents` property containing one or more of these events.
      tags:
        - webhooks
      security:
      - scoold_auth: []
      responses:
        '200':
          description: A list of events
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
  /api/types:
    get:
      summary: List available data types for use as webhook type filters.
      description: You can subscribe to CRUD events in combination with a type filter.
      tags:
        - webhooks
      security:
      - scoold_auth: []
      responses:
        '200':
          description: A list of data types
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
  /api/search/{type}/{query}:
    get:
      summary: Perform full-text search on objects of given type
      tags:
        - search
      security:
      - scoold_auth: []
      parameters:
        - name: type
          in: path
          required: true
          description: The type of object to search for - one of `question`, `reply`, `user`, `profile`, `comment`, `report`, `revision`, `badge`, `feedback`.
          schema:
            type: string
        - name: query
          in: path
          required: true
          description: The search query
          schema:
            type: string
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/sortby'
        - $ref: '#/components/parameters/desc'
      responses:
        '200':
          description: found objects returned
          content:
            application/json:
              schema:
                properties:
                  totalHits:
                    description: number of total hits for this query
                    type: integer
                  page:
                    description: the page number
                    type: integer
                  items:
                    description: a list of search results
                    type: array
                    items:
                      type: object
                  lastKey:
                    description: the last key property of the pager for "searchAfter" queries
                    type: string
  /api/stats:
    get:
      summary: Returns various system statistics and server versions
      tags:
        - stats
      security:
      - scoold_auth: []
      parameters:
        - name: includeLogs
          in: query
          required: false
          description: If set to `true` will read and return the Scoold log file as well.
          schema:
            type: boolean
        - name: maxLogLines
          in: query
          required: false
          description: The number of log lines to return, default is `10000`.
          schema:
            type: integer
      responses:
        '200':
          description: stats
  /api/backup:
    get:
      summary: Returns a backup ZIP archive of all the data in Scoold
      tags:
        - backups
      security:
      - scoold_auth: []
      responses:
        '200':
          description: A ZIP backup archive
          content:
            application/zip:
              schema:
                type: string
                format: binary
        '403':
          description: Forbidden - this feature is disabled or invalid request.
  /api/restore:
    put:
      summary: Restores (asynchronously) a backup ZIP archive, overwriting all existing data in Scoold
      tags:
        - backups
      security:
      - scoold_auth: []
      requestBody:
        description: A ZIP backup archive
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  description: The binary zip file to restore data from.
                  type: string
                  format: binary
                isso:
                  description: Flag to indicate if zip archive is coming from Stack Overflow for Teams
                  type: boolean
                deleteall:
                  description: Flag to delete all existing objects before importing the new archive
                  type: boolean
      responses:
        '200':
          description: Restore operation has started asynchronously but is not necessarily complete.
        '403':
          description: Forbidden - this feature is disabled or invalid request.
  /api/config:
    get:
      summary: Returns the current Scoold configuration as a list of properties in the HOCON or JSON formats.
      tags:
        - config
      security:
      - scoold_auth: []
      parameters:
        - name: format
          in: query
          required: false
          description: The format of the response - either `hocon` or `json`. Default format is `json`.
          schema:
            type: string
      responses:
        '200':
          description: either a JSON object or a HOCON string
    put:
      summary: Overrides multiple configuration properties at once, with a values supplied in the request body. This **will update and overwrite** the `appication.conf` file on disk.
      tags:
        - config
      security:
      - scoold_auth: []
      requestBody:
        description: All configuration properties and values inside a JSON object or HOCON string. Property keys **must not start with** the `scoold.` prefix.
        required: true
        content:
          application/json:
            schema:
              type: object
          application/hocon:
            schema:
              type: string
      responses:
        '200':
          description: Returns the whole updated Scoold configuration as a JSON object
          content:
            application/json:
              schema:
                type: object
        '400':
          description: missing request body
  /api/config/get/{key}:
    get:
      summary: Returns the value of a single configuration property, or its default value if not configured.
      tags:
        - config
      security:
      - scoold_auth: []
      parameters:
        - name: key
          in: path
          required: true
          description: The configuration property key **without** the `scoold.` prefix.
          schema:
            type: string
      responses:
        '200':
          description: The new configuration value inside an envelope object.
          content:
            application/json:
              schema:
                properties:
                  value:
                    description: any value
  /api/config/set/{key}:
    put:
      summary: Overrides a single configuration property with a new value supplied in the request body. This **will update and overwrite** the `appication.conf` file on disk.
      tags:
        - config
      security:
      - scoold_auth: []
      parameters:
        - name: key
          in: path
          required: true
          description: The configuration property key **without** the `scoold.` prefix.
          schema:
            type: string
      requestBody:
        description: A new configuration value
        required: true
        content:
          application/json:
            schema:
              properties:
                value:
                  description: any value
      responses:
        '200':
          description: empty response body
        '400':
          description: missing request body
  /api/config/options:
    get:
      summary: Returns the current Scoold configuration as a list of properties in the HOCON or JSON formats.
      tags:
        - config
      security:
      - scoold_auth: []
      parameters:
        - name: format
          in: query
          required: false
          description: The format of the response - one of `markdown`, `hocon` or `json`. Default is `json`.
          schema:
            type: string
        - name: groupby
          in: query
          required: false
          description: The way to group properties - either by `category` or by `key`. Default is by `key`.
          schema:
            type: string
      responses:
        '200':
          description: either a JSON object or a Markdown/HOCON string
components:
  schemas:
    Post:
      required:
        - id
        - title
      properties:
        id:
          type: integer
          format: int64
        timestamp:
          type: integer
          format: int64
          description: Unix timestamp of when the post was created
        type:
          type: string
          enum:
            - "question"
            - "reply"
            - "sticky"
          description: Can be one of `question`, `reply`, `sticky`
        name:
          type: string
        title:
          type: string
        body:
          type: string
          description: Can contain GitHub-flavored Markdown and mentions like `@<user_id|John Doe>` also basic HTML tags if those are explicitly enabled.
        tags:
          type: array
          items:
            type: string
        creatorid:
          type: string
          description: The `id` of the author of this post (an existing user)
        parentid:
          type: string
          description: The `id` of the parent question when the post is an answer
        location:
          type: string
          description: The location name associated with this post
        latlng:
          type: string
          description: Coordinates of the location in the format `"43.26,25.36"`
        address:
          type: string
          description: The location address associated with this post
        lastactivity:
          type: integer
          format: int64
        lastedited:
          type: integer
          format: int64
        lasteditby:
          type: string
        answerid:
          type: string
        revisionid:
          type: string
        closerid:
          type: string
        wiki:
          type: boolean
        space:
          type: string
          description: Selects a space or returns questions in the default space
        comments:
          $ref: '#/components/schemas/Comments'
        children:
          $ref: '#/components/schemas/Posts'
        similar:
          $ref: '#/components/schemas/Posts'
        author:
          $ref: '#/components/schemas/Profile'
    Posts:
      type: array
      items:
        $ref: '#/components/schemas/Post'
    Profile:
      type: object
      properties:
        id:
          type: string
        creatorid:
          type: string
        name:
          type: string
        picture:
          type: string
        timestamp:
          type: integer
          format: int64
        bannedUntil:
          type: integer
          format: int64
        spaces:
          type: array
          items:
            type: string
        badges:
          type: string
        website:
          type: string
        slackUserId:
          type: string
        mattermostUserId:
          type: string
        microsoftUserId:
          type: string
        location:
          type: string
        latlng:
          type: string
        aboutme:
          type: string
        user:
          $ref: '#/components/schemas/User'
    Profiles:
      type: array
      items:
        $ref: '#/components/schemas/Profile'
    User:
      type: object
      properties:
        id:
          type: string
        identifier:
          description: Can be in the format - `user@domain.com`, `fb:123456` (Facebook), `gp:google_id` (Google), `ldap:ldap_id` (LDAP), `oa2:oauth_id` (OAuth2), etc. Check the [Para docs]() for more details.
          type: string
        name:
          type: string
        picture:
          type: string
        groups:
          type: string
        email:
          type: string
        active:
          type: boolean
        password:
          type: string
    Revision:
      type: object
      properties:
        id:
          type: string
        body:
          type: string
        description:
          type: string
        title:
          type: string
        original:
          type: string
        author:
          $ref: '#/components/schemas/Profile'
    Revisions:
      type: array
      items:
        $ref: '#/components/schemas/Revision'
    Tag:
      type: object
      properties:
        tag:
          type: string
        count:
          type: integer
    Tags:
      type: array
      items:
        $ref: '#/components/schemas/Tag'
    Comment:
      type: object
      properties:
        id:
          type: string
        creatorid:
          type: string
        parentid:
          type: string
        timestamp:
          type: integer
          format: int64
        comment:
          type: string
        hidden:
          type: boolean
        authorName:
          type: string
    Comments:
      type: array
      items:
        $ref: '#/components/schemas/Comment'
    Report:
      type: object
      properties:
        id:
          type: string
        creatorid:
          type: string
        subType:
          type: string
          enum:
            - SPAM
            - OFFENSIVE
            - DUPLICATE
            - INCORRECT
            - OTHER;
        timestamp:
          type: integer
          format: int64
        solution:
          type: string
        link:
          type: string
        closed:
          type: boolean
        authorName:
          type: string
    Reports:
      type: array
      items:
        $ref: '#/components/schemas/Report'
    Space:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        type:
          type: string
    Spaces:
      type: array
      items:
        $ref: '#/components/schemas/Space'
    Webhook:
      type: object
      properties:
        targetUrl:
          type: string
        secret:
          type: string
        typeFilter:
          type: string
        urlEncoded:
          type: boolean
        active:
          type: boolean
        tooManyFailures:
          type: boolean
        create:
          type: boolean
        update:
          type: boolean
        delete:
          type: boolean
        createAll:
          type: boolean
        updateAll:
          type: boolean
        deleteAll:
          type: boolean
        customEvents:
          type: array
          items:
            type: string
        triggeredEvent:
          type: string
          description: Passed in the body of a trigger `POST` request. Only used to trigger a custom event.
        customPayload:
          type: object
          description: Passed in the body of a trigger `POST` request. Only used to trigger a custom event with a custom payload.
    Webhooks:
      type: array
      items:
        $ref: '#/components/schemas/Webhook'
    Health:
      type: object
      properties:
        healthy:
          type: boolean
        message:
          type: string
        pro:
          type: boolean
    Error:
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
  parameters:
    limit:
      name: limit
      in: query
      description: How many items to return at one time (default 30)
      required: false
      schema:
        type: integer
        format: int32
        default: 30
    page:
      name: page
      in: query
      description: Page number (paginate through results)
      required: false
      schema:
        type: integer
        format: int32
        default: 1
    sortby:
      name: sortby
      in: query
      description: Field name on which results will be sorted
      required: false
      schema:
        type: string
        default: "timestamp"
    desc:
      name: desc
      in: query
      description: Descending (true) or ascending (false) sort order
      required: false
      schema:
        type: boolean
        default: true

  securitySchemes:
    scoold_auth:
      description: Don't have an API key? Generate one on the [Administration page](/admin).
      type: http
      scheme: bearer
      bearerFormat: JWT