openapi: 3.0.3
info:
title: XBP API
description: "XBP (XYLEX Build Pack) API provides comprehensive server management, deployment, \nmonitoring, and logging capabilities. Manage ports, systemctl services, PM2 processes, \nand deploy applications with ease, Synthetic monitors as workflows.\n"
version: 10.15.4
contact:
name: Floris
email: floris@xylex.group
license:
name: MIT
url: https://opensource.org/licenses/MIT
servers:
- url: https://api.dev.example.com
description: Development server
- url: https://api.example.com
description: Production server
tags:
- name: Health
description: Health check endpoints
- name: Ports
description: Network port management
- name: Systemctl
description: System service management
- name: PM2
description: PM2 process management
- name: Services
description: XBP service management
- name: Config
description: Configuration management
- name: Logs
description: Log management and streaming
- name: Deployment
description: Application deployment and redeployment
- name: Installation
description: Package installation
- name: Binary
description: Binary download and execution
- name: Monitoring
description: Application monitoring and health checks
- name: Diagnostics
description: System diagnostics and metrics
paths:
/health:
get:
tags:
- Health
summary: Health check
description: Returns the health status and version of the API
operationId: getHealth
responses:
'200':
description: API is healthy
content:
application/json:
schema:
$ref: '#/components/schemas/HealthResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/ports:
get:
tags:
- Ports
summary: List all ports
description: Returns a list of all network ports currently in use
operationId: listPorts
responses:
'200':
description: List of ports
content:
application/json:
schema:
$ref: '#/components/schemas/PortsResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/ports/{port}:
get:
tags:
- Ports
summary: Get specific port information
description: Returns information about a specific port
operationId: getPort
parameters:
- name: port
in: path
required: true
description: Port number to query
schema:
type: integer
format: uint16
minimum: 1
maximum: 65535
responses:
'200':
description: Port information
content:
application/json:
schema:
$ref: '#/components/schemas/PortsResponse'
'400':
description: Bad request - Invalid port number
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Port not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/ports/{port}/kill:
post:
tags:
- Ports
summary: Kill processes on port
description: Terminates all processes listening on the specified port
operationId: killPort
parameters:
- name: port
in: path
required: true
description: Port number to kill processes on
schema:
type: integer
format: uint16
minimum: 1
maximum: 65535
responses:
'200':
description: Processes killed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'400':
description: Bad request - Invalid port number
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: No processes found on port
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/systemctl:
get:
tags:
- Systemctl
summary: List systemctl services
description: Returns a list of all systemctl services
operationId: listSystemctl
responses:
'200':
description: List of systemctl services
content:
application/json:
schema:
$ref: '#/components/schemas/SystemctlResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/systemctl/{service}:
get:
tags:
- Systemctl
summary: Get systemctl service status
description: Returns the status of a specific systemctl service
operationId: getSystemctlService
parameters:
- name: service
in: path
required: true
description: Service name (e.g., nginx, postgresql)
schema:
type: string
responses:
'200':
description: Service status
content:
application/json:
schema:
$ref: '#/components/schemas/SystemctlResponse'
'400':
description: Bad request - Invalid service name
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Service not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/pm2:
get:
tags:
- PM2
summary: List PM2 processes
description: Returns a list of all PM2 managed processes
operationId: listPm2
responses:
'200':
description: List of PM2 processes
content:
application/json:
schema:
$ref: '#/components/schemas/Pm2Response'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/pm2/{name}:
delete:
tags:
- PM2
summary: Delete PM2 process
description: Deletes a PM2 process by name
operationId: deletePm2
parameters:
- name: name
in: path
required: true
description: PM2 process name
schema:
type: string
responses:
'200':
description: Process deleted successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'400':
description: Bad request - Invalid process name
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Process not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/pm2/{name}/start:
post:
tags:
- PM2
summary: Start PM2 process
description: Starts a PM2 process by name
operationId: startPm2
parameters:
- name: name
in: path
required: true
description: PM2 process name
schema:
type: string
responses:
'200':
description: Process started successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'400':
description: Bad request - Invalid process name
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Process not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/pm2/{name}/stop:
post:
tags:
- PM2
summary: Stop PM2 process
description: Stops a PM2 process by name
operationId: stopPm2
parameters:
- name: name
in: path
required: true
description: PM2 process name
schema:
type: string
responses:
'200':
description: Process stopped successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'400':
description: Bad request - Invalid process name
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Process not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/pm2/{name}/restart:
post:
tags:
- PM2
summary: Restart PM2 process
description: Restarts a PM2 process by name
operationId: restartPm2
parameters:
- name: name
in: path
required: true
description: PM2 process name
schema:
type: string
responses:
'200':
description: Process restarted successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'400':
description: Bad request - Invalid process name
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Process not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/services:
get:
tags:
- Services
summary: List XBP services
description: Returns a list of all services defined in xbp.json
operationId: listServices
responses:
'200':
description: List of services
content:
application/json:
schema:
$ref: '#/components/schemas/ServicesResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/services/{name}/{command}:
post:
tags:
- Services
summary: Run service command
description: Executes a command on a specific service (build, install, start, dev)
operationId: runServiceCommand
parameters:
- name: name
in: path
required: true
description: Service name
schema:
type: string
- name: command
in: path
required: true
description: Command to execute
schema:
type: string
enum:
- build
- install
- start
- dev
- stop
responses:
'200':
description: Command executed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'400':
description: Bad request - Invalid service name or command
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Service not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/config:
get:
tags:
- Config
summary: Get configuration
description: Returns the current XBP configuration
operationId: getConfig
responses:
'200':
description: Configuration retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/logs:
get:
tags:
- Logs
summary: Get logs
description: Returns logs information
operationId: getLogs
responses:
'200':
description: Logs information
content:
application/json:
schema:
type: object
properties:
message:
type: string
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/install/{package}:
post:
tags:
- Installation
summary: Install package
description: Installs a package using XBP package installer
operationId: installPackage
parameters:
- name: package
in: path
required: true
description: Package name to install
schema:
type: string
responses:
'200':
description: Package installed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'400':
description: Bad request - Invalid package name
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Package not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/setup:
post:
tags:
- Installation
summary: Run setup
description: Runs the XBP setup process
operationId: setup
responses:
'200':
description: Setup completed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/redeploy:
post:
tags:
- Deployment
summary: Redeploy all services
description: Redeploys all services defined in the configuration
operationId: redeploy
responses:
'200':
description: Redeploy completed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/redeploy/{service_name}:
post:
tags:
- Deployment
summary: Redeploy specific service
description: Redeploys a specific service by name
operationId: redeployService
parameters:
- name: service_name
in: path
required: true
description: Service name to redeploy
schema:
type: string
responses:
'200':
description: Service redeployed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'400':
description: Bad request - Invalid service name
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Service not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/binary/download:
post:
tags:
- Binary
summary: Download and run binary
description: Downloads a binary from a URL and starts it as a PM2 process
operationId: downloadAndRunBinary
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BinaryDownloadRequest'
responses:
'200':
description: Binary downloaded and started successfully
content:
application/json:
schema:
$ref: '#/components/schemas/BinaryDownloadResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
HealthResponse:
type: object
required:
- status
- version
properties:
status:
type: string
example: ok
version:
type: string
example: 0.8.0
PortInfo:
type: object
required:
- port
- local_addr
- remote_addr
- state
- process
properties:
port:
type: integer
format: uint16
minimum: 1
maximum: 65535
example: 3000
pid:
type: string
nullable: true
example: '12345'
local_addr:
type: string
example: 127.0.0.1:3000
remote_addr:
type: string
example: 0.0.0.0:0
state:
type: string
example: Listen
process:
type: string
example: node
PortsResponse:
type: object
required:
- ports
properties:
ports:
type: array
items:
$ref: '#/components/schemas/PortInfo'
SystemctlService:
type: object
required:
- name
- status
- active
- enabled
properties:
name:
type: string
example: nginx.service
status:
type: string
example: active
active:
type: boolean
example: true
enabled:
type: boolean
example: true
SystemctlResponse:
type: object
required:
- services
properties:
services:
type: array
items:
$ref: '#/components/schemas/SystemctlService'
Pm2Process:
type: object
required:
- name
- status
properties:
name:
type: string
example: api-server
pid:
type: integer
format: uint32
nullable: true
example: 12345
status:
type: string
example: online
cpu:
type: number
format: double
nullable: true
example: 2.5
memory:
type: number
format: double
nullable: true
description: Memory usage in MB
example: 128.5
uptime:
type: string
nullable: true
example: 3600s
Pm2Response:
type: object
required:
- processes
properties:
processes:
type: array
items:
$ref: '#/components/schemas/Pm2Process'
ServiceInfo:
type: object
required:
- name
- target
- port
- branch
properties:
name:
type: string
example: api
target:
type: string
example: rust
port:
type: integer
format: uint16
example: 3000
branch:
type: string
example: main
url:
type: string
nullable: true
example: https://api.example.com
ServicesResponse:
type: object
required:
- services
properties:
services:
type: array
items:
$ref: '#/components/schemas/ServiceInfo'
BinaryDownloadRequest:
type: object
required:
- url
- name
properties:
url:
type: string
format: uri
example: https://github.com/user/repo/releases/download/v1.0.0/binary
name:
type: string
example: my-service
args:
type: array
items:
type: string
nullable: true
example:
- --port
- '8080'
BinaryDownloadResponse:
type: object
required:
- success
- message
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Binary downloaded and started as PM2 process: my-service'
pm2_name:
type: string
nullable: true
example: my-service
SuccessResponse:
type: object
required:
- success
- message
properties:
success:
type: boolean
example: true
message:
type: string
example: Operation completed successfully
ErrorResponse:
type: object
required:
- error
properties:
error:
type: string
example: An error occurred
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: JWT token authentication (optional, for future use)
security: []