{
  "openapi": "3.1.0",
  "info": {
    "title": "tunnel.to Dashboard API",
    "version": "0.1.0",
    "description": "API for tunnel.to accounts, names, relays, tunnel registration, downloads, and public relay metadata. IPv6 local upstream targets are supported when IPv6 literals use bracket notation."
  },
  "servers": [
    {
      "url": "https://tunnel.to",
      "description": "Production"
    },
    {
      "url": "http://localhost:8080",
      "description": "Local development"
    }
  ],
  "tags": [
    { "name": "Public" },
    { "name": "Auth" },
    { "name": "Tokens" },
    { "name": "Names" },
    { "name": "Tunnels" },
    { "name": "Relays" }
  ],
  "paths": {
    "/api/health": {
      "get": {
        "tags": ["Public"],
        "summary": "API health",
        "responses": {
          "200": {
            "description": "API, database, and Redis health status"
          }
        }
      }
    },
    "/api/downloads/latest": {
      "get": {
        "tags": ["Public"],
        "summary": "Latest client downloads",
        "responses": {
          "200": {
            "description": "Latest release metadata and artifact checksums"
          }
        }
      }
    },
    "/api/relays/public": {
      "get": {
        "tags": ["Public", "Relays"],
        "summary": "Public relay registry",
        "responses": {
          "200": {
            "description": "Healthy relay metadata for client selection"
          }
        }
      }
    },
    "/api/tunnels/register": {
      "post": {
        "tags": ["Tunnels"],
        "summary": "Register a tunnel and select a relay",
        "security": [{ "bearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/TunnelRegistrationRequest" },
              "examples": {
                "ipv4Localhost": {
                  "summary": "IPv4 or hostname target",
                  "value": {
                    "name": "claw",
                    "target_hint": "http://localhost:3000",
                    "client_version": "0.1.0",
                    "preferred_region": "ca-toronto"
                  }
                },
                "ipv6Loopback": {
                  "summary": "IPv6 loopback target",
                  "value": {
                    "name": "claw",
                    "target_hint": "http://[::1]:3000",
                    "client_version": "0.1.0",
                    "preferred_region": "ca-toronto"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Registered tunnel with selected relay connection details"
          }
        }
      }
    },
    "/api/relays/register": {
      "post": {
        "tags": ["Relays"],
        "summary": "Register or update relay metadata",
        "security": [{ "relaySecret": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/RelayRegistrationRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Relay registration accepted"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "CLI/client API token such as tt_live_..."
      },
      "relaySecret": {
        "type": "http",
        "scheme": "bearer",
        "description": "Shared relay secret from TUNNELTO_RELAY_SHARED_SECRET"
      }
    },
    "schemas": {
      "TunnelRegistrationRequest": {
        "type": "object",
        "required": ["target_hint", "client_version"],
        "properties": {
          "name": {
            "type": "string",
            "description": "Optional reserved tunnel name.",
            "examples": ["claw"]
          },
          "target_hint": {
            "type": "string",
            "format": "uri",
            "description": "Local upstream target. IPv6 literals must use bracket notation.",
            "examples": ["http://localhost:3000", "http://[::1]:3000"]
          },
          "client_version": {
            "type": "string",
            "examples": ["0.1.0"]
          },
          "preferred_region": {
            "type": "string",
            "examples": ["ca-toronto", "us-west"]
          }
        }
      },
      "RelayRegistrationRequest": {
        "type": "object",
        "required": ["slug", "region", "hostname", "public_url", "connect_url", "status", "version"],
        "properties": {
          "slug": { "type": "string", "examples": ["tor1"] },
          "region": { "type": "string", "examples": ["ca-toronto"] },
          "hostname": {
            "type": "string",
            "description": "Public relay hostname. Publish A and AAAA records for dual-stack reachability.",
            "examples": ["tor1.tunnel.to"]
          },
          "public_url": { "type": "string", "format": "uri", "examples": ["https://tor1.tunnel.to"] },
          "connect_url": { "type": "string", "format": "uri", "examples": ["wss://tor1.tunnel.to/connect"] },
          "status": { "type": "string", "examples": ["healthy"] },
          "version": { "type": "string", "examples": ["0.1.0"] }
        }
      }
    }
  }
}