{ "openapi": "3.1.2", "info": { "title": "XenForo API", "description": "Community platform by XenForo\u00ae", "version": "1" }, "servers": [ { "url": "https://example.com/api" } ], "paths": { "/alerts/": { "get": { "tags": [ "Alerts" ], "summary": "Get a list of user alerts", "description": "Get a list of user alerts.", "operationId": "getAlerts", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "cutoff", "in": "query", "description": "Unix timestamp of oldest alert to include. Note that unread or unviewed alerts are always included.", "schema": { "type": "integer" } }, { "name": "unviewed", "in": "query", "description": "If true, gets only unviewed alerts. Unviewed alerts have not been seen (in the standard UI).", "schema": { "type": "boolean" } }, { "name": "unread", "in": "query", "description": "If true, gets only unread alerts. Unread alerts may have been seen but the content they relate to has not been viewed.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "alerts": { "type": "array", "items": { "$ref": "#/components/schemas/UserAlert" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "alert:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ], "post": { "tags": [ "Alerts" ], "summary": "Send an alert to the specified user", "description": "Send an alert to the specified user. Only available to super user keys.", "operationId": "postAlerts", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "to_user_id", "alert" ], "properties": { "to_user_id": { "type": "integer", "description": "ID of the user to receive the alert" }, "alert": { "type": "string", "description": "Text of the alert. May use the placeholder \"{link}\" to have the link automatically inserted." }, "from_user_id": { "type": "integer", "description": "If provided, the user to send the alert from. Otherwise, uses the current API user. May be 0 for an anonymous alert." }, "link_url": { "type": "string", "description": "URL user will be taken to when the alert is clicked." }, "link_title": { "type": "string", "description": "Text of the link URL that will be displayed. If no placeholder is present in the alert, will be automatically appended." } } } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "alert:write" ] }, { "XF-Api-Key": [] } ] } }, "/alerts/mark-all": { "post": { "tags": [ "Alerts" ], "summary": "Mark all alerts as read or viewed", "description": "Mark all alerts as read or viewed. Must specify \"read\" or \"viewed\" parameters.", "operationId": "postAlertsMarkAll", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "read": { "type": "boolean", "description": "If specified, marks all alerts as read." }, "viewed": { "type": "boolean", "description": "If specified, marks all alerts as viewed. This will remove the alert counter but keep unactioned alerts highlighted." } } } } } }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "alert:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/alerts/{id}/": { "get": { "tags": [ "Alerts" ], "summary": "Get information about the specified alert", "description": "Get information about the specified alert.", "operationId": "getAlertsId", "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "alert": { "$ref": "#/components/schemas/UserAlert" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "alert:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/alerts/{id}/mark": { "post": { "tags": [ "Alerts" ], "summary": "Mark the alert as viewed, read, or unread", "description": "Mark the alert as viewed, read, or unread. Marking as unviewed is not supported.", "operationId": "postAlertsIdMark", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "read": { "type": "boolean", "description": "If specified, marks the alert as read." }, "unread": { "type": "boolean", "description": "If specified, marks the alert as unread." }, "viewed": { "type": "boolean", "description": "If specified, marks all alerts as viewed." } } } } } }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "alert:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/attachments/": { "get": { "tags": [ "Attachments" ], "summary": "Get attachments by API attachment key", "description": "Get attachments by API attachment key. Only returns attachments that have not been associated with content.", "operationId": "getAttachments", "parameters": [ { "name": "key", "in": "query", "description": "The API attachment key", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/Attachment" }, "description": "List of matching attachments." } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "attachment:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ], "post": { "tags": [ "Attachments" ], "summary": "Upload an attachment", "description": "Upload an attachment. An API attachment key must be created first. Must be submitted using multipart/form-data encoding.", "operationId": "postAttachments", "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "key", "attachment" ], "properties": { "key": { "type": "string", "description": "The API attachment key to associated with" }, "attachment": { "type": "string", "contentMediaType": "application/octet-stream", "description": "The attachment file" } } } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "attachment": { "$ref": "#/components/schemas/Attachment", "description": "The attachment record of the successful upload" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Triggered if the user making the request does not match the user that created the attachment key.\n\n**Possible errors**\n- `attachment_key_user_wrong`: Triggered if the user making the request does not match the user that created the attachment key." } }, "security": [ { "XF-OAuth2": [ "attachment:write" ] }, { "XF-Api-Key": [] } ] } }, "/attachments/new-key": { "post": { "tags": [ "Attachments" ], "summary": "Create an attachment key", "description": "Create an attachment key. Allows attachments to be uploaded separately from the related content.", "operationId": "postAttachmentsNewKey", "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The content type of the attachment. Default types include post, conversation_message. Add-ons may add more." }, "context": { "type": "array", "items": { "type": "string" }, "description": "Key-value pairs representing the context of the attachment. This will vary depending on content type and the action being taken. See relevant actions for further details." }, "attachment": { "type": "string", "contentMediaType": "application/octet-stream", "description": "The first attachment to be associated with the new key." } } } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "description": "The attachment key created. This should be used to upload additional files or to associate uploaded attachments with other content." }, "attachment": { "$ref": "#/components/schemas/Attachment", "description": "If a file was provided and the upload was successful, this will describe the new attachment." } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "attachment:write" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/attachments/{id}/": { "get": { "tags": [ "Attachments" ], "summary": "Get information about the specified attachment", "description": "Get information about the specified attachment.", "operationId": "getAttachmentsId", "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "attachment": { "$ref": "#/components/schemas/Attachment" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "attachment:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ], "delete": { "tags": [ "Attachments" ], "summary": "Delete the specified attachment", "description": "Delete the specified attachment.", "operationId": "deleteAttachmentsId", "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "attachment:delete" ] }, { "XF-Api-Key": [] } ] } }, "/attachments/{id}/data": { "get": { "tags": [ "Attachments" ], "summary": "Get the data that makes up the specified attachment", "description": "Get the data that makes up the specified attachment. The output is the raw binary data.", "operationId": "getAttachmentsIdData", "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "*/*": { "schema": { "description": "The binary data is output directly, not JSON." } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "attachment:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/attachments/{id}/retina-thumbnail": { "get": { "tags": [ "Attachments" ], "summary": "Get an attachment thumbnail URL", "description": "Get an attachment thumbnail URL. URL returned via a 301 redirect.", "operationId": "getAttachmentsIdRetinaThumbnail", "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "The URL to the thumbnail is returned via a 301 redirect's Location header." } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Not found if the attachment does not have a thumbnail\n\n**Possible errors**\n- `not_found`: Not found if the attachment does not have a thumbnail" } }, "security": [ { "XF-OAuth2": [ "attachment:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/attachments/{id}/thumbnail": { "get": { "tags": [ "Attachments" ], "summary": "Get an attachment thumbnail URL", "description": "Get an attachment thumbnail URL. URL returned via a 301 redirect.", "operationId": "getAttachmentsIdThumbnail", "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "The URL to the thumbnail is returned via a 301 redirect's Location header." } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Not found if the attachment does not have a thumbnail\n\n**Possible errors**\n- `not_found`: Not found if the attachment does not have a thumbnail" } }, "security": [ { "XF-OAuth2": [ "attachment:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/auth/": { "post": { "tags": [ "Auth" ], "summary": "Test a login and password for validity", "description": "Test a login and password for validity. Only available to super user keys. We strongly recommend the login and password parameters are passed into the request body rather than the query string.", "operationId": "postAuth", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "login", "password" ], "properties": { "login": { "type": "string", "description": "The username or email address of the user to test" }, "password": { "type": "string", "description": "The password of the user" }, "limit_ip": { "type": "string", "description": "The IP that should be considered to be making the request. If provided, this will be used to prevent brute force attempts." } } } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User", "description": "If successful, the user record of the matching user" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "auth:write" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/auth/from-session": { "post": { "tags": [ "Auth" ], "summary": "Look up an active user from session data", "description": "Look up an active user from session data. This can be used to help with seamless SSO with XF, assuming the session or remember cookies are available to your page. At least one of session_id and remember_cookie must be provided. Only available to super user keys.", "operationId": "postAuthFromSession", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "session_id": { "type": "string", "description": "If provided, checks for an active session with that ID." }, "remember_cookie": { "type": "string", "description": "If provided, checks to see if this is an active \"remember me\" cookie value." } } } } } }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "If false, no session or remember cookie could be found" }, "user": { "$ref": "#/components/schemas/User", "description": "If successful, the user record of the matching user. May be a guest." } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "auth:write" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/auth/login-token": { "post": { "tags": [ "Auth" ], "summary": "Generate a login token", "description": "Generate a login token. If the visitor is already logged into a XenForo account, they will not be logged into the specified account. Only available to super user keys.", "operationId": "postAuthLoginToken", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "user_id" ], "properties": { "user_id": { "type": "integer" }, "limit_ip": { "type": "string", "description": "If provided, locks the token to the specified IP for additional security" }, "return_url": { "type": "string", "description": "If provided, after logging the user will be returned to this URL. Otherwise they'll go to the XenForo index." }, "force": { "type": "boolean", "description": "If provided, the login URL will forcibly replace the currently logged in user if a user is already logged in and different to the currently logged in user. Defaults to false." }, "remember": { "type": "boolean", "description": "Controls whether the a \"remember me\" cookie will be set when the user logs in. Defaults to true." } } } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "login_token": { "type": "string" }, "login_url": { "type": "string", "description": "Direct user to this URL to trigger a login" }, "expiry_date": { "type": "integer", "description": "Unix timestamp of when the token expires. An error will be displayed if the token is expired or invalid" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "auth:write", "auth:login_token" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/conversation-messages/": { "post": { "tags": [ "Conversations" ], "summary": "Reply to a conversation", "description": "Reply to a conversation.", "operationId": "postConversationMessages", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "conversation_id", "message" ], "properties": { "conversation_id": { "type": "integer" }, "message": { "type": "string" }, "attachment_key": { "type": "string", "description": "API attachment key to upload files. Attachment key content type must be conversation_message with context[conversation_id] set to this conversation ID." } } } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "$ref": "#/components/schemas/ConversationMessage", "description": "The newly inserted message" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "conversation:write" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/conversation-messages/{id}/": { "get": { "tags": [ "Conversations" ], "summary": "Get the specified conversation message", "description": "Get the specified conversation message.", "operationId": "getConversationMessagesId", "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "$ref": "#/components/schemas/ConversationMessage" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "conversation:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ], "post": { "tags": [ "Conversations" ], "summary": "Update the specified conversation message", "description": "Update the specified conversation message.", "operationId": "postConversationMessagesId", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The new message content" }, "attachment_key": { "type": "string", "description": "API attachment key to upload files. Attachment key content type must be conversation_message with context[message_id] set to this message ID." } } } } } }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "$ref": "#/components/schemas/ConversationMessage" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "conversation:write" ] }, { "XF-Api-Key": [] } ] } }, "/conversation-messages/{id}/react": { "post": { "tags": [ "Conversations" ], "summary": "React to the specified conversation message", "description": "React to the specified conversation message.", "operationId": "postConversationMessagesIdReact", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "reaction_id" ], "properties": { "reaction_id": { "type": "integer", "description": "ID of the reaction to use. Use the current reaction ID to undo." } } } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "action": { "type": "string", "description": "\"insert\" or \"delete\" based on whether the reaction was added or removed." } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "conversation:write" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/conversations/": { "get": { "tags": [ "Conversations" ], "summary": "Get a list of user conversations", "description": "Get a list of user conversations.", "operationId": "getConversations", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "starter_id", "in": "query", "schema": { "type": "integer" } }, { "name": "receiver_id", "in": "query", "schema": { "type": "integer" } }, { "name": "starred", "in": "query", "description": "Only gets starred conversations if specified", "schema": { "type": "boolean" } }, { "name": "unread", "in": "query", "description": "Only gets unread conversations if specified", "schema": { "type": "boolean" } }, { "name": "label_id", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "conversations": { "type": "array", "items": { "$ref": "#/components/schemas/Conversation" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "conversation:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ], "post": { "tags": [ "Conversations" ], "summary": "Create a conversation", "description": "Create a conversation.", "operationId": "postConversations", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "recipient_ids", "title", "message" ], "properties": { "recipient_ids": { "type": "array", "items": { "type": "integer" }, "description": "List of user IDs to send the conversation to" }, "title": { "type": "string", "description": "Conversation title" }, "message": { "type": "string", "description": "Conversation message body" }, "attachment_key": { "type": "string", "description": "API attachment key to upload files. Attachment key content type must be conversation_message with no context." }, "conversation_open": { "type": "boolean", "description": "If false, no replies may be made to this conversation." }, "open_invite": { "type": "boolean", "description": "If true, any member of the conversation may add others" } } } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "conversation": { "$ref": "#/components/schemas/Conversation" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "conversation:write" ] }, { "XF-Api-Key": [] } ] } }, "/conversations/{id}/": { "get": { "tags": [ "Conversations" ], "summary": "Get information about the specified conversation", "description": "Get information about the specified conversation.", "operationId": "getConversationsId", "parameters": [ { "name": "with_messages", "in": "query", "description": "If specified, the response will include a page of messages.", "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "description": "The page of messages to include", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "conversation": { "$ref": "#/components/schemas/Conversation" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationMessage" }, "description": "List of messages on the requested page" }, "pagination": { "$ref": "#/components/schemas/Pagination", "description": "Pagination details" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "conversation:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ], "post": { "tags": [ "Conversations" ], "summary": "Update the specified conversation", "description": "Update the specified conversation.", "operationId": "postConversationsId", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Conversation title" }, "open_invite": { "type": "boolean", "description": "If true, any member of the conversation can add others" }, "conversation_open": { "type": "boolean", "description": "If false, no further replies are allowed." } } } } } }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "conversation": { "$ref": "#/components/schemas/Conversation" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "conversation:write" ] }, { "XF-Api-Key": [] } ] }, "delete": { "tags": [ "Conversations" ], "summary": "Delete a conversation from the user list", "description": "Delete a conversation from the user list. Does not delete the conversation for other receivers.", "operationId": "deleteConversationsId", "parameters": [ { "name": "ignore", "in": "query", "description": "If true, further replies to this conversation will be ignored. (Otherwise, replies will restore this conversation to the list.)", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "conversation:write" ] }, { "XF-Api-Key": [] } ] } }, "/conversations/{id}/invite": { "post": { "tags": [ "Conversations" ], "summary": "Invite the specified users to this conversation", "description": "Invite the specified users to this conversation.", "operationId": "postConversationsIdInvite", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "recipient_ids" ], "properties": { "recipient_ids": { "type": "array", "items": { "type": "integer" }, "description": "List of user IDs to invite" } } } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "conversation:write" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/conversations/{id}/labels": { "post": { "tags": [ "Conversations" ], "summary": "Set labels on the specified conversation", "description": "Set labels on the specified conversation.", "operationId": "postConversationsIdLabels", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "labels": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "conversation:write" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/conversations/{id}/mark-read": { "post": { "tags": [ "Conversations" ], "summary": "Mark a conversation as read", "description": "Mark a conversation as read. This cannot move the", "operationId": "postConversationsIdMarkRead", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "date": { "type": "integer", "description": "Unix timestamp to mark the conversation read to. If not specified, defaults to the current time." } } } } } }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "conversation:write" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/conversations/{id}/mark-unread": { "post": { "tags": [ "Conversations" ], "summary": "Mark the conversation as unread", "description": "Mark the conversation as unread. This marks all messages in the conversation as unread.", "operationId": "postConversationsIdMarkUnread", "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "conversation:write" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/conversations/{id}/messages": { "get": { "tags": [ "Conversations" ], "summary": "Get a page of messages in the specified conversation", "description": "Get a page of messages in the specified conversation.", "operationId": "getConversationsIdMessages", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationMessage" }, "description": "List of messages on the requested page" }, "pagination": { "$ref": "#/components/schemas/Pagination", "description": "Pagination details" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "conversation:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/conversations/{id}/star": { "post": { "tags": [ "Conversations" ], "summary": "Set the star status of the specified conversation", "description": "Set the star status of the specified conversation.", "operationId": "postConversationsIdStar", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "star": { "type": "boolean", "description": "If provided, sets the star status as specified. If not provided, toggles the status." } } } } } }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "conversation:write" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/featured/": { "get": { "tags": [ "Featured content" ], "summary": "Get a list of featured content", "description": "Get a list of featured content.", "operationId": "getFeatured", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "content_type", "in": "query", "description": "A content type to restrict results to", "schema": { "type": "string" } }, { "name": "user_id", "in": "query", "description": "A user ID to restrict results to", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "features": { "type": "array", "items": { "$ref": "#/components/schemas/FeaturedContent" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "feature:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/forums/{id}/": { "get": { "tags": [ "Forums" ], "summary": "Get information about the specified forum", "description": "Get information about the specified forum.", "operationId": "getForumsId", "parameters": [ { "name": "with_threads", "in": "query", "description": "If true, gets a page of threads in this forum", "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "prefix_id", "in": "query", "description": "Filters to only threads with the specified prefix.", "schema": { "type": "integer" } }, { "name": "starter_id", "in": "query", "description": "Filters to only threads started by the specified user ID.", "schema": { "type": "integer" } }, { "name": "last_days", "in": "query", "description": "Filters to threads that have had a reply in the last X days.", "schema": { "type": "integer" } }, { "name": "unread", "in": "query", "description": "Filters to unread threads only. Ignored for guests.", "schema": { "type": "boolean" } }, { "name": "thread_type", "in": "query", "description": "Filters to threads of the specified thread type.", "schema": { "type": "string" } }, { "name": "order", "in": "query", "description": "Method of ordering: last_post_date, post_date. When in a specific forum context: title, reply_count, view_count, vote_score, first_post_reaction_score.", "schema": { "type": "string" } }, { "name": "direction", "in": "query", "description": "Either \"asc\" or \"desc\" for ascending or descending. Applies only if an order is provided.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "forum": { "$ref": "#/components/schemas/Forum" }, "threads": { "type": "array", "items": { "$ref": "#/components/schemas/Thread" }, "description": "Threads on this page" }, "pagination": { "$ref": "#/components/schemas/Pagination", "description": "Pagination information" }, "sticky": { "type": "array", "items": { "$ref": "#/components/schemas/Thread" }, "description": "If on page 1, a list of sticky threads in this forum. Does not count towards the per page limit." } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "node:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/forums/{id}/mark-read": { "post": { "tags": [ "Forums" ], "summary": "Mark a forum as read", "description": "Mark a forum as read. This cannot mark a forum as unread or", "operationId": "postForumsIdMarkRead", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "date": { "type": "integer", "description": "Unix timestamp to mark the forum read to. If not specified, defaults to the current time." } } } } } }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "thread:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/forums/{id}/threads": { "get": { "tags": [ "Forums" ], "summary": "Get a page of threads from the specified forum", "description": "Get a page of threads from the specified forum.", "operationId": "getForumsIdThreads", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "prefix_id", "in": "query", "description": "Filters to only threads with the specified prefix.", "schema": { "type": "integer" } }, { "name": "starter_id", "in": "query", "description": "Filters to only threads started by the specified user ID.", "schema": { "type": "integer" } }, { "name": "last_days", "in": "query", "description": "Filters to threads that have had a reply in the last X days.", "schema": { "type": "integer" } }, { "name": "unread", "in": "query", "description": "Filters to unread threads only. Ignored for guests.", "schema": { "type": "boolean" } }, { "name": "thread_type", "in": "query", "description": "Filters to threads of the specified thread type.", "schema": { "type": "string" } }, { "name": "order", "in": "query", "description": "Method of ordering: last_post_date, post_date. When in a specific forum context: title, reply_count, view_count, vote_score, first_post_reaction_score.", "schema": { "type": "string" } }, { "name": "direction", "in": "query", "description": "Either \"asc\" or \"desc\" for ascending or descending. Applies only if an order is provided.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "threads": { "type": "array", "items": { "$ref": "#/components/schemas/Thread" }, "description": "Threads on this page" }, "pagination": { "$ref": "#/components/schemas/Pagination", "description": "Pagination information" }, "sticky": { "type": "array", "items": { "$ref": "#/components/schemas/Thread" }, "description": "If on page 1, a list of sticky threads in this forum. Does not count towards the per page limit." } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "node:read", "thread:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/index/": { "get": { "tags": [ "Index" ], "summary": "Get site and API information", "description": "Get site and API information.", "operationId": "getIndex", "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "version_id": { "type": "integer", "description": "XenForo version ID" }, "site_title": { "type": "string", "description": "Title of the site this API relates to" }, "base_url": { "type": "string", "description": "The base URL of the XenForo install this API relates to" }, "api_url": { "type": "string", "description": "The base API URL" }, "key[type]": { "type": "string", "description": "Type of the API key accessing the API (guest, user or super)" }, "key[user_id]": { "oneOf": [ { "type": "integer" }, { "type": "null" } ], "description": "If a user key, the ID of the user the key is for; null otherwise" }, "key[allow_all_scopes]": { "type": "boolean", "description": "If true, all scopes can be accessed" }, "key[scopes]": { "type": "array", "items": { "type": "string" }, "description": "A list of scopes this key can access (if not allowed to access all scopes)" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/me/": { "get": { "tags": [ "Me" ], "summary": "Get information about the current user", "description": "Get information about the current user.", "operationId": "getMe", "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "me": { "$ref": "#/components/schemas/User" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ], "post": { "tags": [ "Me" ], "summary": "Update information about the current user", "description": "Update information about the current user.", "operationId": "postMe", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "option[creation_watch_state]": { "type": "string" }, "option[interaction_watch_state]": { "type": "string" }, "option[content_show_signature]": { "type": "boolean" }, "option[email_on_conversation]": { "type": "boolean" }, "option[push_on_conversation]": { "type": "boolean" }, "option[receive_admin_email]": { "type": "boolean" }, "option[show_dob_year]": { "type": "boolean" }, "option[show_dob_date]": { "type": "boolean" }, "profile[location]": { "type": "string" }, "profile[website]": { "type": "string" }, "profile[about]": { "type": "string" }, "profile[signature]": { "type": "string" }, "privacy[allow_view_profile]": { "type": "string" }, "privacy[allow_post_profile]": { "type": "string" }, "privacy[allow_receive_news_feed]": { "type": "string" }, "privacy[allow_send_personal_conversation]": { "type": "string" }, "privacy[allow_view_identities]": { "type": "string" }, "visible": { "type": "boolean" }, "activity_visible": { "type": "boolean" }, "timezone": { "type": "string" }, "custom_title": { "type": "string" }, "custom_fields[]": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "user:write" ] }, { "XF-Api-Key": [] } ] } }, "/me/avatar": { "post": { "tags": [ "Me" ], "summary": "Update the current user avatar", "description": "Update the current user avatar.", "operationId": "postMeAvatar", "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "avatar" ], "properties": { "avatar": { "type": "string", "contentMediaType": "application/octet-stream", "description": "The uploaded new avatar" } } } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "user:write" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ], "delete": { "tags": [ "Me" ], "summary": "Delete the current user avatar", "description": "Delete the current user avatar.", "operationId": "deleteMeAvatar", "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "user:write" ] }, { "XF-Api-Key": [] } ] } }, "/me/email": { "post": { "tags": [ "Me" ], "summary": "Update the current user email address", "description": "Update the current user email address.", "operationId": "postMeEmail", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "current_password", "email" ], "properties": { "current_password": { "type": "string" }, "email": { "type": "string" } } } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "confirmation_required": { "type": "boolean", "description": "True if email confirmation is required for this change" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "user:write" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/me/password": { "post": { "tags": [ "Me" ], "summary": "Update the current user password", "description": "Update the current user password.", "operationId": "postMePassword", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "current_password", "new_password" ], "properties": { "current_password": { "type": "string" }, "new_password": { "type": "string" } } } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "user:write" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/media/": { "get": { "tags": [ "Media" ], "summary": "Get a list of media items", "description": "Get a list of media items.", "operationId": "getMedia", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "media_type", "in": "query", "description": "Filters to only media of the specified type. Valid types: image, audio, video, embed.", "schema": { "type": "string" } }, { "name": "user_id", "in": "query", "description": "Filters to only media created by the specified user ID.", "schema": { "type": "integer" } }, { "name": "order", "in": "query", "description": "Method of ordering: media_date, comment_count, rating_weighted, reaction_score, view_count", "schema": { "type": "string" } }, { "name": "direction", "in": "query", "description": "Either \"asc\" or \"desc\" for ascending or descending. Applies only if an order is provided.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "media": { "type": "array", "items": { "$ref": "#/components/schemas/XFMG_MediaItem" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "media:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ], "post": { "tags": [ "Media" ], "summary": "Create a media item", "description": "Create a media item. Provide either album_id or category_id, and either embed_url or file.", "operationId": "postMedia", "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "album_id": { "type": "integer", "description": "ID of the album to add media to. Required if category_id is not provided." }, "category_id": { "type": "integer", "description": "ID of the category to add media to. Required if album_id is not provided." }, "embed_url": { "type": "string", "description": "URL to embed. Required if file is not uploaded." }, "file": { "type": "string", "contentMediaType": "application/octet-stream", "description": "Media file to upload. Required if embed_url is not provided." }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "custom_fields[]": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "media": { "$ref": "#/components/schemas/XFMG_MediaItem", "description": "If the media item was created immediately.\n\n**Note** Conditionally returned" }, "transcoding": { "type": "boolean", "description": "If true, the media requires transcoding and will be available later.\n\n**Note** Conditionally returned" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "media:write" ] }, { "XF-Api-Key": [] } ] } }, "/media/{id}/": { "get": { "tags": [ "Media" ], "summary": "Get information about the specified media item", "description": "Get information about the specified media item.", "operationId": "getMediaId", "parameters": [ { "name": "with_comments", "in": "query", "description": "If specified, the response will include a page of comments.", "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "media": { "$ref": "#/components/schemas/XFMG_MediaItem" }, "comments": { "type": "array", "items": { "$ref": "#/components/schemas/XFMG_Comment" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "media:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ], "post": { "tags": [ "Media" ], "summary": "Update the specified media item", "description": "Update the specified media item.", "operationId": "postMediaId", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "custom_fields[]": { "type": "string" }, "author_alert": { "type": "boolean" }, "author_alert_reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "media": { "$ref": "#/components/schemas/XFMG_MediaItem" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "media:write" ] }, { "XF-Api-Key": [] } ] }, "delete": { "tags": [ "Media" ], "summary": "Delete the specified media item", "description": "Delete the specified media item. Defaults to soft deletion.", "operationId": "deleteMediaId", "parameters": [ { "name": "hard_delete", "in": "query", "schema": { "type": "boolean" } }, { "name": "reason", "in": "query", "schema": { "type": "string" } }, { "name": "author_alert", "in": "query", "schema": { "type": "boolean" } }, { "name": "author_alert_reason", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "media:write" ] }, { "XF-Api-Key": [] } ] } }, "/media/{id}/comments": { "get": { "tags": [ "Media" ], "summary": "Get a page of comments on the specified media item", "description": "Get a page of comments on the specified media item.", "operationId": "getMediaIdComments", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "comments": { "type": "array", "items": { "$ref": "#/components/schemas/XFMG_Comment" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "media:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/media/{id}/data": { "get": { "tags": [ "Media" ], "summary": "Get a media item file", "description": "Get a media item file.", "operationId": "getMediaIdData", "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "media:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/media/{id}/feature": { "post": { "tags": [ "Media" ], "summary": "Set feature state for the specified media", "description": "Set feature state for the specified media.", "operationId": "postMediaIdFeature", "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "A custom title, if desired.\n\n**Note** Conditionally returned" }, "snippet": { "type": "string", "description": "A custom snippet, if desired.\n\n**Note** Conditionally returned" }, "image": { "type": "string", "contentMediaType": "application/octet-stream", "description": "A custom image, if desired.\n\n**Note** Conditionally returned" }, "date": { "type": "string", "description": "A custom feature date, if desired.\n\n**Note** Conditionally returned" }, "unfeature_days": { "type": "integer", "description": "A custom number of days after which to unfeature the content, if desired.\n\n**Note** Conditionally returned" }, "always_visible": { "type": "boolean", "description": "Whether or not the feature should be visible even when the visitor may not view the content.\n\n**Note** Conditionally returned" } } } } } }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "feature": { "$ref": "#/components/schemas/FeaturedContent" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "media:write" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/media/{id}/react": { "post": { "tags": [ "Media" ], "summary": "React to the specified media item", "description": "React to the specified media item.", "operationId": "postMediaIdReact", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "reaction_id" ], "properties": { "reaction_id": { "type": "integer", "description": "ID of the reaction to use. Use the current reaction ID to undo." } } } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "action": { "type": "string", "description": "\"insert\" or \"delete\" based on whether the reaction was added or removed." } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "media:write" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/media/{id}/unfeature": { "post": { "tags": [ "Media" ], "summary": "Delete the feature for the specified media", "description": "Delete the feature for the specified media.", "operationId": "postMediaIdUnfeature", "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "media:write" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/media-albums/": { "get": { "tags": [ "Media albums" ], "summary": "Get a list of albums", "description": "Get a list of albums.", "operationId": "getMediaAlbums", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "user_id", "in": "query", "description": "Filters to only albums created by the specified user ID.", "schema": { "type": "integer" } }, { "name": "order", "in": "query", "description": "Method of ordering: create_date, media_count, comment_count, rating_weighted, reaction_score, view_count", "schema": { "type": "string" } }, { "name": "direction", "in": "query", "description": "Either \"asc\" or \"desc\" for ascending or descending. Applies only if an order is provided.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "albums": { "type": "array", "items": { "$ref": "#/components/schemas/XFMG_Album" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "media:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ], "post": { "tags": [ "Media albums" ], "summary": "Create an album", "description": "Create an album.", "operationId": "postMediaAlbums", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "category_id": { "type": "integer" }, "view_privacy": { "type": "string", "description": "Privacy level for viewing: public, members, shared, private" }, "view_user_ids": { "type": "array", "items": { "type": "integer" }, "description": "User IDs who can view when view_privacy is \"shared\"" }, "add_privacy": { "type": "string", "description": "Privacy level for adding media: public, members, shared, private" }, "add_user_ids": { "type": "array", "items": { "type": "integer" }, "description": "User IDs who can add when add_privacy is \"shared\"" } } } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "album": { "$ref": "#/components/schemas/XFMG_Album" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "media:write" ] }, { "XF-Api-Key": [] } ] } }, "/media-albums/{id}/": { "get": { "tags": [ "Media albums" ], "summary": "Get information about the specified album", "description": "Get information about the specified album.", "operationId": "getMediaAlbumsId", "parameters": [ { "name": "with_media", "in": "query", "description": "If specified, the response will include a page of media.", "schema": { "type": "boolean" } }, { "name": "with_comments", "in": "query", "description": "If specified, the response will include a page of comments.", "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "comment_page", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "album": { "$ref": "#/components/schemas/XFMG_Album" }, "media": { "type": "array", "items": { "$ref": "#/components/schemas/XFMG_MediaItem" }, "description": "Included when with_media is specified\n\n**Note** Conditionally returned" }, "media_pagination": { "$ref": "#/components/schemas/Pagination", "description": "Included when with_media is specified\n\n**Note** Conditionally returned" }, "comments": { "type": "array", "items": { "$ref": "#/components/schemas/XFMG_Comment" }, "description": "Included when with_comments is specified\n\n**Note** Conditionally returned" }, "comment_pagination": { "$ref": "#/components/schemas/Pagination", "description": "Included when with_comments is specified\n\n**Note** Conditionally returned" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "media:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ], "post": { "tags": [ "Media albums" ], "summary": "Update the specified album", "description": "Update the specified album.", "operationId": "postMediaAlbumsId", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "author_alert": { "type": "boolean" }, "author_alert_reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "album": { "$ref": "#/components/schemas/XFMG_Album" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "media:write" ] }, { "XF-Api-Key": [] } ] }, "delete": { "tags": [ "Media albums" ], "summary": "Delete the specified album", "description": "Delete the specified album. Defaults to soft deletion.", "operationId": "deleteMediaAlbumsId", "parameters": [ { "name": "hard_delete", "in": "query", "schema": { "type": "boolean" } }, { "name": "reason", "in": "query", "schema": { "type": "string" } }, { "name": "author_alert", "in": "query", "schema": { "type": "boolean" } }, { "name": "author_alert_reason", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "media:write" ] }, { "XF-Api-Key": [] } ] } }, "/media-albums/{id}/comments": { "get": { "tags": [ "Media albums" ], "summary": "Get a page of comments on the specified album", "description": "Get a page of comments on the specified album.", "operationId": "getMediaAlbumsIdComments", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "comments": { "type": "array", "items": { "$ref": "#/components/schemas/XFMG_Comment" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "media:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/media-albums/{id}/media": { "get": { "tags": [ "Media albums" ], "summary": "Get a page of media from the specified album", "description": "Get a page of media from the specified album.", "operationId": "getMediaAlbumsIdMedia", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "media": { "type": "array", "items": { "$ref": "#/components/schemas/XFMG_MediaItem" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "media:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/media-albums/{id}/react": { "post": { "tags": [ "Media albums" ], "summary": "React to the specified album", "description": "React to the specified album.", "operationId": "postMediaAlbumsIdReact", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "reaction_id" ], "properties": { "reaction_id": { "type": "integer", "description": "ID of the reaction to use. Use the current reaction ID to undo." } } } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "action": { "type": "string", "description": "\"insert\" or \"delete\" based on whether the reaction was added or removed." } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "media:write" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/media-categories/": { "get": { "tags": [ "Media categories" ], "summary": "Get the media category tree", "description": "Get the media category tree.", "operationId": "getMediaCategories", "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "media_category:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ], "post": { "tags": [ "Media categories" ], "summary": "Create a media category", "description": "Create a media category.", "operationId": "postMediaCategories", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "parent_category_id": { "type": "integer" }, "description": { "type": "string" }, "display_order": { "type": "integer" }, "min_tags": { "type": "integer" }, "category_type": { "type": "string" }, "allowed_types": { "type": "array", "items": { "type": "string" } }, "auto_feature": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "category": { "$ref": "#/components/schemas/XFMG_Category" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "media_category:write" ] }, { "XF-Api-Key": [] } ] } }, "/media-categories/flattened": { "get": { "tags": [ "Media categories" ], "summary": "Get a flattened list of media categories", "description": "Get a flattened list of media categories.", "operationId": "getMediaCategoriesFlattened", "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "media_category:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/media-categories/{id}/": { "get": { "tags": [ "Media categories" ], "summary": "Get information about the specified media category", "description": "Get information about the specified media category.", "operationId": "getMediaCategoriesId", "parameters": [ { "name": "with_content", "in": "query", "description": "If specified, the response will include a page of content (albums or media).", "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "category": { "$ref": "#/components/schemas/XFMG_Category" }, "albums": { "type": "array", "items": { "$ref": "#/components/schemas/XFMG_Album" }, "description": "If an album category, albums on this page" }, "media": { "type": "array", "items": { "$ref": "#/components/schemas/XFMG_MediaItem" }, "description": "If a media category, media on this page" }, "pagination": { "$ref": "#/components/schemas/Pagination", "description": "Pagination information" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "media_category:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ], "post": { "tags": [ "Media categories" ], "summary": "Update the specified media category", "description": "Update the specified media category.", "operationId": "postMediaCategoriesId", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "parent_category_id": { "type": "integer" }, "display_order": { "type": "integer" }, "min_tags": { "type": "integer" }, "category_type": { "type": "string" }, "allowed_types": { "type": "array", "items": { "type": "string" } }, "auto_feature": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "category": { "$ref": "#/components/schemas/XFMG_Category" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "media_category:write" ] }, { "XF-Api-Key": [] } ] }, "delete": { "tags": [ "Media categories" ], "summary": "Delete the specified category", "description": "Delete the specified category.", "operationId": "deleteMediaCategoriesId", "parameters": [ { "name": "delete_children", "in": "query", "description": "If true, child nodes will be deleted. Otherwise, they will be connected to this node's parent.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "media_category:delete" ] }, { "XF-Api-Key": [] } ] } }, "/media-categories/{id}/content": { "get": { "tags": [ "Media categories" ], "summary": "Get a page of content from the specified category", "description": "Get a page of content from the specified category.", "operationId": "getMediaCategoriesIdContent", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "albums": { "type": "array", "items": { "$ref": "#/components/schemas/XFMG_Album" }, "description": "If an album category, albums on this page" }, "media": { "type": "array", "items": { "$ref": "#/components/schemas/XFMG_MediaItem" }, "description": "If a media category, media on this page" }, "pagination": { "$ref": "#/components/schemas/Pagination", "description": "Pagination information" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "media_category:read", "media:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/media-comments/": { "get": { "tags": [ "Media comments" ], "summary": "Get a list of latest comments", "description": "Get a list of latest comments.", "operationId": "getMediaComments", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "comments": { "type": "array", "items": { "$ref": "#/components/schemas/XFMG_Comment" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "media:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ], "post": { "tags": [ "Media comments" ], "summary": "Create a comment on an album or media item", "description": "Create a comment on an album or media item.", "operationId": "postMediaComments", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "message" ], "properties": { "album_id": { "type": "integer", "description": "ID of the album to comment on. Required if media_id is not provided." }, "media_id": { "type": "integer", "description": "ID of the media item to comment on. Required if album_id is not provided." }, "message": { "type": "string" } } } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "comment": { "$ref": "#/components/schemas/XFMG_Comment" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "media:write" ] }, { "XF-Api-Key": [] } ] } }, "/media-comments/{id}/": { "get": { "tags": [ "Media comments" ], "summary": "Get information about the specified comment", "description": "Get information about the specified comment.", "operationId": "getMediaCommentsId", "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "$ref": "#/components/schemas/XFMG_Comment" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "media:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ], "post": { "tags": [ "Media comments" ], "summary": "Update the specified comment", "description": "Update the specified comment.", "operationId": "postMediaCommentsId", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "silent": { "type": "boolean", "description": "If true and permissions allow, this edit will not be updated with a \"last edited\" indication" }, "clear_edit": { "type": "boolean", "description": "If true and permissions allow, any \"last edited\" indication will be removed. Requires \"silent\"." }, "author_alert": { "type": "boolean" }, "author_alert_reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "comment": { "$ref": "#/components/schemas/XFMG_Comment" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "media:write" ] }, { "XF-Api-Key": [] } ] }, "delete": { "tags": [ "Media comments" ], "summary": "Delete the specified comment", "description": "Delete the specified comment. Defaults to soft deletion.", "operationId": "deleteMediaCommentsId", "parameters": [ { "name": "hard_delete", "in": "query", "schema": { "type": "boolean" } }, { "name": "reason", "in": "query", "schema": { "type": "string" } }, { "name": "author_alert", "in": "query", "schema": { "type": "boolean" } }, { "name": "author_alert_reason", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "media:write" ] }, { "XF-Api-Key": [] } ] } }, "/media-comments/{id}/react": { "post": { "tags": [ "Media comments" ], "summary": "React to the specified comment", "description": "React to the specified comment.", "operationId": "postMediaCommentsIdReact", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "reaction_id" ], "properties": { "reaction_id": { "type": "integer", "description": "ID of the reaction to use. Use the current reaction ID to undo." } } } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "action": { "type": "string", "description": "\"insert\" or \"delete\" based on whether the reaction was added or removed." } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "media:write" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/nodes/": { "get": { "tags": [ "Nodes" ], "summary": "Get the node tree", "description": "Get the node tree.", "operationId": "getNodes", "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "tree_map": { "type": "array", "items": {}, "description": "A mapping that connects node parent IDs to a list of their child node IDs" }, "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/Node" }, "description": "List of all nodes" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "node:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ], "post": { "tags": [ "Nodes" ], "summary": "Create a new node", "description": "Create a new node.", "operationId": "postNodes", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "node[title]", "node[parent_node_id]", "node_type_id" ], "properties": { "node[title]": { "type": "string" }, "node[node_name]": { "type": "string" }, "node[description]": { "type": "string" }, "node[parent_node_id]": { "type": "integer" }, "node[display_order]": { "type": "integer" }, "node[display_in_list]": { "type": "boolean" }, "type_data": { "type": "array", "items": {}, "description": "Type-specific node data. The available options will vary based on the node type involved." }, "node_type_id": { "type": "string" } } } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "node": { "$ref": "#/components/schemas/Node", "description": "Information about the created node" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "node:write" ] }, { "XF-Api-Key": [] } ] } }, "/nodes/flattened": { "get": { "tags": [ "Nodes" ], "summary": "Get a flattened node tree", "description": "Get a flattened node tree. Traversing this returns a list of nodes in the expected order.", "operationId": "getNodesFlattened", "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "nodes_flat": { "type": "array", "items": {}, "description": "An array. Each entry contains keys of \"node\" and \"depth\"" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "node:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/nodes/{id}/": { "get": { "tags": [ "Nodes" ], "summary": "Get information about the specified node", "description": "Get information about the specified node.", "operationId": "getNodesId", "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "node": { "$ref": "#/components/schemas/Node" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "node:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ], "post": { "tags": [ "Nodes" ], "summary": "Update the specified node", "description": "Update the specified node.", "operationId": "postNodesId", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "node[title]": { "type": "string" }, "node[node_name]": { "type": "string" }, "node[description]": { "type": "string" }, "node[parent_node_id]": { "type": "integer" }, "node[display_order]": { "type": "integer" }, "node[display_in_list]": { "type": "boolean" }, "type_data": { "type": "array", "items": {}, "description": "Type-specific node data. The available options will vary based on the node type involved." } } } } } }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "node": { "$ref": "#/components/schemas/Node", "description": "The updated node information" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "node:write" ] }, { "XF-Api-Key": [] } ] }, "delete": { "tags": [ "Nodes" ], "summary": "Delete the specified node", "description": "Delete the specified node.", "operationId": "deleteNodesId", "parameters": [ { "name": "delete_children", "in": "query", "description": "If true, child nodes will be deleted. Otherwise, they will be connected to this node's parent.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "node:delete" ] }, { "XF-Api-Key": [] } ] } }, "/oauth2/introspect": { "post": { "tags": [ "OAuth2" ], "summary": "Introspect an OAuth token", "description": "Introspect an OAuth token.", "operationId": "postOauth2Introspect", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "client_id", "client_secret", "token" ], "properties": { "client_id": { "type": "string" }, "client_secret": { "type": "string" }, "token": { "type": "string" }, "token_type_hint": { "type": "string", "description": "Either 'access_token' or 'refresh_token'" } } } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "active": { "type": "boolean", "description": "Whether the token is currently active" }, "scope": { "type": "string", "description": "Space-separated list of scopes\n\n**Note** Conditionally returned" }, "client_id": { "type": "string", "description": "The client that the token was issued to\n\n**Note** Conditionally returned" }, "username": { "type": "string", "description": "The user associated with the token\n\n**Note** Conditionally returned" }, "token_type": { "type": "string", "description": "Either 'bearer' or 'refresh_token'\n\n**Note** Conditionally returned" }, "exp": { "type": "integer", "description": "Expiry timestamp\n\n**Note** Conditionally returned" }, "iat": { "type": "integer", "description": "Issue timestamp\n\n**Note** Conditionally returned" }, "sub": { "type": "string", "description": "Subject (user ID)\n\n**Note** Conditionally returned" }, "iss": { "type": "string", "description": "Issuer (board URL)\n\n**Note** Conditionally returned" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [] }, "parameters": [ { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/oauth2/revoke": { "post": { "tags": [ "OAuth2" ], "summary": "Revoke an access token or refresh token", "description": "Revoke an access token or refresh token.", "operationId": "postOauth2Revoke", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "client_id", "client_secret", "token" ], "properties": { "client_id": { "type": "string" }, "client_secret": { "type": "string" }, "token": { "type": "string" }, "token_type_hint": { "type": "string", "description": "Defaults to 'access_token' but can be 'refresh_token' to revoke a refresh token." } } } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [] }, "parameters": [ { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/oauth2/token": { "get": { "tags": [ "OAuth2" ], "summary": "Get information about an OAuth token", "description": "Get information about an OAuth token.", "operationId": "getOauth2Token", "parameters": [ { "name": "client_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "client_secret", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "token", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "integer" }, "scope": { "type": "object", "description": "Key-value pairs of granted scopes" }, "expires_in": { "type": "integer", "description": "Remaining lifetime in seconds" }, "issue_date": { "type": "integer" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [] }, "parameters": [ { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ], "post": { "tags": [ "OAuth2" ], "summary": "Exchange a token grant", "description": "Exchange a token grant.", "operationId": "postOauth2Token", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "client_id", "grant_type" ], "properties": { "client_id": { "type": "string" }, "client_secret": { "type": "string", "description": "Required for confidential clients." }, "grant_type": { "type": "string", "description": "Either 'authorization_code' or 'refresh_token'." }, "code": { "type": "string", "description": "Required when grant_type is 'authorization_code'." }, "refresh_token": { "type": "string", "description": "Required when grant_type is 'refresh_token'." }, "code_verifier": { "type": "string", "description": "Required for public clients using PKCE with 'authorization_code' grant." }, "redirect_uri": { "type": "string", "description": "Required when grant_type is 'authorization_code'." } } } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string" }, "refresh_token": { "type": "string" }, "token_type": { "type": "string", "description": "Always 'bearer'" }, "expires_in": { "type": "integer", "description": "Token lifetime in seconds" }, "scope": { "type": "string", "description": "Space-separated list of granted scopes" }, "issue_date": { "type": "integer" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [] } }, "/posts/": { "post": { "tags": [ "Posts" ], "summary": "Add a new reply to a thread", "description": "Add a new reply to a thread.", "operationId": "postPosts", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "thread_id", "message" ], "properties": { "thread_id": { "type": "integer", "description": "ID of the thread to reply to." }, "message": { "type": "string" }, "attachment_key": { "type": "string", "description": "API attachment key to upload files. Attachment key context type must be post with context[thread_id] set to this thread ID." } } } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "post": { "$ref": "#/components/schemas/Post" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "thread:write" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/posts/{id}/": { "get": { "tags": [ "Posts" ], "summary": "Get information about the specified post", "description": "Get information about the specified post.", "operationId": "getPostsId", "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "post": { "$ref": "#/components/schemas/Post" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "thread:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ], "post": { "tags": [ "Posts" ], "summary": "Update the specified post", "description": "Update the specified post.", "operationId": "postPostsId", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "silent": { "type": "boolean", "description": "If true and permissions allow, this edit will not be updated with a \"last edited\" indication" }, "clear_edit": { "type": "boolean", "description": "If true and permissions allow, any \"last edited\" indication will be removed. Requires \"silent\"." }, "author_alert": { "type": "boolean" }, "author_alert_reason": { "type": "string" }, "attachment_key": { "type": "string", "description": "API attachment key to upload files. Attachment key context type must be post with context[post_id] set to this post ID." } } } } } }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "post": { "$ref": "#/components/schemas/Post" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "thread:write" ] }, { "XF-Api-Key": [] } ] }, "delete": { "tags": [ "Posts" ], "summary": "Delete the specified post", "description": "Delete the specified post. Defaults to soft deletion.", "operationId": "deletePostsId", "parameters": [ { "name": "hard_delete", "in": "query", "schema": { "type": "boolean" } }, { "name": "reason", "in": "query", "schema": { "type": "string" } }, { "name": "author_alert", "in": "query", "schema": { "type": "boolean" } }, { "name": "author_alert_reason", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "thread:write" ] }, { "XF-Api-Key": [] } ] } }, "/posts/{id}/mark-solution": { "post": { "tags": [ "Posts" ], "summary": "Toggle a post as the thread solution", "description": "Toggle a post as the thread solution. If a post is marked as a solution when another is already marked, the existing solution will be unmarked.", "operationId": "postPostsIdMarkSolution", "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "new_solution_post": { "oneOf": [ { "$ref": "#/components/schemas/Post" }, { "type": "null" } ], "description": "A post that was marked as the solution" }, "old_solution_post": { "oneOf": [ { "$ref": "#/components/schemas/Post" }, { "type": "null" } ], "description": "A post that was un-marked as the solution" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "thread:write" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/posts/{id}/react": { "post": { "tags": [ "Posts" ], "summary": "React to the specified post", "description": "React to the specified post.", "operationId": "postPostsIdReact", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "reaction_id" ], "properties": { "reaction_id": { "type": "integer", "description": "ID of the reaction to use. Use the current reaction ID to undo." } } } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "action": { "type": "string", "description": "\"insert\" or \"delete\" based on whether the reaction was added or removed." } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "thread:write" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/posts/{id}/vote": { "post": { "tags": [ "Posts" ], "summary": "Vote on the specified post", "description": "Vote on the specified post. Applies only when voting is supported.", "operationId": "postPostsIdVote", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "Type of vote, \"up\" or \"down\". Use the current type to undo." } } } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "action": { "type": "string", "description": "\"insert\" or \"delete\" based on whether the reaction was added or removed." } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "thread:write" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/profile-post-comments/": { "post": { "tags": [ "Profile posts" ], "summary": "Create a new profile post comment", "description": "Create a new profile post comment.", "operationId": "postProfilePostComments", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "profile_post_id", "message" ], "properties": { "profile_post_id": { "type": "integer", "description": "The ID of the profile post this comment will be attached to." }, "message": { "type": "string" }, "attachment_key": { "type": "string", "description": "API attachment key to upload files. Attachment key context type must be profile_post_comment with context[profile_post_id] set to this profile post ID." } } } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "comment": { "$ref": "#/components/schemas/ProfilePostComment" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "profile_post:write" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/profile-post-comments/{id}/": { "get": { "tags": [ "Profile posts" ], "summary": "Get a profile post comment", "description": "Get a profile post comment.", "operationId": "getProfilePostCommentsId", "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "$ref": "#/components/schemas/ProfilePostComment" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "profile_post:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ], "post": { "tags": [ "Profile posts" ], "summary": "Update the specified profile post comment", "description": "Update the specified profile post comment.", "operationId": "postProfilePostCommentsId", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "author_alert": { "type": "boolean" }, "author_alert_reason": { "type": "string" }, "attachment_key": { "type": "string", "description": "API attachment key to upload files. Attachment key context type must be profile_post_comment with context[profile_post_comment_id] set to this profile post comment ID." } } } } } }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "comment": { "$ref": "#/components/schemas/ProfilePostComment" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "profile_post:write" ] }, { "XF-Api-Key": [] } ] }, "delete": { "tags": [ "Profile posts" ], "summary": "Delete the specified profile post comment", "description": "Delete the specified profile post comment. Defaults to soft deletion.", "operationId": "deleteProfilePostCommentsId", "parameters": [ { "name": "hard_delete", "in": "query", "schema": { "type": "boolean" } }, { "name": "reason", "in": "query", "schema": { "type": "string" } }, { "name": "author_alert", "in": "query", "schema": { "type": "boolean" } }, { "name": "author_alert_reason", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "profile_post:write" ] }, { "XF-Api-Key": [] } ] } }, "/profile-post-comments/{id}/react": { "post": { "tags": [ "Profile posts" ], "summary": "React to the specified profile post comment", "description": "React to the specified profile post comment.", "operationId": "postProfilePostCommentsIdReact", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "reaction_id" ], "properties": { "reaction_id": { "type": "integer", "description": "ID of the reaction to use. Use the current reaction ID to undo." } } } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "action": { "type": "string", "description": "\"insert\" or \"delete\" based on whether the reaction was added or removed." } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "profile_post:write" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/profile-posts/": { "post": { "tags": [ "Profile posts" ], "summary": "Create a new profile post", "description": "Create a new profile post.", "operationId": "postProfilePosts", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "user_id", "message" ], "properties": { "user_id": { "type": "integer", "description": "The ID of the user whose profile this will be posted on." }, "message": { "type": "string" }, "attachment_key": { "type": "string", "description": "API attachment key to upload files. Attachment key context type must be profile_post with context[profile_user_id] set to this user ID." } } } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "profile_post": { "$ref": "#/components/schemas/ProfilePost" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "profile_post:write" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/profile-posts/{id}/": { "get": { "tags": [ "Profile posts" ], "summary": "Get information about the specified profile post", "description": "Get information about the specified profile post.", "operationId": "getProfilePostsId", "parameters": [ { "name": "with_comments", "in": "query", "description": "If specified, the response will include a page of comments.", "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "description": "The page of comments to include", "schema": { "type": "integer" } }, { "name": "direction", "in": "query", "description": "Request a particular sort order for comments - default 'desc' (newest first) also allows 'asc' (oldest first)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "profile_post": { "$ref": "#/components/schemas/ProfilePost" }, "comments": { "type": "array", "items": { "$ref": "#/components/schemas/ProfilePostComment" }, "description": "List of comments on the requested page" }, "pagination": { "$ref": "#/components/schemas/Pagination", "description": "Pagination details" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "profile_post:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ], "post": { "tags": [ "Profile posts" ], "summary": "Update the specified profile post", "description": "Update the specified profile post.", "operationId": "postProfilePostsId", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "author_alert": { "type": "boolean" }, "author_alert_reason": { "type": "string" }, "attachment_key": { "type": "string", "description": "API attachment key to upload files. Attachment key context type must be profile_post with context[profile_post_id] set to this profile post ID." } } } } } }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "profile_post": { "$ref": "#/components/schemas/ProfilePost" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "profile_post:write" ] }, { "XF-Api-Key": [] } ] }, "delete": { "tags": [ "Profile posts" ], "summary": "Delete the specified profile post", "description": "Delete the specified profile post. Defaults to soft deletion.", "operationId": "deleteProfilePostsId", "parameters": [ { "name": "hard_delete", "in": "query", "schema": { "type": "boolean" } }, { "name": "reason", "in": "query", "schema": { "type": "string" } }, { "name": "author_alert", "in": "query", "schema": { "type": "boolean" } }, { "name": "author_alert_reason", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "profile_post:write" ] }, { "XF-Api-Key": [] } ] } }, "/profile-posts/{id}/comments": { "get": { "tags": [ "Profile posts" ], "summary": "Get a page of comments on the specified profile post", "description": "Get a page of comments on the specified profile post.", "operationId": "getProfilePostsIdComments", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "direction", "in": "query", "description": "Request a particular sort order for comments - default 'desc' (newest first) also allows 'asc' (oldest first)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "comments": { "type": "array", "items": { "$ref": "#/components/schemas/ProfilePostComment" }, "description": "List of comments on the requested page" }, "pagination": { "$ref": "#/components/schemas/Pagination", "description": "Pagination details" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "profile_post:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/profile-posts/{id}/react": { "post": { "tags": [ "Profile posts" ], "summary": "React to the specified profile post", "description": "React to the specified profile post.", "operationId": "postProfilePostsIdReact", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "reaction_id" ], "properties": { "reaction_id": { "type": "integer", "description": "ID of the reaction to use. Use the current reaction ID to undo." } } } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "action": { "type": "string", "description": "\"insert\" or \"delete\" based on whether the reaction was added or removed." } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "profile_post:write" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/resource-categories/": { "get": { "tags": [ "Resource categories" ], "summary": "Get the resource category tree", "description": "Get the resource category tree.", "operationId": "getResourceCategories", "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "resource_category:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ], "post": { "tags": [ "Resource categories" ], "summary": "Create a resource category", "description": "Create a resource category.", "operationId": "postResourceCategories", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "parent_category_id": { "type": "integer" }, "description": { "type": "string" }, "display_order": { "type": "integer" }, "allow_local": { "type": "boolean" }, "allow_external": { "type": "boolean" }, "allow_commercial_external": { "type": "boolean" }, "allow_fileless": { "type": "boolean" }, "enable_versioning": { "type": "boolean" }, "enable_support_url": { "type": "boolean" }, "always_moderate_create": { "type": "boolean" }, "always_moderate_update": { "type": "boolean" }, "min_tags": { "type": "integer" }, "thread_node_id": { "type": "integer" }, "thread_prefix_id": { "type": "integer" }, "require_prefix": { "type": "boolean" }, "auto_feature": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "category": { "$ref": "#/components/schemas/XFRM_Category" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "resource_category:write" ] }, { "XF-Api-Key": [] } ] } }, "/resource-categories/flattened": { "get": { "tags": [ "Resource categories" ], "summary": "Get a flattened list of resource categories", "description": "Get a flattened list of resource categories.", "operationId": "getResourceCategoriesFlattened", "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "resource_category:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/resource-categories/{id}/": { "get": { "tags": [ "Resource categories" ], "summary": "Get information about the specified resource category", "description": "Get information about the specified resource category.", "operationId": "getResourceCategoriesId", "parameters": [ { "name": "with_resources", "in": "query", "description": "If specified, the response will include a page of resources.", "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "category": { "$ref": "#/components/schemas/XFRM_Category" }, "resources": { "type": "array", "items": { "$ref": "#/components/schemas/XFRM_ResourceItem" }, "description": "Resources on this page" }, "pagination": { "$ref": "#/components/schemas/Pagination", "description": "Pagination information" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "resource_category:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ], "post": { "tags": [ "Resource categories" ], "summary": "Update the specified resource category", "description": "Update the specified resource category.", "operationId": "postResourceCategoriesId", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "parent_category_id": { "type": "integer" }, "display_order": { "type": "integer" }, "allow_local": { "type": "boolean" }, "allow_external": { "type": "boolean" }, "allow_commercial_external": { "type": "boolean" }, "allow_fileless": { "type": "boolean" }, "enable_versioning": { "type": "boolean" }, "enable_support_url": { "type": "boolean" }, "always_moderate_create": { "type": "boolean" }, "always_moderate_update": { "type": "boolean" }, "min_tags": { "type": "integer" }, "thread_node_id": { "type": "integer" }, "thread_prefix_id": { "type": "integer" }, "require_prefix": { "type": "boolean" }, "auto_feature": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "category": { "$ref": "#/components/schemas/XFRM_Category" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "resource_category:write" ] }, { "XF-Api-Key": [] } ] }, "delete": { "tags": [ "Resource categories" ], "summary": "Delete the specified category", "description": "Delete the specified category.", "operationId": "deleteResourceCategoriesId", "parameters": [ { "name": "delete_children", "in": "query", "description": "If true, child nodes will be deleted. Otherwise, they will be connected to this node's parent.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "resource_category:delete" ] }, { "XF-Api-Key": [] } ] } }, "/resource-categories/{id}/resources": { "get": { "tags": [ "Resource categories" ], "summary": "Get a page of resources from the specified category", "description": "Get a page of resources from the specified category.", "operationId": "getResourceCategoriesIdResources", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "resources": { "type": "array", "items": { "$ref": "#/components/schemas/XFRM_ResourceItem" }, "description": "Resources on this page" }, "pagination": { "$ref": "#/components/schemas/Pagination", "description": "Pagination information" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "resource_category:read", "resource:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/resource-reviews/": { "get": { "tags": [ "Resource reviews" ], "summary": "Get a list of latest resource reviews", "description": "Get a list of latest resource reviews.", "operationId": "getResourceReviews", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "reviews": { "type": "array", "items": { "$ref": "#/components/schemas/XFRM_ResourceRating" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "resource_rating:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ], "post": { "tags": [ "Resource reviews" ], "summary": "Create a review or rating for a resource", "description": "Create a review or rating for a resource.", "operationId": "postResourceReviews", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "resource_id", "rating" ], "properties": { "resource_id": { "type": "integer" }, "rating": { "type": "integer", "description": "Rating value (1-5)" }, "message": { "type": "string", "description": "Review text. If provided, this will be a review rather than just a rating." }, "is_anonymous": { "type": "boolean", "description": "If true and allowed, the review will be anonymous." } } } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "review": { "$ref": "#/components/schemas/XFRM_ResourceRating" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "resource_rating:write" ] }, { "XF-Api-Key": [] } ] } }, "/resource-reviews/{id}/": { "get": { "tags": [ "Resource reviews" ], "summary": "Get information about the specified review", "description": "Get information about the specified review.", "operationId": "getResourceReviewsId", "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "review": { "$ref": "#/components/schemas/XFRM_ResourceRating" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "resource_rating:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ], "delete": { "tags": [ "Resource reviews" ], "summary": "Delete the specified review", "description": "Delete the specified review. Defaults to soft deletion.", "operationId": "deleteResourceReviewsId", "parameters": [ { "name": "hard_delete", "in": "query", "schema": { "type": "boolean" } }, { "name": "reason", "in": "query", "schema": { "type": "string" } }, { "name": "author_alert", "in": "query", "schema": { "type": "boolean" } }, { "name": "author_alert_reason", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "resource_rating:write" ] }, { "XF-Api-Key": [] } ] } }, "/resource-reviews/{id}/author-reply": { "post": { "tags": [ "Resource reviews" ], "summary": "Add or update an author reply", "description": "Add or update an author reply.", "operationId": "postResourceReviewsIdAuthorReply", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "review": { "$ref": "#/components/schemas/XFRM_ResourceRating" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "resource_rating:write" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ], "delete": { "tags": [ "Resource reviews" ], "summary": "Remove the author reply from the specified review", "description": "Remove the author reply from the specified review.", "operationId": "deleteResourceReviewsIdAuthorReply", "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "review": { "$ref": "#/components/schemas/XFRM_ResourceRating" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "resource_rating:write" ] }, { "XF-Api-Key": [] } ] } }, "/resource-updates/": { "post": { "tags": [ "Resource updates" ], "summary": "Create a resource update", "description": "Create a resource update.", "operationId": "postResourceUpdates", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "resource_id", "title", "message" ], "properties": { "resource_id": { "type": "integer" }, "title": { "type": "string" }, "message": { "type": "string" }, "attachment_key": { "type": "string", "description": "API attachment key for update images" } } } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "update": { "$ref": "#/components/schemas/XFRM_ResourceUpdate" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "resource:write" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/resource-updates/{id}/": { "get": { "tags": [ "Resource updates" ], "summary": "Get information about the specified resource update", "description": "Get information about the specified resource update.", "operationId": "getResourceUpdatesId", "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "update": { "$ref": "#/components/schemas/XFRM_ResourceUpdate" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "resource:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ], "post": { "tags": [ "Resource updates" ], "summary": "Update the specified resource update", "description": "Update the specified resource update. Cannot be used on description updates.", "operationId": "postResourceUpdatesId", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "message": { "type": "string" }, "attachment_key": { "type": "string", "description": "API attachment key for update images" }, "author_alert": { "type": "boolean" }, "author_alert_reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "update": { "$ref": "#/components/schemas/XFRM_ResourceUpdate" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "resource:write" ] }, { "XF-Api-Key": [] } ] }, "delete": { "tags": [ "Resource updates" ], "summary": "Delete the specified resource update", "description": "Delete the specified resource update. Defaults to soft deletion. Cannot be used on description updates.", "operationId": "deleteResourceUpdatesId", "parameters": [ { "name": "hard_delete", "in": "query", "schema": { "type": "boolean" } }, { "name": "reason", "in": "query", "schema": { "type": "string" } }, { "name": "author_alert", "in": "query", "schema": { "type": "boolean" } }, { "name": "author_alert_reason", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "resource:write" ] }, { "XF-Api-Key": [] } ] } }, "/resource-versions/": { "post": { "tags": [ "Resource versions" ], "summary": "Create a new version of a resource", "description": "Create a new version of a resource.", "operationId": "postResourceVersions", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "resource_id" ], "properties": { "resource_id": { "type": "integer" }, "version_string": { "type": "string" }, "version_type": { "type": "string", "description": "Type of version download: local or external. Defaults based on current resource type." }, "version_attachment_key": { "type": "string", "description": "API attachment key for local download files. Required if version_type is local." }, "external_download_url": { "type": "string", "description": "Required if version_type is external" }, "currency": { "type": "string", "description": "For externally purchasable resources" }, "external_purchase_url": { "type": "string", "description": "For externally purchasable resources" } } } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "version": { "$ref": "#/components/schemas/XFRM_ResourceVersion" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "resource:write" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/resource-versions/{id}/": { "get": { "tags": [ "Resource versions" ], "summary": "Get information about the specified resource version", "description": "Get information about the specified resource version.", "operationId": "getResourceVersionsId", "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "$ref": "#/components/schemas/XFRM_ResourceVersion" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "resource:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ], "delete": { "tags": [ "Resource versions" ], "summary": "Delete the specified resource version", "description": "Delete the specified resource version. Defaults to soft deletion.", "operationId": "deleteResourceVersionsId", "parameters": [ { "name": "hard_delete", "in": "query", "schema": { "type": "boolean" } }, { "name": "reason", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "resource:write" ] }, { "XF-Api-Key": [] } ] } }, "/resource-versions/{id}/download": { "get": { "tags": [ "Resource versions" ], "summary": "Download a resource version file", "description": "Download a resource version file. For external downloads, redirects to the external URL.", "operationId": "getResourceVersionsIdDownload", "parameters": [ { "name": "file", "in": "query", "description": "Attachment ID of the file to download. Required for local downloads.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "resource:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/resources/": { "get": { "tags": [ "Resources" ], "summary": "Get a list of resources", "description": "Get a list of resources.", "operationId": "getResources", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "prefix_id", "in": "query", "description": "Filters to only resources with the specified prefix.", "schema": { "type": "integer" } }, { "name": "type", "in": "query", "description": "Filters to only resources of the specified type: free, paid.", "schema": { "type": "string" } }, { "name": "creator_id", "in": "query", "description": "Filters to only resources created by the specified user ID.", "schema": { "type": "integer" } }, { "name": "order", "in": "query", "description": "Method of ordering: last_update, resource_date, rating_weighted, download_count, title", "schema": { "type": "string" } }, { "name": "direction", "in": "query", "description": "Either \"asc\" or \"desc\" for ascending or descending. Applies only if an order is provided.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "resources": { "type": "array", "items": { "$ref": "#/components/schemas/XFRM_ResourceItem" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "resource:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ], "post": { "tags": [ "Resources" ], "summary": "Create a resource", "description": "Create a resource.", "operationId": "postResources", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "resource_category_id", "title", "tag_line", "description", "resource_type" ], "properties": { "resource_category_id": { "type": "integer" }, "title": { "type": "string" }, "tag_line": { "type": "string" }, "description": { "type": "string" }, "resource_type": { "type": "string", "description": "Type of resource: download_local, download_external, external_purchase, fileless" }, "prefix_id": { "type": "integer" }, "version_string": { "type": "string" }, "custom_fields[]": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "external_url": { "type": "string" }, "alt_support_url": { "type": "string" }, "description_attachment_key": { "type": "string", "description": "API attachment key for description images" }, "version_attachment_key": { "type": "string", "description": "API attachment key for version file. Required for download_local type." }, "external_download_url": { "type": "string", "description": "External download URL. Required for download_external type." }, "currency": { "type": "string", "description": "Currency code. Required for external_purchase type." }, "external_purchase_url": { "type": "string", "description": "Purchase URL. Required for external_purchase type." } } } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "resource": { "$ref": "#/components/schemas/XFRM_ResourceItem" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "resource:write" ] }, { "XF-Api-Key": [] } ] } }, "/resources/{id}/": { "get": { "tags": [ "Resources" ], "summary": "Get information about the specified resource", "description": "Get information about the specified resource.", "operationId": "getResourcesId", "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "resource": { "$ref": "#/components/schemas/XFRM_ResourceItem" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "resource:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ], "post": { "tags": [ "Resources" ], "summary": "Update the specified resource", "description": "Update the specified resource.", "operationId": "postResourcesId", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "prefix_id": { "type": "integer" }, "title": { "type": "string" }, "version_string": { "type": "string" }, "description": { "type": "string" }, "external_download_url": { "type": "string" }, "custom_fields[]": { "type": "string" }, "add_tags": { "type": "array", "items": { "type": "string" } }, "remove_tags": { "type": "array", "items": { "type": "string" } }, "tag_line": { "type": "string" }, "external_url": { "type": "string" }, "alt_support_url": { "type": "string" }, "currency": { "type": "string" }, "external_purchase_url": { "type": "string" }, "attachment_key": { "type": "string", "description": "API attachment key for description images" }, "author_alert": { "type": "boolean" }, "author_alert_reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "resource": { "$ref": "#/components/schemas/XFRM_ResourceItem" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "resource:write" ] }, { "XF-Api-Key": [] } ] }, "delete": { "tags": [ "Resources" ], "summary": "Delete the specified resource", "description": "Delete the specified resource. Defaults to soft deletion.", "operationId": "deleteResourcesId", "parameters": [ { "name": "hard_delete", "in": "query", "schema": { "type": "boolean" } }, { "name": "reason", "in": "query", "schema": { "type": "string" } }, { "name": "author_alert", "in": "query", "schema": { "type": "boolean" } }, { "name": "author_alert_reason", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "resource:write" ] }, { "XF-Api-Key": [] } ] } }, "/resources/{id}/feature": { "post": { "tags": [ "Resources" ], "summary": "Set feature state for the specified resource", "description": "Set feature state for the specified resource.", "operationId": "postResourcesIdFeature", "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "A custom title, if desired.\n\n**Note** Conditionally returned" }, "snippet": { "type": "string", "description": "A custom snippet, if desired.\n\n**Note** Conditionally returned" }, "image": { "type": "string", "contentMediaType": "application/octet-stream", "description": "A custom image, if desired.\n\n**Note** Conditionally returned" }, "date": { "type": "string", "description": "A custom feature date, if desired.\n\n**Note** Conditionally returned" }, "unfeature_days": { "type": "integer", "description": "A custom number of days after which to unfeature the content, if desired.\n\n**Note** Conditionally returned" }, "always_visible": { "type": "boolean", "description": "Whether or not the feature should be visible even when the visitor may not view the content.\n\n**Note** Conditionally returned" } } } } } }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "feature": { "$ref": "#/components/schemas/FeaturedContent" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "resource:write" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/resources/{id}/reviews": { "get": { "tags": [ "Resources" ], "summary": "Get a page of reviews for the specified resource", "description": "Get a page of reviews for the specified resource.", "operationId": "getResourcesIdReviews", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "reviews": { "type": "array", "items": { "$ref": "#/components/schemas/XFRM_ResourceRating" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "resource:read", "resource_rating:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/resources/{id}/unfeature": { "post": { "tags": [ "Resources" ], "summary": "Delete the feature for the specified resource", "description": "Delete the feature for the specified resource.", "operationId": "postResourcesIdUnfeature", "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "resource:write" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/resources/{id}/updates": { "get": { "tags": [ "Resources" ], "summary": "Get a page of updates for the specified resource", "description": "Get a page of updates for the specified resource.", "operationId": "getResourcesIdUpdates", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "updates": { "type": "array", "items": { "$ref": "#/components/schemas/XFRM_ResourceUpdate" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "resource:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/resources/{id}/versions": { "get": { "tags": [ "Resources" ], "summary": "Get a list of versions for the specified resource", "description": "Get a list of versions for the specified resource. Only available for versioned resources.", "operationId": "getResourcesIdVersions", "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "versions": { "type": "array", "items": { "$ref": "#/components/schemas/XFRM_ResourceVersion" } } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "resource:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/search/": { "post": { "tags": [ "Search" ], "summary": "Create a new search", "description": "Create a new search.", "operationId": "postSearch", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "search_type": { "type": "string" }, "keywords": { "type": "string" }, "c": { "type": "array", "items": {} }, "order": { "type": "string" }, "grouped": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "search": { "$ref": "#/components/schemas/Search" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "search:write" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/search/member": { "post": { "tags": [ "Search" ], "summary": "Retrieve search results for a specific member", "description": "Retrieve search results for a specific member.", "operationId": "postSearchMember", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "user_id" ], "properties": { "user_id": { "type": "integer" }, "content": { "type": "string" }, "type": { "type": "string" }, "before": { "type": "integer" }, "thread_type": { "type": "string" }, "grouped": { "type": "boolean" } } } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "search": { "$ref": "#/components/schemas/Search" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "search:write" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/search/{id}/": { "get": { "tags": [ "Search" ], "summary": "Retrieve search results for a given search", "description": "Retrieve search results for a given search.", "operationId": "getSearchId", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "search": { "$ref": "#/components/schemas/Search" }, "results": { "type": "array", "items": {} }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "get_older_results_date": { "oneOf": [ { "type": "integer" }, { "type": "null" } ] } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "search:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/search/{id}/older": { "post": { "tags": [ "Search" ], "summary": "Retrieve older search results for a given search", "description": "Retrieve older search results for a given search.", "operationId": "postSearchIdOlder", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "search_id" ], "properties": { "search_id": { "type": "integer" }, "before": { "type": "integer" } } } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "search": { "$ref": "#/components/schemas/Search" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "search:write" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/search-forums/{id}/": { "get": { "tags": [ "Search forums" ], "summary": "Get information about the specified search forum", "description": "Get information about the specified search forum.", "operationId": "getSearchForumsId", "parameters": [ { "name": "with_threads", "in": "query", "description": "If true, gets a page of threads in this search forum", "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "threads": { "type": "array", "items": { "$ref": "#/components/schemas/Thread" }, "description": "Threads on this page. Note: this will always respect viewing user permissions regardless of whether the API is set to bypass permissions." }, "pagination": { "$ref": "#/components/schemas/Pagination", "description": "Pagination information" }, "sticky": { "type": "array", "items": { "$ref": "#/components/schemas/Thread" }, "description": "If on page 1, a list of sticky threads in this forum. Does not count towards the per page limit." } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "node:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/search-forums/{id}/threads": { "get": { "tags": [ "Search forums" ], "summary": "Get a page of threads from the specified search forum", "description": "Get a page of threads from the specified search forum.", "operationId": "getSearchForumsIdThreads", "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "threads": { "type": "array", "items": { "$ref": "#/components/schemas/Thread" }, "description": "Threads on this page. Note: this will always respect viewing user permissions regardless of whether the API is set to bypass permissions." }, "pagination": { "$ref": "#/components/schemas/Pagination", "description": "Pagination information" }, "sticky": { "type": "array", "items": { "$ref": "#/components/schemas/Thread" }, "description": "If on page 1, a list of sticky threads in this forum. Does not count towards the per page limit." } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "node:read", "thread:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/stats/": { "get": { "tags": [ "Stats" ], "summary": "Get site statistics", "description": "Get site statistics.", "operationId": "getStats", "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "totals[threads]": { "type": "integer" }, "totals[messages]": { "type": "integer" }, "totals[users]": { "type": "integer" }, "latest_user[user_id]": { "type": "integer" }, "latest_user[username]": { "type": "string" }, "latest_user[register_date]": { "type": "integer" }, "online[total]": { "type": "integer" }, "online[members]": { "type": "integer" }, "online[guests]": { "type": "integer" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/threads/": { "get": { "tags": [ "Threads" ], "summary": "Get a list of threads", "description": "Get a list of threads.", "operationId": "getThreads", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "prefix_id", "in": "query", "description": "Filters to only threads with the specified prefix.", "schema": { "type": "integer" } }, { "name": "starter_id", "in": "query", "description": "Filters to only threads started by the specified user ID.", "schema": { "type": "integer" } }, { "name": "last_days", "in": "query", "description": "Filters to threads that have had a reply in the last X days.", "schema": { "type": "integer" } }, { "name": "unread", "in": "query", "description": "Filters to unread threads only. Ignored for guests.", "schema": { "type": "boolean" } }, { "name": "thread_type", "in": "query", "description": "Filters to threads of the specified thread type.", "schema": { "type": "string" } }, { "name": "order", "in": "query", "description": "Method of ordering: last_post_date, post_date. When in a specific forum context: title, reply_count, view_count, vote_score, first_post_reaction_score.", "schema": { "type": "string" } }, { "name": "direction", "in": "query", "description": "Either \"asc\" or \"desc\" for ascending or descending. Applies only if an order is provided.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "threads": { "type": "array", "items": { "$ref": "#/components/schemas/Thread" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "thread:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ], "post": { "tags": [ "Threads" ], "summary": "Create a thread", "description": "Create a thread. Thread type data can be set using additional input specific to the target thread type.", "operationId": "postThreads", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "node_id", "title", "message" ], "properties": { "node_id": { "type": "integer", "description": "ID of the forum to create the thread in." }, "title": { "type": "string", "description": "Title of the thread." }, "message": { "type": "string", "description": "Body of the first post in the thread." }, "discussion_type": { "type": "string", "description": "The type of thread to create. Specific types may require additional input." }, "prefix_id": { "type": "integer", "description": "ID of the prefix to apply to the thread. If not valid in the selected forum, will be ignored." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Array of tag names to apply to the thread." }, "custom_fields[]": { "type": "string", "description": "Value to apply to the custom field with the specified name." }, "discussion_open": { "type": "boolean" }, "sticky": { "type": "boolean" }, "attachment_key": { "type": "string", "description": "API attachment key to upload files. Attachment key context type must be post with context[node_id] set to the ID of the forum this is being posted in." } } } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "thread": { "$ref": "#/components/schemas/Thread" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "No permission error.\n\n**Possible errors**\n- `no_permission`: No permission error." } }, "security": [ { "XF-OAuth2": [ "thread:write" ] }, { "XF-Api-Key": [] } ] } }, "/threads/{id}/": { "get": { "tags": [ "Threads" ], "summary": "Get information about the specified thread", "description": "Get information about the specified thread.", "operationId": "getThreadsId", "parameters": [ { "name": "with_posts", "in": "query", "description": "If specified, the response will include a page of posts.", "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "description": "The page of posts to include", "schema": { "type": "integer" } }, { "name": "with_first_post", "in": "query", "description": "If specified, the response will contain the first post in the thread.", "schema": { "type": "boolean" } }, { "name": "with_last_post", "in": "query", "description": "If specified, the response will contain the last post in the thread.", "schema": { "type": "boolean" } }, { "name": "order", "in": "query", "description": "Request a particular sort order for posts from the available options for the thread type", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "thread": { "$ref": "#/components/schemas/Thread" }, "first_unread": { "$ref": "#/components/schemas/Post", "description": "If the thread is unread, information about the first unread post.\n\n**Note** Conditionally returned" }, "first_post": { "$ref": "#/components/schemas/Post", "description": "If requested, information about the first post in the thread.\n\n**Note** Conditionally returned" }, "last_post": { "$ref": "#/components/schemas/Post", "description": "If requested, information about the last post in the thread.\n\n**Note** Conditionally returned" }, "pinned_post": { "$ref": "#/components/schemas/Post", "description": "The pinned first post of the thread, if specified by the thread type.\n\n**Note** Conditionally returned" }, "highlighted_posts": { "type": "array", "items": { "$ref": "#/components/schemas/Post" }, "description": "A list of highlighted posts, if relevant to the thread type. The reason for highlighting depends on thread type.\n\n**Note** Conditionally returned" }, "posts": { "type": "array", "items": { "$ref": "#/components/schemas/Post" }, "description": "List of posts on the requested page. Note that even if the first post is pinned, it will be included here." }, "pagination": { "$ref": "#/components/schemas/Pagination", "description": "Pagination details" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "thread:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ], "post": { "tags": [ "Threads" ], "summary": "Update the specified thread", "description": "Update the specified thread.", "operationId": "postThreadsId", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "prefix_id": { "type": "integer" }, "title": { "type": "string" }, "discussion_open": { "type": "boolean" }, "sticky": { "type": "boolean" }, "custom_fields[]": { "type": "string" }, "add_tags": { "type": "array", "items": {} }, "remove_tags": { "type": "array", "items": {} } } } } } }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "thread": { "$ref": "#/components/schemas/Thread" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "thread:write" ] }, { "XF-Api-Key": [] } ] }, "delete": { "tags": [ "Threads" ], "summary": "Delete the specified thread", "description": "Delete the specified thread. Defaults to soft deletion.", "operationId": "deleteThreadsId", "parameters": [ { "name": "hard_delete", "in": "query", "schema": { "type": "boolean" } }, { "name": "reason", "in": "query", "schema": { "type": "string" } }, { "name": "starter_alert", "in": "query", "schema": { "type": "boolean" } }, { "name": "starter_alert_reason", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "thread:write" ] }, { "XF-Api-Key": [] } ] } }, "/threads/{id}/change-type": { "post": { "tags": [ "Threads" ], "summary": "Convert a thread to the specified type", "description": "Convert a thread to the specified type. Additional thread type data can be set using input specific to the new thread type.", "operationId": "postThreadsIdChangeType", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "new_thread_type_id" ], "properties": { "new_thread_type_id": { "type": "string" } } } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "thread": { "$ref": "#/components/schemas/Thread" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "thread:write" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/threads/{id}/feature": { "post": { "tags": [ "Threads" ], "summary": "Set feature state for the specified thread", "description": "Set feature state for the specified thread.", "operationId": "postThreadsIdFeature", "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "A custom title, if desired.\n\n**Note** Conditionally returned" }, "snippet": { "type": "string", "description": "A custom snippet, if desired.\n\n**Note** Conditionally returned" }, "image": { "type": "string", "contentMediaType": "application/octet-stream", "description": "A custom image, if desired.\n\n**Note** Conditionally returned" }, "date": { "type": "string", "description": "A custom feature date, if desired.\n\n**Note** Conditionally returned" }, "unfeature_days": { "type": "integer", "description": "A custom number of days after which to unfeature the content, if desired.\n\n**Note** Conditionally returned" }, "always_visible": { "type": "boolean", "description": "Whether or not the feature should be visible even when the visitor may not view the content.\n\n**Note** Conditionally returned" } } } } } }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "feature": { "$ref": "#/components/schemas/FeaturedContent" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "thread:write" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/threads/{id}/mark-read": { "post": { "tags": [ "Threads" ], "summary": "Mark a thread as read", "description": "Mark a thread as read. This cannot mark a thread as unread or", "operationId": "postThreadsIdMarkRead", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "date": { "type": "integer", "description": "Unix timestamp to mark the thread read to. If not specified, defaults to the current time." } } } } } }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "thread:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/threads/{id}/move": { "post": { "tags": [ "Threads" ], "summary": "Move the specified thread to a different forum", "description": "Move the specified thread to a different forum. Only simple title/prefix updates are supported at the same time.", "operationId": "postThreadsIdMove", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "target_node_id" ], "properties": { "target_node_id": { "type": "integer" }, "prefix_id": { "type": "integer", "description": "If set, will update the thread's prefix. Prefix must be valid in the target forum." }, "title": { "type": "string", "description": "If set, updates the thread's title" }, "notify_watchers": { "type": "boolean", "description": "If true, users watching the target forum will receive a notification as if this thread were created in the target forum" }, "starter_alert": { "type": "boolean", "description": "If true, the thread starter will receive an alert notifying them of the move" }, "starter_alert_reason": { "type": "boolean", "description": "The reason for the move to include with the thread starter alert" } } } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "thread": { "$ref": "#/components/schemas/Thread" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "thread:write" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/threads/{id}/posts": { "get": { "tags": [ "Threads" ], "summary": "Get a page of posts in the specified thread", "description": "Get a page of posts in the specified thread.", "operationId": "getThreadsIdPosts", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "order", "in": "query", "description": "Request a particular sort order for posts from the available options for the thread type", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "pinned_post": { "$ref": "#/components/schemas/Post", "description": "The pinned first post of the thread, if specified by the thread type.\n\n**Note** Conditionally returned" }, "highlighted_posts": { "type": "array", "items": { "$ref": "#/components/schemas/Post" }, "description": "A list of highlighted posts, if relevant to the thread type. The reason for highlighting depends on thread type.\n\n**Note** Conditionally returned" }, "posts": { "type": "array", "items": { "$ref": "#/components/schemas/Post" }, "description": "List of posts on the requested page. Note that even if the first post is pinned, it will be included here." }, "pagination": { "$ref": "#/components/schemas/Pagination", "description": "Pagination details" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "thread:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/threads/{id}/unfeature": { "post": { "tags": [ "Threads" ], "summary": "Delete the feature for the specified thread", "description": "Delete the feature for the specified thread.", "operationId": "postThreadsIdUnfeature", "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "thread:write" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/threads/{id}/vote": { "post": { "tags": [ "Threads" ], "summary": "Vote on the specified thread", "description": "Vote on the specified thread. Applies only when voting is supported.", "operationId": "postThreadsIdVote", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "Type of vote, \"up\" or \"down\". Use the current type to undo." } } } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "action": { "type": "string", "description": "\"insert\" or \"delete\" based on whether the reaction was added or removed." } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "thread:write" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/users/": { "get": { "tags": [ "Users" ], "summary": "Get a list of users", "description": "Get a list of users. Results are ordered alphabetically.", "operationId": "getUsers", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "users": { "type": "array", "items": { "$ref": "#/components/schemas/User" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "user:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ], "post": { "tags": [ "Users" ], "summary": "Create a user", "description": "Create a user.", "operationId": "postUsers", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "option[creation_watch_state]": { "type": "string" }, "option[interaction_watch_state]": { "type": "string" }, "option[content_show_signature]": { "type": "boolean" }, "option[email_on_conversation]": { "type": "boolean" }, "option[push_on_conversation]": { "type": "boolean" }, "option[receive_admin_email]": { "type": "boolean" }, "option[show_dob_year]": { "type": "boolean" }, "option[show_dob_date]": { "type": "boolean" }, "profile[location]": { "type": "string" }, "profile[website]": { "type": "string" }, "profile[about]": { "type": "string" }, "profile[signature]": { "type": "string" }, "privacy[allow_view_profile]": { "type": "string" }, "privacy[allow_post_profile]": { "type": "string" }, "privacy[allow_receive_news_feed]": { "type": "string" }, "privacy[allow_send_personal_conversation]": { "type": "string" }, "privacy[allow_view_identities]": { "type": "string" }, "visible": { "type": "boolean" }, "activity_visible": { "type": "boolean" }, "timezone": { "type": "string" }, "custom_title": { "type": "string" }, "option[is_discouraged]": { "type": "boolean" }, "username": { "type": "string" }, "email": { "type": "string" }, "user_group_id": { "type": "integer" }, "secondary_group_ids": { "type": "array", "items": { "type": "integer" } }, "user_state": { "type": "string" }, "is_staff": { "type": "boolean" }, "message_count": { "type": "integer" }, "reaction_score": { "type": "integer" }, "trophy_points": { "type": "integer" }, "username_change_visible": { "type": "boolean", "description": "If true and the username is changed, the change will be visible (shown in the public list of previous usernames)." }, "password": { "type": "string" }, "dob[day]": { "type": "integer" }, "dob[month]": { "type": "integer" }, "dob[year]": { "type": "integer" }, "custom_fields[]": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "user": { "$ref": "#/components/schemas/User" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "user:write" ] }, { "XF-Api-Key": [] } ] } }, "/users/find-email": { "get": { "tags": [ "Users" ], "summary": "Find users by email", "description": "Find users by email. Only available to admin users. Also available when bypassing permissions.", "operationId": "getUsersFindEmail", "parameters": [ { "name": "email", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "oneOf": [ { "$ref": "#/components/schemas/User" }, { "type": "null" } ], "description": "The user that matched the given email exactly" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "user:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/users/find-name": { "get": { "tags": [ "Users" ], "summary": "Find users by a prefix of their user name", "description": "Find users by a prefix of their user name.", "operationId": "getUsersFindName", "parameters": [ { "name": "username", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "exact": { "oneOf": [ { "$ref": "#/components/schemas/User" }, { "type": "null" } ], "description": "The user that matched the given username exactly" }, "recommendations": { "type": "array", "items": { "$ref": "#/components/schemas/User" }, "description": "A list of users that match the prefix of the username (but not exactly)" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "user:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/users/{id}/": { "get": { "tags": [ "Users" ], "summary": "Get information about the specified user", "description": "Get information about the specified user.", "operationId": "getUsersId", "parameters": [ { "name": "with_posts", "in": "query", "description": "If specified, the response will include a page of profile posts.", "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "description": "The page of comments to include", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" }, "profile_posts": { "type": "array", "items": { "$ref": "#/components/schemas/ProfilePost" }, "description": "List of profile posts on the requested page" }, "pagination": { "$ref": "#/components/schemas/Pagination", "description": "Pagination details" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "user:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ], "post": { "tags": [ "Users" ], "summary": "Update an existing user", "description": "Update an existing user.", "operationId": "postUsersId", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "option[creation_watch_state]": { "type": "string" }, "option[interaction_watch_state]": { "type": "string" }, "option[content_show_signature]": { "type": "boolean" }, "option[email_on_conversation]": { "type": "boolean" }, "option[push_on_conversation]": { "type": "boolean" }, "option[receive_admin_email]": { "type": "boolean" }, "option[show_dob_year]": { "type": "boolean" }, "option[show_dob_date]": { "type": "boolean" }, "profile[location]": { "type": "string" }, "profile[website]": { "type": "string" }, "profile[about]": { "type": "string" }, "profile[signature]": { "type": "string" }, "privacy[allow_view_profile]": { "type": "string" }, "privacy[allow_post_profile]": { "type": "string" }, "privacy[allow_receive_news_feed]": { "type": "string" }, "privacy[allow_send_personal_conversation]": { "type": "string" }, "privacy[allow_view_identities]": { "type": "string" }, "visible": { "type": "boolean" }, "activity_visible": { "type": "boolean" }, "timezone": { "type": "string" }, "custom_title": { "type": "string" }, "option[is_discouraged]": { "type": "boolean" }, "username": { "type": "string" }, "email": { "type": "string" }, "user_group_id": { "type": "integer" }, "secondary_group_ids": { "type": "array", "items": { "type": "integer" } }, "user_state": { "type": "string" }, "is_staff": { "type": "boolean" }, "message_count": { "type": "integer" }, "reaction_score": { "type": "integer" }, "trophy_points": { "type": "integer" }, "username_change_visible": { "type": "boolean", "description": "If true and the username is changed, the change will be visible (shown in the public list of previous usernames)." }, "password": { "type": "string" }, "dob[day]": { "type": "integer" }, "dob[month]": { "type": "integer" }, "dob[year]": { "type": "integer" }, "custom_fields[]": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "user": { "$ref": "#/components/schemas/User" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "user:write" ] }, { "XF-Api-Key": [] } ] }, "delete": { "tags": [ "Users" ], "summary": "Delete the specified user", "description": "Delete the specified user.", "operationId": "deleteUsersId", "parameters": [ { "name": "rename_to", "in": "query", "description": "If specified, the user will be renamed before deletion", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "user:delete" ] }, { "XF-Api-Key": [] } ] } }, "/users/{id}/avatar": { "post": { "tags": [ "Users" ], "summary": "Update the specified user avatar", "description": "Update the specified user avatar.", "operationId": "postUsersIdAvatar", "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "avatar" ], "properties": { "avatar": { "type": "string", "contentMediaType": "application/octet-stream", "description": "The uploaded new avatar" } } } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "user:write" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ], "delete": { "tags": [ "Users" ], "summary": "Delete the specified user avatar", "description": "Delete the specified user avatar.", "operationId": "deleteUsersIdAvatar", "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "user:delete" ] }, { "XF-Api-Key": [] } ] } }, "/users/{id}/profile-posts": { "get": { "tags": [ "Users" ], "summary": "Get a page of user profile posts", "description": "Get a page of user profile posts.", "operationId": "getUsersIdProfilePosts", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "profile_posts": { "type": "array", "items": { "$ref": "#/components/schemas/ProfilePost" }, "description": "List of profile posts on the requested page" }, "pagination": { "$ref": "#/components/schemas/Pagination", "description": "Pagination details" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [ { "XF-OAuth2": [ "user:read", "profile_post:read" ] }, { "XF-Api-Key": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] }, "/oembed/": { "get": { "tags": [ "oEmbed" ], "summary": "Get oEmbed data for the given URL", "description": "Get oEmbed data for the given URL. This is the oEmbed 1.0 consumer endpoint.", "operationId": "getOembed", "parameters": [ { "name": "url", "in": "query", "description": "The URL of the content to retrieve oEmbed data for.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "string", "description": "oEmbed version (always '1.0')" }, "type": { "type": "string", "description": "oEmbed type (e.g. 'rich')" }, "provider_name": { "type": "string" }, "provider_url": { "type": "string" }, "author_name": { "type": "string" }, "author_url": { "type": "string" }, "html": { "type": "string", "description": "HTML embed code" }, "referrer": { "type": "string" }, "cache_age": { "type": "integer", "description": "Recommended cache lifetime in seconds" } } } } } }, "default": { "$ref": "#/components/responses/error", "description": "Error" } }, "security": [] }, "parameters": [ { "$ref": "#/components/parameters/XF-Api-User" }, { "$ref": "#/components/parameters/api_bypass_permissions" } ] } }, "components": { "schemas": { "Attachment": { "type": "object", "properties": { "filename": { "type": "string" }, "file_size": { "type": "integer" }, "height": { "type": "integer" }, "width": { "type": "integer" }, "thumbnail_url": { "type": "string" }, "retina_thumbnail_url": { "type": "string" }, "direct_url": { "type": "string" }, "is_video": { "type": "boolean" }, "is_audio": { "type": "boolean" }, "attachment_id": { "type": "integer" }, "content_type": { "type": "string" }, "content_id": { "type": "integer" }, "attach_date": { "type": "integer" }, "view_count": { "type": "integer" } } }, "Conversation": { "type": "object", "properties": { "username": { "type": "string", "description": "Name of the user that started the conversation" }, "recipients": { "type": "object", "description": "Key-value pair of recipient user IDs and names" }, "is_starred": { "type": "boolean", "description": "True if the viewing user starred the conversation" }, "is_unread": { "type": "boolean", "description": "If accessing as a user, true if this conversation is unread" }, "can_edit": { "type": "boolean" }, "can_reply": { "type": "boolean" }, "can_invite": { "type": "boolean" }, "can_upload_attachment": { "type": "boolean" }, "view_url": { "type": "string" }, "conversation_id": { "type": "integer" }, "title": { "type": "string" }, "user_id": { "type": "integer" }, "start_date": { "type": "integer" }, "open_invite": { "type": "boolean" }, "conversation_open": { "type": "boolean" }, "reply_count": { "type": "integer" }, "recipient_count": { "type": "integer" }, "first_message_id": { "type": "integer" }, "last_message_date": { "type": "integer" }, "last_message_id": { "type": "integer" }, "last_message_user_id": { "type": "integer" }, "Starter": { "$ref": "#/components/schemas/User" } } }, "ConversationMessage": { "type": "object", "properties": { "username": { "type": "string" }, "is_unread": { "type": "boolean", "description": "If accessing as a user, true if this conversation message is unread" }, "message_parsed": { "type": "string", "description": "HTML parsed version of the message contents." }, "can_edit": { "type": "boolean" }, "can_react": { "type": "boolean" }, "view_url": { "type": "string" }, "Conversation": { "$ref": "#/components/schemas/Conversation", "description": "If requested by context, the conversation this message is part of." }, "Attachments": { "type": "array", "items": { "$ref": "#/components/schemas/Attachment" }, "description": "If there are attachments to this message, a list of attachments." }, "is_reacted_to": { "type": "boolean", "description": "True if the viewing user has reacted to this content" }, "visitor_reaction_id": { "type": "integer", "description": "If the viewer reacted, the ID of the reaction they used" }, "message_id": { "type": "integer" }, "conversation_id": { "type": "integer" }, "message_date": { "type": "integer" }, "user_id": { "type": "integer" }, "message": { "type": "string" }, "attach_count": { "type": "integer" }, "reaction_score": { "type": "integer" }, "User": { "$ref": "#/components/schemas/User" } } }, "FeaturedContent": { "type": "object", "properties": { "content_username": { "type": "string" }, "title": { "type": "string" }, "image": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "snippet": { "type": "string" }, "view_url": { "type": "string" }, "can_view_content": { "type": "boolean" }, "feature_user_id": { "type": "integer", "description": "Present for members with permission to feature or unfeature the content" }, "unfeature_date": { "type": "integer", "description": "Present for members with permission to feature or unfeature the content" }, "auto_featured": { "type": "boolean", "description": "Present for members with permission to feature or unfeature the content" }, "always_visible": { "type": "boolean", "description": "Present for members with permission to feature or unfeature the content" }, "unfeature_days": { "type": "integer", "description": "Present for members with permission to feature or unfeature the content" }, "is_customized": { "type": "boolean", "description": "Present for members with permission to feature or unfeature the content" }, "featured_content_id": { "type": "integer" }, "content_type": { "type": "string" }, "content_id": { "type": "integer" }, "content_container_id": { "type": "integer" }, "content_user_id": { "type": "integer" }, "content_date": { "type": "integer" }, "content_visible": { "type": "boolean" }, "feature_date": { "type": "integer" }, "image_date": { "type": "integer" }, "ContentUser": { "$ref": "#/components/schemas/User" } } }, "Forum": { "type": "object", "properties": { "forum_type_id": { "type": "string" }, "allow_posting": { "type": "boolean" }, "require_prefix": { "type": "boolean" }, "min_tags": { "type": "integer" } } }, "LinkForum": { "type": "object", "properties": { "link_url": { "type": "string" }, "redirect_count": { "type": "integer" } } }, "Node": { "type": "object", "properties": { "breadcrumbs": { "type": "array", "items": {}, "description": "A list of breadcrumbs for this node, including the node_id, title, and node_type_id" }, "type_data": { "type": "object", "description": "Data related to the specific node type this represents. Contents will vary significantly." }, "view_url": { "type": "string" }, "node_id": { "type": "integer" }, "title": { "type": "string" }, "node_name": { "type": "string" }, "description": { "type": "string" }, "node_type_id": { "type": "string" }, "parent_node_id": { "type": "integer" }, "display_order": { "type": "integer" }, "display_in_list": { "type": "boolean" } } }, "Page": { "type": "object", "properties": { "publish_date": { "type": "integer" }, "view_count": { "type": "integer" } } }, "Pagination": { "type": "object", "description": "Pagination details for paginated responses.", "properties": { "current_page": { "type": "integer", "description": "The current page number." }, "last_page": { "type": "integer", "description": "The last page number." }, "per_page": { "type": "integer", "description": "The number of items per page." }, "shown": { "type": "integer", "description": "The number of items returned." }, "total": { "type": "integer", "description": "The total number of items." } } }, "Poll": { "type": "object", "properties": { "can_vote": { "type": "boolean" }, "has_voted": { "type": "boolean" }, "responses": { "type": "array", "items": {}, "description": "List of possible responses with text, vote count (if visible) and whether the API user has voted for each" }, "poll_id": { "type": "integer" }, "question": { "type": "string" }, "voter_count": { "type": "integer" }, "public_votes": { "type": "boolean" }, "max_votes": { "type": "integer" }, "close_date": { "type": "integer" }, "change_vote": { "type": "boolean" }, "view_results_unvoted": { "type": "boolean" } } }, "Post": { "type": "object", "properties": { "username": { "type": "string" }, "is_first_post": { "type": "boolean" }, "is_last_post": { "type": "boolean" }, "is_unread": { "type": "boolean", "description": "If accessing as a user, true if this post is unread" }, "message_parsed": { "type": "string", "description": "HTML parsed version of the message contents." }, "can_edit": { "type": "boolean" }, "can_soft_delete": { "type": "boolean" }, "can_hard_delete": { "type": "boolean" }, "can_react": { "type": "boolean" }, "can_view_attachments": { "type": "boolean" }, "view_url": { "type": "string" }, "Thread": { "$ref": "#/components/schemas/Thread", "description": "If requested by context, the thread this post is part of." }, "Attachments": { "type": "array", "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Attachments to this post, if it has any." }, "is_reacted_to": { "type": "boolean", "description": "True if the viewing user has reacted to this content" }, "visitor_reaction_id": { "type": "integer", "description": "If the viewer reacted, the ID of the reaction they used" }, "vote_score": { "type": "integer", "description": "The content's vote score (if supported)" }, "can_content_vote": { "type": "boolean", "description": "True if the viewing user can vote on this content" }, "allowed_content_vote_types": { "type": "array", "items": { "type": "string" }, "description": "List of content vote types allowed on this content" }, "is_content_voted": { "type": "boolean", "description": "True if the viewing user has voted on this content" }, "visitor_content_vote": { "type": "string", "description": "If the viewer reacted, the vote they case (up/down)" }, "post_id": { "type": "integer" }, "thread_id": { "type": "integer" }, "user_id": { "type": "integer" }, "post_date": { "type": "integer" }, "message": { "type": "string" }, "message_state": { "type": "string" }, "attach_count": { "type": "integer" }, "warning_message": { "type": "string" }, "position": { "type": "integer" }, "last_edit_date": { "type": "integer" }, "reaction_score": { "type": "integer" }, "User": { "$ref": "#/components/schemas/User" } } }, "ProfilePost": { "type": "object", "properties": { "username": { "type": "string" }, "message_parsed": { "type": "string", "description": "HTML parsed version of the message contents." }, "can_edit": { "type": "boolean" }, "can_soft_delete": { "type": "boolean" }, "can_hard_delete": { "type": "boolean" }, "can_react": { "type": "boolean" }, "can_view_attachments": { "type": "boolean" }, "view_url": { "type": "string" }, "ProfileUser": { "$ref": "#/components/schemas/User", "description": "If requested by context, the user this profile post was left for." }, "Attachments": { "type": "array", "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Attachments to this profile post, if it has any." }, "LatestComments": { "type": "array", "items": { "$ref": "#/components/schemas/ProfilePostComment" }, "description": "If requested, the most recent comments on this profile post." }, "is_reacted_to": { "type": "boolean", "description": "True if the viewing user has reacted to this content" }, "visitor_reaction_id": { "type": "integer", "description": "If the viewer reacted, the ID of the reaction they used" }, "profile_post_id": { "type": "integer" }, "profile_user_id": { "type": "integer" }, "user_id": { "type": "integer" }, "post_date": { "type": "integer" }, "message": { "type": "string" }, "message_state": { "type": "string" }, "warning_message": { "type": "string" }, "comment_count": { "type": "integer" }, "first_comment_date": { "type": "integer" }, "last_comment_date": { "type": "integer" }, "reaction_score": { "type": "integer" }, "User": { "$ref": "#/components/schemas/User" } } }, "ProfilePostComment": { "type": "object", "properties": { "username": { "type": "string" }, "message_parsed": { "type": "string", "description": "HTML parsed version of the message contents." }, "can_edit": { "type": "boolean" }, "can_soft_delete": { "type": "boolean" }, "can_hard_delete": { "type": "boolean" }, "can_react": { "type": "boolean" }, "can_view_attachments": { "type": "boolean" }, "Attachments": { "type": "array", "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Attachments to this profile post, if it has any." }, "ProfilePost": { "$ref": "#/components/schemas/ProfilePost", "description": "If requested by context, the profile post this comment relates to." }, "is_reacted_to": { "type": "boolean", "description": "True if the viewing user has reacted to this content" }, "visitor_reaction_id": { "type": "integer", "description": "If the viewer reacted, the ID of the reaction they used" }, "profile_post_comment_id": { "type": "integer" }, "profile_post_id": { "type": "integer" }, "user_id": { "type": "integer" }, "comment_date": { "type": "integer" }, "message": { "type": "string" }, "message_state": { "type": "string" }, "warning_message": { "type": "string" }, "reaction_score": { "type": "integer" }, "User": { "$ref": "#/components/schemas/User" } } }, "Search": { "type": "object", "properties": { "search_id": { "type": "integer" }, "result_count": { "type": "integer" }, "search_type": { "type": "string" }, "search_query": { "type": "string" }, "search_constraints": { "type": "array", "items": {} }, "search_order": { "type": "string" }, "search_grouping": { "type": "boolean" }, "warnings": { "type": "array", "items": {} }, "user_id": { "type": "integer" }, "search_date": { "type": "integer" }, "query_hash": { "type": "string" } } }, "Thread": { "type": "object", "properties": { "username": { "type": "string" }, "is_watching": { "type": "boolean", "description": "If accessing as a user, true if they are watching this thread" }, "visitor_post_count": { "type": "integer", "description": "If accessing as a user, the number of posts they have made in this thread" }, "is_unread": { "type": "boolean", "description": "If accessing as a user, true if this thread is unread" }, "custom_fields": { "type": "object", "description": "Key-value pairs of custom field values for this thread" }, "tags": { "type": "array", "items": {} }, "prefix": { "type": "string", "description": "Present if this thread has a prefix. Printable name of the prefix." }, "can_edit": { "type": "boolean" }, "can_edit_tags": { "type": "boolean" }, "can_reply": { "type": "boolean" }, "can_soft_delete": { "type": "boolean" }, "can_hard_delete": { "type": "boolean" }, "can_view_attachments": { "type": "boolean" }, "view_url": { "type": "string" }, "is_first_post_pinned": { "type": "boolean" }, "highlighted_post_ids": { "type": "array", "items": {} }, "is_search_engine_indexable": { "type": "boolean" }, "index_state": { "type": "string", "description": "Present for members with permission to change the search index state of this thread." }, "Forum": { "$ref": "#/components/schemas/Node", "description": "If requested by context, the forum this thread was posted in." }, "vote_score": { "type": "integer", "description": "The content's vote score (if supported)" }, "can_content_vote": { "type": "boolean", "description": "True if the viewing user can vote on this content" }, "allowed_content_vote_types": { "type": "array", "items": { "type": "string" }, "description": "List of content vote types allowed on this content" }, "is_content_voted": { "type": "boolean", "description": "True if the viewing user has voted on this content" }, "visitor_content_vote": { "type": "string", "description": "If the viewer reacted, the vote they case (up/down)" }, "thread_id": { "type": "integer" }, "node_id": { "type": "integer" }, "title": { "type": "string" }, "reply_count": { "type": "integer" }, "view_count": { "type": "integer" }, "user_id": { "type": "integer" }, "post_date": { "type": "integer" }, "sticky": { "type": "boolean" }, "discussion_state": { "type": "string" }, "discussion_open": { "type": "boolean" }, "discussion_type": { "type": "string" }, "first_post_id": { "type": "integer" }, "last_post_date": { "type": "integer" }, "last_post_id": { "type": "integer" }, "last_post_user_id": { "type": "integer" }, "last_post_username": { "type": "string" }, "first_post_reaction_score": { "type": "integer" }, "prefix_id": { "type": "integer" }, "featured": { "type": "boolean" }, "User": { "$ref": "#/components/schemas/User" } } }, "ThreadField": { "type": "object", "properties": { "field_id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "display_order": { "type": "integer" }, "field_type": { "type": "string" }, "field_choices": { "type": "object", "description": "For choice types, an ordered list of choices, with \"option\" and \"name\" keys for each." }, "match_type": { "type": "string" }, "match_params": { "type": "array", "items": {} }, "max_length": { "type": "integer" }, "required": { "type": "boolean" }, "display_group": { "type": "string", "description": "If this field type supports grouping, the group this field belongs to." }, "filter_enabled": { "type": "boolean" }, "search_enabled": { "type": "boolean" } } }, "ThreadPrefix": { "type": "object", "properties": { "prefix_id": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": "string" }, "usage_help": { "type": "string" }, "is_usable": { "type": "boolean", "description": "True if the acting user can use (select) this prefix." }, "prefix_group_id": { "type": "integer" }, "display_order": { "type": "integer" }, "materialized_order": { "type": "integer", "description": "Effective order, taking group ordering into account." } } }, "User": { "type": "object", "description": "Information about the user. Different information will be included based on permissions and verbosity.", "properties": { "about": { "type": "string" }, "activity_visible": { "type": "boolean" }, "age": { "type": "integer", "description": "The user's current age. Only included if available." }, "alert_optout": { "type": "array", "items": {} }, "allow_post_profile": { "type": "string" }, "allow_receive_news_feed": { "type": "string" }, "allow_send_personal_conversation": { "type": "string" }, "allow_view_identities": { "type": "string" }, "allow_view_profile": { "type": "string" }, "avatar_urls": { "type": "object", "description": "Maps from size types to URL." }, "profile_banner_urls": { "type": "object", "description": "Maps from size types to URL." }, "can_ban": { "type": "boolean" }, "can_converse": { "type": "boolean" }, "can_edit": { "type": "boolean" }, "can_follow": { "type": "boolean" }, "can_ignore": { "type": "boolean" }, "can_post_profile": { "type": "boolean" }, "can_view_profile": { "type": "boolean" }, "can_view_profile_posts": { "type": "boolean" }, "can_warn": { "type": "boolean" }, "content_show_signature": { "type": "boolean" }, "creation_watch_state": { "type": "string" }, "custom_fields": { "type": "object", "description": "Map of custom field keys and values." }, "custom_title": { "type": "string", "description": "Will have a value if a custom title has been specifically set; prefer user_title instead." }, "dob": { "type": "object", "description": "Date of birth with year, month and day keys." }, "email": { "type": "string" }, "email_on_conversation": { "type": "boolean" }, "gravatar": { "type": "string" }, "interaction_watch_state": { "type": "boolean" }, "is_admin": { "type": "boolean" }, "is_banned": { "type": "boolean" }, "is_discouraged": { "type": "boolean" }, "is_followed": { "type": "boolean", "description": "True if the visitor is following this user. Only included if visitor is not a guest." }, "is_ignored": { "type": "boolean", "description": "True if the visitor is ignoring this user. Only included if visitor is not a guest." }, "is_moderator": { "type": "boolean" }, "is_super_admin": { "type": "boolean" }, "last_activity": { "type": "integer", "description": "Unix timestamp of user's last activity, if available." }, "location": { "type": "string" }, "push_on_conversation": { "type": "boolean" }, "push_optout": { "type": "array", "items": {} }, "receive_admin_email": { "type": "boolean" }, "secondary_group_ids": { "type": "array", "items": {} }, "show_dob_date": { "type": "boolean" }, "show_dob_year": { "type": "boolean" }, "signature": { "type": "string" }, "timezone": { "type": "string" }, "use_tfa": { "type": "boolean" }, "user_group_id": { "type": "integer" }, "user_state": { "type": "string" }, "user_title": { "type": "string" }, "visible": { "type": "boolean" }, "warning_points": { "type": "integer", "description": "Current warning points." }, "website": { "type": "string" }, "view_url": { "type": "string" }, "user_id": { "type": "integer" }, "username": { "type": "string" }, "message_count": { "type": "integer" }, "question_solution_count": { "type": "integer" }, "register_date": { "type": "integer" }, "trophy_points": { "type": "integer" }, "is_staff": { "type": "boolean" }, "reaction_score": { "type": "integer" }, "vote_score": { "type": "integer" } } }, "UserAlert": { "type": "object", "properties": { "alert_id": { "type": "integer" }, "alerted_user_id": { "type": "integer" }, "user_id": { "type": "integer" }, "username": { "type": "string" }, "content_type": { "type": "string" }, "content_id": { "type": "integer" }, "action": { "type": "string" }, "event_date": { "type": "integer" }, "view_date": { "type": "integer" }, "read_date": { "type": "integer" }, "auto_read": { "type": "boolean" }, "alert_text": { "type": "string" }, "alert_url": { "type": "string" }, "User": { "$ref": "#/components/schemas/User" } } }, "UserField": { "type": "object", "properties": { "field_id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "display_order": { "type": "integer" }, "field_type": { "type": "string" }, "field_choices": { "type": "object", "description": "For choice types, an ordered list of choices, with \"option\" and \"name\" keys for each." }, "match_type": { "type": "string" }, "match_params": { "type": "array", "items": {} }, "max_length": { "type": "integer" }, "required": { "type": "boolean" }, "display_group": { "type": "string", "description": "If this field type supports grouping, the group this field belongs to." } } }, "XFMG_Album": { "type": "object", "properties": { "username": { "type": "string" }, "Category": { "$ref": "#/components/schemas/XFMG_Category", "description": "If the album belongs to a category." }, "view_users": { "type": "array", "items": {}, "description": "If view privacy is \"shared\", the user IDs who can view." }, "add_users": { "type": "array", "items": {}, "description": "If add privacy is \"shared\", the user IDs who can add." }, "is_watching": { "type": "boolean", "description": "If accessing as a user, true if they are watching this album" }, "thumbnail_url": { "type": "string" }, "can_add": { "type": "boolean" }, "can_edit": { "type": "boolean" }, "can_soft_delete": { "type": "boolean" }, "can_hard_delete": { "type": "boolean" }, "can_react": { "type": "boolean" }, "view_url": { "type": "string" }, "is_reacted_to": { "type": "boolean", "description": "True if the viewing user has reacted to this content" }, "visitor_reaction_id": { "type": "integer", "description": "If the viewer reacted, the ID of the reaction they used" }, "album_id": { "type": "integer" }, "category_id": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": "string" }, "create_date": { "type": "integer" }, "last_update_date": { "type": "integer" }, "view_privacy": { "type": "string" }, "add_privacy": { "type": "string" }, "album_state": { "type": "string" }, "user_id": { "type": "integer" }, "media_count": { "type": "integer" }, "view_count": { "type": "integer" }, "warning_message": { "type": "string" }, "last_comment_date": { "type": "integer" }, "last_comment_id": { "type": "integer" }, "last_comment_user_id": { "type": "integer" }, "last_comment_username": { "type": "string" }, "comment_count": { "type": "integer" }, "rating_count": { "type": "integer" }, "rating_avg": { "type": "number" }, "rating_weighted": { "type": "number" }, "reaction_score": { "type": "integer" }, "User": { "$ref": "#/components/schemas/User" } } }, "XFMG_Category": { "type": "object", "properties": { "custom_fields": { "type": "array", "items": {}, "description": "Custom field definitions available in this category" }, "can_add": { "type": "boolean" }, "view_url": { "type": "string" }, "category_id": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": "string" }, "category_type": { "type": "string" }, "media_count": { "type": "integer" }, "album_count": { "type": "integer" }, "comment_count": { "type": "integer" }, "allowed_types": { "type": "array", "items": {} }, "min_tags": { "type": "integer" }, "category_index_limit": { "type": "integer" }, "parent_category_id": { "type": "integer" }, "display_order": { "type": "integer" } } }, "XFMG_Comment": { "type": "object", "properties": { "username": { "type": "string" }, "Media": { "$ref": "#/components/schemas/XFMG_MediaItem", "description": "If requested by context, the media item this comment belongs to." }, "Album": { "$ref": "#/components/schemas/XFMG_Album", "description": "If requested by context, the album this comment belongs to." }, "message_parsed": { "type": "string", "description": "HTML parsed version of the message contents." }, "can_edit": { "type": "boolean" }, "can_soft_delete": { "type": "boolean" }, "can_hard_delete": { "type": "boolean" }, "can_react": { "type": "boolean" }, "view_url": { "type": "string" }, "is_reacted_to": { "type": "boolean", "description": "True if the viewing user has reacted to this content" }, "visitor_reaction_id": { "type": "integer", "description": "If the viewer reacted, the ID of the reaction they used" }, "comment_id": { "type": "integer" }, "content_id": { "type": "integer" }, "content_type": { "type": "string" }, "message": { "type": "string" }, "user_id": { "type": "integer" }, "comment_date": { "type": "integer" }, "comment_state": { "type": "string" }, "warning_message": { "type": "string" }, "last_edit_date": { "type": "integer" }, "reaction_score": { "type": "integer" }, "User": { "$ref": "#/components/schemas/User" } } }, "XFMG_MediaField": { "type": "object", "properties": { "field_id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "display_order": { "type": "integer" }, "field_type": { "type": "string" }, "field_choices": { "type": "object", "description": "For choice types, an ordered list of choices, with \"option\" and \"name\" keys for each." }, "match_type": { "type": "string" }, "match_params": { "type": "array", "items": {} }, "max_length": { "type": "integer" }, "required": { "type": "boolean" }, "display_group": { "type": "string", "description": "If this field type supports grouping, the group this field belongs to." } } }, "XFMG_MediaItem": { "type": "object", "properties": { "username": { "type": "string" }, "Category": { "$ref": "#/components/schemas/XFMG_Category", "description": "If requested by context, the category this media belongs to." }, "Album": { "$ref": "#/components/schemas/XFMG_Album", "description": "If requested by context, the album this media belongs to." }, "media_embed_url": { "type": "string", "description": "If media type is embed, the embed URL." }, "media_url": { "type": "string", "description": "If media type is image, audio, or video, the URL to the media data." }, "file_size": { "type": "integer", "description": "If media type is not embed, the file size in bytes." }, "height": { "type": "integer", "description": "If media type is not embed, the height of the media." }, "width": { "type": "integer", "description": "If media type is not embed, the width of the media." }, "custom_fields": { "type": "object", "description": "Key-value pairs of custom field values for this media item" }, "tags": { "type": "array", "items": {} }, "is_watching": { "type": "boolean", "description": "If accessing as a user, true if they are watching this media item" }, "thumbnail_url": { "type": "string" }, "can_edit": { "type": "boolean" }, "can_edit_tags": { "type": "boolean" }, "can_soft_delete": { "type": "boolean" }, "can_hard_delete": { "type": "boolean" }, "can_react": { "type": "boolean" }, "view_url": { "type": "string" }, "is_reacted_to": { "type": "boolean", "description": "True if the viewing user has reacted to this content" }, "visitor_reaction_id": { "type": "integer", "description": "If the viewer reacted, the ID of the reaction they used" }, "media_id": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": "string" }, "media_date": { "type": "integer" }, "last_edit_date": { "type": "integer" }, "media_type": { "type": "string" }, "media_state": { "type": "string" }, "album_id": { "type": "integer" }, "album_state": { "type": "string" }, "category_id": { "type": "integer" }, "user_id": { "type": "integer" }, "view_count": { "type": "integer" }, "warning_message": { "type": "string" }, "last_comment_date": { "type": "integer" }, "last_comment_id": { "type": "integer" }, "last_comment_user_id": { "type": "integer" }, "last_comment_username": { "type": "string" }, "comment_count": { "type": "integer" }, "rating_count": { "type": "integer" }, "rating_avg": { "type": "number" }, "rating_weighted": { "type": "number" }, "reaction_score": { "type": "integer" }, "featured": { "type": "boolean" }, "User": { "$ref": "#/components/schemas/User" } } }, "XFRM_Category": { "type": "object", "properties": { "prefixes": { "type": "array", "items": { "$ref": "#/components/schemas/XFRM_ResourcePrefix" } }, "custom_fields": { "type": "array", "items": { "type": "object" } }, "can_add": { "type": "boolean" }, "can_upload_images": { "type": "boolean" }, "view_url": { "type": "string" }, "resource_category_id": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": "string" }, "resource_count": { "type": "integer" }, "last_update": { "type": "integer" }, "last_resource_title": { "type": "string" }, "last_resource_id": { "type": "integer" }, "allow_local": { "type": "boolean" }, "allow_external": { "type": "boolean" }, "allow_commercial_external": { "type": "boolean" }, "allow_fileless": { "type": "boolean" }, "min_tags": { "type": "integer" }, "enable_versioning": { "type": "boolean" }, "enable_support_url": { "type": "boolean" }, "parent_category_id": { "type": "integer" }, "display_order": { "type": "integer" } } }, "XFRM_ResourceField": { "type": "object", "properties": { "field_id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "display_order": { "type": "integer" }, "field_type": { "type": "string" }, "field_choices": { "type": "object", "description": "For choice types, an ordered list of choices, with \"option\" and \"name\" keys for each." }, "match_type": { "type": "string" }, "match_params": { "type": "array", "items": {} }, "max_length": { "type": "integer" }, "required": { "type": "boolean" }, "display_group": { "type": "string", "description": "If this field type supports grouping, the group this field belongs to." } } }, "XFRM_ResourceItem": { "type": "object", "properties": { "username": { "type": "string" }, "description": { "type": "string" }, "description_parsed": { "type": "string", "description": "HTML parsed version of the description" }, "description_attach_count": { "type": "integer" }, "DescriptionAttachments": { "type": "array", "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Attachments to the description, if any" }, "reaction_score": { "type": "integer" }, "update_count": { "type": "integer" }, "review_count": { "type": "integer" }, "current_download_url": { "type": "string", "description": "For downloadable resources with an external download URL" }, "current_files": { "type": "array", "items": { "type": "object" }, "description": "For downloadable resources with local files" }, "external_purchase_url": { "type": "string", "description": "For externally purchasable resources" }, "is_watching": { "type": "boolean", "description": "If visitor is logged in" }, "icon_url": { "type": "string", "description": "If resource icons are enabled" }, "version": { "type": "string", "description": "Current version string, if the resource is versioned" }, "custom_fields": { "type": "object", "description": "Key-value pairs of custom field values" }, "tags": { "type": "array", "items": { "type": "string" } }, "prefix": { "type": "string", "description": "Rendered prefix title, if a prefix is set" }, "can_edit": { "type": "boolean" }, "can_edit_tags": { "type": "boolean" }, "can_edit_icon": { "type": "boolean" }, "can_soft_delete": { "type": "boolean" }, "can_hard_delete": { "type": "boolean" }, "can_download": { "type": "boolean" }, "can_view_description_attachments": { "type": "boolean" }, "view_url": { "type": "string" }, "resource_id": { "type": "integer" }, "title": { "type": "string" }, "tag_line": { "type": "string" }, "user_id": { "type": "integer" }, "resource_state": { "type": "string" }, "resource_type": { "type": "string" }, "resource_date": { "type": "integer" }, "resource_category_id": { "type": "integer" }, "external_url": { "type": "string" }, "price": { "type": "number" }, "currency": { "type": "string" }, "view_count": { "type": "integer" }, "download_count": { "type": "integer" }, "rating_count": { "type": "integer" }, "rating_avg": { "type": "number" }, "rating_weighted": { "type": "number" }, "last_update": { "type": "integer" }, "alt_support_url": { "type": "string" }, "prefix_id": { "type": "integer" }, "featured": { "type": "boolean" }, "Category": { "$ref": "#/components/schemas/XFRM_Category" }, "User": { "$ref": "#/components/schemas/User" } } }, "XFRM_ResourcePrefix": { "type": "object", "properties": { "prefix_id": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": "string" }, "usage_help": { "type": "string" }, "is_usable": { "type": "boolean", "description": "True if the acting user can use (select) this prefix." }, "prefix_group_id": { "type": "integer" }, "display_order": { "type": "integer" }, "materialized_order": { "type": "integer", "description": "Effective order, taking group ordering into account." } } }, "XFRM_ResourceRating": { "type": "object", "properties": { "Resource": { "$ref": "#/components/schemas/XFRM_ResourceItem", "description": "Conditionally included based on request context" }, "custom_fields": { "type": "object", "description": "Key-value pairs of review custom field values" }, "can_soft_delete": { "type": "boolean" }, "can_hard_delete": { "type": "boolean" }, "can_author_reply": { "type": "boolean" }, "AnonymousUser": { "$ref": "#/components/schemas/User", "description": "If anonymous and viewer has permission to see the author" }, "anonymous_user_id": { "type": "integer", "description": "If anonymous and viewer has permission to see the author" }, "User": { "$ref": "#/components/schemas/User", "description": "If not anonymous" }, "view_url": { "type": "string", "description": "Only included for reviews (not ratings)" }, "resource_rating_id": { "type": "integer" }, "resource_id": { "type": "integer" }, "resource_version_id": { "type": "integer" }, "rating": { "type": "integer" }, "rating_date": { "type": "integer" }, "message": { "type": "string" }, "version_string": { "type": "string" }, "author_response": { "type": "string" }, "rating_state": { "type": "string" }, "is_anonymous": { "type": "boolean" } } }, "XFRM_ResourceReviewField": { "type": "object", "properties": { "field_id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "display_order": { "type": "integer" }, "field_type": { "type": "string" }, "field_choices": { "type": "object", "description": "For choice types, an ordered list of choices, with \"option\" and \"name\" keys for each." }, "match_type": { "type": "string" }, "match_params": { "type": "array", "items": {} }, "max_length": { "type": "integer" }, "required": { "type": "boolean" }, "display_group": { "type": "string", "description": "If this field type supports grouping, the group this field belongs to." } } }, "XFRM_ResourceUpdate": { "type": "object", "properties": { "Resource": { "$ref": "#/components/schemas/XFRM_ResourceItem", "description": "Conditionally included based on request context" }, "Attachments": { "type": "array", "items": { "$ref": "#/components/schemas/Attachment" }, "description": "If the update has attachments" }, "message_parsed": { "type": "string", "description": "HTML parsed version of the message" }, "can_edit": { "type": "boolean" }, "can_soft_delete": { "type": "boolean" }, "can_hard_delete": { "type": "boolean" }, "can_react": { "type": "boolean" }, "can_view_attachments": { "type": "boolean" }, "view_url": { "type": "string" }, "is_reacted_to": { "type": "boolean", "description": "True if the viewing user has reacted to this content" }, "visitor_reaction_id": { "type": "integer", "description": "If the viewer reacted, the ID of the reaction they used" }, "resource_update_id": { "type": "integer" }, "resource_id": { "type": "integer" }, "title": { "type": "string" }, "message": { "type": "string" }, "message_state": { "type": "string" }, "post_date": { "type": "integer" }, "attach_count": { "type": "integer" }, "warning_message": { "type": "string" }, "last_edit_date": { "type": "integer" }, "reaction_score": { "type": "integer" } } }, "XFRM_ResourceVersion": { "type": "object", "properties": { "Resource": { "$ref": "#/components/schemas/XFRM_ResourceItem", "description": "Conditionally included based on request context" }, "download_url": { "type": "string", "description": "For versions with an external download URL" }, "files": { "type": "array", "items": { "type": "object" }, "description": "For versions with local download files" }, "can_download": { "type": "boolean" }, "can_soft_delete": { "type": "boolean" }, "can_hard_delete": { "type": "boolean" }, "view_url": { "type": "string" }, "resource_version_id": { "type": "integer" }, "resource_id": { "type": "integer" }, "version_string": { "type": "string" }, "release_date": { "type": "integer" }, "download_count": { "type": "integer" }, "rating_count": { "type": "integer" }, "version_state": { "type": "string" } } } }, "responses": { "error": { "description": "Error", "headers": { "XF-Latest-Api-Version": { "$ref": "#/components/headers/XF-Latest-Api-Version" }, "XF-Used-Api-Version": { "$ref": "#/components/headers/XF-Used-Api-Version" }, "XF-Request-User": { "$ref": "#/components/headers/XF-Request-User" }, "XF-Request-User-Extras": { "$ref": "#/components/headers/XF-Request-User-Extras" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "params": { "type": "object", "additionalProperties": true } } } } } } } } } }, "parameters": { "XF-Api-User": { "name": "XF-Api-User", "in": "header", "description": "User ID to execute the request as. Requires a super user API key.", "schema": { "type": "integer" } }, "api_bypass_permissions": { "name": "api_bypass_permissions", "in": "query", "description": "Whether or not to bypass the context user permissions. Requires a super user API key.", "schema": { "type": "boolean" } } }, "headers": { "XF-Latest-Api-Version": { "description": "The latest API version available.", "schema": { "type": "integer" } }, "XF-Used-Api-Version": { "description": "The API version used to render the response.", "schema": { "type": "integer" } }, "XF-Request-User": { "description": "The user ID of the request user.", "schema": { "type": "integer" } }, "XF-Request-User-Extras": { "description": "Additional information about the request user in JSON encoding. Requires XF-Request-User header to be non-zero.", "schema": { "type": "string" } } }, "securitySchemes": { "XF-OAuth2": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://example.com/oauth2/authorize", "tokenUrl": "https://example.com/api/oauth2/token", "refreshUrl": "https://example.com/api/oauth2/token", "scopes": { "alert:read": "Covers viewing the active user's alerts. Also includes read/unread marking of these alerts.", "alert:write": "Covers creating custom user alerts. Applies to super-user keys only.", "attachment:delete": "Covers deleting attachments.", "attachment:read": "Covers viewing attachment data.", "attachment:write": "Covers uploading new attachments.", "conversation:read": "Covers viewing direct messages.", "conversation:write": "Covers creating or updating direct messages.", "feature:read": "Covers reading featured content.", "media:delete_hard": "Covers hard-deleting media, albums and their comments.", "media:read": "Covers viewing media, albums, and their comments.", "media:write": "Covers creating, updating and soft-deleting media, albums and their comments.", "media_category:delete": "Covers deleting a media category.", "media_category:read": "Covers view media categories or the list of categories.", "media_category:write": "Covers updating or creating a media category.", "node:delete": "Covers deleting a node.", "node:read": "Covers reading the list of nodes or an individual node.", "node:write": "Covers creating or updating a node. Node deletion is not included.", "profile_post:delete_hard": "Covers hard-deleting profile posts and profile post comments.", "profile_post:read": "Covers viewing profile posts and profile post comments.", "profile_post:write": "Covers creating, updating and soft-deleting profile posts and profile post comments.", "resource:delete_hard": "Covers hard-deleting resources.", "resource:read": "Covers viewing resources and their content.", "resource:write": "Covers creating, updating and soft-deleting resources and their content.", "resource_category:delete": "Covers deleting a resource category.", "resource_category:read": "Covers viewing resource categories or the list of categories.", "resource_category:write": "Covers updating or creating a resource category.", "resource_rating:delete_hard": "Covers hard-deleting resource ratings/reviews.", "resource_rating:read": "Covers viewing resource ratings/reviews.", "resource_rating:write": "Covers creating, updating and soft-deleting resource ratings/reviews.", "search:read": "Covers viewing searches.", "search:write": "Covers creating searches.", "thread:delete_hard": "Covers hard-deleting threads and posts.", "thread:read": "Covers reading thread and post information.", "thread:write": "Covers creating, updating and soft-deleting threads and posts.", "user:delete": "Covers deleting a user.", "user:read": "Covers reading user profile information. Note that some profile details may be returned with other data.", "user:write": "Covers updating user profile information." } } } }, "XF-Api-Key": { "type": "apiKey", "name": "XF-Api-Key", "in": "header" } } }, "tags": [ { "name": "Alerts" }, { "name": "Attachments" }, { "name": "Auth" }, { "name": "Conversations" }, { "name": "Featured content" }, { "name": "Forums" }, { "name": "Index" }, { "name": "Me" }, { "name": "Media" }, { "name": "Media albums" }, { "name": "Media categories" }, { "name": "Media comments" }, { "name": "Nodes" }, { "name": "OAuth2" }, { "name": "Posts" }, { "name": "Profile posts" }, { "name": "Resource categories" }, { "name": "Resource reviews" }, { "name": "Resource updates" }, { "name": "Resource versions" }, { "name": "Resources" }, { "name": "Search" }, { "name": "Search forums" }, { "name": "Stats" }, { "name": "Threads" }, { "name": "Users" }, { "name": "oEmbed" } ], "externalDocs": { "description": "XenForo API Documentation", "url": "https://docs.xenforo.com/api" } }