{"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":"https://demo.scoold.com"}],"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`, `location` and `wiki` 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/users/{id}/subscriptions":{"get":{"summary":"Returns a user's notification subscriptions","description":"Returns the notification channels a user is subscribed to and their followed posts. Only accessible by administrators.","tags":["users"],"security":[{"scoold_auth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The id of the user (can be the user id or profile id)","schema":{"type":"string"}},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/sortby"},{"$ref":"#/components/parameters/desc"}],"responses":{"200":{"description":"A map of subscription channels and followed posts"},"403":{"description":"Forbidden - only administrators can access this endpoint"}}},"delete":{"summary":"Unsubscribe a user from all notifications","description":"Removes the user from all notification channels and disables all email notification preferences. Only accessible by administrators.","tags":["users"],"security":[{"scoold_auth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The id of the user to unsubscribe","schema":{"type":"string"}}],"responses":{"200":{"description":"User was unsubscribed from all notifications"},"403":{"description":"Forbidden - only administrators can access this endpoint"}}}},"/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/files":{"post":{"summary":"Upload a file","description":"Uploads a single file to Scoold. The request must contain the file as a multipart body.","tags":["files"],"security":[{"scoold_auth":[]}],"requestBody":{"description":"File is uploaded","required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}}}}}},"responses":{"200":{"description":"File is uploaded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/File"}}}},"403":{"description":"Forbidden - file uploads are disabled or invalid request."}}}},"/api/files/{filename}":{"get":{"summary":"Download a file","description":"Downloads a single file.","tags":["files"],"security":[{"scoold_auth":[]}],"parameters":[{"name":"filename","in":"path","required":true,"description":"The file name to download","schema":{"type":"string"}}],"responses":{"200":{"description":"Returns the binary file stream with the header `Content-Disposition: attachment`."}}}},"/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"}}},"File":{"type":"object","properties":{"data":{"type":"object","properties":{"isImage":{"type":"boolean"},"isVideo":{"type":"boolean"},"isAudio":{"type":"boolean"},"link":{"type":"string"},"id":{"type":"string"}}}}},"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"}}}}