thegame_1980/xui-one-api-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
worldofiptvcom
2025-12-12 15:07:46 +03:00
commit 385ba5f309
12 changed files with 2626 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitattributes
+2
View File
@@ -0,0 +1,2 @@
# Auto detect text files and perform LF normalization
* text=auto
.gitignore
+78
View File
@@ -0,0 +1,78 @@
# Editor directories and files
.vscode/
.idea/
*.swp
*.swo
*~
.DS_Store
# OS files
Thumbs.db
Desktop.ini
# Logs
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
# Environment variables (IMPORTANT: Never commit credentials!)
.env
.env.local
.env.*.local
config.local.yaml
secrets.yaml
# Temporary files
tmp/
temp/
*.tmp
# API keys and credentials (IMPORTANT: Never commit these!)
**/api-keys.txt
**/credentials.json
**/secrets.json
# Build outputs
dist/
build/
out/
# Dependency directories
node_modules/
vendor/
# Test coverage
coverage/
.nyc_output/
# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
env/
venv/
ENV/
.venv
# Ruby
*.gem
*.rbc
/.config
/coverage/
/InstalledFiles
/pkg/
/spec/reports/
/test/tmp/
/test/version_tmp/
/tmp/
# PHP
/vendor/
composer.lock
# Documentation build
docs/_build/
site/
CONTRIBUTING.md
+331
View File
@@ -0,0 +1,331 @@
# Contributing to XUI.ONE API Documentation
Thank you for your interest in contributing! This documentation is community-driven and we welcome all contributions.
## 🎯 Ways to Contribute
- 🐛 **Report bugs** - Found incorrect information? Let us know!
- 📝 **Improve documentation** - Fix typos, clarify explanations
- 💡 **Add examples** - Share working code in different languages
- ✨ **Add new endpoints** - Document undocumented API actions
- 🔍 **Test and verify** - Test endpoints and confirm behavior
- 🌍 **Translations** - Help translate documentation
## 📋 Before You Start
1. **Check existing issues** - Someone might already be working on it
2. **Open an issue first** - For major changes, discuss before implementing
3. **Follow the style guide** - Keep documentation consistent
4. **Test your changes** - Verify all code examples work
## 🚀 Quick Start
### Fork and Clone
```bash
# Fork the repository on GitHub, then:
git clone https://github.com/YOUR_USERNAME/xui-one-api-docs.git
cd xui-one-api-docs
# Add upstream remote
git remote add upstream https://github.com/worldofiptvcom/xui-one-api-docs.git
```
### Create a Branch
```bash
# Create a new branch for your contribution
git checkout -b feature/add-streams-api-docs
# Or for bug fixes:
git checkout -b fix/correct-line-api-example
```
### Make Your Changes
Edit the relevant files following our [Style Guide](#style-guide).
### Test Your Changes
```bash
# For OpenAPI changes, validate the spec:
# 1. Open index.html in browser
# 2. Check for validation errors in Swagger UI
# For code examples, test them:
curl "http://your-server.com/cSbuFLhp/?api_key=YOUR_KEY&action=user_info"
```
### Commit Your Changes
```bash
git add .
git commit -m "Add Streams API documentation with examples"
# Use clear commit messages:
# ✅ "Add Python examples for Line API"
# ✅ "Fix typo in authentication guide"
# ✅ "Update get_lines endpoint parameters"
# ❌ "Update docs"
# ❌ "Fix stuff"
```
### Push and Create Pull Request
```bash
git push origin feature/add-streams-api-docs
```
Then open a Pull Request on GitHub with:
- Clear title describing the change
- Description of what was changed and why
- Screenshots if applicable
- Reference to any related issues
## 📝 Style Guide
### OpenAPI Specification
Follow OpenAPI 3.0.3 standards:
```yaml
paths:
/?action=example:
get:
summary: Brief one-line description
description: |
Detailed description with examples.
**Example Request:**
```bash
curl "http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=example"
```
operationId: uniqueOperationId
tags:
- CategoryName
parameters:
- $ref: '#/components/parameters/ApiKey'
- name: action
in: query
required: true
schema:
type: string
enum: [example]
```
### Markdown Documentation
- Use clear headers (h1 for title, h2 for sections, h3 for subsections)
- Include code examples for each operation
- Add response examples (both success and error)
- Use tables for parameter documentation
- Include emojis for visual appeal (but don't overuse)
### Code Examples
Always provide examples in multiple languages when possible:
#### cURL
```bash
curl "http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=example"
```
#### Python
```python
import requests
response = requests.get(
"http://your-server.com/cSbuFLhp/",
params={
"api_key": "8D3135D30437F86EAE2FA4A2A8345000",
"action": "example"
}
)
```
#### PHP
```php
<?php
$url = "http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=example";
$response = file_get_contents($url);
$data = json_decode($response, true);
?>
```
#### JavaScript
```javascript
const response = await fetch(
'http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=example'
);
const data = await response.json();
```
### Placeholder Values
Always use consistent placeholder values:
- **Server**: `your-server.com`
- **Access Code**: `cSbuFLhp`
- **API Key**: `8D3135D30437F86EAE2FA4A2A8345000`
- **IDs**: Use sequential numbers (123, 456, etc.)
- **Usernames**: `testuser`, `user123`, etc.
- **Passwords**: `testpass123`, `securepass`, etc.
### Security Considerations
- **Never** include real API keys, passwords, or server IPs
- Always mention security best practices
- Warn about sensitive operations
- Recommend HTTPS for production
## 🏗️ Project Structure
```
xui-one-api-docs/
├── openapi.yaml # Main OpenAPI specification
├── README.md # Project overview
├── LICENSE # License information
├── CONTRIBUTING.md # This file
├── .gitignore # Git ignore rules
├── index.html # Swagger UI viewer
├── docs/ # Detailed documentation
│ ├── getting-started.md # Setup guide
│ ├── authentication.md # Auth details
│ ├── categories/ # API by category
│ │ ├── 01-get-info.md
│ │ ├── 02-logs-events.md
│ │ ├── 03-line-api.md
│ │ └── ...
│ └── examples/ # Code examples
│ ├── curl-examples.md
│ ├── python-examples.md
│ ├── php-examples.md
│ └── javascript-examples.md
└── postman/ # Postman collection
└── XUI-ONE-API.postman_collection.json
```
## 📚 Documentation Categories
When adding new API endpoints, place them in the appropriate category:
1. **GET INFO** - Query operations (get_lines, get_users, etc.)
2. **Logs & Events** - Monitoring (activity_logs, live_connections)
3. **Line API** - Subscription management
4. **User API** - User management
5. **MAG API** - MAG device operations
6. **Enigma API** - Enigma2 STB operations
7. **Streams API** - Live stream management
8. **Channel API** - Channel operations
9. **Station API** - Radio station management
10. **Movie API** - VOD movie management
11. **Series API** - Series management
12. **Episode API** - Episode management
13. **Servers API** - Server and load balancer management
14. **Settings & System** - System configuration
## ✅ Pull Request Checklist
Before submitting your PR, ensure:
- [ ] Code examples are tested and working
- [ ] OpenAPI spec validates without errors
- [ ] Markdown is properly formatted
- [ ] No real credentials are included
- [ ] Commit messages are clear
- [ ] Branch is up to date with main
- [ ] Documentation follows style guide
- [ ] Changes are described in PR description
## 🧪 Testing
### Test OpenAPI Specification
1. Open `index.html` in a browser
2. Check for validation errors in Swagger UI
3. Verify examples render correctly
4. Test "Try it out" functionality with your credentials
### Test Code Examples
Test all code examples with a real XUI.ONE instance:
```bash
# Test cURL examples
bash docs/examples/test-curl.sh
# Test Python examples
python docs/examples/test-python.py
```
## 🐛 Reporting Issues
When reporting bugs or issues:
1. **Check existing issues first**
2. **Use the issue template**
3. **Provide details:**
- What you expected
- What actually happened
- Steps to reproduce
- XUI.ONE version
- API endpoint affected
4. **Include examples** (sanitize credentials!)
### Issue Template
```markdown
## Description
Brief description of the issue
## Expected Behavior
What should happen
## Actual Behavior
What actually happens
## Steps to Reproduce
1. Step one
2. Step two
3. Step three
## Environment
- XUI.ONE Version: 1.5.13
- Endpoint: /?action=get_lines
- Request Method: GET
## Additional Context
Any other relevant information
```
## 💬 Communication
- **GitHub Issues** - Bug reports and feature requests
- **GitHub Discussions** - Questions and general discussion
- **Pull Requests** - Code and documentation contributions
## 🏆 Recognition
Contributors will be:
- Listed in the project README
- Credited in release notes
- Appreciated by the community! 🙏
## 📄 License
By contributing, you agree that your contributions will be licensed under the MIT License (for documentation). See [LICENSE](LICENSE) file for details.
## ❓ Questions?
- Check the [README](README.md)
- Read the [Getting Started Guide](docs/getting-started.md)
- Open a [GitHub Discussion](https://github.com/worldofiptvcom/xui-one-api-docs/discussions)
- Ask in the [World of IPTV Forums](https://www.worldofiptv.com)
---
## 🙏 Thank You!
Thank you for contributing to make XUI.ONE API documentation better for everyone!
**Happy documenting! 📚✨**
DEPLOYMENT.md
+364
View File
@@ -0,0 +1,364 @@
# Deployment Guide
This guide explains how to upload the documentation to GitHub and deploy it online.
## Table of Contents
1. [Automatic Upload (Recommended)](#automatic-upload)
2. [Manual Upload](#manual-upload)
3. [Deploy to GitHub Pages](#deploy-to-github-pages)
4. [Alternative Hosting](#alternative-hosting)
---
## Automatic Upload (Recommended)
### Prerequisites
- Git installed on your system
- GitHub account credentials or Personal Access Token
### Steps
1. **Navigate to the project directory:**
```bash
cd /path/to/xui-one-api-docs
```
2. **Run the upload script:**
```bash
./upload-to-github.sh
```
3. **Follow the prompts:**
- Enter commit message (or press Enter for default)
- Provide GitHub credentials when prompted
4. **Done!** Your documentation is now on GitHub.
---
## Manual Upload
If you prefer manual control or the automatic script doesn't work:
### Step 1: Initialize Git
```bash
cd /path/to/xui-one-api-docs
git init
```
### Step 2: Add Remote
```bash
git remote add origin https://github.com/worldofiptvcom/xui-one-api-docs.git
```
### Step 3: Stage Files
```bash
git add .
```
### Step 4: Commit
```bash
git commit -m "Initial commit: Add XUI.ONE API documentation with authentication section"
```
### Step 5: Set Branch
```bash
git branch -M main
```
### Step 6: Push to GitHub
```bash
git push -u origin main
```
**Note:** You'll be prompted for GitHub credentials.
---
## Authentication Options
### Option 1: Personal Access Token (Recommended)
1. **Generate Token:**
- Go to GitHub: Settings → Developer settings → Personal access tokens → Tokens (classic)
- Click "Generate new token (classic)"
- Select scopes: `repo` (Full control of private repositories)
- Generate and copy the token
2. **Use Token:**
- When prompted for password, paste your token instead
### Option 2: GitHub CLI
```bash
# Install GitHub CLI
# macOS
brew install gh
# Linux
sudo apt install gh
# Windows
winget install --id GitHub.cli
# Authenticate
gh auth login
# Push repository
git push -u origin main
```
### Option 3: SSH Key
1. **Generate SSH Key:**
```bash
ssh-keygen -t ed25519 -C "your_email@example.com"
```
2. **Add to GitHub:**
- Copy public key: `cat ~/.ssh/id_ed25519.pub`
- Go to GitHub: Settings → SSH and GPG keys → New SSH key
- Paste and save
3. **Change Remote URL:**
```bash
git remote set-url origin git@github.com:worldofiptvcom/xui-one-api-docs.git
```
4. **Push:**
```bash
git push -u origin main
```
---
## Deploy to GitHub Pages
After uploading to GitHub, deploy the documentation website:
### Step 1: Enable GitHub Pages
1. Go to your repository on GitHub
2. Click **Settings** tab
3. Scroll to **Pages** section (left sidebar)
4. Under **Source**:
- Branch: `main`
- Folder: `/ (root)`
5. Click **Save**
### Step 2: Wait for Deployment
- GitHub will build your site (takes 1-2 minutes)
- Check the Actions tab to see deployment progress
### Step 3: Access Your Documentation
Your documentation will be available at:
```
https://worldofiptvcom.github.io/xui-one-api-docs/
```
Open `index.html` to view the interactive Swagger UI documentation.
### Custom Domain (Optional)
1. **Add CNAME file:**
```bash
echo "docs.yoursite.com" > CNAME
git add CNAME
git commit -m "Add custom domain"
git push
```
2. **Configure DNS:**
- Add CNAME record: `docs.yoursite.com` → `worldofiptvcom.github.io`
3. **Update GitHub Pages:**
- Settings → Pages → Custom domain
- Enter: `docs.yoursite.com`
- Save
---
## Alternative Hosting
### Netlify
1. **Connect Repository:**
- Go to https://netlify.com
- New site from Git
- Select your GitHub repository
2. **Build Settings:**
- Build command: (leave empty)
- Publish directory: `/`
3. **Deploy:**
- Click Deploy Site
- Done! Your site is live
### Vercel
1. **Import Project:**
- Go to https://vercel.com
- Import Git Repository
- Select your repository
2. **Deploy:**
- Click Deploy
- Done! Your site is live
### GitLab Pages
1. **Create `.gitlab-ci.yml`:**
```yaml
pages:
stage: deploy
script:
- mkdir .public
- cp -r * .public
- mv .public public
artifacts:
paths:
- public
only:
- main
```
2. **Push to GitLab:**
```bash
git remote add gitlab https://gitlab.com/yourusername/xui-one-api-docs.git
git push gitlab main
```
### Self-Hosted
1. **Copy Files to Web Server:**
```bash
scp -r xui-one-api-docs/* user@your-server.com:/var/www/html/docs/
```
2. **Configure Nginx:**
```nginx
server {
listen 80;
server_name docs.yoursite.com;
root /var/www/html/docs;
index index.html;
location / {
try_files $uri $uri/ =404;
}
}
```
3. **Restart Nginx:**
```bash
sudo systemctl restart nginx
```
---
## Updating Documentation
When you make changes:
```bash
# Stage changes
git add .
# Commit
git commit -m "Update: Add Streams API documentation"
# Push
git push origin main
```
GitHub Pages will automatically rebuild and deploy.
---
## Troubleshooting
### "Permission Denied" Error
**Solution:**
- Use Personal Access Token instead of password
- Or set up SSH key authentication
### "Repository Not Found" Error
**Solution:**
- Verify repository URL: `git remote -v`
- Ensure repository exists on GitHub
- Check you have access rights
### GitHub Pages Not Working
**Solution:**
- Verify Pages is enabled in repository settings
- Check Actions tab for deployment status
- Ensure `index.html` exists in repository root
- Wait a few minutes for initial deployment
### Changes Not Appearing
**Solution:**
- Clear browser cache
- Wait 1-2 minutes for GitHub Pages rebuild
- Check if git push was successful
---
## Viewing Locally
Before deploying, test locally:
```bash
# Using Python
python3 -m http.server 8000
# Using Node.js
npx http-server
# Using PHP
php -S localhost:8000
```
Then open: `http://localhost:8000/index.html`
---
## Support
- **GitHub Issues:** Report deployment problems
- **GitHub Discussions:** Ask deployment questions
- **World of IPTV:** Community support
---
**Need help?** Open an issue on GitHub with:
- What you tried
- Error messages
- Your operating system
- Screenshots if applicable
LICENSE
+21
View File
@@ -0,0 +1,21 @@
MIT License
Copyright (c) 2025 worldofiptvcom
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
README.md
+339
View File
@@ -0,0 +1,339 @@
# XUI.ONE Admin API Documentation
<div align="center">
![XUI.ONE](https://img.shields.io/badge/XUI.ONE-v1.5.13-blue)
![OpenAPI](https://img.shields.io/badge/OpenAPI-3.0.3-green)
![License](https://img.shields.io/badge/License-Proprietary-red)
**Complete API Documentation for XUI.ONE IPTV Panel Administration**
[View Documentation](#documentation) • [Quick Start](#quick-start) • [Examples](#examples) • [Contributing](#contributing)
</div>
---
## 📚 Overview
This repository contains comprehensive API documentation for **XUI.ONE**, a professional IPTV/OTT panel for managing live streams, VOD content, subscriptions, and more.
### Features
- ✅ **180+ API Endpoints** - Complete coverage of all XUI.ONE Admin API actions
- ✅ **Interactive Documentation** - Swagger/OpenAPI 3.0 specification
- ✅ **Code Examples** - cURL, Python, PHP, and JavaScript examples
- ✅ **Detailed Guides** - Step-by-step authentication and usage instructions
- ✅ **Response Examples** - Real-world request/response samples
---
## 🚀 Quick Start
### Prerequisites
1. XUI.ONE panel installed and running (v1.5.5+)
2. Admin account with appropriate permissions
3. Admin API access code created
4. API key generated
### Authentication Setup
#### Step 1: Create Admin API Access Code
1. Log into your XUI.ONE admin panel
2. Navigate to **Management → Access Control → Access Codes**
3. Click **Add Access Code**
4. Select **Access Type: Admin API**
5. Assign to **Administrators** group
6. Save the access code (e.g., `cSbuFLhp`)
#### Step 2: Generate API Key
1. Log into admin panel
2. Click your profile (top right)
3. Select **Edit Profile**
4. Click **Generate API Key**
5. Copy and save your API key
#### Step 3: Test Connection
```bash
curl "http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=user_info"
```
**Expected Response:**
```json
{
"status": "STATUS_SUCCESS",
"data": {
"username": "admin",
"member_group_id": "1",
...
}
}
```
---
## 📖 Documentation
### View Interactive Documentation
**Option 1: Swagger UI (Recommended)**
1. Download this repository
2. Open `index.html` in your browser
3. Interactive API documentation with testing capability
**Option 2: Online Swagger Editor**
1. Go to https://editor.swagger.io/
2. Import the `openapi.yaml` file
3. Explore the API interactively
**Option 3: VS Code**
Install the "OpenAPI (Swagger) Editor" extension and open `openapi.yaml`
### Documentation Structure
```
xui-one-api-docs/
├── openapi.yaml # Main OpenAPI 3.0 specification
├── README.md # This file
├── docs/ # Detailed documentation
│ ├── getting-started.md # Setup and authentication guide
│ ├── authentication.md # Detailed authentication docs
│ ├── categories/ # API organized by category
│ │ ├── 01-get-info.md
│ │ ├── 02-logs-events.md
│ │ ├── 03-line-api.md
│ │ └── ...
│ └── examples/ # Code examples
│ ├── curl-examples.md
│ ├── python-examples.md
│ ├── php-examples.md
│ └── javascript-examples.md
├── postman/ # Postman collection
│ └── XUI-ONE-API.postman_collection.json
└── index.html # Swagger UI for local viewing
```
---
## 🎯 API Categories
### 1. **Authentication** ✅
- `user_info` - Get current user information
### 2. **GET INFO / Query Actions** 🔄 (Coming Soon)
- `get_lines` - Retrieve all subscription lines
- `get_users` - Retrieve all users
- `get_streams` - Retrieve all live streams
- `get_channels` - Retrieve all channels
- `get_movies` - Retrieve all movies
- `get_series_list` - Retrieve all series
- And more...
### 3. **Line API** 🔄 (Coming Soon)
- `create_line` - Create new subscription
- `edit_line` - Edit existing line
- `delete_line` - Delete subscription
- `enable_line` / `disable_line` - Toggle line status
- `ban_line` / `unban_line` - Ban/unban subscription
### 4. **User API** 🔄 (Coming Soon)
- `create_user` - Create new user
- `edit_user` - Edit user details
- `delete_user` - Delete user
- And more...
### 5. **MAG API** 🔄 (Coming Soon)
- MAG device management
### 6. **Enigma API** 🔄 (Coming Soon)
- Enigma2 STB management
### 7. **Streams API** 🔄 (Coming Soon)
- Live stream management
### 8. **Movies/Series/Episodes API** 🔄 (Coming Soon)
- VOD content management
### 9. **Servers API** 🔄 (Coming Soon)
- Server and load balancer management
### 10. **Logs & Events** 🔄 (Coming Soon)
- Activity monitoring
---
## 💡 Examples
### cURL Example
```bash
# Get all lines
curl "http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=get_lines"
# Create a new line
curl -X POST "http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=create_line" \
-d "username=testuser" \
-d "password=testpass" \
-d "max_connections=1" \
-d "exp_date=2025-12-31"
# Edit existing line (ID: 123)
curl "http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=edit_line&id=123&password=newpassword"
```
### Python Example
```python
import requests
# API Configuration
BASE_URL = "http://your-server.com/cSbuFLhp/"
API_KEY = "8D3135D30437F86EAE2FA4A2A8345000"
# Get all lines
response = requests.get(
BASE_URL,
params={
"api_key": API_KEY,
"action": "get_lines"
}
)
data = response.json()
if data["status"] == "STATUS_SUCCESS":
print(f"Found {len(data['data'])} lines")
else:
print(f"Error: {data['error']}")
```
### PHP Example
```php
<?php
// API Configuration
$baseUrl = "http://your-server.com/cSbuFLhp/";
$apiKey = "8D3135D30437F86EAE2FA4A2A8345000";
// Get all lines
$url = $baseUrl . "?api_key=" . $apiKey . "&action=get_lines";
$response = file_get_contents($url);
$data = json_decode($response, true);
if ($data['status'] === 'STATUS_SUCCESS') {
echo "Found " . count($data['data']) . " lines\n";
} else {
echo "Error: " . $data['error'] . "\n";
}
?>
```
### JavaScript Example
```javascript
// API Configuration
const BASE_URL = 'http://your-server.com/cSbuFLhp/';
const API_KEY = '8D3135D30437F86EAE2FA4A2A8345000';
// Get all lines
async function getLines() {
const url = `${BASE_URL}?api_key=${API_KEY}&action=get_lines`;
const response = await fetch(url);
const data = await response.json();
if (data.status === 'STATUS_SUCCESS') {
console.log(`Found ${data.data.length} lines`);
return data.data;
} else {
console.error(`Error: ${data.error}`);
return null;
}
}
getLines();
```
---
## 🔒 Security Best Practices
1. **Use HTTPS** - Always use port 9000 with SSL in production
2. **IP Whitelisting** - Restrict API access to specific IPs
3. **Rotate Keys** - Regenerate API keys periodically
4. **Never Expose Keys** - Don't commit API keys to version control
5. **Monitor Usage** - Check activity logs regularly
6. **HMAC Authentication** - Use HMAC for enhanced security
---
## 🤝 Contributing
We welcome contributions! Here's how you can help:
1. **Report Issues** - Found a bug or error? [Open an issue](https://github.com/worldofiptvcom/xui-one-api-docs/issues)
2. **Suggest Improvements** - Have ideas? Create a feature request
3. **Submit Pull Requests** - Fixed something? Submit a PR
4. **Share Examples** - Have working code examples? Share them!
### Contribution Guidelines
- Follow the existing documentation style
- Test all code examples before submitting
- Update the OpenAPI specification for API changes
- Provide clear commit messages
---
## 📋 Roadmap
- [x] Initial repository setup
- [x] Authentication documentation
- [ ] Complete all API categories (2-14)
- [ ] Add Postman collection
- [ ] Add more code examples (Ruby, Go, Node.js)
- [ ] Create video tutorials
- [ ] Add troubleshooting guide
- [ ] HMAC authentication detailed guide
---
## 📄 License
This documentation is provided for XUI.ONE users. XUI.ONE itself is proprietary software.
Documentation: MIT License
XUI.ONE Software: Proprietary (https://xui.one)
---
## 🆘 Support
- **Documentation Issues**: [GitHub Issues](https://github.com/worldofiptvcom/xui-one-api-docs/issues)
- **XUI.ONE Support**: Contact official support
- **Community**: [World of IPTV Forums](https://www.worldofiptv.com)
- **API Questions**: Open a discussion on GitHub
---
## 🙏 Acknowledgments
- XUI.ONE development team for creating the API
- World of IPTV community for testing and feedback
- All contributors to this documentation project
---
<div align="center">
**⭐ Star this repo if you find it helpful!**
Made with ❤️ by [World of IPTV](https://www.worldofiptv.com)
</div>
UPLOAD_INSTRUCTIONS.md
+299
View File
@@ -0,0 +1,299 @@
# 🚀 Upload Instructions for XUI.ONE API Documentation
## 📦 What You Have
I've created a complete documentation structure for XUI.ONE API with:
- ✅ OpenAPI 3.0.3 specification (openapi.yaml)
- ✅ Interactive Swagger UI (index.html)
- ✅ Comprehensive README
- ✅ Getting Started guide
- ✅ Contributing guidelines
- ✅ Deployment instructions
- ✅ Automated upload script
- ✅ MIT License
- ✅ .gitignore file
**Current Status:** Category 1 (Authentication & Getting Started) is **COMPLETE** ✅
---
## 🎯 Quick Start (2 Options)
### Option A: Automatic Upload (Easiest) ⭐
1. **Open Terminal in the project folder**
2. **Run the script:**
```bash
cd xui-one-api-docs
./upload-to-github.sh
```
3. **Follow prompts and enter GitHub credentials**
4. **Done!** 🎉
### Option B: Manual Upload
1. **Open Terminal in the project folder**
2. **Run these commands:**
```bash
cd xui-one-api-docs
# Initialize git
git init
# Add remote
git remote add origin https://github.com/worldofiptvcom/xui-one-api-docs.git
# Stage all files
git add .
# Commit
git commit -m "Initial commit: Add XUI.ONE API documentation with authentication section"
# Set branch name
git branch -M main
# Push to GitHub
git push -u origin main
```
3. **Enter GitHub credentials when prompted**
4. **Done!** 🎉
---
## 🔐 GitHub Authentication
You'll need to authenticate when pushing. Here are your options:
### Recommended: Personal Access Token
1. **Go to GitHub:**
- Settings → Developer settings → Personal access tokens → Tokens (classic)
2. **Generate new token:**
- Click "Generate new token (classic)"
- Give it a name: "XUI API Docs"
- Select scope: ✅ `repo` (Full control of private repositories)
- Click "Generate token"
- **Copy the token immediately** (you won't see it again!)
3. **Use token when pushing:**
- Username: `worldofiptvcom`
- Password: `<paste your token here>`
### Alternative: GitHub CLI
```bash
# Install GitHub CLI (if not installed)
# macOS:
brew install gh
# Linux:
sudo apt install gh
# Windows:
winget install --id GitHub.cli
# Authenticate
gh auth login
# Then push normally
git push -u origin main
```
---
## 🌐 Deploy Documentation Website
After uploading to GitHub:
### Step 1: Enable GitHub Pages
1. Go to: https://github.com/worldofiptvcom/xui-one-api-docs
2. Click **Settings** tab
3. Scroll to **Pages** (left sidebar)
4. Under **Build and deployment**:
- **Source:** Deploy from a branch
- **Branch:** main
- **Folder:** / (root)
5. Click **Save**
### Step 2: Wait for Deployment
- GitHub will automatically build your site (1-2 minutes)
- Check progress in **Actions** tab
### Step 3: Access Your Live Documentation
Your documentation will be available at:
```
https://worldofiptvcom.github.io/xui-one-api-docs/
```
Open `index.html` for the interactive Swagger UI! 🎊
---
## 📁 What's Included
```
xui-one-api-docs/
├── 📄 openapi.yaml # Main API specification (OpenAPI 3.0.3)
├── 🌐 index.html # Interactive Swagger UI
├── 📖 README.md # Project overview and documentation
├── 🚀 DEPLOYMENT.md # Detailed deployment guide
├── 🤝 CONTRIBUTING.md # Contribution guidelines
├── 📄 LICENSE # MIT License
├── 🙈 .gitignore # Git ignore rules
├── 📜 upload-to-github.sh # Automated upload script
├── docs/
│ ├── 📘 getting-started.md # Complete setup guide
│ ├── categories/
│ │ └── 📋 01-get-info.md # Placeholder for next category
│ └── examples/ # (Empty - for future code examples)
└── postman/ # (Empty - for future Postman collection)
```
---
## ✅ Completed in This Release
### 1. Authentication & Setup ✅
- `user_info` endpoint fully documented
- Complete OpenAPI specification
- Authentication guide
- Security best practices
- Example code in cURL, Python, PHP, JavaScript
### 2. Project Infrastructure ✅
- GitHub repository structure
- Contributing guidelines
- Deployment instructions
- Automated upload script
- Interactive Swagger UI
---
## 🔄 Next Steps (Future Categories)
After uploading, we'll add documentation for:
2. **GET INFO** - Query operations (get_lines, get_users, get_streams, etc.)
3. **Line API** - Subscription management
4. **Logs & Events** - Monitoring
5. **User API** - User management
6. **MAG API** - MAG devices
7. **Enigma API** - Enigma2 STBs
8. **Streams API** - Live streams
9. **Channel API** - Channels
10. **Station API** - Radio stations
11. **Movie API** - VOD movies
12. **Series API** - Series
13. **Episode API** - Episodes
14. **Servers API** - Server management
Each category will include:
- Complete endpoint documentation
- All parameters
- Response examples
- Code examples in multiple languages
- Use cases and best practices
---
## 🧪 Test Locally Before Uploading
Want to preview the documentation first?
```bash
cd xui-one-api-docs
# Option 1: Python
python3 -m http.server 8000
# Option 2: Node.js
npx http-server
# Option 3: PHP
php -S localhost:8000
```
Then open: http://localhost:8000/index.html
---
## 🆘 Troubleshooting
### Problem: "Permission denied" when running script
**Solution:**
```bash
chmod +x upload-to-github.sh
./upload-to-github.sh
```
### Problem: "Authentication failed"
**Solution:**
- Use Personal Access Token instead of password
- Make sure token has `repo` scope
- Or use GitHub CLI: `gh auth login`
### Problem: "Repository not found"
**Solution:**
- Verify you created the repository on GitHub
- Check the URL is correct: https://github.com/worldofiptvcom/xui-one-api-docs
- Ensure you're logged in to GitHub
### Problem: Changes not showing on GitHub Pages
**Solution:**
- Clear browser cache
- Wait 1-2 minutes for rebuild
- Check Actions tab for deployment status
---
## 📞 Need Help?
1. **Check DEPLOYMENT.md** - Detailed deployment guide
2. **Check CONTRIBUTING.md** - How to contribute
3. **Open GitHub Issue** - Report problems
4. **World of IPTV Forums** - Community support
---
## 🎉 You're All Set!
Once uploaded, you'll have:
- ✅ Professional API documentation
- ✅ Interactive testing interface (Swagger UI)
- ✅ Live website on GitHub Pages
- ✅ Version controlled documentation
- ✅ Community contribution ready
- ✅ Foundation for remaining categories
**Ready to upload? Run:** `./upload-to-github.sh`
---
## 📝 After Upload Checklist
- [ ] Repository uploaded successfully
- [ ] GitHub Pages enabled
- [ ] Documentation website accessible
- [ ] Swagger UI working correctly
- [ ] Update repository description on GitHub
- [ ] Add topics/tags to repository (api, documentation, iptv, xuione, openapi)
- [ ] Share with community!
---
**Made with ❤️ for the XUI.ONE community**
Questions? Open an issue on GitHub!
docs/categories/01-get-info.md
+39
View File
@@ -0,0 +1,39 @@
# GET INFO / Query Actions
> 📋 **Status:** Coming Soon
>
> This section will document all query and information retrieval endpoints.
## Overview
GET INFO endpoints allow you to retrieve information about your XUI.ONE panel resources without making modifications.
## Available Endpoints
- `mysql_query` - Execute custom MySQL queries
- `user_info` - Get current user information ✅ (Documented in openapi.yaml)
- `get_lines` - Retrieve all subscription lines
- `get_mags` - Retrieve all MAG devices
- `get_enigmas` - Retrieve all Enigma2 devices
- `get_users` - Retrieve all users
- `get_streams` - Retrieve all live streams
- `get_channels` - Retrieve all channels
- `get_stations` - Retrieve all radio stations
- `get_movies` - Retrieve all movies
- `get_series_list` - Retrieve all series
- `get_episodes` - Retrieve all episodes
- `get_packages` - Retrieve all subscription packages
## Coming Soon
Detailed documentation for each endpoint will include:
- Complete parameter list
- Response structure
- Code examples (cURL, Python, PHP, JavaScript)
- Use cases
- Pagination support
- Filtering options
---
**Want to help?** Check our [Contributing Guide](../../CONTRIBUTING.md) to add documentation for these endpoints!
docs/getting-started.md
+403
View File
@@ -0,0 +1,403 @@
# Getting Started with XUI.ONE Admin API
Welcome to the XUI.ONE Admin API! This guide will help you get up and running quickly.
## Table of Contents
1. [Prerequisites](#prerequisites)
2. [Authentication Setup](#authentication-setup)
3. [Making Your First API Call](#making-your-first-api-call)
4. [Understanding Responses](#understanding-responses)
5. [Common Operations](#common-operations)
6. [Troubleshooting](#troubleshooting)
7. [Next Steps](#next-steps)
---
## Prerequisites
Before you begin, ensure you have:
- ✅ **XUI.ONE Panel Installed** - Version 1.5.5 or higher
- ✅ **Admin Access** - Full administrator privileges
- ✅ **Server Access** - Ability to access your XUI.ONE server
- ✅ **API Client** - cURL, Postman, or programming language of choice
### Check Your XUI.ONE Version
SSH into your server and run:
```bash
cat /home/xui/config/config.ini | grep version
```
Or check in the admin panel footer.
---
## Authentication Setup
### Step 1: Create Admin API Access Code
The access code is a unique identifier that protects your API endpoint.
1. **Log into XUI.ONE Admin Panel**
- Navigate to your panel URL: `http://your-server.com:25500/your-access-code`
2. **Navigate to Access Codes**
- Click **Management** (left sidebar)
- Select **Access Control**
- Click **Access Codes**
3. **Create New Access Code**
- Click **Add Access Code** button
- Fill in the form:
- **Access Type**: Select `Admin API`
- **Group**: Select `Administrators`
- **IP Restriction** (Optional but recommended):
- Add your IP address for security
- Leave empty to allow all IPs (not recommended for production)
4. **Save and Note Your Access Code**
- After saving, note your access code (e.g., `cSbuFLhp`)
- This will be part of your API URL
### Step 2: Generate API Key
The API key authenticates your requests.
1. **Access Your Profile**
- Click your username (top right corner)
- Select **Edit Profile**
2. **Generate API Key**
- Scroll to the API section
- Click the blue **Generate API Key** button
- Your API key will be displayed (e.g., `8D3135D30437F86EAE2FA4A2A8345000`)
3. **Save Your API Key Securely**
- Copy the API key immediately
- Store it in a password manager or secure location
- **Never commit this to version control!**
### Step 3: Construct Your Base URL
Your API base URL follows this format:
```
http://your-server.com/<Access-Code>/?api_key=<API-KEY>
```
**Example:**
```
http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000
```
**For HTTPS (Recommended for Production):**
```
https://your-server.com:9000/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000
```
---
## Making Your First API Call
### Test Authentication
Let's verify everything is set up correctly by getting your user information.
#### Using cURL
```bash
curl "http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=user_info"
```
#### Using Python
```python
import requests
response = requests.get(
"http://your-server.com/cSbuFLhp/",
params={
"api_key": "8D3135D30437F86EAE2FA4A2A8345000",
"action": "user_info"
}
)
print(response.json())
```
#### Using PHP
```php
<?php
$url = "http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=user_info";
$response = file_get_contents($url);
$data = json_decode($response, true);
print_r($data);
?>
```
#### Using JavaScript (Node.js)
```javascript
const fetch = require('node-fetch');
async function getUserInfo() {
const url = 'http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=user_info';
const response = await fetch(url);
const data = await response.json();
console.log(data);
}
getUserInfo();
```
### Expected Success Response
```json
{
"status": "STATUS_SUCCESS",
"data": {
"id": "1",
"username": "admin",
"member_group_id": "1",
"email": "admin@example.com",
"date_registered": "1609459200",
"last_login": "1734048000",
"status": "1"
}
}
```
✅ **Success!** If you see this response, your authentication is working correctly.
---
## Understanding Responses
### Success Response Structure
All successful API calls return:
```json
{
"status": "STATUS_SUCCESS",
"data": {
// Response data here
}
}
```
- **status**: Always `"STATUS_SUCCESS"` for successful requests
- **data**: Contains the requested information (structure varies by endpoint)
### Error Response Structure
Failed API calls return:
```json
{
"status": "STATUS_FAILURE",
"error": "Error message description"
}
```
- **status**: Always `"STATUS_FAILURE"` for failed requests
- **error**: Human-readable error message
### Common Error Messages
| Error Message | Meaning | Solution |
|--------------|---------|----------|
| `Invalid API key` | API key is wrong or expired | Regenerate API key in profile |
| `Access denied` | Access code is incorrect | Verify access code |
| `Missing required parameters` | Required field not provided | Check API documentation |
| `Invalid action` | Action name misspelled | Verify action name |
| `Permission denied` | Insufficient privileges | Check access code group assignment |
| `Resource not found` | ID doesn't exist | Verify the resource ID |
---
## Common Operations
### 1. Get All Subscription Lines
```bash
curl "http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=get_lines"
```
### 2. Get Specific Line Details
First, get the line ID from `get_lines`, then:
```bash
curl "http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=get_line&id=123"
```
### 3. Create New Subscription Line
```bash
curl -X POST "http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=create_line" \
-d "username=testuser" \
-d "password=testpass123" \
-d "max_connections=1" \
-d "exp_date=2025-12-31"
```
### 4. Edit Existing Line
```bash
curl "http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=edit_line&id=123&password=newpassword&max_connections=2"
```
### 5. Get All Streams
```bash
curl "http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=get_streams"
```
### 6. Get Live Connections
```bash
curl "http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=live_connections"
```
### 7. Get Activity Logs
```bash
curl "http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=activity_logs"
```
---
## Troubleshooting
### Problem: "Invalid API key" Error
**Solution:**
1. Regenerate your API key in admin profile
2. Ensure you're using the complete key without spaces
3. Check for special characters that need URL encoding
### Problem: "Access denied" Error
**Solution:**
1. Verify your access code is correct
2. Check that the access code is assigned to Administrators group
3. If using IP restriction, verify your current IP is whitelisted
### Problem: Connection Timeout
**Solution:**
1. Check if XUI.ONE service is running: `service xuione status`
2. Verify firewall allows the port (80, 8000, or 9000)
3. Check if nginx is running: `systemctl status nginx`
### Problem: SSL/HTTPS Not Working
**Solution:**
1. Verify SSL certificate is installed in XUI.ONE
2. Use port 9000 for HTTPS: `https://your-server.com:9000/...`
3. Check certificate validity in panel settings
### Problem: Empty Response Data
**Solution:**
1. Check if the resource exists (e.g., lines, streams)
2. Verify you're using the correct action name
3. Check if pagination is needed for large datasets
---
## Best Practices
### Security
1. **Use HTTPS in Production**
```
https://your-server.com:9000/cSbuFLhp/?api_key=...
```
2. **IP Whitelist Your API Access**
- Restrict access code to your application server IPs
3. **Rotate API Keys Regularly**
- Regenerate keys every 90 days
4. **Never Log API Keys**
- Sanitize logs to remove sensitive data
5. **Use Environment Variables**
```bash
export XUI_API_KEY="8D3135D30437F86EAE2FA4A2A8345000"
export XUI_ACCESS_CODE="cSbuFLhp"
export XUI_SERVER="your-server.com"
```
### Performance
1. **Cache Responses**
- Cache data that doesn't change frequently (streams, movies)
2. **Implement Rate Limiting**
- Limit to 100 requests per minute
3. **Use Pagination**
- For large datasets, use limit/offset parameters
4. **Batch Operations**
- When possible, batch multiple updates
### Error Handling
1. **Always Check Response Status**
```python
if data['status'] != 'STATUS_SUCCESS':
handle_error(data['error'])
```
2. **Implement Retry Logic**
- Use exponential backoff for transient errors
3. **Log All Errors**
- Keep detailed logs for debugging
---
## Next Steps
Now that you're set up, explore more API capabilities:
1. 📖 **Read Full API Reference** - Check `openapi.yaml` for all endpoints
2. 🔍 **Explore Categories** - Browse `/docs/categories/` for detailed guides
3. 💻 **Try Code Examples** - See `/docs/examples/` for language-specific examples
4. 📦 **Use Postman** - Import the Postman collection for easy testing
5. 🎯 **Build Your Application** - Start integrating XUI.ONE into your project
### Recommended Reading Order
1. **Line API** - Manage subscriptions
2. **Streams API** - Control live streams
3. **Logs & Events** - Monitor your platform
4. **Movies/Series API** - Manage VOD content
5. **Servers API** - Configure load balancers
---
## Support
Need help?
- 📖 **Documentation**: Check the full API reference
- 🐛 **Issues**: [Report bugs on GitHub](https://github.com/worldofiptvcom/xui-one-api-docs/issues)
- 💬 **Community**: [World of IPTV Forums](https://www.worldofiptv.com)
- 📧 **Official Support**: Contact XUI.ONE team
---
**Happy coding! 🚀**
index.html
+158
View File
@@ -0,0 +1,158 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="description" content="XUI.ONE Admin API Documentation - Interactive Swagger UI" />
<title>XUI.ONE Admin API Documentation</title>
<link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5.9.0/swagger-ui.css" />
<style>
body {
margin: 0;
padding: 0;
}
.topbar {
display: none;
}
.swagger-ui .info {
margin: 50px 0;
}
.swagger-ui .info .title {
font-size: 36px;
color: #3b4151;
}
.custom-header {
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
color: white;
padding: 30px;
text-align: center;
box-shadow: 0 2px 10px rgba(0,0,0,0.1);
}
.custom-header h1 {
margin: 0;
font-size: 42px;
font-weight: 700;
}
.custom-header p {
margin: 10px 0 0;
font-size: 18px;
opacity: 0.9;
}
.custom-links {
margin-top: 20px;
}
.custom-links a {
color: white;
text-decoration: none;
margin: 0 15px;
padding: 8px 20px;
border: 2px solid white;
border-radius: 5px;
transition: all 0.3s;
display: inline-block;
}
.custom-links a:hover {
background: white;
color: #667eea;
}
.info-banner {
background: #fff3cd;
border: 1px solid #ffc107;
border-radius: 5px;
padding: 15px;
margin: 20px auto;
max-width: 1200px;
text-align: center;
}
.info-banner strong {
color: #856404;
}
</style>
</head>
<body>
<div class="custom-header">
<h1>🎬 XUI.ONE Admin API</h1>
<p>Complete API Documentation for IPTV Panel Administration</p>
<div class="custom-links">
<a href="https://github.com/worldofiptvcom/xui-one-api-docs" target="_blank">📖 GitHub</a>
<a href="https://www.worldofiptv.com" target="_blank">💬 Community</a>
<a href="https://xui.one" target="_blank">🌐 XUI.ONE</a>
</div>
</div>
<div class="info-banner">
<strong>📢 Note:</strong> This documentation is for XUI.ONE v1.5.13+.
Replace placeholder values (<code>your-server.com</code>, <code>&lt;API-KEY&gt;</code>, <code>&lt;Access-Code&gt;</code>) with your actual credentials.
</div>
<div id="swagger-ui"></div>
<script src="https://unpkg.com/swagger-ui-dist@5.9.0/swagger-ui-bundle.js" crossorigin></script>
<script src="https://unpkg.com/swagger-ui-dist@5.9.0/swagger-ui-standalone-preset.js" crossorigin></script>
<script>
window.onload = () => {
window.ui = SwaggerUIBundle({
url: './openapi.yaml',
dom_id: '#swagger-ui',
deepLinking: true,
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIStandalonePreset
],
plugins: [
SwaggerUIBundle.plugins.DownloadUrl
],
layout: "StandaloneLayout",
defaultModelsExpandDepth: 1,
defaultModelExpandDepth: 1,
docExpansion: 'list',
filter: true,
showRequestHeaders: true,
tryItOutEnabled: true,
requestSnippetsEnabled: true,
requestSnippets: {
generators: {
curl_bash: {
title: "cURL (bash)",
syntax: "bash"
},
curl_powershell: {
title: "cURL (PowerShell)",
syntax: "powershell"
},
curl_cmd: {
title: "cURL (CMD)",
syntax: "bash"
}
},
defaultExpanded: true,
languages: null
}
});
};
</script>
<footer style="text-align: center; padding: 40px 20px; background: #fafafa; margin-top: 50px; border-top: 1px solid #e5e5e5;">
<p style="color: #666; margin: 0;">
<strong>XUI.ONE Admin API Documentation</strong>
</p>
<p style="color: #999; margin: 10px 0 0; font-size: 14px;">
Made with ❤️ by <a href="https://www.worldofiptv.com" target="_blank" style="color: #667eea; text-decoration: none;">World of IPTV</a>
</p>
<p style="color: #999; margin: 10px 0 0; font-size: 12px;">
Documentation licensed under MIT | XUI.ONE software is proprietary
</p>
</footer>
</body>
</html>
openapi.yaml
+479
View File
@@ -0,0 +1,479 @@
openapi: 3.0.3
info:
title: XUI.ONE Admin API
description: |
# XUI.ONE Admin API Documentation
Comprehensive API documentation for XUI.ONE IPTV Panel Administration.
## Overview
The XUI.ONE Admin API provides programmatic access to manage your IPTV platform. With over 180+ endpoints, you can:
- Manage subscriptions (Lines, MAG devices, Enigma2 devices)
- Control streams, channels, movies, and series
- Monitor connections and logs
- Configure servers and load balancers
- Administer users and resellers
## Base URL Structure
All API requests follow this pattern:
```
http://YOUR_SERVER:PORT/<Access-Code>/?api_key=<API-KEY>&action=ACTION_NAME
```
**Components:**
- `YOUR_SERVER` - Your XUI.ONE server IP or domain
- `PORT` - API port (default: 80 for HTTP, 8000 for HTTP explicit, 9000 for HTTPS)
- `<Access-Code>` - Unique access code for API access
- `<API-KEY>` - Your generated API key
- `ACTION_NAME` - The API action to perform
## Authentication
XUI.ONE API uses **API Key authentication** combined with **Access Codes** for secure access.
### Prerequisites
Before using the API, you need:
1. ✅ XUI.ONE panel installed and running
2. ✅ Admin account with appropriate permissions
3. ✅ Admin API access code created
4. ✅ API key generated
### Step 1: Create Admin API Access Code
1. Log into your XUI.ONE admin panel
2. Navigate to **Management → Access Control → Access Codes**
3. Click **Add Access Code**
4. Select **Access Type: Admin API**
5. Assign to **Administrators** group
6. (Optional) Restrict to specific IP address for security
7. Save the access code (e.g., `cSbuFLhp`)
### Step 2: Generate API Key
1. Log into admin panel
2. Click your profile (top right)
3. Select **Edit Profile**
4. Click the blue **Generate API Key** button
5. Copy and save your API key (e.g., `8D3135D30437F86EAE2FA4A2A8345000`)
⚠️ **Security Warning:** Keep your API key secure. If compromised, regenerate immediately.
### Step 3: Test Authentication
Test your credentials with a simple API call:
```bash
curl "http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=user_info"
```
Successful response:
```json
{
"status": "STATUS_SUCCESS",
"data": {
"username": "admin",
"member_group_id": "1",
...
}
}
```
## Request Methods
The API supports both **GET** and **POST** methods:
### GET Requests
Pass parameters in the URL query string:
```
http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=get_lines&limit=10
```
### POST Requests
Send parameters as form data or JSON in request body:
```bash
curl -X POST "http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=create_line" \
-d "username=testuser" \
-d "password=testpass" \
-d "max_connections=1"
```
## Response Format
All API responses return JSON with a consistent structure:
### Success Response
```json
{
"status": "STATUS_SUCCESS",
"data": {
// Response data here
}
}
```
### Error Response
```json
{
"status": "STATUS_FAILURE",
"error": "Error message description"
}
```
## Common Error Messages
| Error Message | Cause | Solution |
|--------------|-------|----------|
| `Invalid API key` | Wrong or expired API key | Regenerate API key in admin profile |
| `Access denied` | Invalid access code | Verify access code is correct |
| `Missing required parameters` | Required field not provided | Check API documentation for required fields |
| `Invalid action` | Action name is incorrect | Verify action name spelling |
| `Permission denied` | Insufficient privileges | Ensure API access code is assigned to Administrators group |
## Rate Limiting
XUI.ONE implements rate limiting to prevent abuse:
- Default: No strict rate limit
- Recommended: Max 100 requests per minute per IP
- Heavy operations (database queries): Use sparingly
If you experience rate limiting, implement exponential backoff in your application.
## Security Best Practices
1. 🔒 **Use HTTPS** - Always use port 9000 with SSL enabled in production
2. 🔐 **IP Whitelisting** - Restrict API access to specific IPs
3. 🔑 **Rotate Keys** - Regenerate API keys periodically
4. 📝 **Audit Logs** - Monitor API usage via activity logs
5. 🚫 **Never Expose Keys** - Don't commit API keys to version control
6. 🛡️ **HMAC Authentication** - Use HMAC for enhanced security (advanced)
## HMAC Authentication (Advanced)
For enhanced security, XUI.ONE supports HMAC-based authentication:
1. Generate HMAC key: `action=create_hmac`
2. Sign each request with HMAC-SHA256
3. Include signature in request header
See detailed HMAC documentation for implementation details.
## Getting Help
- 📖 Documentation: https://github.com/worldofiptvcom/xui-one-api-docs
- 💬 Community: World of IPTV Forums (https://www.worldofiptv.com)
- 🐛 Issues: Report bugs via GitHub Issues
- 📧 Support: Contact XUI.ONE support team
## API Version
Current API Version: **v1.5.13**
Compatible with XUI.ONE versions 1.5.5+
version: 1.5.13
contact:
name: XUI.ONE API Support
url: https://xui.one
license:
name: Proprietary
url: https://xui.one
servers:
- url: http://{server}:{port}/{accessCode}
description: XUI.ONE API Server (HTTP)
variables:
server:
default: your-server.com
description: Your XUI.ONE server IP or domain
port:
default: '80'
description: API port
enum:
- '80'
- '8000'
accessCode:
default: cSbuFLhp
description: Your unique access code for API access
- url: https://{server}:9000/{accessCode}
description: XUI.ONE API Server (HTTPS - Recommended)
variables:
server:
default: your-server.com
description: Your XUI.ONE server IP or domain
accessCode:
default: cSbuFLhp
description: Your unique access code for API access
security:
- ApiKeyAuth: []
tags:
- name: Authentication
description: Authentication and authorization operations
- name: GET INFO
description: Query and retrieve information
- name: Logs & Events
description: Activity logs, connections, and monitoring
- name: Line API
description: Subscription line management
- name: User API
description: User account management
- name: MAG API
description: MAG device management
- name: Enigma API
description: Enigma2 STB management
- name: Streams API
description: Live stream management
- name: Channel API
description: Channel management
- name: Station API
description: Radio station management
- name: Movie API
description: VOD movie management
- name: Series API
description: Series management
- name: Episode API
description: Episode management
- name: Servers API
description: Server and load balancer management
- name: Settings & System
description: System settings and administrative functions
paths:
/:
get:
summary: API Base Endpoint
description: |
Base endpoint for all API requests. All actions are performed by adding the `action` parameter.
**Usage:**
```
/?api_key=<API-KEY>&action=ACTION_NAME&param1=value1&param2=value2
```
operationId: apiBase
tags:
- Authentication
parameters:
- $ref: '#/components/parameters/ApiKey'
- $ref: '#/components/parameters/Action'
responses:
'200':
description: Successful response
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/SuccessResponse'
- $ref: '#/components/schemas/ErrorResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/ServerError'
/?action=user_info:
get:
summary: Get Current User Info
description: |
Retrieves information about the currently authenticated admin user.
**Use Case:** Verify authentication and check admin privileges.
**Example Request:**
```bash
curl "http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=user_info"
```
**Example Response:**
```json
{
"status": "STATUS_SUCCESS",
"data": {
"id": "1",
"username": "admin",
"member_group_id": "1",
"email": "admin@example.com",
"date_registered": "1609459200",
"last_login": "1734048000",
"status": "1"
}
}
```
operationId: getUserInfo
tags:
- Authentication
parameters:
- $ref: '#/components/parameters/ApiKey'
- name: action
in: query
required: true
schema:
type: string
enum: [user_info]
example: user_info
responses:
'200':
description: Current user information
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/SuccessResponse'
- type: object
properties:
data:
$ref: '#/components/schemas/UserInfo'
example:
status: "STATUS_SUCCESS"
data:
id: "1"
username: "admin"
member_group_id: "1"
email: "admin@example.com"
date_registered: "1609459200"
last_login: "1734048000"
status: "1"
'401':
$ref: '#/components/responses/Unauthorized'
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: query
name: api_key
description: |
API key for authentication. Generate from your admin profile in the XUI.ONE panel.
**Example:** `8D3135D30437F86EAE2FA4A2A8345000`
parameters:
ApiKey:
name: api_key
in: query
required: true
description: Your API key for authentication
schema:
type: string
example: "8D3135D30437F86EAE2FA4A2A8345000"
Action:
name: action
in: query
required: true
description: The API action to perform
schema:
type: string
example: user_info
schemas:
SuccessResponse:
type: object
required:
- status
- data
properties:
status:
type: string
enum: [STATUS_SUCCESS]
description: Response status indicator
data:
type: object
description: Response data (structure varies by endpoint)
example:
status: "STATUS_SUCCESS"
data: {}
ErrorResponse:
type: object
required:
- status
- error
properties:
status:
type: string
enum: [STATUS_FAILURE]
description: Error status indicator
error:
type: string
description: Error message describing what went wrong
example:
status: "STATUS_FAILURE"
error: "Invalid API key"
UserInfo:
type: object
properties:
id:
type: string
description: User ID
example: "1"
username:
type: string
description: Username
example: "admin"
member_group_id:
type: string
description: Member group ID (1 = Administrator)
example: "1"
email:
type: string
format: email
description: User email address
example: "admin@example.com"
date_registered:
type: string
description: Unix timestamp of registration date
example: "1609459200"
last_login:
type: string
description: Unix timestamp of last login
example: "1734048000"
status:
type: string
description: User status (1 = Active, 0 = Inactive)
enum: ["0", "1"]
example: "1"
responses:
Unauthorized:
description: Authentication failed - Invalid API key or access code
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: "STATUS_FAILURE"
error: "Invalid API key"
ServerError:
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: "STATUS_FAILURE"
error: "Internal server error"
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: "STATUS_FAILURE"
error: "Resource not found"
upload-to-github.sh
+113
View File
@@ -0,0 +1,113 @@
#!/bin/bash
# XUI.ONE API Documentation - Git Upload Script
# This script will initialize git and push all files to GitHub
echo "================================================"
echo " XUI.ONE API Documentation - Git Upload"
echo "================================================"
echo ""
# Colors for output
GREEN='\033[0;32m'
BLUE='\033[0;34m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color
# Configuration
REPO_URL="https://github.com/worldofiptvcom/xui-one-api-docs.git"
BRANCH="main"
# Step 1: Initialize Git (if not already initialized)
echo -e "${BLUE}Step 1: Initializing Git repository...${NC}"
if [ ! -d ".git" ]; then
git init
echo -e "${GREEN}✓ Git initialized${NC}"
else
echo -e "${GREEN}✓ Git already initialized${NC}"
fi
echo ""
# Step 2: Add remote
echo -e "${BLUE}Step 2: Setting up remote repository...${NC}"
if git remote | grep -q "origin"; then
echo -e "${YELLOW}⚠ Remote 'origin' already exists. Updating URL...${NC}"
git remote set-url origin $REPO_URL
else
git remote add origin $REPO_URL
fi
echo -e "${GREEN}✓ Remote configured: $REPO_URL${NC}"
echo ""
# Step 3: Add all files
echo -e "${BLUE}Step 3: Adding files to git...${NC}"
git add .
echo -e "${GREEN}✓ Files staged for commit${NC}"
echo ""
# Step 4: Show what will be committed
echo -e "${BLUE}Files to be committed:${NC}"
git status --short
echo ""
# Step 5: Commit
echo -e "${BLUE}Step 4: Creating commit...${NC}"
read -p "Enter commit message (or press Enter for default): " COMMIT_MSG
if [ -z "$COMMIT_MSG" ]; then
COMMIT_MSG="Initial commit: Add XUI.ONE API documentation with authentication section"
fi
git commit -m "$COMMIT_MSG"
echo -e "${GREEN}✓ Commit created${NC}"
echo ""
# Step 6: Set branch name
echo -e "${BLUE}Step 5: Setting branch name...${NC}"
git branch -M $BRANCH
echo -e "${GREEN}✓ Branch set to: $BRANCH${NC}"
echo ""
# Step 7: Push to GitHub
echo -e "${BLUE}Step 6: Pushing to GitHub...${NC}"
echo -e "${YELLOW}You may be prompted for your GitHub username and password/token${NC}"
git push -u origin $BRANCH
# Check if push was successful
if [ $? -eq 0 ]; then
echo ""
echo -e "${GREEN}================================================${NC}"
echo -e "${GREEN} ✓ Successfully uploaded to GitHub!${NC}"
echo -e "${GREEN}================================================${NC}"
echo ""
echo -e "View your repository at:"
echo -e "${BLUE}https://github.com/worldofiptvcom/xui-one-api-docs${NC}"
echo ""
echo -e "Next steps:"
echo "1. Visit the repository URL above"
echo "2. Enable GitHub Pages (Settings → Pages → Source: main branch)"
echo "3. Your documentation will be live at:"
echo " https://worldofiptvcom.github.io/xui-one-api-docs/"
echo ""
else
echo ""
echo -e "${YELLOW}================================================${NC}"
echo -e "${YELLOW} ⚠ Push failed or requires authentication${NC}"
echo -e "${YELLOW}================================================${NC}"
echo ""
echo "If you're having authentication issues:"
echo ""
echo "Option 1: Use Personal Access Token (Recommended)"
echo " 1. Go to GitHub Settings → Developer settings → Personal access tokens"
echo " 2. Generate new token (classic) with 'repo' scope"
echo " 3. Use token as password when prompted"
echo ""
echo "Option 2: Use GitHub CLI"
echo " 1. Install: https://cli.github.com/"
echo " 2. Run: gh auth login"
echo " 3. Re-run this script"
echo ""
echo "Option 3: Use SSH"
echo " 1. Add SSH key to GitHub"
echo " 2. Change remote: git remote set-url origin git@github.com:worldofiptvcom/xui-one-api-docs.git"
echo " 3. Re-run: git push -u origin main"
echo ""
fi