API Reference

WG-CP is API-first. You can manage networks completely via HTTP. Note: All API endpoints enforce a minimum 1-second response delay to mitigate misconfigured or malfunctioning agents.

Authentication & Concurrency

  • Authentication: If admin_tokens or write_tokens is set in your YAML, include an Authorization: Bearer <token> header. Note: write_tokens only protect mutations (POST/DELETE).
  • Concurrency: To prevent stale overwrites, add a write_barrier: <integer> to the root of your YAML. Updates will be rejected (HTTP 409) if the incoming barrier is not greater than or equal to the stored one.

Endpoints

1. Create Network

POST /api/v1/networks
Creates a new network namespace and returns its ID.

curl -X POST https://w1.wgcp.dev/api/v1/networks
# Response: {"id": "..."}

2. Push Configuration

POST /api/v1/networks/:networkId/yaml
Updates the network configuration. Send raw YAML in the body.

curl -X POST https://w1.wgcp.dev/api/v1/networks/:networkId/yaml \
  -H "Content-Type: text/plain" \
  --data-binary @network.yml

3. Fetch Global Hosts File

GET /api/v1/networks/:networkId/hosts
Returns a plain-text /etc/hosts compatible file for the entire network.

curl -s "https://w1.wgcp.dev/api/v1/networks/:networkId/hosts"

4. Fetch Agent Config (WireGuard Format)

GET /api/v1/networks/:networkId/config/:pubkey
Generates the wg0.conf format for a specific node based on its public key. No auth required.

WireGuard Configuration (.conf): Returns the literal WireGuard configuration file for the node. Use this for initial setup, manual provisioning, or one-off fetches.

curl -s "https://w1.wgcp.dev/api/v1/networks/:networkId/config/:publicKey"

Streaming Updates (NDJSON): Append ?stream=true to receive a persistent NDJSON stream of updates. The stream outputs JSON objects containing the latest configuration (e.g., {"status":200,"config":"..."}) as network state changes.

curl -sN "https://w1.wgcp.dev/api/v1/networks/:networkId/config/:publicKey?stream=true"

5. Read Raw YAML

GET /api/v1/networks/:networkId/yaml
Fetches the current raw YAML configuration.

curl -X GET https://w1.wgcp.dev/api/v1/networks/:networkId/yaml

6. Delete Network

DELETE /api/v1/networks/:networkId
Deletes the network and all configurations.

curl -X DELETE https://w1.wgcp.dev/api/v1/networks/:networkId