Документация · API v1

API ARTΞMIDA
для вашего VPN-сервиса

Создавайте, продлевайте и отключайте VPN-ключи своих клиентов одним HTTP-запросом. Ниже — все методы с примерами запросов и ответов.

Получить доступ Как работает баланс Цены и доход

Как устроена оплата

Баланс API — простыми словами

Никакой абонентской платы: вы платите только за ключи, которые выдаёте клиентам.

1
Пополняете баланс
В кабинете API или запросом POST /wallet/topups: СБП, карта или крипта. Это отдельный баланс, его нельзя потратить в обычном кабинете.
2
Выдаёте ключ — списывается цена
При создании, продлении или добавлении устройств с баланса списывается оптовая цена. Чем больше у вас активных ключей, тем она ниже.
3
Не хватает — ничего не создаётся
Если баланса мало, API вернёт 402, и ключ не будет создан. Без автосписаний: деньги уходят только по вашему запросу. Вся история — в кабинете.

DOCS · V1

ARTΞMIDA Paid API

Компактная документация для VPN-ботов. Нажмите endpoint — запрос и пример ответа откроются сразу. Каждый блок можно свернуть отдельно.

Base URLhttps://artemida.cc/v1

Idempotency-Key

Для запросов, которые создают или изменяют ключ, передавайте уникальный Idempotency-Key. Это защищает от случайного повтора операции.

DNSedge.example.comСвой домен для подписок

Коротко: направьте домен на сервер, дождитесь DNS и сохраните его в «Бренд подписок».

Рекомендуем — CNAME: edge.example.com → CNAME → xskx.artemida.live. Если мы сменим IP сервера, домен переедет сам — ничего делать не придётся.
Или A-запись (для корневого домена, где CNAME нельзя): example.com → …. При смене IP её нужно будет поменять — мы предупредим заранее.
Подождите обновления DNS — от нескольких минут до нескольких часов. Проверить можно через dnschecker.org, затем сохраните домен в кабинете.
HTTPS подключится автоматически. Готовая ссылка: https://edge.example.com/SHORT_UUID.

Нужна только одна запись: CNAME или A. Если используете Cloudflare — DNS only. Не направляйте AAAA-запись на другой сервер.

GET/balanceБаланс API

Отдельный баланс, который нельзя тратить в обычном кабинете.

Запрос

curl https://artemida.cc/v1/balance \
  -H "Authorization: Bearer $API_KEY"

200 · ответ

{"ok":true,"data":{"balance":1840,"currency":"RUB"},"meta":{"requestId":"req_..."}}

GET/pricing?devices=10&days=30Расчёт цены

Любой срок от 1 до 365 дней (включительно), с точной серверной ценой по индивидуальному тарифу магазина. Те же серверные формулы и скидки, что на сайте.

Запрос

curl "https://artemida.cc/v1/pricing?devices=10&days=30" \
  -H "Authorization: Bearer $API_KEY"

200 · ответ

{"ok":true,"data":{"periods":[7,30,60,90,180,365],"minDays":1,"maxDays":365,"trial":{"days":1,"devices":2,"amount":2,"currency":"RUB"},"quote":{"devices":10,"days":30,"amount":600,"currency":"RUB"}}}

POST/wallet/topupsСоздать пополнение

Создаёт Platega-счёт для API-баланса. Повтор с тем же Idempotency-Key не создаёт второй счёт.

Запрос

curl -X POST https://artemida.cc/v1/wallet/topups \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: topup-client-845912-01" \
  -H "Content-Type: application/json" \
  -d '{"amount":1000}'

201 · ответ

{
  "ok": true,
  "data": {
    "operationId": "op_...",
    "payment": {"id":"A...","amount":1000,"currency":"RUB","url":"https://...","status":"CREATED"}
  }
}

GET/wallet/topups/{paymentId}Проверить оплату

Проверяет статус платежа и после подтверждения зачисляет сумму на API-баланс. Повторная проверка уже обработанного платежа не зачисляет средства второй раз.

Запрос

curl https://artemida.cc/v1/wallet/topups/A1234567890ABCDEF \
  -H "Authorization: Bearer $API_KEY"

200 · ответ

{"ok":true,"data":{"payment":{"id":"A...","amount":1000,"currency":"RUB","status":"CONFIRMED","paid":true,"processed":true,"processing":false},"balance":2840}}

POST/trialTrial · 1 день · 2 ₽

Создаёт отдельный VPN-ключ на 1 день и 2 устройства за 2 ₽ с API-баланса. Лимит на серверах-обходах: 5 ГБ, остальные серверы без лимита на время trial. Количество trial-заказов не ограничено; для каждого нового заказа используйте новый Idempotency-Key.

Запрос

curl -X POST https://artemida.cc/v1/trial \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: trial-my-account-01"

201 · ответ

{"ok":true,"data":{"operationId":"op_...","key":{"id":"key_...","name":"api_trial","devices":2,"trial":true},"trial":{"days":1,"devices":2,"price":2},"charged":2,"balance":998,"currency":"RUB"}}

POST/keysКупить VPN-ключ

Списывает API-баланс и создаёт подписку. name — название ключа для вашего удобства, customerRef — необязательный ID клиента, trafficLimitGb=0 или отсутствие поля означает безлимитный трафик.

Запрос · безлимит

curl -X POST https://artemida.cc/v1/keys \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: order-845912" \
  -H "Content-Type: application/json" \
  -d '{"days":30,"devices":2,"name":"client_845912","customerRef":"845912"}'

Запрос · лимит 100 ГБ

curl -X POST https://artemida.cc/v1/keys \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: order-845912-100gb" \
  -H "Content-Type: application/json" \
  -d '{"days":30,"devices":2,"trafficLimitGb":100,"name":"client_845912","customerRef":"845912"}'

201 · ответ

{"ok":true,"data":{"operationId":"op_...","key":{"id":"key_...","name":"api_client_845912","devices":2,"trafficUnlimited":false,"trafficLimitGb":100,"trafficLimitBytes":107374182400,"subscriptionUrl":"https://..."},"charged":120,"balance":1720,"currency":"RUB"}}

GET/keysСписок ключей

Параметры: limit, offset, includeRevoked=true, q — поиск по ID, названию или customerRef.

Запрос

curl https://artemida.cc/v1/keys?limit=100 \
  -H "Authorization: Bearer $API_KEY"

200 · ответ

{"ok":true,"data":{"items":[{"id":"key_...","name":"api_client_845912","devices":2,"trafficUnlimited":false,"trafficLimitGb":100,"trial":false}],"count":1}}

GET/keys/{id}Актуальное состояние

Возвращает актуальное состояние ключа: статус, срок, устройства, трафик и ссылку подписки.

Запрос

curl https://artemida.cc/v1/keys/key_abc123 \
  -H "Authorization: Bearer $API_KEY"

200 · ответ

{"ok":true,"data":{"key":{"id":"key_abc123","name":"api_client","status":"ACTIVE","devices":2,"trafficUnlimited":false,"trafficLimitGb":100,"remainingDays":18,"subscriptionUrl":"https://..."}}}

POST/keys/{id}/renewПродлить ключ

Платная операция. Trial-ключи продлевать нельзя.

Запрос

curl -X POST https://artemida.cc/v1/keys/key_abc123/renew \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: renew-845912-202609" \
  -H "Content-Type: application/json" \
  -d '{"days":30,"devices":5}'

200 · ответ

{"ok":true,"data":{"operationId":"op_...","key":{"id":"key_abc123","devices":5,"expireAt":"..."},"charged":223,"balance":1528,"currency":"RUB"}}

POST/keys/{id}/upgradeУвеличить устройства

Списывает доплату по оставшемуся сроку. Trial-ключи апгрейдить нельзя.

Запрос

curl -X POST https://artemida.cc/v1/keys/key_abc123/upgrade \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: upgrade-845912-01" \
  -H "Content-Type: application/json" \
  -d '{"addDevices":3}'

200 · ответ

{"ok":true,"data":{"operationId":"op_...","key":{"id":"key_abc123","devices":5},"charged":134,"balance":1394}}

DELETE/keys/{id}Отозвать ключ

Идемпотентно отключает ключ. Требует Idempotency-Key.

Запрос

curl -X DELETE https://artemida.cc/v1/keys/key_abc123 \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: revoke-abc123-01"

200 · ответ

{"ok":true,"data":{"operationId":"op_...","key":{"id":"key_abc123","status":"REVOKED"},"deleted":true}}

POST/keys/{id}/disableОтключить ключ

Бесплатно. Временно отключает ключ, не меняя срок, лимит трафика и устройства.

Запрос

curl -X POST https://artemida.cc/v1/keys/key_abc123/disable \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: disable-abc123-01"

200 · ответ

{"ok":true,"data":{"operationId":"op_...","key":{"id":"key_abc123","status":"DISABLED"},"enabled":false}}

POST/keys/{id}/enableВключить ключ

Бесплатно. Включает ранее отключённый неистёкший ключ. Истёкший ключ сначала нужно продлить.

Запрос

curl -X POST https://artemida.cc/v1/keys/key_abc123/enable \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: enable-abc123-01"

200 · ответ

{"ok":true,"data":{"operationId":"op_...","key":{"id":"key_abc123","status":"ACTIVE"},"enabled":true}}

POST/PATCH/keys/{id}/trafficИзменить лимит трафика

Бесплатно. trafficLimitGb=0 включает безлимит. Значение 1–100000 задаёт новый общий лимит на ключ. Увеличивать и уменьшать лимит можно в любой момент.

Запрос · 250 ГБ

curl -X PATCH https://artemida.cc/v1/keys/key_abc123/traffic \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: traffic-abc123-250" \
  -H "Content-Type: application/json" \
  -d '{"trafficLimitGb":250}'

Запрос · безлимит

curl -X PATCH https://artemida.cc/v1/keys/key_abc123/traffic \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: traffic-abc123-unlimited" \
  -H "Content-Type: application/json" \
  -d '{"trafficLimitGb":0}'

200 · ответ

{"ok":true,"data":{"operationId":"op_...","key":{"id":"key_abc123"},"trafficLimitGb":250,"trafficLimitBytes":268435456000,"trafficUnlimited":false,"charged":0}}

POST/keys/{id}/traffic/resetСбросить использованный трафик

Бесплатно. Сбрасывает счётчик использованного трафика, но не меняет установленный лимит.

Запрос

curl -X POST https://artemida.cc/v1/keys/key_abc123/traffic/reset \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: traffic-reset-abc123-01"

200 · ответ

{"ok":true,"data":{"operationId":"op_...","key":{"id":"key_abc123"},"reset":true,"charged":0}}

DELETE/keys/{id}/permanentУдалить навсегда

Без возврата средств. Удаляет ключ без возможности восстановления.

Запрос

curl -X DELETE https://artemida.cc/v1/keys/key_abc123/permanent \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: delete-abc123-01"

200 · ответ

{"ok":true,"data":{"operationId":"op_...","key":{"id":"key_abc123"},"deleted":true}}

GET/keys/{id}/devicesПросмотреть устройства

Возвращает список подключённых устройств.

Запрос

curl https://artemida.cc/v1/keys/key_abc123/devices \
  -H "Authorization: Bearer $API_KEY"

200 · ответ

{"ok":true,"data":{"items":[{"token":"42f9d0f3d6ad10ce","name":"iPhone"}],"used":1,"limit":5}}

DELETE/keys/{id}/devices/{token}Удалить устройство

Требует Idempotency-Key; повтор после успешного удаления считается успешным.

Запрос

curl -X DELETE https://artemida.cc/v1/keys/key_abc123/devices/42f9d0f3d6ad10ce \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: device-delete-abc123-01"

200 · ответ

{"ok":true,"data":{"operationId":"op_...","deleted":true}}

POST/keys/{id}/devices/clearСбросить все устройства

Требует Idempotency-Key.

Запрос

curl -X POST https://artemida.cc/v1/keys/key_abc123/devices/clear \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: devices-clear-abc123-01"

200 · ответ

{"ok":true,"data":{"operationId":"op_...","cleared":true}}

GET/keys/{id}/subscription-linksАктуальные VLESS / ссылки

Возвращает актуальные ссылки подключения для этого ключа.

Запрос

curl https://artemida.cc/v1/keys/key_abc123/subscription-links \
  -H "Authorization: Bearer $API_KEY"

200 · VLESS в ответе

{
  "ok": true,
  "data": {
    "keyId": "key_abc123",
    "subscriptionUrl": "https://sub.example/s/abc123",
    "fetchedAt": 1788330000,
    "cached": false,
    "count": 3,
    "vless": [
      "vless://00000000-0000-4000-8000-000000000001@de.example:443?security=tls&type=tcp#DE-1",
      "vless://00000000-0000-4000-8000-000000000002@nl.example:443?security=tls&type=ws#NL-1"
    ],
    "links": ["vless://...", "vless://...", "trojan://..."]
  }
}

ERROR FORMATJSON-ошибки и Retry-After

{
  "ok": false,
  "error": {"code":"insufficient_balance","message":"Недостаточно средств. Нужно 436 ₽, доступно 100 ₽."},
  "meta": {"requestId":"req_..."}
}

401 — авторизация, 402 — баланс, 409 — idempotency/состояние, 429 — слишком много запросов, 502/503 — временная ошибка интеграции. Для временных ошибок учитывайте Retry-After.

API ARTΞMIDAдля вашего VPN-сервиса

ARTΞMIDA Paid API

API ARTΞMIDA
для вашего VPN-сервиса