Get started
For partners

Partner API

Buy and manage hosting, business email and VPS servers for your clients from your own systems — paid from your partner balance at your partner prices.

Base URL
https://api.rivervo.com/api/partner/v1
Partner section in the panel Partner programme

API keys and the webhook are managed by you in the Partner section of the Rivervo panel. OpenAPI 3.1 (JSON)

Guide

Authentication

Create an API key in the Partner section of the Rivervo panel. The key is shown once — keep it on your server, never in a browser or a mobile app. Send it on every call:

http
Authorization: Bearer 12|3c9f…
  • Requests and answers are JSON. Amounts are integer US cents (6300 = $63.00); dates are ISO 8601.
  • The key works only on the Partner API (not in the customer panel), and the Partner API accepts no other token.
  • If your account has an IP allowlist, calls from other addresses get 403 ip_not_allowed. A suspended partner account gets 403 partner_inactive.
  • A leaked key: revoke it in the panel and create a new one.
bash
curl https://api.rivervo.com/api/partner/v1/me \
  -H "Authorization: Bearer $RIVERVO_API_KEY"

Idempotency-Key

Every call that changes something (POST, PUT, PATCH, DELETE) must carry an Idempotency-Key header — your own unique value for this change, 1–128 characters of letters, digits, - _ . :. Your order or invoice number works well.

http
Idempotency-Key: inv-2026-0042
  • Same key + same request → the first answer again, with the header Idempotent-Replayed: true. Never a second charge, so a timeout is safe to retry.
  • Same key + a different request → 409 idempotency_conflict. While the first is still running → 409 idempotency_in_progress.
  • No key → 400 idempotency_key_required.
  • Secrets (a new password, a sign-in link, a root password) are only in the first answer; a replay returns them as null.

Errors

Every error has the same shape:

json
{"error": {
  "code": "insufficient_funds",
  "message": "Not enough partner balance: this costs 63.00 USD, available 10.00 USD (balance plus credit limit)."
}}
HTTPcodemeaning
400idempotency_key_required, bad_requestFix the request.
401unauthenticatedMissing or wrong API key.
402insufficient_fundsThe partner balance does not cover it; nothing is charged.
403forbidden, ip_not_allowed, partner_inactiveNot allowed for this key, this IP address or this partner account.
404not_foundNot yours, or does not exist.
409idempotency_conflict, idempotency_in_progress, conflictThe Idempotency-Key was used for another request, or the first one is still running.
410not_availableThe feature is not available for this service.
422validation_failed (+ fields), refusedValid JSON that cannot be done; the message says why.
422out_of_stockPOST /vps: the location has no room for the plan right now — see VPS availability.
429rate_limitedSlow down; wait for the Retry-After seconds.
502upstream_failedCould not be done right now; nothing is charged — try again later.
500internal_errorOur fault; we are told automatically.

validation_failed adds fields — the field names with their messages. A failed change still has an order (status: failed with error), also returned in the error answer under order.

Orders and asynchronous operations

Every change becomes an order, returned next to the result:

json
{"data": {…},
 "order": {"id": 812, "action": "hosting.create", "status": "processing",
   "idempotency_key": "inv-2026-0042", "resource": {"type": "hosting", "id": 3301},
   "charged_cents": 6300, "retail_cents": 9000, "currency": "USD",
   "error": null, "created_at": "…", "completed_at": null}}

Creating a hosting account or a server takes a little while: the answer is 202 Accepted with the order in processing. It becomes completed when the service is ready, or failed. Follow it with GET /orders/{id} or, better, with the webhooks. GET /orders?status=processing lists the ones still running.

bash
curl -X POST https://api.rivervo.com/api/partner/v1/hosting \
  -H "Authorization: Bearer $RIVERVO_API_KEY" \
  -H "Idempotency-Key: client-417-hosting" \
  -H "Content-Type: application/json" \
  -d '{"domain": "client.az", "plan_id": 2, "term_months": 12}'

# 202 Accepted → later:
curl https://api.rivervo.com/api/partner/v1/orders/812 \
  -H "Authorization: Bearer $RIVERVO_API_KEY"

Partner balance

  • Every purchase and renewal through the API is paid from your partner balance at your partner price. GET /me shows the balance, the credit limit and your discounts.
  • If available_cents (balance plus the credit allowed) does not cover a purchase: 402 insufficient_funds, nothing is charged.
  • Services bought from the partner balance renew by themselves from it, 24 hours before they end, at the partner price. If the balance cannot cover a renewal, nothing is charged, you are told, and the service stops at the end of its paid period.
  • GET /balance/transactions?from=2026-11-01&to=2026-11-30 — every movement, newest first, with our retail price next to what you paid.

Prices

GET /prices returns everything you can buy with our retail price and your partner price, so you can compute and publish your own prices. Retail already includes our term discounts (a hosting year, yearly email); your discount is applied on top: partner_cents = round(retail_cents × (100 − discount) / 100).

json
{"data": {
  "currency": "USD", "updated_at": "2026-11-08T10:00:00+04:00",
  "discounts_pct": {"hosting": 30, "mail": 30, "vps": 10, "domains": 0},
  "hosting": [{"id": 2, "name": "Rapids", "terms": [
    {"months": 1, "retail_cents": 900, "partner_cents": 630},
    {"months": 12, "retail_cents": 9000, "partner_cents": 6300}]}],
  "mail": [{"plan": "professional-mail", "name": "Rivervo Mail — Professional",
    "per_mailbox": {"monthly": {"retail_cents": 300, "partner_cents": 210},
                    "yearly": {"retail_cents": 3060, "partner_cents": 2142}}}],
  "vps": [{"id": 5, "name": "Brook", "cpu": 2, "ram_gb": 4, "disk_gb": 40,
    "locations": ["de-nuremberg", "de-falkenstein", "fi-helsinki"],
    "available_locations": ["de-nuremberg", "fi-helsinki"],
    "monthly": {"retail_cents": 749, "partner_cents": 674}}],
  "domains": [{"tld": "com", "register": {"1y": {"retail_cents": 1299, "partner_cents": 1299}}}]
}}

The answer has an ETag and Cache-Control: private, max-age=300. Send If-None-Match with the last ETag and you get 304 Not Modified while nothing changed — so you can poll often and update your site only when our prices move:

js
// Run every few minutes (cron). Re-publishes your prices only when ours changed.
let etag = await store.get('rivervo_prices_etag');
const res = await fetch('https://api.rivervo.com/api/partner/v1/prices', {
  headers: {
    Authorization: `Bearer ${process.env.RIVERVO_API_KEY}`,
    ...(etag ? { 'If-None-Match': etag } : {}),
  },
});
if (res.status === 304) return;                 // nothing changed
const { data } = await res.json();
for (const plan of data.hosting) {
  for (const term of plan.terms) {
    // your price: our partner price plus your margin, in cents
    const yours = Math.ceil(term.partner_cents * 1.25);
    await store.setPrice(`hosting-${plan.id}-${term.months}m`, yours);
  }
}
await store.set('rivervo_prices_etag', res.headers.get('ETag'));

Catalog helpers for your order forms: GET /catalog/hosting-plans, GET /catalog/mail-plans, GET /catalog/vps-plans, GET /catalog/regions, GET /catalog/os.

VPS availability

Each server plan in GET /catalog/vps-plans and GET /prices has locations (where we sell it) and available_locations (where it can be made right now; refreshed every 5 minutes). GET /catalog/vps-availability returns the same availability on its own — a light call to check before showing a location to your client.

  • A location in locations but not in available_locations has no room now: POST /vps there answers 422 out_of_stock and nothing is charged.
  • To buy it anyway, send "wait": true. The server is paid now, gets status: waiting_for_room and waiting_until, and is made as soon as room appears — the order stays processing, then you get order.completed.
  • If no room appears by waiting_until (14 days), the payment goes back to the partner balance and the order fails with out_of_stock. Deleting a server that is still waiting cancels it and returns the payment.
bash
curl -X POST https://api.rivervo.com/api/partner/v1/vps \
  -H "Authorization: Bearer $RIVERVO_API_KEY" \
  -H "Idempotency-Key: client-417-vps" \
  -H "Content-Type: application/json" \
  -d '{"plan_id": 5, "location": "de-falkenstein", "os": "ubuntu-24.04",
       "ssh_public_key": "ssh-ed25519 AAAA... me@pc", "wait": true}'

Webhooks

Set your webhook URL (https) and get its signing secret in the Partner section of the panel. We send a POST with JSON:

json
{"id": "whd_k3j…", "event": "order.completed",
 "created_at": "2026-11-08T12:00:00+04:00", "data": {"order": {…}}}
  • Events: order.completed, order.failed, balance.low (data: stage below_75 | below_120 | limit, balance_cents, credit_limit_cents, available_cents).
  • Headers: X-Rivervo-Event, X-Rivervo-Delivery (the id), X-Rivervo-Signature — lowercase hex HMAC-SHA256 of the raw body with your secret.
  • Answer any 2xx within 10 seconds; otherwise we retry after 1 min, 5 min, 15 min, 1 h and 6 h. Use id to ignore repeats.

PHP

php
$body = file_get_contents('php://input');
$expected = hash_hmac('sha256', $body, getenv('RIVERVO_WEBHOOK_SECRET'));
if (!hash_equals($expected, $_SERVER['HTTP_X_RIVERVO_SIGNATURE'] ?? '')) {
    http_response_code(401);
    exit;
}
$event = json_decode($body, true);
// $event['id'] — ignore deliveries you have already handled
http_response_code(200);

Node.js (Express)

js
const crypto = require('crypto');

app.post('/hooks/rivervo', express.raw({ type: 'application/json' }), (req, res) => {
  const expected = crypto
    .createHmac('sha256', process.env.RIVERVO_WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');
  const got = req.get('X-Rivervo-Signature') || '';
  if (got.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected))) {
    return res.sendStatus(401);
  }
  const event = JSON.parse(req.body.toString('utf8'));
  // event.id — ignore deliveries you have already handled
  res.sendStatus(200);
});

Rate limits

  • 120 requests a minute per partner account, of them 30 changes (POST, PUT, PATCH, DELETE).
  • Over the limit: 429 rate_limited with a Retry-After header in seconds. Wait that long and retry with the same Idempotency-Key.
  • Cache GET /prices and the catalog (see Prices) instead of asking on every page view of your site.
API reference

API reference

Generated from the OpenAPI document of the API. Every change needs an Idempotency-Key header; amounts are integer US cents. Version 1.0.0

Account

GET/me

The partner, its balance and discounts

Responses
200 OKFields
  • dataPartnerrequired
    • idinteger
    • namestring
    • emailstring
    • statusstring
    • currencystring
    • balance_centsinteger
    • credit_allowedboolean
    • credit_limit_centsinteger
    • available_centsinteger
    • discounts_pctobject
      • hostingnumber
      • mailnumber
      • vpsnumber
      • domainsnumber
401403404429 Errors — error format and codes
Example
curl
curl https://api.rivervo.com/api/partner/v1/me \
  -H "Authorization: Bearer $RIVERVO_API_KEY"
GET/balance/transactions

Partner balance movements (newest first)

Parameters
  • fromquerystring (date)
  • toquerystring (date)
  • pagequeryinteger
  • per_pagequeryinteger
Responses
200 OKFields
  • dataarray of Transaction
    • idinteger
    • typestring
    • amount_centsinteger
    • retail_centsinteger | null
    • balance_after_centsinteger | null
    • currencystring
    • resourceobject | null
      • typestring
      • idinteger
    • receipt_nostring | null
    • created_atstring (date-time) | null
  • metaPageMeta
    • totalinteger
    • per_pageinteger
    • current_pageinteger
    • last_pageinteger
401403404429 Errors — error format and codes
Example
curl
curl https://api.rivervo.com/api/partner/v1/balance/transactions \
  -H "Authorization: Bearer $RIVERVO_API_KEY"

Catalog

GET/prices

Every price for you: retail and partner, per term and region (cache it; ETag / If-None-Match)

Responses
200 OKFields
  • dataPriceListrequired
    • currencystring
    • updated_atstring (date-time) | null
    • discounts_pctobject
    • hostingarray of object
      • idinteger
      • namestring
      • termsarray of object
        • monthsinteger
        • retail_centsinteger
        • partner_centsinteger
    • mailarray of object
      • planstring
      • namestring
      • mailbox_quota_gbinteger
      • min_mailboxesinteger
      • per_mailboxobject
        • monthlyPrice | null
          • retail_centsinteger
          • partner_centsinteger
        • yearlyPrice
          • retail_centsinteger
          • partner_centsinteger
      • extra_storage_per_gb_per_mailboxobject
        • monthlyPrice
          • retail_centsinteger
          • partner_centsinteger
        • yearlyPrice
          • retail_centsinteger
          • partner_centsinteger
    • vpsarray of object
      • idinteger
      • namestring
      • cpuinteger
      • ram_gbnumber
      • disk_gbinteger
      • traffic_tbnumber
      • cpu_typestring

        Values: shared · dedicated

      • archstring

        Values: x86 · arm

      • regionstring
      • locationsarray of string

        Where the plan is sold.

      • available_locationsarray of string

        Where it can be made right now (in GET /catalog/vps-plans and GET /prices only; refreshed every 5 minutes). Elsewhere in `locations` POST /vps answers out_of_stock unless "wait": true.

      • monthlyPrice
        • retail_centsinteger
        • partner_centsinteger
    • vps_addonsobject
      • backupsobject
        • percent_of_planinteger
        • notestring
      • volume_per_gb_monthlyPrice
        • retail_centsinteger
        • partner_centsinteger
      • monitoring_monthlyPrice
        • retail_centsinteger
        • partner_centsinteger
    • domainsarray of object
      • tldstring
      • registerobject
        • 1yPrice
          • retail_centsinteger
          • partner_centsinteger
        • 2yPrice
          • retail_centsinteger
          • partner_centsinteger
        • 3yPrice
          • retail_centsinteger
          • partner_centsinteger
      • renew_1yPrice
        • retail_centsinteger
        • partner_centsinteger
      • transfer_1yPrice
        • retail_centsinteger
        • partner_centsinteger
401403404429 Errors — error format and codes
Example
curl
curl https://api.rivervo.com/api/partner/v1/prices \
  -H "Authorization: Bearer $RIVERVO_API_KEY"
GET/catalog/regions

Regions and locations for servers

Responses
200 OKFields
  • dataarray of Regionrequired
    • idstring
    • namestring
    • locationsarray of object
      • idstring
      • countrystring
      • citystring
401403404429 Errors — error format and codes
Example
curl
curl https://api.rivervo.com/api/partner/v1/catalog/regions \
  -H "Authorization: Bearer $RIVERVO_API_KEY"
GET/catalog/os

Operating systems for servers

Responses
200 OKFields
  • dataarray of objectrequired
    • idstring

      Values: ubuntu-24.04 · ubuntu-22.04 · debian-12 · debian-11 · centos-stream-9 · centos-stream-10 · rocky-9 · rocky-10 · almalinux-9 · almalinux-10 · fedora-43 · opensuse-16

401403404429 Errors — error format and codes
Example
curl
curl https://api.rivervo.com/api/partner/v1/catalog/os \
  -H "Authorization: Bearer $RIVERVO_API_KEY"
GET/catalog/vps-plans

Server plans

Responses
200 OKFields
  • dataarray of VpsPlanrequired
    • idinteger
    • namestring
    • cpuinteger
    • ram_gbnumber
    • disk_gbinteger
    • traffic_tbnumber
    • cpu_typestring

      Values: shared · dedicated

    • archstring

      Values: x86 · arm

    • regionstring
    • locationsarray of string

      Where the plan is sold.

    • available_locationsarray of string

      Where it can be made right now (in GET /catalog/vps-plans and GET /prices only; refreshed every 5 minutes). Elsewhere in `locations` POST /vps answers out_of_stock unless "wait": true.

401403404429 Errors — error format and codes
Example
curl
curl https://api.rivervo.com/api/partner/v1/catalog/vps-plans \
  -H "Authorization: Bearer $RIVERVO_API_KEY"
GET/catalog/vps-availability

Where each server plan can be made right now (refreshed every 5 minutes)

Responses
200 OKFields
  • dataarray of object
    • plan_idinteger
    • namestring
    • available_locationsarray of string

      Values: de-nuremberg · de-falkenstein · fi-helsinki · us-east · us-west · sg-singapore

  • cached_atstring (date-time)

    When the stock was taken; it is kept 5 minutes.

401403404429 Errors — error format and codes
Example
curl
curl https://api.rivervo.com/api/partner/v1/catalog/vps-availability \
  -H "Authorization: Bearer $RIVERVO_API_KEY"
GET/catalog/hosting-plans

Hosting plans and terms

Responses
200 OKFields
  • dataarray of object
    • idinteger
    • namestring
  • terms_monthsarray of integer
401403404429 Errors — error format and codes
Example
curl
curl https://api.rivervo.com/api/partner/v1/catalog/hosting-plans \
  -H "Authorization: Bearer $RIVERVO_API_KEY"
GET/catalog/mail-plans

Email plans

Responses
200 OKFields
  • dataarray of objectrequired
    • planstring
    • namestring
    • mailbox_quota_gbinteger
    • min_mailboxesinteger
    • monthlyboolean
401403404429 Errors — error format and codes
Example
curl
curl https://api.rivervo.com/api/partner/v1/catalog/mail-plans \
  -H "Authorization: Bearer $RIVERVO_API_KEY"

Orders

GET/orders

Your orders (every change you made through the API)

Parameters
  • statusquerystring

    Values: processing · completed · failed

  • pagequeryinteger
  • per_pagequeryinteger
Responses
200 OKFields
  • dataarray of Order
    • idinteger
    • actionstring
    • statusstring

      Values: processing · completed · failed

    • idempotency_keystring
    • resourceobject | null
      • typestring
      • idinteger
    • charged_centsinteger | null
    • retail_centsinteger | null
    • currencystring
    • errorobject | null
      • codestring
      • messagestring
    • created_atstring (date-time) | null
    • completed_atstring (date-time) | null
  • metaPageMeta
    • totalinteger
    • per_pageinteger
    • current_pageinteger
    • last_pageinteger
401403404429 Errors — error format and codes
Example
curl
curl https://api.rivervo.com/api/partner/v1/orders \
  -H "Authorization: Bearer $RIVERVO_API_KEY"
GET/orders/{id}

One order

Parameters
  • idpathintegerrequired

    The order id.

Responses
200 OKFields
  • dataOrderrequired
    • idinteger
    • actionstring
    • statusstring

      Values: processing · completed · failed

    • idempotency_keystring
    • resourceobject | null
      • typestring
      • idinteger
    • charged_centsinteger | null
    • retail_centsinteger | null
    • currencystring
    • errorobject | null
      • codestring
      • messagestring
    • created_atstring (date-time) | null
    • completed_atstring (date-time) | null
401403404429 Errors — error format and codes
Example
curl
curl https://api.rivervo.com/api/partner/v1/orders/812 \
  -H "Authorization: Bearer $RIVERVO_API_KEY"

Hosting

GET/hosting

Your hosting accounts

Parameters
  • pagequeryinteger
  • per_pagequeryinteger
Responses
200 OKFields
  • dataarray of Hosting
    • idinteger
    • domainstring
    • usernamestring
    • planobject | null
      • idinteger
      • namestring
    • term_monthsinteger | null
    • statusstring

      Values: provisioning · active · expired · suspended · deleted

    • paid_untilstring (date-time) | null
    • renews_from_partner_balanceboolean
    • created_atstring (date-time) | null
  • metaPageMeta
    • totalinteger
    • per_pageinteger
    • current_pageinteger
    • last_pageinteger
401403404429 Errors — error format and codes
Example
curl
curl https://api.rivervo.com/api/partner/v1/hosting \
  -H "Authorization: Bearer $RIVERVO_API_KEY"
POST/hosting

Create a hosting account (paid from the partner balance)

Parameters
  • Idempotency-Keyheaderstringrequired

    Your unique key for this change (1–128 of A–Z a–z 0–9 - _ . :). The same key with the same request returns the first answer (header Idempotent-Replayed: true) and never charges twice; with another request: 409 idempotency_conflict.

Request body application/json
  • domainstringrequired
  • plan_idintegerrequired
  • term_monthsintegerrequired
Responses
202 Accepted: the order is processing; follow it with GET /orders/{id} or the webhook.Fields
  • dataHosting
    • idinteger
    • domainstring
    • usernamestring
    • planobject | null
      • idinteger
      • namestring
    • term_monthsinteger | null
    • statusstring

      Values: provisioning · active · expired · suspended · deleted

    • paid_untilstring (date-time) | null
    • renews_from_partner_balanceboolean
    • created_atstring (date-time) | null
  • orderOrder
    • idinteger
    • actionstring
    • statusstring

      Values: processing · completed · failed

    • idempotency_keystring
    • resourceobject | null
      • typestring
      • idinteger
    • charged_centsinteger | null
    • retail_centsinteger | null
    • currencystring
    • errorobject | null
      • codestring
      • messagestring
    • created_atstring (date-time) | null
    • completed_atstring (date-time) | null
400401402403404409422429502 Errors — error format and codes
Example
curl
curl -X POST https://api.rivervo.com/api/partner/v1/hosting \
  -H "Authorization: Bearer $RIVERVO_API_KEY" \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "client.az",
    "plan_id": 2,
    "term_months": 12
  }'
GET/hosting/{id}

One hosting account

Parameters
  • idpathintegerrequired

    The hosting id.

Responses
200 OKFields
  • dataHostingrequired
    • idinteger
    • domainstring
    • usernamestring
    • planobject | null
      • idinteger
      • namestring
    • term_monthsinteger | null
    • statusstring

      Values: provisioning · active · expired · suspended · deleted

    • paid_untilstring (date-time) | null
    • renews_from_partner_balanceboolean
    • created_atstring (date-time) | null
401403404429 Errors — error format and codes
Example
curl
curl https://api.rivervo.com/api/partner/v1/hosting/812 \
  -H "Authorization: Bearer $RIVERVO_API_KEY"
DELETE/hosting/{id}

Delete a hosting account (no refund)

Parameters
  • Idempotency-Keyheaderstringrequired

    Your unique key for this change (1–128 of A–Z a–z 0–9 - _ . :). The same key with the same request returns the first answer (header Idempotent-Replayed: true) and never charges twice; with another request: 409 idempotency_conflict.

  • idpathintegerrequired

    The hosting id.

Responses
200 OKFields
  • dataobject
    • idinteger
    • deletedboolean
  • orderOrder
    • idinteger
    • actionstring
    • statusstring

      Values: processing · completed · failed

    • idempotency_keystring
    • resourceobject | null
      • typestring
      • idinteger
    • charged_centsinteger | null
    • retail_centsinteger | null
    • currencystring
    • errorobject | null
      • codestring
      • messagestring
    • created_atstring (date-time) | null
    • completed_atstring (date-time) | null
400401402403404409422429502 Errors — error format and codes
Example
curl
curl -X DELETE https://api.rivervo.com/api/partner/v1/hosting/812 \
  -H "Authorization: Bearer $RIVERVO_API_KEY" \
  -H "Idempotency-Key: order-1042"
POST/hosting/{id}/renew

Renew (default: its own term)

Parameters
  • Idempotency-Keyheaderstringrequired

    Your unique key for this change (1–128 of A–Z a–z 0–9 - _ . :). The same key with the same request returns the first answer (header Idempotent-Replayed: true) and never charges twice; with another request: 409 idempotency_conflict.

  • idpathintegerrequired

    The hosting id.

Request body application/json
  • term_monthsinteger
Responses
200 OKFields
  • dataHosting
    • idinteger
    • domainstring
    • usernamestring
    • planobject | null
      • idinteger
      • namestring
    • term_monthsinteger | null
    • statusstring

      Values: provisioning · active · expired · suspended · deleted

    • paid_untilstring (date-time) | null
    • renews_from_partner_balanceboolean
    • created_atstring (date-time) | null
  • orderOrder
    • idinteger
    • actionstring
    • statusstring

      Values: processing · completed · failed

    • idempotency_keystring
    • resourceobject | null
      • typestring
      • idinteger
    • charged_centsinteger | null
    • retail_centsinteger | null
    • currencystring
    • errorobject | null
      • codestring
      • messagestring
    • created_atstring (date-time) | null
    • completed_atstring (date-time) | null
400401402403404409422429502 Errors — error format and codes
Example
curl
curl -X POST https://api.rivervo.com/api/partner/v1/hosting/812/renew \
  -H "Authorization: Bearer $RIVERVO_API_KEY" \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "term_months": 12
  }'
POST/hosting/{id}/change-plan

Change plan (charged now)

Parameters
  • Idempotency-Keyheaderstringrequired

    Your unique key for this change (1–128 of A–Z a–z 0–9 - _ . :). The same key with the same request returns the first answer (header Idempotent-Replayed: true) and never charges twice; with another request: 409 idempotency_conflict.

  • idpathintegerrequired

    The hosting id.

Request body application/json
  • plan_idintegerrequired
  • term_monthsintegerrequired
Responses
200 OKFields
  • dataHosting
    • idinteger
    • domainstring
    • usernamestring
    • planobject | null
      • idinteger
      • namestring
    • term_monthsinteger | null
    • statusstring

      Values: provisioning · active · expired · suspended · deleted

    • paid_untilstring (date-time) | null
    • renews_from_partner_balanceboolean
    • created_atstring (date-time) | null
  • orderOrder
    • idinteger
    • actionstring
    • statusstring

      Values: processing · completed · failed

    • idempotency_keystring
    • resourceobject | null
      • typestring
      • idinteger
    • charged_centsinteger | null
    • retail_centsinteger | null
    • currencystring
    • errorobject | null
      • codestring
      • messagestring
    • created_atstring (date-time) | null
    • completed_atstring (date-time) | null
400401402403404409422429502 Errors — error format and codes
Example
curl
curl -X POST https://api.rivervo.com/api/partner/v1/hosting/812/change-plan \
  -H "Authorization: Bearer $RIVERVO_API_KEY" \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_id": 2,
    "term_months": 12
  }'
POST/hosting/{id}/reset-password

New password for the hosting account (shown in this answer only)

Parameters
  • Idempotency-Keyheaderstringrequired

    Your unique key for this change (1–128 of A–Z a–z 0–9 - _ . :). The same key with the same request returns the first answer (header Idempotent-Replayed: true) and never charges twice; with another request: 409 idempotency_conflict.

  • idpathintegerrequired

    The hosting id.

Responses
200 OKFields
  • dataobject
    • usernamestring
    • passwordstring
  • orderOrder
    • idinteger
    • actionstring
    • statusstring

      Values: processing · completed · failed

    • idempotency_keystring
    • resourceobject | null
      • typestring
      • idinteger
    • charged_centsinteger | null
    • retail_centsinteger | null
    • currencystring
    • errorobject | null
      • codestring
      • messagestring
    • created_atstring (date-time) | null
    • completed_atstring (date-time) | null
400401402403404409422429502 Errors — error format and codes
Example
curl
curl -X POST https://api.rivervo.com/api/partner/v1/hosting/812/reset-password \
  -H "Authorization: Bearer $RIVERVO_API_KEY" \
  -H "Idempotency-Key: order-1042"

Servers

GET/vps

Your servers

Parameters
  • pagequeryinteger
  • per_pagequeryinteger
Responses
200 OKFields
  • dataarray of Vps
    • idinteger
    • hostnamestring
    • planVpsPlan
      • idinteger
      • namestring
      • cpuinteger
      • ram_gbnumber
      • disk_gbinteger
      • traffic_tbnumber
      • cpu_typestring

        Values: shared · dedicated

      • archstring

        Values: x86 · arm

      • regionstring
      • locationsarray of string

        Where the plan is sold.

      • available_locationsarray of string

        Where it can be made right now (in GET /catalog/vps-plans and GET /prices only; refreshed every 5 minutes). Elsewhere in `locations` POST /vps answers out_of_stock unless "wait": true.

    • locationobject | null
      • idstring
      • regionstring
      • countrystring
      • citystring
    • osstring
    • statusstring

      provisioning, waiting_for_room, active, suspended, archived …

    • waiting_untilstring (date-time) | null

      Only while waiting_for_room: refunded if no room appears by then.

    • ipv4string | null
    • ipv6string | null
    • reverse_dnsstring | null

      The name the server's addresses resolve back to (<name>.rivervo.app); null until it is set.

    • paid_untilstring (date-time) | null
    • renews_from_partner_balanceboolean
    • root_passwordstring

      Only in the rebuild answer.

    • created_atstring (date-time) | null
  • metaPageMeta
    • totalinteger
    • per_pageinteger
    • current_pageinteger
    • last_pageinteger
401403404429 Errors — error format and codes
Example
curl
curl https://api.rivervo.com/api/partner/v1/vps \
  -H "Authorization: Bearer $RIVERVO_API_KEY"
POST/vps

Create a server (one month, paid from the partner balance)

Parameters
  • Idempotency-Keyheaderstringrequired

    Your unique key for this change (1–128 of A–Z a–z 0–9 - _ . :). The same key with the same request returns the first answer (header Idempotent-Replayed: true) and never charges twice; with another request: 409 idempotency_conflict.

Request body application/json
  • plan_idintegerrequired
  • locationstringrequired

    Values: de-nuremberg · de-falkenstein · fi-helsinki · us-east · us-west · sg-singapore

  • osstring

    Values: ubuntu-24.04 · ubuntu-22.04 · debian-12 · debian-11 · centos-stream-9 · centos-stream-10 · rocky-9 · rocky-10 · almalinux-9 · almalinux-10 · fedora-43 · opensuse-16

  • ssh_public_keystring
  • waitboolean

    The location has no room now (out_of_stock): buy anyway; the server is made as soon as there is room (status waiting_for_room until then, the order stays processing). If no room appears by waiting_until, the payment is returned to the partner balance and the order fails with out_of_stock.

    Default: false

Responses
202 Accepted: the order is processing; follow it with GET /orders/{id} or the webhook.Fields
  • dataVps
    • idinteger
    • hostnamestring
    • planVpsPlan
      • idinteger
      • namestring
      • cpuinteger
      • ram_gbnumber
      • disk_gbinteger
      • traffic_tbnumber
      • cpu_typestring

        Values: shared · dedicated

      • archstring

        Values: x86 · arm

      • regionstring
      • locationsarray of string

        Where the plan is sold.

      • available_locationsarray of string

        Where it can be made right now (in GET /catalog/vps-plans and GET /prices only; refreshed every 5 minutes). Elsewhere in `locations` POST /vps answers out_of_stock unless "wait": true.

    • locationobject | null
      • idstring
      • regionstring
      • countrystring
      • citystring
    • osstring
    • statusstring

      provisioning, waiting_for_room, active, suspended, archived …

    • waiting_untilstring (date-time) | null

      Only while waiting_for_room: refunded if no room appears by then.

    • ipv4string | null
    • ipv6string | null
    • reverse_dnsstring | null

      The name the server's addresses resolve back to (<name>.rivervo.app); null until it is set.

    • paid_untilstring (date-time) | null
    • renews_from_partner_balanceboolean
    • root_passwordstring

      Only in the rebuild answer.

    • created_atstring (date-time) | null
  • orderOrder
    • idinteger
    • actionstring
    • statusstring

      Values: processing · completed · failed

    • idempotency_keystring
    • resourceobject | null
      • typestring
      • idinteger
    • charged_centsinteger | null
    • retail_centsinteger | null
    • currencystring
    • errorobject | null
      • codestring
      • messagestring
    • created_atstring (date-time) | null
    • completed_atstring (date-time) | null
400401402403404409422429502 Errors — error format and codes
Example
curl
curl -X POST https://api.rivervo.com/api/partner/v1/vps \
  -H "Authorization: Bearer $RIVERVO_API_KEY" \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_id": 2,
    "location": "de-nuremberg",
    "os": "ubuntu-24.04",
    "ssh_public_key": "ssh-ed25519 AAAA... me@pc",
    "wait": false
  }'
GET/vps/{id}

One server

Parameters
  • idpathintegerrequired

    The server id.

Responses
200 OKFields
  • dataVpsrequired
    • idinteger
    • hostnamestring
    • planVpsPlan
      • idinteger
      • namestring
      • cpuinteger
      • ram_gbnumber
      • disk_gbinteger
      • traffic_tbnumber
      • cpu_typestring

        Values: shared · dedicated

      • archstring

        Values: x86 · arm

      • regionstring
      • locationsarray of string

        Where the plan is sold.

      • available_locationsarray of string

        Where it can be made right now (in GET /catalog/vps-plans and GET /prices only; refreshed every 5 minutes). Elsewhere in `locations` POST /vps answers out_of_stock unless "wait": true.

    • locationobject | null
      • idstring
      • regionstring
      • countrystring
      • citystring
    • osstring
    • statusstring

      provisioning, waiting_for_room, active, suspended, archived …

    • waiting_untilstring (date-time) | null

      Only while waiting_for_room: refunded if no room appears by then.

    • ipv4string | null
    • ipv6string | null
    • reverse_dnsstring | null

      The name the server's addresses resolve back to (<name>.rivervo.app); null until it is set.

    • paid_untilstring (date-time) | null
    • renews_from_partner_balanceboolean
    • root_passwordstring

      Only in the rebuild answer.

    • created_atstring (date-time) | null
401403404429 Errors — error format and codes
Example
curl
curl https://api.rivervo.com/api/partner/v1/vps/812 \
  -H "Authorization: Bearer $RIVERVO_API_KEY"
DELETE/vps/{id}

Delete a server (no refund)

Parameters
  • Idempotency-Keyheaderstringrequired

    Your unique key for this change (1–128 of A–Z a–z 0–9 - _ . :). The same key with the same request returns the first answer (header Idempotent-Replayed: true) and never charges twice; with another request: 409 idempotency_conflict.

  • idpathintegerrequired

    The server id.

Responses
200 OKFields
  • dataobject
    • idinteger
    • deletedboolean
  • orderOrder
    • idinteger
    • actionstring
    • statusstring

      Values: processing · completed · failed

    • idempotency_keystring
    • resourceobject | null
      • typestring
      • idinteger
    • charged_centsinteger | null
    • retail_centsinteger | null
    • currencystring
    • errorobject | null
      • codestring
      • messagestring
    • created_atstring (date-time) | null
    • completed_atstring (date-time) | null
400401402403404409422429502 Errors — error format and codes
Example
curl
curl -X DELETE https://api.rivervo.com/api/partner/v1/vps/812 \
  -H "Authorization: Bearer $RIVERVO_API_KEY" \
  -H "Idempotency-Key: order-1042"
POST/vps/{id}/power/{action}

Power on, off (graceful) or reboot

Parameters
  • Idempotency-Keyheaderstringrequired

    Your unique key for this change (1–128 of A–Z a–z 0–9 - _ . :). The same key with the same request returns the first answer (header Idempotent-Replayed: true) and never charges twice; with another request: 409 idempotency_conflict.

  • idpathintegerrequired

    The server id.

  • actionpathstringrequired

    Values: on · off · reboot

Responses
200 OKFields
  • dataVps
    • idinteger
    • hostnamestring
    • planVpsPlan
      • idinteger
      • namestring
      • cpuinteger
      • ram_gbnumber
      • disk_gbinteger
      • traffic_tbnumber
      • cpu_typestring

        Values: shared · dedicated

      • archstring

        Values: x86 · arm

      • regionstring
      • locationsarray of string

        Where the plan is sold.

      • available_locationsarray of string

        Where it can be made right now (in GET /catalog/vps-plans and GET /prices only; refreshed every 5 minutes). Elsewhere in `locations` POST /vps answers out_of_stock unless "wait": true.

    • locationobject | null
      • idstring
      • regionstring
      • countrystring
      • citystring
    • osstring
    • statusstring

      provisioning, waiting_for_room, active, suspended, archived …

    • waiting_untilstring (date-time) | null

      Only while waiting_for_room: refunded if no room appears by then.

    • ipv4string | null
    • ipv6string | null
    • reverse_dnsstring | null

      The name the server's addresses resolve back to (<name>.rivervo.app); null until it is set.

    • paid_untilstring (date-time) | null
    • renews_from_partner_balanceboolean
    • root_passwordstring

      Only in the rebuild answer.

    • created_atstring (date-time) | null
  • orderOrder
    • idinteger
    • actionstring
    • statusstring

      Values: processing · completed · failed

    • idempotency_keystring
    • resourceobject | null
      • typestring
      • idinteger
    • charged_centsinteger | null
    • retail_centsinteger | null
    • currencystring
    • errorobject | null
      • codestring
      • messagestring
    • created_atstring (date-time) | null
    • completed_atstring (date-time) | null
400401402403404409422429502 Errors — error format and codes
Example
curl
curl -X POST https://api.rivervo.com/api/partner/v1/vps/812/power/on \
  -H "Authorization: Bearer $RIVERVO_API_KEY" \
  -H "Idempotency-Key: order-1042"
POST/vps/{id}/rebuild

Reinstall the server from its image (data lost; the new root password is in this answer only)

Parameters
  • Idempotency-Keyheaderstringrequired

    Your unique key for this change (1–128 of A–Z a–z 0–9 - _ . :). The same key with the same request returns the first answer (header Idempotent-Replayed: true) and never charges twice; with another request: 409 idempotency_conflict.

  • idpathintegerrequired

    The server id.

Responses
200 OKFields
  • dataVps
    • idinteger
    • hostnamestring
    • planVpsPlan
      • idinteger
      • namestring
      • cpuinteger
      • ram_gbnumber
      • disk_gbinteger
      • traffic_tbnumber
      • cpu_typestring

        Values: shared · dedicated

      • archstring

        Values: x86 · arm

      • regionstring
      • locationsarray of string

        Where the plan is sold.

      • available_locationsarray of string

        Where it can be made right now (in GET /catalog/vps-plans and GET /prices only; refreshed every 5 minutes). Elsewhere in `locations` POST /vps answers out_of_stock unless "wait": true.

    • locationobject | null
      • idstring
      • regionstring
      • countrystring
      • citystring
    • osstring
    • statusstring

      provisioning, waiting_for_room, active, suspended, archived …

    • waiting_untilstring (date-time) | null

      Only while waiting_for_room: refunded if no room appears by then.

    • ipv4string | null
    • ipv6string | null
    • reverse_dnsstring | null

      The name the server's addresses resolve back to (<name>.rivervo.app); null until it is set.

    • paid_untilstring (date-time) | null
    • renews_from_partner_balanceboolean
    • root_passwordstring

      Only in the rebuild answer.

    • created_atstring (date-time) | null
  • orderOrder
    • idinteger
    • actionstring
    • statusstring

      Values: processing · completed · failed

    • idempotency_keystring
    • resourceobject | null
      • typestring
      • idinteger
    • charged_centsinteger | null
    • retail_centsinteger | null
    • currencystring
    • errorobject | null
      • codestring
      • messagestring
    • created_atstring (date-time) | null
    • completed_atstring (date-time) | null
400401402403404409422429502 Errors — error format and codes
Example
curl
curl -X POST https://api.rivervo.com/api/partner/v1/vps/812/rebuild \
  -H "Authorization: Bearer $RIVERVO_API_KEY" \
  -H "Idempotency-Key: order-1042"
POST/vps/{id}/renew

Renew one month (plan and add-ons)

Parameters
  • Idempotency-Keyheaderstringrequired

    Your unique key for this change (1–128 of A–Z a–z 0–9 - _ . :). The same key with the same request returns the first answer (header Idempotent-Replayed: true) and never charges twice; with another request: 409 idempotency_conflict.

  • idpathintegerrequired

    The server id.

Responses
200 OKFields
  • dataVps
    • idinteger
    • hostnamestring
    • planVpsPlan
      • idinteger
      • namestring
      • cpuinteger
      • ram_gbnumber
      • disk_gbinteger
      • traffic_tbnumber
      • cpu_typestring

        Values: shared · dedicated

      • archstring

        Values: x86 · arm

      • regionstring
      • locationsarray of string

        Where the plan is sold.

      • available_locationsarray of string

        Where it can be made right now (in GET /catalog/vps-plans and GET /prices only; refreshed every 5 minutes). Elsewhere in `locations` POST /vps answers out_of_stock unless "wait": true.

    • locationobject | null
      • idstring
      • regionstring
      • countrystring
      • citystring
    • osstring
    • statusstring

      provisioning, waiting_for_room, active, suspended, archived …

    • waiting_untilstring (date-time) | null

      Only while waiting_for_room: refunded if no room appears by then.

    • ipv4string | null
    • ipv6string | null
    • reverse_dnsstring | null

      The name the server's addresses resolve back to (<name>.rivervo.app); null until it is set.

    • paid_untilstring (date-time) | null
    • renews_from_partner_balanceboolean
    • root_passwordstring

      Only in the rebuild answer.

    • created_atstring (date-time) | null
  • orderOrder
    • idinteger
    • actionstring
    • statusstring

      Values: processing · completed · failed

    • idempotency_keystring
    • resourceobject | null
      • typestring
      • idinteger
    • charged_centsinteger | null
    • retail_centsinteger | null
    • currencystring
    • errorobject | null
      • codestring
      • messagestring
    • created_atstring (date-time) | null
    • completed_atstring (date-time) | null
400401402403404409422429502 Errors — error format and codes
Example
curl
curl -X POST https://api.rivervo.com/api/partner/v1/vps/812/renew \
  -H "Authorization: Bearer $RIVERVO_API_KEY" \
  -H "Idempotency-Key: order-1042"

Email

GET/mail/subscription

Your email subscription (one per account, shared by all its domains)

Responses
200 OKFields
  • dataMailSubscription | nullrequired
    • idinteger
    • planobject | null
      • keystring
      • namestring
      • mailbox_quota_gbinteger
    • periodstring
    • mailboxes_paidinteger
    • mailboxes_usedinteger
    • extra_storage_gb_per_mailboxinteger
    • statusstring
    • paid_untilstring (date-time) | null
    • renews_from_partner_balanceboolean
    • domainsarray of MailDomain
      • idinteger
      • domainstring
      • statusstring
      • dns_verifiedboolean
      • mailboxesinteger
      • created_atstring (date-time) | null
    • created_atstring (date-time) | null
401403404429 Errors — error format and codes
Example
curl
curl https://api.rivervo.com/api/partner/v1/mail/subscription \
  -H "Authorization: Bearer $RIVERVO_API_KEY"
POST/mail/subscription

Buy the email subscription (paid now from the partner balance)

Parameters
  • Idempotency-Keyheaderstringrequired

    Your unique key for this change (1–128 of A–Z a–z 0–9 - _ . :). The same key with the same request returns the first answer (header Idempotent-Replayed: true) and never charges twice; with another request: 409 idempotency_conflict.

Request body application/json
  • planstringrequired
  • periodstringrequired

    Values: monthly · yearly

  • mailboxesintegerrequired
  • domainstring
Responses
201 OKFields
  • dataMailSubscription
    • idinteger
    • planobject | null
      • keystring
      • namestring
      • mailbox_quota_gbinteger
    • periodstring
    • mailboxes_paidinteger
    • mailboxes_usedinteger
    • extra_storage_gb_per_mailboxinteger
    • statusstring
    • paid_untilstring (date-time) | null
    • renews_from_partner_balanceboolean
    • domainsarray of MailDomain
      • idinteger
      • domainstring
      • statusstring
      • dns_verifiedboolean
      • mailboxesinteger
      • created_atstring (date-time) | null
    • created_atstring (date-time) | null
  • orderOrder
    • idinteger
    • actionstring
    • statusstring

      Values: processing · completed · failed

    • idempotency_keystring
    • resourceobject | null
      • typestring
      • idinteger
    • charged_centsinteger | null
    • retail_centsinteger | null
    • currencystring
    • errorobject | null
      • codestring
      • messagestring
    • created_atstring (date-time) | null
    • completed_atstring (date-time) | null
400401402403404409422429502 Errors — error format and codes
Example
curl
curl -X POST https://api.rivervo.com/api/partner/v1/mail/subscription \
  -H "Authorization: Bearer $RIVERVO_API_KEY" \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "plan": "string",
    "period": "monthly",
    "mailboxes": 10,
    "domain": "client.az"
  }'
POST/mail/subscription/renew

Renew the email subscription

Parameters
  • Idempotency-Keyheaderstringrequired

    Your unique key for this change (1–128 of A–Z a–z 0–9 - _ . :). The same key with the same request returns the first answer (header Idempotent-Replayed: true) and never charges twice; with another request: 409 idempotency_conflict.

Request body application/json
  • periodstring

    Values: monthly · yearly

Responses
200 OKFields
  • dataMailSubscription
    • idinteger
    • planobject | null
      • keystring
      • namestring
      • mailbox_quota_gbinteger
    • periodstring
    • mailboxes_paidinteger
    • mailboxes_usedinteger
    • extra_storage_gb_per_mailboxinteger
    • statusstring
    • paid_untilstring (date-time) | null
    • renews_from_partner_balanceboolean
    • domainsarray of MailDomain
      • idinteger
      • domainstring
      • statusstring
      • dns_verifiedboolean
      • mailboxesinteger
      • created_atstring (date-time) | null
    • created_atstring (date-time) | null
  • orderOrder
    • idinteger
    • actionstring
    • statusstring

      Values: processing · completed · failed

    • idempotency_keystring
    • resourceobject | null
      • typestring
      • idinteger
    • charged_centsinteger | null
    • retail_centsinteger | null
    • currencystring
    • errorobject | null
      • codestring
      • messagestring
    • created_atstring (date-time) | null
    • completed_atstring (date-time) | null
400401402403404409422429502 Errors — error format and codes
Example
curl
curl -X POST https://api.rivervo.com/api/partner/v1/mail/subscription/renew \
  -H "Authorization: Bearer $RIVERVO_API_KEY" \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "period": "monthly"
  }'
PUT/mail/subscription/mailboxes

Set the number of paid mailboxes (more: charged for the rest of the period)

Parameters
  • Idempotency-Keyheaderstringrequired

    Your unique key for this change (1–128 of A–Z a–z 0–9 - _ . :). The same key with the same request returns the first answer (header Idempotent-Replayed: true) and never charges twice; with another request: 409 idempotency_conflict.

Request body application/json
  • mailboxesintegerrequired
Responses
200 OKFields
  • dataMailSubscription
    • idinteger
    • planobject | null
      • keystring
      • namestring
      • mailbox_quota_gbinteger
    • periodstring
    • mailboxes_paidinteger
    • mailboxes_usedinteger
    • extra_storage_gb_per_mailboxinteger
    • statusstring
    • paid_untilstring (date-time) | null
    • renews_from_partner_balanceboolean
    • domainsarray of MailDomain
      • idinteger
      • domainstring
      • statusstring
      • dns_verifiedboolean
      • mailboxesinteger
      • created_atstring (date-time) | null
    • created_atstring (date-time) | null
  • orderOrder
    • idinteger
    • actionstring
    • statusstring

      Values: processing · completed · failed

    • idempotency_keystring
    • resourceobject | null
      • typestring
      • idinteger
    • charged_centsinteger | null
    • retail_centsinteger | null
    • currencystring
    • errorobject | null
      • codestring
      • messagestring
    • created_atstring (date-time) | null
    • completed_atstring (date-time) | null
400401402403404409422429502 Errors — error format and codes
Example
curl
curl -X PUT https://api.rivervo.com/api/partner/v1/mail/subscription/mailboxes \
  -H "Authorization: Bearer $RIVERVO_API_KEY" \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "mailboxes": 10
  }'
PUT/mail/subscription/storage

Extra storage on every mailbox (GB)

Parameters
  • Idempotency-Keyheaderstringrequired

    Your unique key for this change (1–128 of A–Z a–z 0–9 - _ . :). The same key with the same request returns the first answer (header Idempotent-Replayed: true) and never charges twice; with another request: 409 idempotency_conflict.

Request body application/json
  • gb_per_mailboxintegerrequired
Responses
200 OKFields
  • dataMailSubscription
    • idinteger
    • planobject | null
      • keystring
      • namestring
      • mailbox_quota_gbinteger
    • periodstring
    • mailboxes_paidinteger
    • mailboxes_usedinteger
    • extra_storage_gb_per_mailboxinteger
    • statusstring
    • paid_untilstring (date-time) | null
    • renews_from_partner_balanceboolean
    • domainsarray of MailDomain
      • idinteger
      • domainstring
      • statusstring
      • dns_verifiedboolean
      • mailboxesinteger
      • created_atstring (date-time) | null
    • created_atstring (date-time) | null
  • orderOrder
    • idinteger
    • actionstring
    • statusstring

      Values: processing · completed · failed

    • idempotency_keystring
    • resourceobject | null
      • typestring
      • idinteger
    • charged_centsinteger | null
    • retail_centsinteger | null
    • currencystring
    • errorobject | null
      • codestring
      • messagestring
    • created_atstring (date-time) | null
    • completed_atstring (date-time) | null
400401402403404409422429502 Errors — error format and codes
Example
curl
curl -X PUT https://api.rivervo.com/api/partner/v1/mail/subscription/storage \
  -H "Authorization: Bearer $RIVERVO_API_KEY" \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "gb_per_mailbox": 5
  }'
GET/mail/domains

Domains on your email subscription

Parameters
  • pagequeryinteger
  • per_pagequeryinteger
Responses
200 OKFields
  • dataarray of MailDomain
    • idinteger
    • domainstring
    • statusstring
    • dns_verifiedboolean
    • mailboxesinteger
    • created_atstring (date-time) | null
  • metaPageMeta
    • totalinteger
    • per_pageinteger
    • current_pageinteger
    • last_pageinteger
401403404429 Errors — error format and codes
Example
curl
curl https://api.rivervo.com/api/partner/v1/mail/domains \
  -H "Authorization: Bearer $RIVERVO_API_KEY"
POST/mail/domains

Add a client domain

Parameters
  • Idempotency-Keyheaderstringrequired

    Your unique key for this change (1–128 of A–Z a–z 0–9 - _ . :). The same key with the same request returns the first answer (header Idempotent-Replayed: true) and never charges twice; with another request: 409 idempotency_conflict.

Request body application/json
  • domainstringrequired
Responses
201 OKFields
  • dataMailDomain
    • idinteger
    • domainstring
    • statusstring
    • dns_verifiedboolean
    • mailboxesinteger
    • created_atstring (date-time) | null
  • orderOrder
    • idinteger
    • actionstring
    • statusstring

      Values: processing · completed · failed

    • idempotency_keystring
    • resourceobject | null
      • typestring
      • idinteger
    • charged_centsinteger | null
    • retail_centsinteger | null
    • currencystring
    • errorobject | null
      • codestring
      • messagestring
    • created_atstring (date-time) | null
    • completed_atstring (date-time) | null
400401402403404409422429502 Errors — error format and codes
Example
curl
curl -X POST https://api.rivervo.com/api/partner/v1/mail/domains \
  -H "Authorization: Bearer $RIVERVO_API_KEY" \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "client.az"
  }'
GET/mail/domains/{id}

One email domain

Parameters
  • idpathintegerrequired

    The email domain id.

Responses
200 OKFields
  • dataMailDomainrequired
    • idinteger
    • domainstring
    • statusstring
    • dns_verifiedboolean
    • mailboxesinteger
    • created_atstring (date-time) | null
401403404429 Errors — error format and codes
Example
curl
curl https://api.rivervo.com/api/partner/v1/mail/domains/812 \
  -H "Authorization: Bearer $RIVERVO_API_KEY"
DELETE/mail/domains/{id}

Remove a domain with its mailboxes and mail

Parameters
  • Idempotency-Keyheaderstringrequired

    Your unique key for this change (1–128 of A–Z a–z 0–9 - _ . :). The same key with the same request returns the first answer (header Idempotent-Replayed: true) and never charges twice; with another request: 409 idempotency_conflict.

  • idpathintegerrequired

    The email domain id.

Responses
200 OKFields
  • dataobject
    • idinteger
    • deletedboolean
  • orderOrder
    • idinteger
    • actionstring
    • statusstring

      Values: processing · completed · failed

    • idempotency_keystring
    • resourceobject | null
      • typestring
      • idinteger
    • charged_centsinteger | null
    • retail_centsinteger | null
    • currencystring
    • errorobject | null
      • codestring
      • messagestring
    • created_atstring (date-time) | null
    • completed_atstring (date-time) | null
400401402403404409422429502 Errors — error format and codes
Example
curl
curl -X DELETE https://api.rivervo.com/api/partner/v1/mail/domains/812 \
  -H "Authorization: Bearer $RIVERVO_API_KEY" \
  -H "Idempotency-Key: order-1042"
GET/mail/domains/{id}/dns

DNS records the domain needs and the mail settings for clients

Parameters
  • idpathintegerrequired

    The email domain id.

  • refreshqueryboolean
Responses
200 OKFields
  • dataMailDnsrequired
    • domainstring
    • statusstring

      Values: pending · partial · verified

    • recordsarray of object
      • typestring
      • hoststring | null
      • valuestring | null
      • priorityinteger | null
      • purposestring | null
      • availableboolean

        false: ask support for this record.

    • settingsobject
      • imap_hoststring | null
      • imap_portinteger | null
      • smtp_hoststring | null
      • smtp_portinteger | null
      • webmail_urlstring | null
    • verified_atstring (date-time) | null
401403404429 Errors — error format and codes
Example
curl
curl https://api.rivervo.com/api/partner/v1/mail/domains/812/dns \
  -H "Authorization: Bearer $RIVERVO_API_KEY"
GET/mail/domains/{id}/mailboxes

Mailboxes of a domain

Parameters
  • idpathintegerrequired

    The email domain id.

  • pagequeryinteger
  • per_pagequeryinteger
Responses
200 OKFields
  • dataarray of Mailbox
    • idinteger
    • addressstring
    • first_namestring | null
    • last_namestring | null
    • quota_gbinteger | null
    • statusstring
    • created_atstring (date-time) | null
  • metaPageMeta
    • totalinteger
    • per_pageinteger
    • current_pageinteger
    • last_pageinteger
401403404429 Errors — error format and codes
Example
curl
curl https://api.rivervo.com/api/partner/v1/mail/domains/812/mailboxes \
  -H "Authorization: Bearer $RIVERVO_API_KEY"
POST/mail/domains/{id}/mailboxes

Create a mailbox

Parameters
  • Idempotency-Keyheaderstringrequired

    Your unique key for this change (1–128 of A–Z a–z 0–9 - _ . :). The same key with the same request returns the first answer (header Idempotent-Replayed: true) and never charges twice; with another request: 409 idempotency_conflict.

  • idpathintegerrequired

    The email domain id.

Request body application/json
  • local_partstringrequired
  • passwordstringrequired
  • first_namestring
  • last_namestring
Responses
201 OKFields
  • dataMailbox
    • idinteger
    • addressstring
    • first_namestring | null
    • last_namestring | null
    • quota_gbinteger | null
    • statusstring
    • created_atstring (date-time) | null
  • orderOrder
    • idinteger
    • actionstring
    • statusstring

      Values: processing · completed · failed

    • idempotency_keystring
    • resourceobject | null
      • typestring
      • idinteger
    • charged_centsinteger | null
    • retail_centsinteger | null
    • currencystring
    • errorobject | null
      • codestring
      • messagestring
    • created_atstring (date-time) | null
    • completed_atstring (date-time) | null
400401402403404409422429502 Errors — error format and codes
Example
curl
curl -X POST https://api.rivervo.com/api/partner/v1/mail/domains/812/mailboxes \
  -H "Authorization: Bearer $RIVERVO_API_KEY" \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "local_part": "info",
    "password": "A-long-secret-1",
    "first_name": "Aysel",
    "last_name": "Mammadova"
  }'
PATCH/mail/mailboxes/{id}

Change a mailbox password or name

Parameters
  • Idempotency-Keyheaderstringrequired

    Your unique key for this change (1–128 of A–Z a–z 0–9 - _ . :). The same key with the same request returns the first answer (header Idempotent-Replayed: true) and never charges twice; with another request: 409 idempotency_conflict.

  • idpathintegerrequired

    The mailbox id.

Request body application/json
  • passwordstring
  • first_namestring
  • last_namestring
Responses
200 OKFields
  • dataMailbox
    • idinteger
    • addressstring
    • first_namestring | null
    • last_namestring | null
    • quota_gbinteger | null
    • statusstring
    • created_atstring (date-time) | null
  • orderOrder
    • idinteger
    • actionstring
    • statusstring

      Values: processing · completed · failed

    • idempotency_keystring
    • resourceobject | null
      • typestring
      • idinteger
    • charged_centsinteger | null
    • retail_centsinteger | null
    • currencystring
    • errorobject | null
      • codestring
      • messagestring
    • created_atstring (date-time) | null
    • completed_atstring (date-time) | null
400401402403404409422429502 Errors — error format and codes
Example
curl
curl -X PATCH https://api.rivervo.com/api/partner/v1/mail/mailboxes/812 \
  -H "Authorization: Bearer $RIVERVO_API_KEY" \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "password": "A-long-secret-1",
    "first_name": "Aysel",
    "last_name": "Mammadova"
  }'
DELETE/mail/mailboxes/{id}

Delete a mailbox with its mail

Parameters
  • Idempotency-Keyheaderstringrequired

    Your unique key for this change (1–128 of A–Z a–z 0–9 - _ . :). The same key with the same request returns the first answer (header Idempotent-Replayed: true) and never charges twice; with another request: 409 idempotency_conflict.

  • idpathintegerrequired

    The mailbox id.

Responses
200 OKFields
  • dataobject
    • idinteger
    • deletedboolean
  • orderOrder
    • idinteger
    • actionstring
    • statusstring

      Values: processing · completed · failed

    • idempotency_keystring
    • resourceobject | null
      • typestring
      • idinteger
    • charged_centsinteger | null
    • retail_centsinteger | null
    • currencystring
    • errorobject | null
      • codestring
      • messagestring
    • created_atstring (date-time) | null
    • completed_atstring (date-time) | null
400401402403404409422429502 Errors — error format and codes
Example
curl
curl -X DELETE https://api.rivervo.com/api/partner/v1/mail/mailboxes/812 \
  -H "Authorization: Bearer $RIVERVO_API_KEY" \
  -H "Idempotency-Key: order-1042"
GET/mail/domains/{id}/aliases

Aliases and forwards of a domain

Parameters
  • idpathintegerrequired

    The email domain id.

  • pagequeryinteger
  • per_pagequeryinteger
Responses
200 OKFields
  • dataarray of MailAlias
    • idinteger
    • addressstring
    • destinationsarray of string
    • created_atstring (date-time) | null
  • metaPageMeta
    • totalinteger
    • per_pageinteger
    • current_pageinteger
    • last_pageinteger
401403404429 Errors — error format and codes
Example
curl
curl https://api.rivervo.com/api/partner/v1/mail/domains/812/aliases \
  -H "Authorization: Bearer $RIVERVO_API_KEY"
POST/mail/domains/{id}/aliases

Create an alias or forward

Parameters
  • Idempotency-Keyheaderstringrequired

    Your unique key for this change (1–128 of A–Z a–z 0–9 - _ . :). The same key with the same request returns the first answer (header Idempotent-Replayed: true) and never charges twice; with another request: 409 idempotency_conflict.

  • idpathintegerrequired

    The email domain id.

Request body application/json
  • local_partstringrequired
  • destinationsarray of string (email)required
Responses
201 OKFields
  • dataMailAlias
    • idinteger
    • addressstring
    • destinationsarray of string
    • created_atstring (date-time) | null
  • orderOrder
    • idinteger
    • actionstring
    • statusstring

      Values: processing · completed · failed

    • idempotency_keystring
    • resourceobject | null
      • typestring
      • idinteger
    • charged_centsinteger | null
    • retail_centsinteger | null
    • currencystring
    • errorobject | null
      • codestring
      • messagestring
    • created_atstring (date-time) | null
    • completed_atstring (date-time) | null
400401402403404409422429502 Errors — error format and codes
Example
curl
curl -X POST https://api.rivervo.com/api/partner/v1/mail/domains/812/aliases \
  -H "Authorization: Bearer $RIVERVO_API_KEY" \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "local_part": "info",
    "destinations": [
      "office@client.az"
    ]
  }'
DELETE/mail/aliases/{id}

Delete an alias

Parameters
  • Idempotency-Keyheaderstringrequired

    Your unique key for this change (1–128 of A–Z a–z 0–9 - _ . :). The same key with the same request returns the first answer (header Idempotent-Replayed: true) and never charges twice; with another request: 409 idempotency_conflict.

  • idpathintegerrequired

    The alias id.

Responses
200 OKFields
  • dataobject
    • idinteger
    • deletedboolean
  • orderOrder
    • idinteger
    • actionstring
    • statusstring

      Values: processing · completed · failed

    • idempotency_keystring
    • resourceobject | null
      • typestring
      • idinteger
    • charged_centsinteger | null
    • retail_centsinteger | null
    • currencystring
    • errorobject | null
      • codestring
      • messagestring
    • created_atstring (date-time) | null
    • completed_atstring (date-time) | null
400401402403404409422429502 Errors — error format and codes
Example
curl
curl -X DELETE https://api.rivervo.com/api/partner/v1/mail/aliases/812 \
  -H "Authorization: Bearer $RIVERVO_API_KEY" \
  -H "Idempotency-Key: order-1042"

Webhook events

What we send to your webhook URL. Signature verification and retries are described in the Webhooks section. →

POSTorder.completed

An order finished

PayloadFields
  • idstring
  • eventstring
  • created_atstring (date-time) | null
  • dataobject
    • orderOrder
      • idinteger
      • actionstring
      • statusstring

        Values: processing · completed · failed

      • idempotency_keystring
      • resourceobject | null
        • typestring
        • idinteger
      • charged_centsinteger | null
      • retail_centsinteger | null
      • currencystring
      • errorobject | null
        • codestring
        • messagestring
      • created_atstring (date-time) | null
      • completed_atstring (date-time) | null
POSTorder.failed

An order failed (nothing charged, or refunded)

PayloadFields
  • idstring
  • eventstring
  • created_atstring (date-time) | null
  • dataobject
    • orderOrder
      • idinteger
      • actionstring
      • statusstring

        Values: processing · completed · failed

      • idempotency_keystring
      • resourceobject | null
        • typestring
        • idinteger
      • charged_centsinteger | null
      • retail_centsinteger | null
      • currencystring
      • errorobject | null
        • codestring
        • messagestring
      • created_atstring (date-time) | null
      • completed_atstring (date-time) | null
POSTbalance.low

The partner balance crossed a threshold (accounts with credit)

PayloadFields
  • idstring
  • eventstring
  • created_atstring (date-time) | null
  • dataobject
    • stagestring
    • balance_centsinteger
    • credit_limit_centsinteger
    • available_centsinteger
Partner API documentation