Files

GitHub Actions 1426c6f885 docs: complete feature documentation rewrite

Comprehensive documentation overhaul for Charon features:

Rewrite features.md as marketing overview (87% reduction)
Create comprehensive dns-challenge.md for new DNS feature
Expand 18 feature stub pages into complete documentation:
SSL certificates, CrowdSec, WAF, ACLs, rate limiting
Security headers, proxy headers, web UI, Docker integration
Caddyfile import, logs, WebSocket, backup/restore
Live reload, localization, API, UI themes, supply chain security
Update README.md with DNS Challenge in Top Features
Total: ~2,000+ lines of new user-facing documentation

Refs: #21, #461

2026-01-15 02:50:06 +00:00

4.5 KiB

Raw Blame History

title, description

title	description
REST API	Comprehensive REST API for automation and integrations

REST API

Automate everything. Charon's comprehensive REST API lets you manage hosts, certificates, security rules, and settings programmatically. Perfect for CI/CD pipelines, Infrastructure as Code, or custom integrations.

Overview

The REST API provides full control over Charon's functionality through HTTP endpoints. All responses are JSON-formatted, and the API follows RESTful conventions for resource management.

Base URL: http://your-charon-instance:81/api

Authentication

All API requests require a Bearer token. Generate tokens in Settings → API Tokens.

# Include in all requests
Authorization: Bearer your-api-token-here

Tokens support granular permissions:

Read-only: View configurations without modification
Full access: Complete CRUD operations
Scoped: Limit to specific resource types

Why Use the API?

Use Case	Benefit
CI/CD Pipelines	Automatically create proxy hosts for staging/preview deployments
Infrastructure as Code	Version control your Charon configuration
Custom Dashboards	Build monitoring integrations
Bulk Operations	Manage hundreds of hosts programmatically
GitOps Workflows	Sync configuration from Git repositories

Key Endpoints

Proxy Hosts

# List all proxy hosts
curl -X GET "http://charon:81/api/nginx/proxy-hosts" \
  -H "Authorization: Bearer $TOKEN"

# Create a proxy host
curl -X POST "http://charon:81/api/nginx/proxy-hosts" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domain_names": ["app.example.com"],
    "forward_host": "10.0.0.5",
    "forward_port": 3000,
    "ssl_forced": true,
    "certificate_id": 1
  }'

# Update a proxy host
curl -X PUT "http://charon:81/api/nginx/proxy-hosts/1" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"forward_port": 8080}'

# Delete a proxy host
curl -X DELETE "http://charon:81/api/nginx/proxy-hosts/1" \
  -H "Authorization: Bearer $TOKEN"

SSL Certificates

# List certificates
curl -X GET "http://charon:81/api/nginx/certificates" \
  -H "Authorization: Bearer $TOKEN"

# Request new Let's Encrypt certificate
curl -X POST "http://charon:81/api/nginx/certificates" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "letsencrypt",
    "domain_names": ["secure.example.com"],
    "meta": {"dns_challenge": true, "dns_provider": "cloudflare"}
  }'

DNS Providers

# List configured DNS providers
curl -X GET "http://charon:81/api/nginx/dns-providers" \
  -H "Authorization: Bearer $TOKEN"

# Add a DNS provider (for DNS-01 challenges)
curl -X POST "http://charon:81/api/nginx/dns-providers" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cloudflare Production",
    "acme_dns_provider": "cloudflare",
    "meta": {"CF_API_TOKEN": "your-cloudflare-token"}
  }'

Security Settings

# Get WAF status
curl -X GET "http://charon:81/api/security/waf" \
  -H "Authorization: Bearer $TOKEN"

# Enable WAF for a host
curl -X PUT "http://charon:81/api/nginx/proxy-hosts/1" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"waf_enabled": true, "waf_mode": "block"}'

# List CrowdSec decisions
curl -X GET "http://charon:81/api/security/crowdsec/decisions" \
  -H "Authorization: Bearer $TOKEN"

CI/CD Integration Example

GitHub Actions

- name: Create Preview Environment
  run: |
    curl -X POST "${{ secrets.CHARON_URL }}/api/nginx/proxy-hosts" \
      -H "Authorization: Bearer ${{ secrets.CHARON_TOKEN }}" \
      -H "Content-Type: application/json" \
      -d '{
        "domain_names": ["pr-${{ github.event.number }}.preview.example.com"],
        "forward_host": "${{ steps.deploy.outputs.ip }}",
        "forward_port": 3000
      }'

Error Handling

The API returns standard HTTP status codes:

Code	Meaning
`200`	Success
`201`	Resource created
`400`	Invalid request body
`401`	Invalid or missing token
`403`	Insufficient permissions
`404`	Resource not found
`500`	Server error

Backup & Restore - API-managed backups
SSL Certificates - Certificate automation
Back to Features

4.5 KiB Raw Blame History