docs/api.md

@@ -27,7 +27,13 @@ kubectl -n egress-proxies-operator-system port-forward \
   svc/egress-proxies-operator-controller-manager-discovery-service 8090:8090 &
 ```
 
-All examples below assume `localhost:8090` via that port-forward.
+Set `BASE_URL` to wherever you reach the API; all examples below use it:
+
+```sh
+export BASE_URL=localhost:8090   # via the port-forward above
+# or, from inside the cluster:
+# export BASE_URL=http://egress-proxies-operator-controller-manager-discovery-service.egress-proxies-operator-system.svc.cluster.local:8090
+```
 
 ## Authentication
 
@@ -46,7 +52,7 @@ Send the token on every request:
 
 ```sh
 export TOKEN=<the token>
-curl -s -H "Authorization: Bearer $TOKEN" localhost:8090/v1/proxies | jq
+curl -s -H "Authorization: Bearer $TOKEN" "$BASE_URL/v1/proxies" | jq
 ```
 
 A missing or wrong token gets `401 {"error":"unauthorized",...}`.
@@ -86,7 +92,7 @@ The shipped Deployment passes none of these flags, so the defaults apply.
 Liveness check. Unauthenticated, always `200` with body `ok`.
 
 ```sh
-curl -s localhost:8090/healthz
+curl -s "$BASE_URL/healthz"
 ```
 
 ### `GET /v1/proxies` — list proxies
@@ -101,13 +107,13 @@ Query parameters (all optional):
 List everything:
 
 ```sh
-curl -s localhost:8090/v1/proxies | jq
+curl -s "$BASE_URL/v1/proxies" | jq
 ```
 
 List healthy proxies in a given geo:
 
 ```sh
-curl -s 'localhost:8090/v1/proxies?healthy=true&attr.geo=eu' | jq
+curl -s "$BASE_URL/v1/proxies?healthy=true&attr.geo=eu" | jq
 ```
 
 Response — `200`, proxies sorted by `id`, an empty match is `200` with
@@ -168,7 +174,7 @@ Request body (every field optional; `{}` is valid):
 | `target` | none | The site you intend to crawl; enables per-target cooldowns (see below) |
 
 ```sh
-curl -s -XPOST localhost:8090/v1/leases \
+curl -s -XPOST "$BASE_URL/v1/leases" \
   -d '{"selector":{"geo":"eu"},"ttlSeconds":300,"target":"example.com"}' | jq
 ```
 
@@ -228,7 +234,7 @@ Frees the lease's capacity slot immediately. Idempotent: always `204`,
 including for unknown or already-expired lease IDs.
 
 ```sh
-curl -si -XDELETE localhost:8090/v1/leases/P3X6HHQTPCM5UTGVGE3B5UPS3A
+curl -si -XDELETE "$BASE_URL/v1/leases/P3X6HHQTPCM5UTGVGE3B5UPS3A"
 ```
 
 ### `POST /v1/leases/{id}/report` — report an outcome
@@ -248,7 +254,7 @@ Request body:
 | `target` | optional | Which site produced the result; falls back to the lease's `target`, then to global |
 
 ```sh
-curl -si -XPOST localhost:8090/v1/leases/P3X6HHQTPCM5UTGVGE3B5UPS3A/report \
+curl -si -XPOST "$BASE_URL/v1/leases/P3X6HHQTPCM5UTGVGE3B5UPS3A/report" \
   -d '{"result":"rate_limited","target":"example.com"}'
 ```
 
@@ -287,7 +293,7 @@ Cooldowns are keyed by **(proxy, target)**:
 
 ```sh
 # 1. Acquire a lease for crawling example.com through an EU proxy
-LEASE=$(curl -s -XPOST localhost:8090/v1/leases \
+LEASE=$(curl -s -XPOST "$BASE_URL/v1/leases" \
   -H "Authorization: Bearer $TOKEN" \
   -d '{"selector":{"geo":"eu"},"ttlSeconds":600,"target":"example.com"}')
 LEASE_ID=$(echo "$LEASE" | jq -r .leaseID)
@@ -298,12 +304,12 @@ curl -x "http://$PROXY" https://example.com/some/page
 
 # 3. Got a 429? Report it — example.com-bound leases will avoid this
 #    proxy for the next 15 minutes
-curl -s -XPOST "localhost:8090/v1/leases/$LEASE_ID/report" \
+curl -s -XPOST "$BASE_URL/v1/leases/$LEASE_ID/report" \
   -H "Authorization: Bearer $TOKEN" \
   -d '{"result":"rate_limited","target":"example.com"}'
 
 # 4. Done early? Release the slot (otherwise the TTL frees it)
-curl -s -XDELETE "localhost:8090/v1/leases/$LEASE_ID" \
+curl -s -XDELETE "$BASE_URL/v1/leases/$LEASE_ID" \
   -H "Authorization: Bearer $TOKEN"
 ```