# 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](/resources/changelog.md).

## Authentication

Every API call needs a Bearer token issued from **Dashboard → API**. See [Authentication](/api-reference/authentication.md) for details.

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

## Resource overview

| Resource                                         | Endpoint                  | Purpose                                 |
| ------------------------------------------------ | ------------------------- | --------------------------------------- |
| [Users](/api-reference/users.md)                 | `/users`                  | Account profile and security            |
| [Sub-users](/api-reference/sub-users.md)         | `/subusers`               | Per-product credentials and limits      |
| [Orders](/api-reference/orders.md)               | `/orders`, `/isp/batches` | Buying and managing IP batches          |
| [Subscriptions](/api-reference/subscriptions.md) | `/subscriptions`          | Recurring traffic and IP plans          |
| [Traffic & usage](/api-reference/traffic.md)     | `/{product}/traffic`      | Bandwidth and request analytics         |
| [Whitelists](/api-reference/whitelists.md)       | `/whitelists`             | IP allowlists for auth                  |
| [Sessions](/api-reference/sessions.md)           | `/{product}/sessions`     | Inspect active sticky sessions          |
| [Reports](/api-reference/reports.md)             | `/reports`                | Scheduled or ad-hoc exports             |
| [Rate limits](/api-reference/rate-limits.md)     | —                         | What we throttle and when               |
| [Postman collection](/api-reference/postman.md)  | —                         | 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:

```json
{
  "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.

```bash
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).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.helodata.com/api-reference/api-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.