relay.api
PRIVATE API
Back to overview
API REFERENCE / V1

VPN catalog API

A stable, authenticated interface for your server catalog, app configuration, and OpenVPN profiles.

BASE URL/api/public/v1STABLE

Getting started

Send requests to the base URL with your shared wrapper key in the x-api-key header. The provider address and any provider credentials remain server-side.

cURL
curl "/api/public/v1/servers?page=1&per_page=20" \ -H "x-api-key: YOUR_WRAPPER_KEY"

Authentication

All catalog endpoints require the shared API key. Include it with every request. The key is checked before forwarding a call.

Headerx-api-key: YOUR_WRAPPER_KEY

Missing or invalid keys receive 401 Unauthorized. Never put the key in a URL, browser app, public repository, or mobile binary; keep it in a trusted server environment.

Endpoints

GET/app-config

Application name, branding, social links, and gate policy.

GET/servers?page=1&per_page=20

Paginated VPN server catalog.

GET/servers/{id}

Details and availability for a server ID.

GET/servers/{id}/profile SENSITIVE

Raw OpenVPN profile for the selected server. Treat the response as sensitive configuration.

GET/countries

Available countries and flag metadata.

GET/apk-updates/latest

Latest APK version and update metadata.

Only the routes shown above are forwarded. Unsupported paths and methods are rejected.

Pagination

Use the server list query parameters below. Responses retain the provider envelope, including current page, last page, page size, total, and navigation links.

PARAMETERDEFAULTLIMIT
pageProvider default1 – 100,000
per_pageProvider default1 – 100

Responses & limits

  • Successful calls pass through the provider status, body, and selected safe response headers.
  • Unknown paths return 404; invalid pagination values are rejected before forwarding.
  • Provider unavailable or timed out returns 502.
  • Response size is capped at 8 MB; calls time out after 12 seconds.
  • Usage policy permits GET only; request bodies, cookies, and caller-supplied provider headers are not forwarded.

Security & monitoring

Provider is masked

Upstream address and response headers that identify it are not exposed.

Metrics without payloads

Only route name, status, duration, and time are retained for 24-hour aggregates.

API keys, request content, caller IP addresses, and VPN profile contents are never saved to monitoring records. Profile responses should still be handled as sensitive material by the calling service.