REST API overview

Quickstart

All API requests use HTTPS and JSON. The base URL is https://api.vless.blog. Start by listing the services available to your token.

curl https://api.vless.blog/v1/services \
  -H "Authorization: Bearer $GATEWAY_TOKEN" \
  -H "Accept: application/json"

{
  "data": [
    { "id": "svc_payments", "name": "payments", "status": "healthy" }
  ],
  "request_id": "req_01J5D5W8R9F2"
}

Authentication

Pass a workspace token in the Authorization header. Tokens are scoped to environments and routes; a production token cannot modify a development route.

Authorization: Bearer gw_live_••••••••••••

Core endpoints

Management endpoints configure the gateway. Proxy endpoints carry application traffic and preserve the upstream status code and body.

Lists services visible to the current token. Use cursor and limit for pagination.

Creates a named route to an existing service. Route names are unique within an environment.

curl -X POST https://api.vless.blog/v1/routes \
  -H "Authorization: Bearer $GATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "payments",
    "service_id": "svc_payments",
    "timeout_ms": 3000,
    "retry_count": 1
  }'

Forwards a request through the named route. Query parameters, body, and supported headers are sent to the upstream service.

Returns gateway timing, selected upstream, retry count, and final outcome for one request. Request metadata is retained for 30 days.

Responses

Management endpoints return a JSON object. Proxy endpoints return the upstream body, plus gateway metadata in headers.

Error handling

Gateway errors use a stable machine-readable code. A failed upstream remains distinguishable from a rejected gateway request.

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Request quota exceeded for route payments.",
    "request_id": "req_01J5D62AYM0P"
  }
}