Overview

The helodata REST API lets you manage everything you'd otherwise click in the dashboard — sub-users, orders, whitelists, traffic reports — programmatically. Use it for provisioning, billing pipelines, and custom dashboards.

The API is separate from the proxy gateway: the gateway lives at gate.helodata.io, the API at api.helodata.com.

Base URL

https://api.helodata.com/v1

All endpoints are versioned in the URL. Breaking changes ship as a new major version with a 6-month deprecation window — see Changelog.

Authentication

Every API call needs a Bearer token issued from Dashboard → API. See Authentication for details.

curl -H "Authorization: Bearer API_KEY" https://api.helodata.com/v1/users/me

Resource overview

Resource	Endpoint	Purpose
Users	/users	Account profile and security
Sub-users	/subusers	Per-product credentials and limits
Orders	/orders, /isp/batches	Buying and managing IP batches
Subscriptions	/subscriptions	Recurring traffic and IP plans
Traffic & usage	/{product}/traffic	Bandwidth and request analytics
Whitelists	/whitelists	IP allowlists for auth
Sessions	/{product}/sessions	Inspect active sticky sessions
Reports	/reports	Scheduled or ad-hoc exports
Rate limits	—	What we throttle and when
Postman collection	—	Importable collection for the whole API

Conventions

• Content type: application/json on all writes
• Dates: RFC 3339 / ISO 8601 in UTC
• IDs: ULIDs prefixed by resource type (sub_01HX…, bat_01HX…, ord_01HX…)
• Pagination: cursor-based via ?cursor=…&limit=…; Link header points to the next page
• Errors: structured JSON with code, message, request_id

Example error:

{
  "code":       "invalid_argument",
  "message":    "region must be a 2-letter ISO 3166 code",
  "request_id": "req_01HX2K3PQ4M5",
  "field":      "region"
}

Include the request_id when contacting support so we can trace the call.

Idempotency

Mutating endpoints accept an Idempotency-Key header — any string up to 64 chars. Retries that share the same key get the same response, so you can safely retry network failures.

curl -X POST \
     -H "Authorization: Bearer API_KEY" \
     -H "Idempotency-Key: order-2026-05-28-001" \
     -H "Content-Type: application/json" \
     -d '{"product":"residential","gb":50}' \
     https://api.helodata.com/v1/orders

Webhooks

Subscribe to events (order completed, batch expiring, traffic threshold) via Dashboard → API → Webhooks. Payload format and signing key are documented in the Webhooks page (coming soon).