HTTP REST API

Overview

  • The base endpoint is: https://api.octa.space/v1
  • For requests HTTP header Content-Type must be to ‘application/json’
  • All endpoints return either a JSON object or array
  • Disk and memory sizes are in bytes
  • Price fields are in cents, ex: 100 = Ø1

Endpoints

Path Description
/health Check if system operate normal
/network Common network information
/containers List of predefined containers used in MR service
/services List, use and other functions related to services build on project

Authentication

Each request to the API must contain the authentication token. This token is possible to specify using HTTP header Authorization or as query string parameter token

Examples

  • Passing authentication token using HTTP header
curl -H "Authorization: 60f95" https://api.octa.space/v1/services
[
  {
    "description": "CPU/GPU rental",
    "name": "mr"
  },
  {
    "description": "VPN",
    "name": "vpn"
  }
]
  • Passing authentication token as query string parameter
curl -H "https://api.octa.space/v1/services?token=60f95"
[
  {
    "description": "CPU/GPU rental",
    "name": "mr"
  },
  {
    "description": "VPN",
    "name": "vpn"
  }
]

List of service nodes

  • Method: GET
  • Endpoint: /services/:type, where type is vpn or mr

List VPN services

curl -H "Authorization: 60f95" https://api.octa.space/v1/services/vpn
[
  {
    "city": "Dnipropetrovsk",
    "country": "Ukraine",
    "country_iso": "UA",
    "node_id": 8,
    "traffic_price": 2000
  },
  {
    "city": "Amsterdam",
    "country": "Netherlands",
    "country_iso": "NL",
    "node_id": 5,
    "traffic_price": 100000
  }
]

You can pass country query string parameter to filter by country:

curl -H "Authorization: 60f95" "https://api.octa.space/v1/services/vpn?country=ukraine"
[
  {
    "city": "Dnipropetrovsk",
    "country": "Ukraine",
    "country_iso": "UA",
    "node_id": 8,
    "traffic_price": 2000
  }
]

List MR services

curl -H "Authorization: 60f95" https://api.octa.space/v1/services/mr
[
  {
    "base_price": 10000,
    "city": "Dnipropetrovsk",
    "country": "Ukraine",
    "country_iso": "UA",
    "cpu_cores": 8,
    "cpu_model_name": "Intel(R) Core(TM) i7-4770K CPU @ 3.50GHz",
    "free_disk": 75957895020,
    "gpu": {
      "amd": [],
      "nvidia": [
        {
          "cuda_cores": 3648,
          "gpu_clock_mhz": 1683,
          "mem_bandwidth_gbs": 256.256,
          "mem_clock_mhz": 4004,
          "mem_free_mb": 8016,
          "mem_total_mb": 8117,
          "model": "NVIDIA GeForce GTX 1070 Ti"
        }
      ]
    },
    "node_id": 34,
    "storage_price": 0,
    "total_memory": 16724127744,
    "total_price": 20000,
    "traffic_price": 10000
  }
]

Acquire service

  • Method: POST
  • Endpoint: /services

To acquire service you need to make POST request to /services endpoint and pass the JSON with details of your request:

For VPN service:

{
    "node_id": 30,
    "kind": "vpn"
}
Field Type Mandatory Description
node_id Integer Yes Node identifier
kind Yes String Type of service, for VPN service it’s must be ‘vpn’

For MR service:

{
    "node_id": 30,
    "kind": "mr",
    "disk_size": 1,
    "image": "ubuntu18"
}
Field Type Mandatory Description
node_id Integer Yes Node identifier
kind String Yes Type of service, for MR service it’s must be ‘mr’
disk_size Integer Yes Amount of disk space to allocated in GB
image String Yes The image name what can be taken from /containers API
curl -H "Content-Type: application/json" -H "Authorization: 60f950" -d@acquire-vpn.json https://api.octa.space/v1/services
{
  "uuid": "9bd8b6e6-c96d-11ec-a76b-da0a8f9f020e"
}

This UUID is identifier of acquired service on the specific node, it may be used to retrieve information about service or stop it.

Get service info

  • Method: GET
  • Endpoint: /service/:uuid/info
curl -s -H "Authorization: 60f950" https://api.octa.space/v1/services/9bd8b6e6-c96d-11ec-a76b-da0a8f9f020e/info

In case of VPN service this request will return the config which may be used by wireguard client:

{
  "config": "[Interface]\nAddress = 10.13.13.2\nPrivateKey = 0JECu02OebiNYFuOzou91KEMdMKT0Ff5BqHZeWZn12Y=\nListenPort = 51820\nDNS = 10.13.13.1\n\n[Peer]\nPublicKey = vhlnQjFg8g2KR8TFevCPbnYlyJbWC7yykpEEqVtPkWU=\nEndpoint = 178.62.175.149:51803\nAllowedIPs = 0.0.0.0/0, ::/0\n",
  "is_ready": true,
  "qr": "iVBORw0KGgoAAAANSUhEUgAAAMMAAADDAQMAAAAFsTfpAAAABlBMVEUAAAD"
}

For MR it will return the hostname and port to connect using SSH:

{
  "host": "ssh.octa.space",
  "is_ready": true,
  "port": 26146
}

For both services the field is_ready is show is service ready to use or configuration in process.

Stop service

  • Method: GET
  • Endpoint: /service/:uuid/stop
curl -s -H "Authorization: 60f950" https://api.octa.space/v1/services/9bd8b6e6-c96d-11ec-a76b-da0a8f9f020e/stop