OutFleet/API.md

# OutFleet Xray Admin API

Base URL: `http://localhost:8080`

## Overview
Complete API documentation for OutFleet - a web admin panel for managing xray-core VPN proxy servers.

## Base Endpoints

### Health Check
- `GET /health` - Service health check

**Response:**
```json
{
  "status": "ok",
  "service": "xray-admin", 
  "version": "0.1.0"
}
```

## API Endpoints

All API endpoints are prefixed with `/api`.

### Users

#### List Users
- `GET /users?page=1&per_page=20` - Get paginated list of users

#### Search Users
- `GET /users/search?q=john` - Universal search for users
  
**Search capabilities:**
- By name (partial match, case-insensitive): `?q=john`
- By telegram_id: `?q=123456789`
- By user UUID: `?q=550e8400-e29b-41d4-a716-446655440000`

**Response:** Array of user objects (limited to 100 results)
```json
[
  {
    "id": "uuid",
    "name": "string",
    "comment": "string|null",
    "telegram_id": "number|null",
    "created_at": "timestamp",
    "updated_at": "timestamp"
  }
]
```

#### Get User
- `GET /users/{id}` - Get user by ID

#### Create User
- `POST /users` - Create new user
```json
{
  "name": "John Doe",
  "comment": "Admin user",
  "telegram_id": 123456789
}
```

#### Update User  
- `PUT /users/{id}` - Update user by ID
```json
{
  "name": "Jane Doe",
  "comment": null,
  "telegram_id": 987654321
}
```

#### Delete User
- `DELETE /users/{id}` - Delete user by ID

#### Get User Access
- `GET /users/{id}/access?include_uris=true` - Get user access to inbounds (optionally with client URIs)

**Query Parameters:**
- `include_uris`: boolean (optional) - Include client configuration URIs in response

**Response (without URIs):**
```json
[
  {
    "id": "uuid",
    "user_id": "uuid",
    "server_inbound_id": "uuid", 
    "xray_user_id": "string",
    "level": 0,
    "is_active": true
  }
]
```

**Response (with URIs):**
```json
[
  {
    "id": "uuid",
    "user_id": "uuid",
    "server_inbound_id": "uuid", 
    "xray_user_id": "string",
    "level": 0,
    "is_active": true,
    "uri": "vless://uuid@hostname:port?parameters#alias",
    "protocol": "vless",
    "server_name": "Server Name",
    "inbound_tag": "inbound-tag"
  }
]
```

#### Generate Client Configurations
- `GET /users/{user_id}/configs` - Get all client configuration URIs for a user
- `GET /users/{user_id}/access/{inbound_id}/config` - Get specific client configuration URI

**Response:**
```json
{
  "user_id": "uuid",
  "server_name": "string",
  "inbound_tag": "string", 
  "protocol": "vmess|vless|trojan|shadowsocks",
  "uri": "protocol://uri_string",
  "qr_code": null
}
```

### Servers

#### List Servers
- `GET /servers` - Get all servers

**Response:**
```json
[
  {
    "id": "uuid",
    "name": "string",
    "hostname": "string",
    "grpc_hostname": "string", 
    "grpc_port": 2053,
    "status": "online|offline|error|unknown",
    "default_certificate_id": "uuid|null",
    "created_at": "timestamp",
    "updated_at": "timestamp",
    "has_credentials": true
  }
]
```

#### Get Server
- `GET /servers/{id}` - Get server by ID

#### Create Server
- `POST /servers` - Create new server

**Request:**
```json
{
  "name": "Server Name",
  "hostname": "server.example.com",
  "grpc_hostname": "192.168.1.100", // optional, defaults to hostname
  "grpc_port": 2053, // optional, defaults to 2053
  "api_credentials": "optional credentials",
  "default_certificate_id": "uuid" // optional
}
```

#### Update Server
- `PUT /servers/{id}` - Update server

**Request:** (all fields optional)
```json
{
  "name": "New Server Name",
  "hostname": "new.server.com",
  "grpc_hostname": "192.168.1.200",
  "grpc_port": 2054,
  "api_credentials": "new credentials", 
  "status": "online",
  "default_certificate_id": "uuid"
}
```

#### Delete Server
- `DELETE /servers/{id}` - Delete server

#### Test Server Connection
- `POST /servers/{id}/test` - Test connection to server

**Response:**
```json
{
  "connected": true,
  "endpoint": "192.168.1.100:2053"
}
```

#### Get Server Statistics
- `GET /servers/{id}/stats` - Get server statistics

### Server Inbounds

#### List Server Inbounds
- `GET /servers/{server_id}/inbounds` - Get all inbounds for a server

**Response:**
```json
[
  {
    "id": "uuid",
    "server_id": "uuid", 
    "template_id": "uuid",
    "template_name": "string",
    "tag": "string",
    "port_override": 8080,
    "certificate_id": "uuid|null",
    "variable_values": {},
    "is_active": true,
    "created_at": "timestamp",
    "updated_at": "timestamp"
  }
]
```

#### Get Server Inbound
- `GET /servers/{server_id}/inbounds/{inbound_id}` - Get specific inbound

#### Create Server Inbound
- `POST /servers/{server_id}/inbounds` - Create new inbound for server

**Request:**
```json
{
  "template_id": "uuid",
  "port": 8080,
  "certificate_id": "uuid", // optional
  "is_active": true
}
```

#### Update Server Inbound
- `PUT /servers/{server_id}/inbounds/{inbound_id}` - Update inbound

**Request:** (all fields optional)
```json
{
  "tag": "new-tag",
  "port_override": 8081,
  "certificate_id": "uuid",
  "variable_values": {"domain": "example.com"},
  "is_active": false
}
```

#### Delete Server Inbound
- `DELETE /servers/{server_id}/inbounds/{inbound_id}` - Delete inbound

### User-Inbound Management

#### Add User to Inbound
- `POST /servers/{server_id}/inbounds/{inbound_id}/users` - Grant user access to inbound

**Request:**
```json
{
  "user_id": "uuid", // optional, will create new user if not provided
  "name": "username",
  "comment": "User description", // optional
  "telegram_id": 123456789, // optional
  "level": 0 // optional, defaults to 0
}
```

#### Remove User from Inbound
- `DELETE /servers/{server_id}/inbounds/{inbound_id}/users/{email}` - Remove user access

#### Get Inbound Client Configurations  
- `GET /servers/{server_id}/inbounds/{inbound_id}/configs` - Get all client configuration URIs for an inbound

**Response:**
```json
[
  {
    "user_id": "uuid",
    "server_name": "string",
    "inbound_tag": "string",
    "protocol": "vmess|vless|trojan|shadowsocks", 
    "uri": "protocol://uri_string",
    "qr_code": null
  }
]
```

### Certificates

#### List Certificates
- `GET /certificates` - Get all certificates

#### Get Certificate
- `GET /certificates/{id}` - Get certificate by ID

#### Create Certificate
- `POST /certificates` - Create new certificate

**Request:**
```json
{
  "name": "Certificate Name",
  "cert_type": "self_signed|letsencrypt",
  "domain": "example.com", 
  "auto_renew": true,
  "certificate_pem": "-----BEGIN CERTIFICATE-----...",
  "private_key": "-----BEGIN PRIVATE KEY-----..."
}
```

#### Update Certificate
- `PUT /certificates/{id}` - Update certificate

**Request:** (all fields optional)
```json
{
  "name": "New Certificate Name",
  "auto_renew": false
}
```

#### Delete Certificate
- `DELETE /certificates/{id}` - Delete certificate

#### Get Certificate Details
- `GET /certificates/{id}/details` - Get detailed certificate information

#### Get Expiring Certificates
- `GET /certificates/expiring` - Get certificates that are expiring soon

### Templates

#### List Templates
- `GET /templates` - Get all inbound templates

#### Get Template
- `GET /templates/{id}` - Get template by ID

#### Create Template
- `POST /templates` - Create new inbound template

**Request:**
```json
{
  "name": "Template Name",
  "protocol": "vmess|vless|trojan|shadowsocks",
  "default_port": 8080,
  "requires_tls": true,
  "config_template": "JSON template string"
}
```

#### Update Template
- `PUT /templates/{id}` - Update template

**Request:** (all fields optional)
```json
{
  "name": "New Template Name",
  "description": "Template description", 
  "default_port": 8081,
  "base_settings": {},
  "stream_settings": {},
  "requires_tls": false,
  "requires_domain": true,
  "variables": [],
  "is_active": true
}
```

#### Delete Template
- `DELETE /templates/{id}` - Delete template

## Response Format

### User Object
```json
{
  "id": "uuid",
  "name": "string",
  "comment": "string|null", 
  "telegram_id": "number|null",
  "created_at": "timestamp",
  "updated_at": "timestamp"
}
```

### Users List Response
```json
{
  "users": [UserObject],
  "total": 100,
  "page": 1,
  "per_page": 20
}
```

### Server Object
```json
{
  "id": "uuid",
  "name": "string", 
  "hostname": "string",
  "grpc_hostname": "string",
  "grpc_port": 2053,
  "status": "online|offline|error|unknown",
  "default_certificate_id": "uuid|null",
  "created_at": "timestamp",
  "updated_at": "timestamp", 
  "has_credentials": true
}
```

### Server Inbound Object
```json
{
  "id": "uuid",
  "server_id": "uuid",
  "template_id": "uuid", 
  "template_name": "string",
  "tag": "string",
  "port_override": 8080,
  "certificate_id": "uuid|null",
  "variable_values": {},
  "is_active": true,
  "created_at": "timestamp",
  "updated_at": "timestamp"
}
```

### Certificate Object
```json
{
  "id": "uuid",
  "name": "string",
  "cert_type": "self_signed|letsencrypt", 
  "domain": "string",
  "auto_renew": true,
  "expires_at": "timestamp|null",
  "created_at": "timestamp",
  "updated_at": "timestamp"
}
```

### Template Object  
```json
{
  "id": "uuid",
  "name": "string",
  "description": "string|null",
  "protocol": "vmess|vless|trojan|shadowsocks",
  "default_port": 8080,
  "base_settings": {},
  "stream_settings": {},
  "requires_tls": true,
  "requires_domain": false,
  "variables": [],
  "is_active": true,
  "created_at": "timestamp",
  "updated_at": "timestamp"
}
```

### Inbound User Object
```json
{
  "id": "uuid",
  "user_id": "uuid",
  "server_inbound_id": "uuid",
  "xray_user_id": "string",
  "password": "string|null",
  "level": 0,
  "is_active": true,
  "created_at": "timestamp", 
  "updated_at": "timestamp"
}
```

## Status Codes
- `200` - Success
- `201` - Created  
- `204` - No Content (successful deletion)
- `400` - Bad Request (invalid data)
- `404` - Not Found
- `409` - Conflict (duplicate data, e.g. telegram_id)
- `500` - Internal Server Error

## Error Response Format
```json
{
  "error": "Error message description",
  "code": "ERROR_CODE",
  "details": "Additional error details"
}
```