Skip to content
ProxyRequest/ DOCS

API fundamentals

Use the API hostname assigned to your deployment, with the /api/v1 prefix:

https://{api_host}/api/v1

Replace {api_host} with your deployment’s API hostname, without a scheme or path. Values in braces are placeholders, not literal credentials. The proxy gateway host and port are separate; they do not receive REST requests.

Authentication schemes

Section titled “Authentication schemes”

Using JavaScript, TypeScript, Python or PHP? Install the official SDK, then select its tab in a Request window below. The SDK configures the same authentication headers for you.

JWT bearer

Use the login and refresh operations for an account session. Send the access token as Authorization: Bearer {access_token}.

Static API key

Create a key through the API-key resource and send it as Authorization: Static {api_key} for server-to-server integrations.

RequestGET /profile
curl 'https://{api_host}/api/v1/profile' \
  --header 'Authorization: Bearer {access_token}'
Response200 OK

Selected fields

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "username": "customer_demo_42",
  "is_reseller": false,
  "is_superuser": false,
  "orders": []
}
Show full responseShow selected fields
{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "username": "customer_demo_42",
  "email": "",
  "is_reseller": false,
  "is_marketer": false,
  "is_superuser": false,
  "date_joined": "2026-09-16T12:00:00Z",
  "date_joined_ts": 1789560000,
  "first_name": "",
  "last_name": "",
  "balance": 0,
  "language": "en",
  "country": "",
  "state": "",
  "city": "",
  "address": "",
  "zip": "",
  "company_name": "",
  "company_address": "",
  "company_city": "",
  "company_postal_code": "",
  "company_country": "",
  "company_vat_number": "",
  "allowed_ips": [],
  "blocked_domains": [],
  "connection_limit": 100,
  "parent_id": "550e8400-e29b-41d4-a716-446655440010",
  "sub_users": 0,
  "referrals": 0,
  "referral_id": "",
  "referral_code": "example42",
  "referral_data_earned": 0,
  "referral_data_pending": 0,
  "referral_balance_pending": 0,
  "referral_balance_earned": 0,
  "currency": {
    "code": "USD",
    "symbol": "$"
  },
  "coupons": [],
  "orders": []
}

Replace placeholders in braces with your values. Responses use synthetic example data.Install SDKsAPI reference →

JSON requests

Section titled “JSON requests”

Send JSON for request bodies unless an operation explicitly documents another media type:

Content-Type: application/json
Accept: application/json

UUID-like resource identifiers should be treated as opaque strings. Do not parse business meaning from them.

Pagination

Section titled “Pagination”

List operations commonly accept limit and offset and return a page envelope:

{
  "count": 125,
  "next": "https://{api_host}/api/v1/users?limit=25&offset=25",
  "previous": null,
  "results": []
}

Follow next until it is null when a complete export is required. For an interactive UI, keep the selected limit stable and store the current offset in view state.

Error model

Section titled “Error model”

Errors can contain detail, non_field_errors, or dynamic field arrays. Internal localization keys are not exposed:

{
  "non_field_errors": ["The request could not be processed."]
}
StatusIntegration response
400Show field-safe validation feedback and preserve the submitted form
401Refresh a JWT once or replace an invalid key; do not retry indefinitely
403Stop and check account role or resource ownership
404Verify both the identifier and authenticated account scope
409Read the error details, resolve the operation conflict, and retry only when instructed
412Re-read the resource: your If-Match validator is stale
429Respect retry guidance and reduce request rate
5xxRetry safe reads with bounded backoff and record the request context

Use Accept-Language to request human-readable error messages; Content-Language identifies the selected language. Unsupported or omitted languages fall back to English. Do not use translated message text as a stable error code.

Roles, units and safe writes

Section titled “Roles, units and safe writes”

A static key acts with its owner’s permissions; it does not make a reseller an administrator. In particular, status=paid requires is_superuser, and targeting another account in an invoice also requires is_reseller. Sub-users cannot create another user generation or create invoices themselves. See account and security workflows.

Data amounts are integer bytes. In these guides 1 GiB is 1,073,741,824 bytes; decimal 1 GB is 1,000,000,000 bytes. Monetary amount is a different unit: the smallest currency unit. Invoice expires is a Unix timestamp in seconds, while read responses can use ISO dates. Keep the units with each field in your local model.

Before implementing purchases or allocations, read retries and concurrent changes. It explains how to recover an uncertain write, handle 409, and use ETag/If-Match to avoid lost updates.

Catalog caching

Section titled “Catalog caching”

Cache packages and location catalogs in your application, but do not hard-code a universal TTL that the API does not publish. Refresh on package changes, administrative invalidation, or a cache miss. Do not cache balance-changing responses as catalog data.

Browse exact parameters and responses in the generated API Reference or download the OpenAPI YAML.