XenForo

https://docs.xenforo.com/
Admin
XenForo is a modern community platform featuring a comprehensive REST API for managing forums,...
Tokens:308,484
Snippets:2,298
Trust Score:10
Update:2 months ago
Show doc for...
Tokens:
Raw
### Implement a basic Setup class

Source: https://docs.xenforo.com/devs/add-on-structure

Create a Setup.php file in the add-on root that extends \XF\AddOn\AbstractSetup and defines install, upgrade, and uninstall logic.

```php
<?php  
  
namespace Demo;  
  
class Setup extends \XF\AddOn\AbstractSetup  
{  
	public function install(array $stepParams = [])  
	{  
		$this->schemaManager()->createTable('xf_demo', function(\XF\Db\Schema\Create $table)  
		{  
			$table->addColumn('demo_id', 'int');  
		});  
	}  
  
	public function upgrade(array $stepParams = [])  
	{  
		if ($this->addOn->version_id < 1000170)  
		{  
			$this->schemaManager()->alterTable('xf_demo', function(\XF\Db\Schema\Alter $table)  
			{  
				$table->addColumn('foo', 'varchar', 10)->setDefault('');  
			});  
		}  
	}  
  
	public function uninstall(array $stepParams = [])  
	{  
		$this->schemaManager()->dropTable('xf_demo');  
	}  
}
```

--------------------------------

### Run Setup steps

Source: https://docs.xenforo.com/devs/development-tools

Executes specific installation, upgrade, or uninstall steps for add-ons using StepRunner traits.

```bash
php cmd.php xf-addon:install-step [addon_id] [step]
```

```bash
php cmd.php xf-addon:upgrade-step [addon_id] [version] [step]
```

```bash
php cmd.php xf-addon:uninstall-step [addon_id] [step]
```

--------------------------------

### Define the Setup class skeleton

Source: https://docs.xenforo.com/devs/lets-build-an-add-on

Initial structure for the Setup class using StepRunner traits for installation, upgrade, and uninstallation.

```php
<?php  
  
namespace Demo\Portal;  
  
use XF\AddOn\AbstractSetup;  
use XF\AddOn\StepRunnerInstallTrait;  
use XF\AddOn\StepRunnerUninstallTrait;  
use XF\AddOn\StepRunnerUpgradeTrait;  
  
class Setup extends AbstractSetup  
{  
	use StepRunnerInstallTrait;  
	use StepRunnerUpgradeTrait;  
	use StepRunnerUninstallTrait;  
}  
```

--------------------------------

### Register Default Widgets in Setup Class

Source: https://docs.xenforo.com/devs/lets-build-an-add-on

Define an installation step to create and position default widgets for the portal sidebar.

```php
public function installStep4()  

{  

	$this->createWidget('demo_portal_view_members_online', 'members_online', [  

		'positions' => ['demo_portal_view_sidebar' => 10]  

	]);  

  

	$this->createWidget('demo_portal_view_new_posts', 'new_posts', [  

		'positions' => ['demo_portal_view_sidebar' => 20]  

	]);  

  

	$this->createWidget('demo_portal_view_new_profile_posts', 'new_profile_posts', [  

		'positions' => ['demo_portal_view_sidebar' => 30]  

	]);  

  

	$this->createWidget('demo_portal_view_forum_statistics', 'forum_statistics', [  

		'positions' => ['demo_portal_view_sidebar' => 40]  

	]);  

  

	$this->createWidget('demo_portal_view_share_page', 'share_page', [  

		'positions' => ['demo_portal_view_sidebar' => 50]  

	]);  

}  
```

--------------------------------

### Implement uninstall steps in Setup.php

Source: https://docs.xenforo.com/devs/lets-build-an-add-on

Define methods in the Setup class to drop columns and tables created during installation. These methods are executed automatically when the add-on is uninstalled.

```php
public function uninstallStep1()  

{  

	$this->schemaManager()->alterTable('xf_forum', function(Alter $table)  

	{  

		$table->dropColumns('demo_portal_auto_feature');  

	});  

}  

  

public function uninstallStep2()  

{  

	$this->schemaManager()->alterTable('xf_thread', function(Alter $table)  

	{  

		$table->dropColumns('demo_portal_featured');  

	});  

}  

  

public function uninstallStep3()  

{  

	$this->schemaManager()->dropTable('xf_demo_portal_featured_thread');  

}  
```

--------------------------------

### Switching Database Packages and Services

Source: https://docs.xenforo.com/devs/appendix/macos-dev

Commands to install and start either MariaDB or MySQL on macOS via Homebrew.

```bash
# install packages including MariaDB:  

brew install pkg-config mariadb httpd mailhog imagemagick elastic/tap/elasticsearch-full shivammathur/php/php@5.6 shivammathur/php/php@7.4 shivammathur/php/php@8.0;  

  

# install packages using MySQL instead:  

brew install pkg-config mysql httpd mailhog imagemagick elastic/tap/elasticsearch-full shivammathur/php/php@5.6 shivammathur/php/php@7.4 shivammathur/php/php@8.0;  

  

# start MariaDB service  

brew services start mariadb  

  

# start MySQL service instead  

brew services start mysql
```

--------------------------------

### Install Homebrew

Source: https://docs.xenforo.com/devs/appendix/macos-dev

Downloads and executes the Homebrew installation script via the terminal.

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)";  
```

--------------------------------

### Execute Installation Step via CLI

Source: https://docs.xenforo.com/devs/lets-build-an-add-on

Run the specific installation step to apply the widget configuration.

```bash
php cmd.php xf-addon:install-step Demo/Portal 4  
```

--------------------------------

### Execute installation steps via CLI

Source: https://docs.xenforo.com/devs/lets-build-an-add-on

Commands to manually trigger specific installation steps for the add-on.

```bash
php cmd.php xf-addon:install-step Demo/Portal 1  
```

```bash
php cmd.php xf-addon:install-step Demo/Portal 2  
```

```bash
php cmd.php xf-addon:install-step Demo/Portal 3  
```

--------------------------------

### Install XenForo via CLI

Source: https://docs.xenforo.com/devs

Executes the initial installation process for XenForo from the root directory.

```bash
php cmd.php xf:install
```

--------------------------------

### Install development packages via Homebrew

Source: https://docs.xenforo.com/devs/appendix/macos-dev

Installs PHP versions, Apache, MariaDB, ElasticSearch, MailHog, and ImageMagick. Requires adding specific taps before installation.

```bash
brew tap elastic/tap;  

brew tap shivammathur/php;  

brew install pkg-config mariadb httpd mailhog imagemagick elastic/tap/elasticsearch-full shivammathur/php/php@5.6 shivammathur/php/php@7.4 shivammathur/php/php@8.0;  
```

--------------------------------

### cURL request example

Source: https://docs.xenforo.com/api/get-oembed

Example command to fetch oEmbed data using cURL.

```bash
curl -L 'https://example.com/api/oembed/' \
-H 'Accept: application/json'
```

--------------------------------

### Install an add-on via CLI

Source: https://docs.xenforo.com/devs

Installs an available add-on after verifying file health.

```bash
php cmd.php xf:addon-install [addon_id]
```

--------------------------------

### Start development services via Homebrew

Source: https://docs.xenforo.com/devs/appendix/macos-dev

Commands to start Elasticsearch, PHP versions, and Apache HTTPD at system startup.

```bash
brew services start elasticsearch-full;  

brew services start php@5.6;  

brew services start php@7.4;  

brew services start php@8.0;  

brew services start httpd;  


```

--------------------------------

### CURL Request Example

Source: https://docs.xenforo.com/api/post-media-categories-id

Example of how to perform the POST request using cURL.

```bash
curl -L -X POST 'https://example.com/api/media-categories/:id/' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <token>'
```

--------------------------------

### Verify PHP installation

Source: https://docs.xenforo.com/devs/appendix/windows-dev

Check the installed PHP version and confirm the PATH configuration.

```bash
C:\Users\Kier>php -v  

PHP 7.2.19 (cli) (built: May 29 2019 13:58:59) ( ZTS MSVC15 (Visual C++ 2017) x64 )  

Copyright (c) 1997-2018 The PHP Group  

Zend Engine v3.2.0, Copyright (c) 1998-2018 Zend Technologies
```

--------------------------------

### Install PHP, Apache, and development tools

Source: https://docs.xenforo.com/devs/appendix/linux-dev

Installs multiple PHP versions, required modules, Apache, and database software. It is recommended to save this as a script and execute it with appropriate permissions.

```bash
#!/bin/bash  
  
# PHP stuff  
sudo apt install php5.6-fpm -y  
sudo apt install php7.4-fpm -y  
sudo apt install php8.0-fpm -y  
sudo apt install php-pear -y  
sudo apt install php-memcache -y  
  
# PHP modules  
for module in xdebug imagick gettext gd bcmath bz2 curl dba xml gmp intl ldap mbstring mysql odbc soap zip enchant sqlite3  
do  
    for version in 7.4 5.6 8.0  
    do  
        sudo apt install php${version}-${module} -y  
    done  
done  
  
# Apache web server  
sudo apt install apache2 -y  
# enable Apache FastCGI / FPM module  
sudo a2enmod proxy_fcgi  
  
# TablePlus (optional)  
sudo apt install tableplus -y  
  
# ElasticSearch (optional)  
sudo apt install elasticsearch -y  
  
# MariaDB (MySQL)  
sudo apt install mariadb-server -y  
```

--------------------------------

### GET /media/{id}/

Source: https://docs.xenforo.com/api/openapi.json

Get information about the specified media item.

```APIDOC
## GET /media/{id}/

### Description
Get information about the specified media item.

### Method
GET

### Endpoint
/media/{id}/

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the media item.

#### Query Parameters
- **with_comments** (boolean) - Optional - If specified, the response will include a page of comments.
- **page** (integer) - Optional - The page number for comments.
```

--------------------------------

### CURL Request Example

Source: https://docs.xenforo.com/api/get-media-categories-flattened

Example command to fetch flattened media categories using a Bearer token.

```bash
curl -L 'https://example.com/api/media-categories/flattened' \
-H 'Authorization: Bearer <token>'
```

--------------------------------

### cURL Request Example

Source: https://docs.xenforo.com/api/get-oauth-2-token

Example command to retrieve token information using cURL.

```bash
curl -L 'https://example.com/api/oauth2/token' \
-H 'Accept: application/json'
```

--------------------------------

### GET /profile-post-comments/{id}/

Source: https://docs.xenforo.com/api/openapi.json

Get a profile post comment.

```APIDOC
## GET /profile-post-comments/{id}/

### Description
Get a profile post comment.

### Method
GET

### Endpoint
/profile-post-comments/{id}/

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the profile post comment to retrieve.

### Response
#### Success Response (200)
- **comment** (object) - The profile post comment object.
```

--------------------------------

### CURL Request Example

Source: https://docs.xenforo.com/api/get-resource-categories-flattened

Example command to fetch flattened resource categories using a Bearer token.

```bash
curl -L 'https://example.com/api/resource-categories/flattened' \
-H 'Authorization: Bearer <token>'
```

--------------------------------

### CURL Request Example

Source: https://docs.xenforo.com/api/get-resource-categories

Example command to retrieve resource categories using a Bearer token for authentication.

```bash
curl -L 'https://example.com/api/resource-categories/' \
-H 'Authorization: Bearer <token>'
```

--------------------------------

### Install development tools and services via terminal

Source: https://docs.xenforo.com/devs/appendix/macos-dev

Executes the installation of Xcode command line tools, Homebrew, PHP versions, and necessary services like MariaDB and Elasticsearch.

```bash
#!/bin/bash  
  
# install macOS command line development tools  
sudo xcode-select --install;  
  
# install homebrew  
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)";  
  
# additional homebrew package sources  
brew tap elastic/tap;
brew tap shivammathur/php;  
  
# install homebrew packages  
brew install pkg-config mariadb httpd mailhog imagemagick elastic/tap/elasticsearch-full;  
  
# install php 5.6  
brew install shivammathur/php/php@5.6;
pecl install xdebug-2.5.5;
printf "\n" | pecl install imagick;  
  
# install php 7.4  
brew install shivammathur/php/php@7.4;
pecl install xdebug;
printf "\n" | pecl install imagick;  
  
# install php 8.0  
brew install shivammathur/php/php@8.0;
pecl install xdebug;
# this command fails with PHP 8.0 at the time of writing  
printf "\n" | pecl install imagick;  
  
# start and setup mariadb  
brew services start mariadb;
sudo /usr/local/bin/mysql_upgrade;
sudo /usr/local/bin/mysql_secure_installation;  
  
#  
# Edit config files for Apache and PHP at this point,  
# see the 'Configuration summary' below  
#  
  
# start the rest of the services  
brew services start elasticsearch-full;
brew services start php@5.6;
brew services start php@7.4;
brew services start php@8.0;
brew services start httpd;
```

--------------------------------

### cURL Request Example

Source: https://docs.xenforo.com/api/post-users-id-avatar

Example command to perform a POST request to update a user's avatar.

```bash
curl -L -X POST 'https://example.com/api/users/:id/avatar' \
-H 'Content-Type: multipart/form-data' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <token>'
```

--------------------------------

### cURL Request Example

Source: https://docs.xenforo.com/api/post-profile-post-comments-id

Example command to perform a POST request to the profile post comments endpoint.

```bash
curl -L -X POST 'https://example.com/api/profile-post-comments/:id/' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <token>'
```

--------------------------------

### CURL Request Example

Source: https://docs.xenforo.com/api/get-forums-id

Example command to retrieve forum data using a Bearer token for authentication.

```bash
curl -L 'https://example.com/api/forums/:id/' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <token>'
```

--------------------------------

### Implement installation step 3

Source: https://docs.xenforo.com/devs/lets-build-an-add-on

Creates a new table to log featured threads.

```php
public function installStep3()  
{  
    $this->schemaManager()->createTable('xf_demo_portal_featured_thread', function(Create $table)  
    {  
        $table->addColumn('thread_id', 'int');  
        $table->addColumn('featured_date', 'int');  
        $table->addPrimaryKey('thread_id');  
    });  
}  
```

--------------------------------

### Implement installation step 2

Source: https://docs.xenforo.com/devs/lets-build-an-add-on

Adds a new column to the xf_thread table to track featured status.

```php
public function installStep2()  
{  
    $this->schemaManager()->alterTable('xf_thread', function(Alter $table)  
    {  
        $table->addColumn('demo_portal_featured', 'tinyint')->setDefault(0);  
    });  
}  
```

--------------------------------

### CURL Request to API Index

Source: https://docs.xenforo.com/api/get-index

Example of how to perform a GET request to the API index endpoint using cURL with an OAuth2 bearer token.

```bash
curl -L 'https://example.com/api/index/' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <token>'
```

--------------------------------

### Get Profile Post Details Endpoint

Source: https://docs.xenforo.com/api/openapi.json

Defines the GET endpoint for retrieving profile post information, including optional comment pagination parameters.

```json
"/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",
```

--------------------------------

### GET /media/

Source: https://docs.xenforo.com/api/openapi.json

Retrieves a list of media items with optional filtering and sorting.

```APIDOC
## GET /media/

### Description
Get a list of media items.

### Method
GET

### Endpoint
/media/

### Parameters
#### Query Parameters
- **page** (integer) - Optional - The page number of results to retrieve.
- **media_type** (string) - Optional - Filters to only media of the specified type. Valid types: image, audio, video, embed.
- **user_id** (integer) - Optional - Filters to only media created by the specified user ID.
- **order** (string) - Optional - Method of ordering: media_date, comment_count, rating_weighted, reaction_score, view_count
```

--------------------------------

### GET /me/

Source: https://docs.xenforo.com/api/openapi.json

Retrieves information about the currently authenticated user.

```APIDOC
## GET /me/

### Description
Get information about the current user.

### Method
GET

### Endpoint
/me/

### Response
#### Success Response (200)
- **me** (User) - Information about the current user.

### Security
- XF-OAuth2
- XF-Api-Key
```

--------------------------------

### Invoke PHP method with xf:callback

Source: https://docs.xenforo.com/devs/template-basics

Use this tag to call a specific PHP class method from a template. Ensure the method name starts with a read-only prefix like get, render, is, or has.

```html
<xf:callback class="Demo\Template" method="renderStats" params="['sidebar']"></xf:callback>
```

--------------------------------

### Start and Upgrade MariaDB

Source: https://docs.xenforo.com/devs/appendix/macos-dev

Initializes the MariaDB service and runs the upgrade utility.

```bash
brew services start mariadb;  

sudo /usr/local/bin/mysql_upgrade;  

```

--------------------------------

### GET /resource-categories/

Source: https://docs.xenforo.com/api/openapi.json

Retrieves the full tree of resource categories.

```APIDOC
## GET /resource-categories/

### Description
Get the resource category tree.

### Method
GET

### Endpoint
/resource-categories/

### Parameters
#### Query Parameters
- **XF-Api-User** (reference) - Optional - API User context
- **api_bypass_permissions** (reference) - Optional - Bypass permission checks
```

--------------------------------

### GET /media-albums/{id}/

Source: https://docs.xenforo.com/api/openapi.json

Retrieve information about a specific media album by its ID.

```APIDOC
## GET /media-albums/{id}/

### Description
Get information about the specified album.

### Method
GET

### Endpoint
/media-albums/{id}/

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the media album.
```

--------------------------------

### GET /index/

Source: https://docs.xenforo.com/api/openapi.json

Retrieves general site and API information, including versioning and base URLs.

```APIDOC
## GET /index/

### Description
Get site and API information.

### Method
GET

### Endpoint
/index/

### Response
#### Success Response (200)
- **version_id** (integer) - XenForo version ID
- **site_title** (string) - Title of the site this API relates to
- **base_url** (string) - The base URL of the XenForo install this API relates to
- **api_url** (string) - The base API URL
- **key[type]** (string) - The type of API key used
```

--------------------------------

### GET /resource-versions/{id}/

Source: https://docs.xenforo.com/api/openapi.json

Retrieves detailed information about a specific resource version by its ID.

```APIDOC
## GET /resource-versions/{id}/

### Description
Get information about the specified resource version.

### Method
GET

### Endpoint
/resource-versions/{id}/

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the resource version to retrieve.

### Response
#### Success Response (200)
- **OK** - Returns resource version details.
```

--------------------------------

### GET /media-categories/

Source: https://docs.xenforo.com/api/openapi.json

Retrieves the full tree structure of media categories.

```APIDOC
## GET /media-categories/

### Description
Get the media category tree.

### Method
GET

### Endpoint
/media-categories/

### Response
#### Success Response (200)
- **OK** - The media category tree was retrieved successfully.
```

--------------------------------

### GET /resource-reviews/{id}/

Source: https://docs.xenforo.com/api/openapi.json

Retrieves detailed information about a specific resource review by its ID.

```APIDOC
## GET /resource-reviews/{id}/

### Description
Get information about the specified review.

### Method
GET

### Endpoint
/resource-reviews/{id}/

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the review to retrieve.

### Response
#### Success Response (200)
- **review** (object) - The review object containing details about the resource rating.
```

--------------------------------

### Implement installation step 1

Source: https://docs.xenforo.com/devs/lets-build-an-add-on

Adds a new column to the xf_forum table using the schema manager.

```php
<?php  
  
namespace Demo\Portal;  
  
use XF\AddOn\AbstractSetup;  
use XF\AddOn\StepRunnerInstallTrait;  
use XF\AddOn\StepRunnerUninstallTrait;  
use XF\AddOn\StepRunnerUpgradeTrait;  
  
use XF\Db\Schema\Alter;  
use XF\Db\Schema\Create;  
  
class Setup extends \XF\AddOn\AbstractSetup  
{  
	use StepRunnerInstallTrait;  
	use StepRunnerUpgradeTrait;  
	use StepRunnerUninstallTrait;  
  
	public function installStep1()  
	{  
		$this->schemaManager()->alterTable('xf_forum', function(Alter $table)  
		{  
			$table->addColumn('demo_portal_auto_feature', 'tinyint')->setDefault(0);  
		});  
	}  
}  
```

--------------------------------

### GET /resources/{id}/

Source: https://docs.xenforo.com/api/openapi.json

Retrieves detailed information about a specific resource identified by its ID.

```APIDOC
## GET /resources/{id}/

### Description
Get information about the specified resource.

### Method
GET

### Endpoint
/resources/{id}/

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the resource.
```

--------------------------------

### GET /media-albums/

Source: https://docs.xenforo.com/api/openapi.json

Retrieves a paginated list of media albums, with optional filtering by user and custom sorting.

```APIDOC
## GET /media-albums/

### Description
Get a list of albums.

### Method
GET

### Endpoint
/media-albums/

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Page number for pagination.
- **user_id** (integer) - Optional - Filters to only albums created by the specified user ID.
- **order** (string) - Optional - Method of ordering: create_date, media_count, comment_count, rating_weighted, reaction_score, view_count.
- **direction** (string) - Optional - Either "asc" or "desc" for ascending or descending. Applies only if an order is provided.

### Response
#### Success Response (200)
- **albums** (array) - List of media albums.
- **pagination** (object) - Pagination information.
```

--------------------------------

### GET /resources/

Source: https://docs.xenforo.com/api/openapi.json

Retrieves a list of resources based on optional filters such as page, prefix, type, creator, and ordering preferences.

```APIDOC
## GET /resources/

### Description
Get a list of resources.

### Method
GET

### Endpoint
/resources/

### Parameters
#### Query Parameters
- **page** (integer) - Optional - The page number of results to return.
- **prefix_id** (integer) - Optional - Filters to only resources with the specified prefix.
- **type** (string) - Optional - Filters to only resources of the specified type: free, paid.
- **creator_id** (integer) - Optional - Filters to only resources created by the specified user ID.
- **order** (string) - Optional - Method of ordering: last_update, resource_date, rating_weighted, download_count, title.
- **direction** (string) - Optional - Either "asc" or "desc" for ascending or descending. Applies only if an order is provided.

### Response
#### Success Response (200)
- **OK** - Returns a list of resources.
```

--------------------------------

### CURL Request Example

Source: https://docs.xenforo.com/api/post-conversations-id-star

Example command to star a conversation using cURL.

```bash
curl -L -X POST 'https://example.com/api/conversations/:id/star' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <token>'
```

--------------------------------

### GET /alerts/

Source: https://docs.xenforo.com/api/openapi.json

Retrieves a list of user alerts based on optional filtering parameters.

```APIDOC
## GET /alerts/

### Description
Get a list of user alerts.

### Method
GET

### Endpoint
/alerts/

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Page number
- **cutoff** (integer) - Optional - Unix timestamp of oldest alert to include. Note that unread or unviewed alerts are always included.
- **unviewed** (boolean) - Optional - If true, gets only unviewed alerts. Unviewed alerts have not been seen (in the standard UI).
- **unread** (boolean) - Optional - If true, gets only unread alerts. Unread alerts may have been seen but the content they relate to has not been viewed.

### Response
#### Success Response (200)
- **alerts** (array) - List of user alerts
- **pagination** (object) - Pagination information
```

--------------------------------

### GET /resources/{id}/reviews

Source: https://docs.xenforo.com/api/openapi.json

Retrieves a paginated list of reviews for a specific resource.

```APIDOC
## GET /resources/{id}/reviews

### Description
Get a page of reviews for the specified resource.

### Method
GET

### Endpoint
/resources/{id}/reviews

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the resource.

#### Query Parameters
- **page** (integer) - Optional - The page number of reviews to retrieve.

### Response
#### Success Response (200)
- **reviews** (array) - List of resource ratings.
- **pagination** (object) - Pagination information.
```

--------------------------------

### POST https://example.com/api/resources/

Source: https://docs.xenforo.com/api/post-resources

Creates a new resource in the system.

```APIDOC
## POST https://example.com/api/resources/

### Description
Create a resource.

### Method
POST

### Endpoint
https://example.com/api/resources/

### Parameters
#### Query Parameters
- **api_bypass_permissions** (boolean) - Optional - Whether or not to bypass the context user permissions. Requires a super user API key.

#### Header Parameters
- **XF-Api-User** (integer) - Optional - User ID to execute the request as. Requires a super user API key.

#### Request Body
- **resource_category_id** (integer) - Required - ID of the resource category.
- **title** (string) - Required - Title of the resource.
- **tag_line** (string) - Required - Tag line for the resource.
- **description** (string) - Required - Description of the resource.
- **resource_type** (string) - Required - Type of resource: download_local, download_external, external_purchase, fileless.
- **prefix_id** (integer) - Optional - ID of the prefix.
- **version_string** (string) - Optional - Version string.
- **custom_fields[<name>]** (string) - Optional - Custom fields.
- **tags** (string[]) - Optional - Array of tags.
- **external_url** (string) - Optional - External URL.
- **alt_support_url** (string) - Optional - Alternative support URL.
- **description_attachment_key** (string) - Optional - API attachment key for description images.
- **version_attachment_key** (string) - Optional - API attachment key for version file. Required for download_local type.
- **external_download_url** (string) - Optional - External download URL. Required for download_external type.
- **currency** (string) - Optional - Currency code. Required for external_purchase type.
- **external_purchase_url** (string) - Optional - Purchase URL. Required for external_purchase type.

### Request Example
{
  "resource_category_id": 0,
  "title": "string",
  "tag_line": "string",
  "description": "string",
  "resource_type": "string",
  "prefix_id": 0,
  "version_string": "string",
  "custom_fields[<name>]": "string",
  "tags": ["string"],
  "external_url": "string",
  "alt_support_url": "string",
  "description_attachment_key": "string",
  "version_attachment_key": "string",
  "external_download_url": "string",
  "currency": "string",
  "external_purchase_url": "string"
}
```

--------------------------------

### GET /featured/

Source: https://docs.xenforo.com/api/openapi.json

Retrieves a list of featured content, with optional filtering by page, content type, or user ID.

```APIDOC
## GET /featured/

### Description
Get a list of featured content.

### Method
GET

### Endpoint
/featured/

### Parameters
#### Query Parameters
- **page** (integer) - Optional - The page number of results to retrieve.
- **content_type** (string) - Optional - A content type to restrict results to.
- **user_id** (integer) - Optional - A user ID to restrict results to.

### Response
#### Success Response (200)
- **features** (array) - List of featured content items.
- **pagination** (object) - Pagination information for the results.
```

--------------------------------

### GET /stats/

Source: https://docs.xenforo.com/api/openapi.json

Retrieves general site statistics including total threads, messages, users, and online counts.

```APIDOC
## GET /stats/

### Description
Get site statistics.

### Method
GET

### Endpoint
/stats/

### Response
#### Success Response (200)
- **totals[threads]** (integer) - Total number of threads
- **totals[messages]** (integer) - Total number of messages
- **totals[users]** (integer) - Total number of users
- **latest_user[user_id]** (integer) - ID of the latest user
- **latest_user[username]** (string) - Username of the latest user
- **latest_user[register_date]** (integer) - Registration date of the latest user
- **online[total]** (integer) - Total number of users online
- **online[members]** (integer) - Number of members online
- **online[guests]** (integer) - Number of guests online
```

--------------------------------

### GET /profile-posts/{id}/

Source: https://docs.xenforo.com/api/openapi.json

Retrieves information about a specific profile post, with optional support for fetching comments.

```APIDOC
## GET /profile-posts/{id}/

### Description
Get information about the specified profile post.

### Method
GET

### Endpoint
/profile-posts/{id}/

### Parameters
#### Query Parameters
- **with_comments** (boolean) - Optional - If specified, the response will include a page of comments.
- **page** (integer) - Optional - The page of comments to include
- **direction** (string) - Optional - Request a particular sort order for comments - default 'desc' (newest first) also allows 'asc' (oldest first)

### Response
#### Success Response (200)
- **profile_post** (object) - The profile post object
- **comments** (array) - List of comments on the requested page
- **pagination** (object) - Pagination details
```

--------------------------------

### cURL Request Example

Source: https://docs.xenforo.com/api/post-conversations-id-mark-read

Example command to mark a conversation as read using cURL.

```bash
curl -L -X POST 'https://example.com/api/conversations/:id/mark-read' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <token>'
```

--------------------------------

### POST https://example.com/api/resource-versions/

Source: https://docs.xenforo.com/api/post-resource-versions

Create a new version of a resource.

```APIDOC
## POST https://example.com/api/resource-versions/

### Description
Create a new version of a resource.

### Method
POST

### Endpoint
https://example.com/api/resource-versions/

### Parameters
#### Query Parameters
- **api_bypass_permissions** (boolean) - Optional - Whether or not to bypass the context user permissions. Requires a super user API key.

#### Header Parameters
- **XF-Api-User** (integer) - Optional - User ID to execute the request as. Requires a super user API key.

#### Request Body
- **resource_id** (integer) - Required - The ID of the resource.
- **version_string** (string) - Optional - The version string.
- **version_type** (string) - Optional - Type of version download: local or external. Defaults based on current resource type.
- **version_attachment_key** (string) - Optional - API attachment key for local download files. Required if version_type is local.
- **external_download_url** (string) - Optional - Required if version_type is external.
- **currency** (string) - Optional - For externally purchasable resources.
- **external_purchase_url** (string) - Optional - For externally purchasable resources.

### Request Example
{
  "resource_id": 0,
  "version_string": "string",
  "version_type": "string",
  "version_attachment_key": "string",
  "external_download_url": "string",
  "currency": "string",
  "external_purchase_url": "string"
}

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **version** (object) - The created version object.
- **Resource** (object) - The associated resource object.
```

--------------------------------

### GET /posts/{id}/

Source: https://docs.xenforo.com/api/openapi.json

Retrieves detailed information about a specific post identified by its ID.

```APIDOC
## GET /posts/{id}/

### Description
Get information about the specified post.

### Method
GET

### Endpoint
/posts/{id}/

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the post to retrieve.

### Response
#### Success Response (200)
- **post** (object) - The post object containing detailed information.
```

--------------------------------

### GET /media/{id}/data

Source: https://docs.xenforo.com/api/openapi.json

Retrieves the file data for a specific media item.

```APIDOC
## GET /media/{id}/data

### Description
Get a media item file.

### Method
GET

### Endpoint
/media/{id}/data

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the media item.
```

--------------------------------

### GET /nodes/{id}/

Source: https://docs.xenforo.com/api/openapi.json

Retrieves information about a specific node by its ID.

```APIDOC
## GET /nodes/{id}/

### Description
Get information about the specified node.

### Method
GET

### Endpoint
/nodes/{id}/

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the node to retrieve.
```

--------------------------------

### GET /users/{id}/

Source: https://docs.xenforo.com/api/openapi.json

Retrieves detailed information about a specific user identified by their ID.

```APIDOC
## GET /users/{id}/

### Description
Get information about the specified user.

### Method
GET

### Endpoint
/users/{id}/

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the user.

#### Query Parameters
- **with_posts** (boolean) - Optional - If specified, the response will include a page of profile posts.
```

--------------------------------

### CURL Request Example

Source: https://docs.xenforo.com/api/get-conversations-id

Example command to retrieve a conversation by ID using cURL.

```bash
curl -L 'https://example.com/api/conversations/:id/' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <token>'
```

--------------------------------

### Create a new add-on

Source: https://docs.xenforo.com/devs/development-tools

Initializes a new add-on structure and generates the addon.json file.

```bash
php cmd.php xf-addon:create
```

--------------------------------

### GET /users/{id}

Source: https://docs.xenforo.com/api/openapi.json

Retrieves profile posts for a specific user, including pagination details.

```APIDOC
## GET /users/{id}

### Description
Retrieves a list of profile posts for the specified user. Supports pagination via query parameters.

### Method
GET

### Endpoint
/users/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the user.

#### Query Parameters
- **page** (integer) - Optional - The page of comments to include.

### Response
#### Success Response (200)
- **user** (object) - The user object.
- **profile_posts** (array) - List of profile posts on the requested page.
- **pagination** (object) - Pagination details.
```

--------------------------------

### GET /attachments/{id}/data

Source: https://docs.xenforo.com/api/openapi.json

Retrieves the raw binary data for a specified attachment.

```APIDOC
## GET /attachments/{id}/data

### Description
Get the data that makes up the specified attachment. The output is the raw binary data.

### Method
GET

### Endpoint
/attachments/{id}/data

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the attachment.
```

--------------------------------

### GET /nodes/

Source: https://docs.xenforo.com/api/openapi.json

Retrieves the full node tree, including a mapping of parent IDs to child IDs and a list of all nodes.

```APIDOC
## GET /nodes/

### Description
Get the node tree.

### Method
GET

### Endpoint
/nodes/

### Response
#### Success Response (200)
- **tree_map** (array) - A mapping that connects node parent IDs to a list of their child node IDs
- **nodes** (array) - List of all nodes
```

--------------------------------

### POST https://example.com/api/users/

Source: https://docs.xenforo.com/api/post-users

Creates a new user account with the specified profile, privacy, and account configuration settings.

```APIDOC
## POST https://example.com/api/users/

### Description
Create a new user in the system.

### Method
POST

### Endpoint
https://example.com/api/users/

### Parameters
#### Query Parameters
- **api_bypass_permissions** (boolean) - Optional - Whether or not to bypass the context user permissions. Requires a super user API key.

#### Header Parameters
- **XF-Api-User** (integer) - Optional - User ID to execute the request as. Requires a super user API key.

#### Request Body
- **option[creation_watch_state]** (string) - Optional
- **option[interaction_watch_state]** (string) - Optional
- **option[content_show_signature]** (boolean) - Optional
- **option[email_on_conversation]** (boolean) - Optional
- **option[push_on_conversation]** (boolean) - Optional
- **option[receive_admin_email]** (boolean) - Optional
- **option[show_dob_year]** (boolean) - Optional
- **option[show_dob_date]** (boolean) - Optional
- **profile[location]** (string) - Optional
- **profile[website]** (string) - Optional
- **profile[about]** (string) - Optional
- **profile[signature]** (string) - Optional
- **privacy[allow_view_profile]** (string) - Optional
- **privacy[allow_post_profile]** (string) - Optional
- **privacy[allow_receive_news_feed]** (string) - Optional
- **privacy[allow_send_personal_conversation]** (string) - Optional
- **privacy[allow_view_identities]** (string) - Optional
- **visible** (boolean) - Optional
- **activity_visible** (boolean) - Optional
- **timezone** (string) - Optional
- **custom_title** (string) - Optional
- **option[is_discouraged]** (boolean) - Optional
- **username** (string) - Optional
- **email** (string) - Optional
- **user_group_id** (integer) - Optional
- **secondary_group_ids** (integer[]) - Optional
- **user_state** (string) - Optional
- **is_staff** (boolean) - Optional
- **message_count** (integer) - Optional
- **reaction_score** (integer) - Optional
- **trophy_points** (integer) - Optional
- **username_change_visible** (boolean) - Optional - If true and the username is changed, the change will be visible.
- **password** (string) - Optional
- **dob[day]** (integer) - Optional
- **dob[month]** (integer) - Optional
- **dob[year]** (integer) - Optional
- **custom_fields[<name>]** (string) - Optional

### Request Example
{
  "username": "example_user",
  "email": "user@example.com",
  "password": "securepassword"
}
```

--------------------------------

### Attachments response schema example

Source: https://docs.xenforo.com/api/get-attachments

Example JSON structure for a successful attachments response.

```json
{
  "attachments": [
    {
      "filename": "string",
      "file_size": 0,
      "height": 0,
      "width": 0,
      "thumbnail_url": "string",
      "retina_thumbnail_url": "string",
      "direct_url": "string",
      "is_video": true,
      "is_audio": true,
      "attachment_id": 0,
      "content_type": "string",
      "content_id": 0,
      "attach_date": 0,
      "view_count": 0
    }
  ]
}
```

--------------------------------

### GET /media/albums/{id}

Source: https://docs.xenforo.com/api/openapi.json

Retrieves details for a specific album, including optional media items and comments based on query parameters.

```APIDOC
## GET /media/albums/{id}

### Description
Retrieves the details of a specific album by its ID. Optionally includes paginated media items or comments in the response.

### Method
GET

### Endpoint
/media/albums/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the album.

#### Query Parameters
- **with_media** (boolean) - Optional - If specified, the response will include a page of media.
- **with_comments** (boolean) - Optional - If specified, the response will include a page of comments.
- **page** (integer) - Optional - Page number for media pagination.
- **comment_page** (integer) - Optional - Page number for comment pagination.

### Response
#### Success Response (200)
- **album** (object) - The album details.
- **media** (array) - Included when with_media is specified.
- **media_pagination** (object) - Included when with_media is specified.
- **comments** (array) - Included when with_comments is specified.
- **comment_pagination** (object) - Included when with_comments is specified.
```

--------------------------------

### POST https://example.com/api/nodes/

Source: https://docs.xenforo.com/api/post-nodes

Create a new node in the system.

```APIDOC
## POST https://example.com/api/nodes/

### Description
Create a new node.

### Method
POST

### Endpoint
https://example.com/api/nodes/

### Parameters
#### Query Parameters
- **api_bypass_permissions** (boolean) - Optional - Whether or not to bypass the context user permissions. Requires a super user API key.

#### Header Parameters
- **XF-Api-User** (integer) - Optional - User ID to execute the request as. Requires a super user API key.

#### Request Body
- **node[title]** (string) - Required - The title of the node.
- **node[node_name]** (string) - Optional - The name of the node.
- **node[description]** (string) - Optional - The description of the node.
- **node[parent_node_id]** (integer) - Required - The ID of the parent node.
- **node[display_order]** (integer) - Optional - The display order of the node.
- **node[display_in_list]** (boolean) - Optional - Whether to display the node in the list.
- **type_data** (array) - Optional - Type-specific node data.
- **node_type_id** (string) - Required - The type ID of the node.

### Request Example
{
  "node[title]": "string",
  "node[node_name]": "string",
  "node[description]": "string",
  "node[parent_node_id]": 0,
  "node[display_order]": 0,
  "node[display_in_list]": true,
  "type_data": [null],
  "node_type_id": "string"
}

### Response
#### Success Response (200)
- **node** (object) - Information about the created node.
- **breadcrumbs** (array) - A list of breadcrumbs for this node.
- **type_data** (object) - Data related to the specific node type.
- **view_url** (string) - The URL to view the node.
- **node_id** (integer) - The ID of the created node.
- **title** (string) - The title of the node.
- **node_name** (string) - The name of the node.
- **description** (string) - The description of the node.
- **node_type_id** (string) - The type ID of the node.
- **parent_node_id** (integer) - The parent node ID.
- **display_order** (integer) - The display order.
- **display_in_list** (boolean) - Whether it is displayed in the list.

#### Response Example
{
  "node": {
    "breadcrumbs": [null],
    "type_data": {},
    "view_url": "string",
    "node_id": 0,
    "title": "string",
    "node_name": "string",
    "description": "string",
    "node_type_id": "string",
    "parent_node_id": 0,
    "display_order": 0,
    "display_in_list": true
  }
}
```

--------------------------------

### CURL Request Example

Source: https://docs.xenforo.com/api/get-attachments-id-data

Example command to fetch attachment data using cURL.

```bash
curl -L 'https://example.com/api/attachments/:id/data' \
-H 'Accept: */*' \
-H 'Authorization: Bearer <token>'
```
Tokens:
Raw