API

Introduction

CLORE.AI api can be used to automate deployments of your workloads onto CLORE.AI

Firstly you need to get an API key

---

Введение

API CLORE.AI можно использовать для автоматизации развёртывания ваших рабочих процессов на платформе CLORE.AI.

В первую очередь, вам нужно получить API-ключ.

Ответы API

Ответы возвращаются в формате JSON и могут содержать разные поля.

Поле code, указывающее статус, всегда присутствует.

Поле code

code	Описание
0	NORMAL
1	DATABASE ERROR
2	INVALID INPUT DATA
3	INVALID API TOKEN
4	INVALID ENDPOINT
5	EXCEEDED 1 request/second limit
6	Ошибка, указанная в поле error

Конечные точки

1. wallets

   • Описание: Возвращает кошельки и балансы.

   Заголовки

   Поле	Тип	Обязательное	Описание
   auth	string	Да	API токен

   Ответ

   Поле	Тип	Описание
   code	int	Код статуса
   wallets	[]string	Массив кошельков

   Пример

   Запрос:

   curl -XGET -H 'auth: b8qwqRAL5W7YDyDJeB4XANVvKndbrrPk' 'https://api.clore.ai/v1/wallets'

   Ответ:

   {
     "wallets": [
       {
         "name": "bitcoin",
         "deposit": "tb1q6erw7v02t7hakgmlcl4wfnlykzqj05alndruwr",
         "balance": 0.00153176,
         "withdrawal_fee": 0.0001
       }
     ],
     "code": 0
   }

2. my_servers

   • Описание: Возвращает список ваших серверов, предоставляемых на маркетплейсе clore.ai.

   Заголовки

   Поле	Тип	Обязательное	Описание
   auth	string	Да	API токен

   Ответ

   Поле	Тип	Описание
   code	int	Код статуса
   limit	int	Максимальное количество серверов, которые вы можете иметь
   servers	[]string	Массив серверов
   servers[x].name	string	Имя сервера, выбранное пользователем
   servers[x].connected	string	Был ли сервер когда-либо подключен к clore.ai
   servers[x].visibility	string	Видимость на маркетплейсе
   servers[x].pricing	[]string	Цена в день на on-demand
   servers[x].online	bool	В сети ли сервер
   servers[x].min_spot_pricing	[]string	Минимальная цена в день для аренды на spot рынке
   servers[x].init_token	string	Токен инициализации
   servers[x].specs	[]string	Характеристики сервера

   Пример

   Запрос:

   curl -XGET -H 'auth: b8qwqRAL5W7YDyDJeB4XANVvKndbrrPk' 'https://api.clore.ai/v1/my_servers'

   Ответ:

   {
     "servers": [
       {
         "name": "Michael",
         "connected": false,
         "visibility": "hidden",
         "pricing": { "bitcoin": 0, "usd": 0 },
         "online": false,
         "min_spot_pricing": { "bitcoin": 0, "usd": 0 },
         "init_token": "qnwVIMsZPjUWS7jw6gAbTOeoGQNgTH9XVxJaiCEbG0OlmfjF"
       },
       {
         "name": "Jan Vykydal",
         "connected": true,
         "visibility": "public",
         "pricing": { "bitcoin": 0.00010337, "usd": 0 },
         "online": false,
         "min_spot_pricing": { "bitcoin": 0.00005168, "usd": 0 },
         "specs": {
           "mb": "Z590 GAMING X",
           "cpu": "Intel Core i9-11900",
           "cpus": "8/16",
           "ram": 64,
           "disk": "NVMe 512GB",
           "disk_speed": 2000,
           "gpu": "1x GeForce GTX 1080 Ti",
           "gpuram": 11,
           "net": {
             "down": 119.61,
             "up": 25.24
           }
         }
       }
     ],
     "limit": 16,
     "code": 0
   }

   *USD пока не поддерживается

3. server_config

   • Описание: Получить конфигурацию конкретного сервера.

   Заголовки

   Поле	Тип	Обязательное	Описание
   auth	string	Да	API токен
   Content-type	string	Да	Должно быть application/json

   Тело запроса

   Поле	Тип	Обязательное	Описание
   server_name	string	Да	Имя сервера

   Ответ

   Поле	Тип	Описание
   code	int	Код статуса
   creation_completed	bool	Завершено ли создание сервера
   config	[]string	Конфигурация сервера
   config.name	string	Имя сервера, выбранное пользователем
   config.connected	bool	Был ли сервер когда-либо подключен к clore.ai
   config.visibility	string	Видимость на маркетплейсе
   config.pricing	[]string	Цена в день на on-demand
   config.spot_pricing	[]string	Минимальная цена в день для аренды на spot рынке
   config.mrl	int	Максимальная длина аренды в часах
   config.online	bool	В сети ли сервер
   config.initialized	bool	Был ли сервер когда-либо подключен к clore.ai
   config.id	int	Уникальный идентификатор сервера
   config.rental_status	int	0 - не арендован
   config.specs	[]string	Характеристики сервера
   config.background_job	[]string	Задание на фоновые операции, если не в аренде

   Пример

   Запрос:

   curl -XGET -H 'auth: b8qwqRAL5W7YDyDJeB4XANVvKndbrrPk' -H "Content-type: application/json" -d '{
       "server_name":"Jan Vykydal"
   }' 'https://api.clore.ai/v1/server_config'

   Ответ:

   {
     "config": {
       "name": "Jan Vykydal",
       "connected": true,
       "visibility": "public",
       "pricing": { "bitcoin": 0.00010337, "usd": 0 },
       "spot_pricing": { "bitcoin": 0.00005168, "usd": 0 },
       "mrl": 72,
       "online": false,
       "initialized": true,
       "id": 4,
       "rental_status": 0,
       "specs": {
         "mb": "Z590 GAMING X",
         "cpu": "Intel Core i9-11900",
         "cpus": "8/16",
         "ram": 64,
         "disk": "NVMe 512GB",
         "disk_speed": 2000,
         "gpu": "1x GeForce GTX 1080 Ti",
         "gpuram": 11,
         "net": {
           "down": 119.61,
           "up": 25.24
         }
       },
       "background_job": {
         "times_updated": 1,
         "image": "cloreai/ubuntu20.04-jupyter",
         "command": "",
         "env": []
       }
     },
     "creation_completed": true,
     "code": 0
   }

   *USD пока не поддерживается

---

1. marketplace

   • Описание: Получить список серверов на маркетплейсе.

   Заголовки

   Поле	Тип	Обязательное	Описание
   auth	string	Да	API токен

   Ответ

   Поле	Тип	Описание
   code	int	Код статуса
   my_servers	[]string	Массив ID серверов, которые вы предоставляете на clore.ai (не доступны для аренды)
   servers	[]string	Массив публичных серверов на маркетплейсе
   servers[x].id	int	Уникальный идентификатор сервера
   servers[x].owner	int	Уникальный идентификатор владельца
   servers[x].mrl	int	Максимальная длина аренды в часах
   servers[x].price.on_demand	[]string	Цена в день на on-demand аренду
   servers[x].spot	[]string	Минимальная цена в день на spot рынке
   servers[x].rented	bool	Арендован ли сервер в данный момент
   servers[x].specs	[]string	Характеристики сервера

   Пример

   Запрос:

   curl -XGET -H 'auth: b8qwqRAL5W7YDyDJeB4XANVvKndbrrPk' 'https://api.clore.ai/v1/marketplace'

   Ответ:

   {
     "servers": [
       {
         "id": 6,
         "owner": 4,
         "mrl": 73,
         "price": { "on_demand": { "bitcoin": 0.00001 }, "spot": { "bitcoin": 0.000001 }},
         "rented": false,
         "specs": {
           "mb": "Z590 GAMING X",
           "cpu": "11th Gen Intel(R) Core(TM) i9-11900 @ 2.50GHz",
           "cpus": "8/16",
           "ram": 62.67,
           "disk": "NVMe диск 247.36 ГБ",
           "disk_speed": 0,
           "gpu": "1x NVIDIA GeForce GTX 1080 Ti",
           "gpuram": 11,
           "net": {
             "up": 26.38,
             "down": 118.42,
             "cc": "CZ"
           }
         }
       }
     ],
     "my_servers": [1, 2, 4],
     "code": 0
   }

2. my_orders

   • Описание: Получить список ваших заказов.

   Заголовки

   Поле	Тип	Обязательное	Описание
   auth	string	Да	API токен

   Строка запроса

   Поле	Тип	Обязательное	Описание
   return_completed	bool	Нет	Возвращает завершённые (истекшие) заказы

   Ответ

   Поле	Тип	Описание
   code	int	Код статуса
   limit	int	Максимальное количество активных заказов
   orders	[]string	Массив заказов
   orders[x].id	int	Уникальный ID заказа
   orders[x].fee	float	Комиссия (%) для clore.ai
   orders[x].creation_fee	float	Комиссия при создании заказа
   orders[x].price	float	Цена заказа (стоимость) за день
   orders[x].mrl	int	Максимальная длина аренды в секундах
   orders[x].image	string	Используемый docker образ
   orders[x].currency	string	Валюта, используемая для оплаты
   orders[x].spend	float	Сумма, потраченная на заказ
   orders[x].ct	int	Время создания (UNIX)
   orders[x].p	int	Используемый прокси-кластер
   orders[x].specs	[]string	Характеристики сервера
   orders[x].si	int	Уникальный ID сервера
   orders[x].pub_cluster	[]string	Публичные конечные точки с перенаправленными портами
   orders[x].tcp_ports	[]string	Перенаправление TCP портов
   orders[x].http_port	string	Порт контейнера, перенаправленный через HTTPS-прокси
   orders[x].spot	bool	Является ли заказ на spot рынке
   orders[x].expired	bool	Указание, что заказ истек

   Пример

   Запрос:

   curl -XGET -H 'auth: b8qwqRAL5W7YDyDJeB4XANVvKndbrrPk' 'https://api.clore.ai/v1/my_orders?return_completed=true'

   Ответ:

   {
     "orders": [
       {
         "id": 38,
         "fee": 5,
         "creation_fee": 3e-7,
         "price": 0.00001,
         "mrl": 262800,
         "image": "cloreai/ubuntu20.04-jupyter",
         "currency": "bitcoin",
         "spend": 6.944444444444445e-9,
         "ct": 1667401396,
         "p": 1,
         "specs": {
           "mb": "Z590 GAMING X",
           "cpu": "Intel Core i9-11900",
           "cpus": "8/16",
           "ram": 62.67,
           "disk": "NVMe диск 247.36 ГБ",
           "disk_speed": 2000,
           "gpu": "1x NVIDIA GeForce GTX 1080 Ti",
           "gpuram": 11,
           "net": {
             "up": 26.38,
             "down": 118.42
           }
         },
         "si": 6,
         "pub_cluster": [ "n1.c1.clorecloud.net", "n2.c1.clorecloud.net" ],
         "tcp_ports": [ "22:10000" ],
         "http_port": "8888"
       },
       {
         "id": 36,
         "fee": 2.5,
         "creation_fee": 1e-7,
         "price": 0.00001,
         "mrl": 262800,
         "image": "cloreai/ubuntu20.04-jupyter",
         "currency": "bitcoin",
         "spend": 1.3888888888888888e-7,
         "ct": 1667248597,
         "specs": {
           "mb": "Z590 GAMING X",
           "cpu": "Intel Core i9-11900",
           "cpus": "8/16",
           "ram": 62.67,
           "disk": "NVMe диск 247.36 ГБ",
           "disk_speed": 2000,
           "gpu": "1x NVIDIA GeForce GTX 1080 Ti",
           "gpuram": 11,
           "net": {
             "up": 26.38,
             "down": 118.42
           }
         },
         "si": 6,
         "spot": true,
         "expired": true,
         "tcp_ports": []
       }
     ],
     "limit": 13,
     "code": 0
   }

---

1. spot_marketplace

   • Описание: Получить список предложений на spot рынке для конкретного сервера.

   Заголовки

   Поле	Тип	Обязательное	Описание
   auth	string	Да	API токен

   Строка запроса

   Поле	Тип	Обязательное	Описание
   market	int	Да	Уникальный ID сервера

   Ответ

   Поле	Тип	Описание
   code	int	Код статуса
   exists	bool	Проверка, что рынок существует
   market	object	Рынок
   market.offers	array	Предложения аренды для сервера
   market.offers[x].offer_id	int	Уникальный ID предложения
   market.offers[x].bid	float	Предложенная цена за день
   market.offers[x].active	bool	Действующее предложение
   market.offers[x].my	bool	Является ли это предложение вашим
   market.server	object	Информация о сервере
   market.server.min_pricing	object	Минимальная цена за день
   market.server.mrl	int	Максимальная длина аренды в секундах
   market.server.visibility	string	Можно создавать предложения, только если видимость - публичная
   market.server.online	bool	Сервер онлайн

   Пример

   Запрос:

   curl -XGET -H 'auth: b8qwqRAL5W7YDyDJeB4XANVvKndbrrPk' 'https://api.clore.ai/v1/spot_marketplace?market=6'

   Ответ:

   {
     "market": {
       "offers": [
         {
           "offer_id": 39,
           "bid": 0.0000042,
           "active": true,
           "my": true
         }
       ],
       "server": {
         "min_pricing": {
           "bitcoin": 0.000001
         },
         "mrl": 262800,
         "visibility": "public",
         "online": true
       }
     },
     "exists": true,
     "code": 0
   }

2. set_server_settings

   • Описание: Настройка параметров сервера, который вы предоставляете на маркетплейсе clore.ai.

   Заголовки

   Поле	Тип	Обязательное	Описание
   auth	string	Да	API токен
   Content-type	string	Да	Должно быть application/json

   Тело запроса

   Поле	Тип	Обязательное	Описание
   name	string	Да	Выбранное пользователем имя сервера
   availability	bool	Да	Может ли сервер быть арендован
   mrl	int	Да	Максимальная длина аренды сервера
   on_demand	float	Да	Цена за день аренды сервера по требованию
   spot	float	Да	Минимальная цена за день аренды на SPOT-рынке

   Ответ

   Поле	Тип	Описание
   code	int	Код статуса

   Пример

   Создаём транзакцию для отправки средств из текущего кошелька.

   Запрос:

   curl -XPOST -H 'auth: b8qwqRAL5W7YDyDJeB4XANVvKndbrrPk' -H "Content-type: application/json" -d '{
       "name": "Jan Vykydal",
       "availability": true,
       "mrl": 96,
       "on_demand": 0.0001,
       "spot": 0.00000113
   }' 'https://api.clore.ai/v1/set_server_settings'

   Ответ:

   {
     "code": 0
   }

---

1. set_spot_price

   • Описание: Установить цену за день аренды на SPOT-рынке.

   Заголовки

   Поле	Тип	Обязательное	Описание
   auth	string	Да	API токен
   Content-type	string	Да	Должно быть application/json

   Тело запроса

   Поле	Тип	Обязательное	Описание
   order_id	int	Да	Уникальный ID предложения
   desired_price	float	Да	Желаемая цена за день аренды

   Пример

   Попробуем обновить цену на SPOT-рынке.

   Запрос 1 (Шаг снижения был слишком большим):

   curl -XPOST -H 'auth: b8qwqRAL5W7YDyDJeB4XANVvKndbrrPk' -H "Content-type: application/json" -d '{
       "order_id": 39,
       "desired_price": 0.00000200
   }' 'https://api.clore.ai/v1/set_spot_price'

   Возможный ответ 1 (Шаг снижения был слишком большим):

   {
       "error": "exceeded_max_step",
       "max_step": 0.0000032,
       "code": 6
   }

   Поля ответа

   Поле	Тип	Описание
   code	int	Код статуса
   error	string	Описание ошибки
   max_step	float	Наименьшее значение, до которого можно снизить цену

   Запрос 2 (Корректный шаг снижения):

   curl -XPOST -H 'auth: b8qwqRAL5W7YDyDJeB4XANVvKndbrrPk' -H "Content-type: application/json" -d '{
       "order_id": 39,
       "desired_price": 0.00000320
   }' 'https://api.clore.ai/v1/set_spot_price'

   Возможный ответ 2 (Корректный шаг снижения):

   {
       "code": 0
   }

   Запрос 3 (Снижение цены ещё раз после отправки Запроса 2):

   curl -XPOST -H 'auth: b8qwqRAL5W7YDyDJeB4XANVvKndbrrPk' -H "Content-type: application/json" -d '{
       "order_id": 39,
       "desired_price": 0.00000220
   }' 'https://api.clore.ai/v1/set_spot_price'

   Возможный ответ 3 (Снижение цены ещё раз после отправки Запроса 2):

   {
       "error": "can_lower_every_600_seconds",
       "time_to_lowering": 513,
       "code": 6
   }

   Поля ответа

   Поле	Тип	Описание
   code	int	Код статуса
   error	string	Описание ошибки
   time_to_lowering	float	Оставшееся время (в секундах) до возможности повторного снижения цены

{
    "error":"can_lower_every_600_seconds",
    "time_to_lowering":513,
    "code":6
}

1. cancel_order

   • Описание: Установить цену за день на SPOT-предложении

   Заголовки

   Поле	Тип	Обязательное	Описание
   auth	string	Да	API токен
   Content-type	string	Да	Должно быть application/json

   Тело запроса

   Поле	Тип	Обязательное	Описание
   id	int	Да	Уникальный ID заказа/предложения
   issue	string	Нет	Если возникли проблемы с сервером, можно сообщить их команде clore.ai (максимум 2048 символов)

   Выходные данные

   Поле	Тип	Описание
   code	int	Код статуса

   Пример

   Отменить заказ/предложение.

   Ввод: В этом примере мы сообщаем о проблемах с GPU #1. Если у вас нет проблем, не включайте поле issue. Вы можете написать любое сообщение, и мы его проверим.

   curl -XPOST -H 'auth: b8qwqRAL5W7YDyDJeB4XANVvKndbrrPk' -H "Content-type: application/json" -d '{
       "id": 39,
       "issue": "GPU #1 перегревался и снижал производительность"
   }' 'https://api.clore.ai/v1/cancel_order'

   Выход:

   {
     "code": 0
   }

---

1. create_order

• Описание: Вы можете создать предложение на SPOT-рынке или по требованию с помощью этого конечного запроса. Ограничение — не более 1 запроса в 5 секунд.

Заголовки

Поле	Тип	Обязательное	Описание
auth	string	Да	API токен
Content-type	string	Да	Должно быть application/json

Тело запроса

Поле	Тип	Обязательное	Описание
currency	string	Да	Название валюты
image	string	Да	Действительный образ с DockerHub
renting_server	int	Да	ID сервера, который вы хотите арендовать
type	string	Да	on-demand или spot
spotprice	float	Зависит от типа	Цена за день на SPOT-рынке, обязательна при создании SPOT-заказа
ports	object	Нет	Конфигурация перенаправления портов, максимум 5 записей
env	object	Нет	Переменные окружения, ограничение — 12000 символов, после приведения к строке
jupyter_token	string	Нет	Токен Jupyter для образов с Jupyter Notebook, максимум 32 символа *
ssh_key	string	Нет	SSH-ключ для образов с SSH, максимум 3072 символа *
ssh_password	string	Нет	SSH-пароль для образов с SSH, максимум 32 символа *
command	string	Нет	Команда, которая будет выполнена на сервере после создания заказа
required_price	float	Нет	Укажите цену для начала заказа; если владелец изменит цену, заказ не запустится (только on-demand)
autossh_entrypoint	bool	Нет	Использовать точку входа clore.ai, которая автоматически развертывает SSH-сервер и скрипт /root/onstart.sh

• В поля, помеченные звездочкой, можно вводить только символы из регулярного выражения /^[a-zA-Z0-9\s-=.@+/]+$/

Выходные данные

Поле	Тип	Описание
code	int	Код статуса

Пример

Ввод 1 (Создание предложения на SPOT-рынке):

curl -XPOST -H 'auth: 6FcuR7ibcwKR1Z32lEFoSotzUUtzKO2H' -H "Content-type: application/json" -d '
{
    "currency": "bitcoin",
    "image": "cloreai/ubuntu20.04-jupyter",
    "renting_server": 6,
    "type": "spot",
    "spotprice": 0.000001,
    "ports": {
        "22": "tcp",
        "8888": "http"
    },
    "env": {
        "VARIABLE_NAME": "VARIABLE_VALUE"
    },
    "jupyter_token": "hoZluOjbCOQ5D5yH7R",
    "ssh_password": "Hpcj08ZaOpCbTmn1Eu",
    "command": "#!/bin/sh\napt update -y && apt install htop"
}' 'https://api.clore.ai/v1/create_order'

Выход 1 (Создание предложения на SPOT-рынке):

{
  "code": 0
}

Ввод 2 (Создание заказа по требованию):

curl -XPOST -H 'auth: 6FcuR7ibcwKR1Z32lEFoSotzUUtzKO2H' -H "Content-type: application/json" -d '
{
    "currency": "bitcoin",
    "image": "cloreai/ubuntu20.04-jupyter",
    "renting_server": 6,
    "type": "on-demand",
    "ports": {
        "22": "tcp",
        "8888": "http"
    },
    "env": {
        "VARIABLE_NAME": "VARIABLE_VALUE"
    },
    "jupyter_token": "hoZluOjbCOQ5D5yH7R",
    "ssh_password": "Hpcj08ZaOpCbTmn1Eu",
    "command": "#!/bin/sh\napt update -y && apt install htop"
}' 'https://api.clore.ai/v1/create_order'

Выход 2 (Создание заказа по требованию):

{
  "code": 0
}