API Reference¶

Version: 1.0.0 | Last Updated: 2025-01-06 | Status: Stable

Overview¶

MBPanel provides a comprehensive REST API for managing WordPress sites, environments, domains, backups, and more. This reference documentation is auto-generated from the FastAPI codebase using mkdocstrings.

Base URL¶

Production¶

https://api.mbpanel.io/v1

Development¶

http://localhost:8000/v1

Authentication¶

All API requests require authentication using JWT bearer tokens.

Headers¶

Authorization: Bearer <access_token>
Content-Type: application/json

Authentication Flow¶

# 1. Obtain token
POST /auth/login
{
  "email": "user@example.com",
  "password": "secure_password"
}

# 2. Use token in requests
GET /sites
Authorization: Bearer <access_token>

API Domains¶

Core Domains¶

Sites - Site creation, cloning, deletion, configuration
Environments - Environment lifecycle (dev/stage/prod)
WordPress - WP installations, plugins, themes
Backups - Backup scheduling and restoration
Domains - Hosted domains, SSL certificates, DNS

Business Domains¶

Payments - Payment processing
Billing - Subscriptions, plans, invoicing
Nodes - Server/node management

Cross-Cutting Modules¶

Auth - Authentication, tokens, sessions
Users - User management
Teams - Team and membership management
RBAC - Roles and permissions
Activity - Activity logs and audit trails
Webhooks - Webhook management
SFTP - SFTP access management

Response Format¶

All API responses follow this structure:

Success Response¶

{
  "data": { ... },
  "meta": {
    "timestamp": "2025-01-06T00:00:00Z",
    "request_id": "req_abc123"
  }
}

Error Response¶

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": { ... }
  },
  "meta": {
    "timestamp": "2025-01-06T00:00:00Z",
    "request_id": "req_abc123"
  }
}

Error Codes¶

Code	Description
`VALIDATION_ERROR`	Request validation failed
`AUTHENTICATION_ERROR`	Invalid or missing credentials
`AUTHORIZATION_ERROR`	Insufficient permissions
`NOT_FOUND`	Resource not found
`CONFLICT`	Resource already exists
`RATE_LIMIT_EXCEEDED`	Too many requests
`INTERNAL_ERROR`	Server error

Pagination¶

List endpoints support pagination:

GET /sites?page=1&page_size=20

Response includes pagination metadata:

{
  "data": [ ... ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 100,
    "total_pages": 5
  }
}

Rate Limiting¶

API requests are rate limited: - Default: 100 requests per minute - Burst: 10 requests per second

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1609459200

Versioning¶

API versioning is via URL path: - Current: /v1/ - No breaking changes within a version

Interactive Documentation¶

Swagger UI¶

Interactive API explorer with "Try it out" functionality. - Production: https://docs.mbpanel.io/api/docs - Development: http://localhost:8000/docs

ReDoc¶

Alternative documentation format with reference-style layout. - Production: https://docs.mbpanel.io/api/redoc - Development: http://localhost:8000/redoc

Guides¶

Authentication Guide - Complete authentication flow
Error Handling Guide - Common errors and solutions
Webhooks Guide - Webhook integration
Pagination Guide - Efficient data retrieval

SDKs¶

Official SDKs: - Python SDK - JavaScript SDK

Changelog¶

See CHANGELOG.md for API changes and version history.