API Documentation¶

Note

The below information reflects the latest API shipped in the most recent version of Evon Hub. Your Hub itself includes Redoc rendered API documentation specific to its own version, and is available by clicking the API Developer Docs link in the top horizontal nav menu of your Hub’s Web UI.

Authentication¶

The API’s base url is simply that of your Hub, eg:

GET https://myhub.example.com/api/bootstrap/linux

To authorize to the Hub API, include your auth token in the request header as:

Authorization: Token <YOUR_AUTH_TOKEN>

Your auth token can be retrieved by navigating to Tokens in the left nav menu in the Web UI.

API Paths and Methods¶

bootstrap¶

POST /api/bootstrap/decrypt¶

Decrypt the encrypted payload located within the bootstrap installer scripts and return its cleartext. This function is used internally by the bootstrap scripts. Requesting user must be a superuser or the “deployer” user.

Status Codes:

200 OK –

GET /api/bootstrap/linux¶

Download the bootstrap.sh installer for connecting remote Linux systems to this overlay network. Requesting user must be a superuser or the “deployer” user.

Example request:

GET /api/bootstrap/linux HTTP/1.1
Host: example.com

Status Codes:

200 OK –

GET /api/bootstrap/windows¶

Download the bootstrap.ps1 installer for connecting remote Windows systems to this overlay network. Requesting user must be a superuser or the “deployer” user.

Example request:

GET /api/bootstrap/windows HTTP/1.1
Host: example.com

Status Codes:

200 OK –

config¶

GET /api/config¶

List Config

Query Parameters:

page (integer) – A page number within the paginated result set.

Example request:

GET /api/config HTTP/1.1
Host: example.com

Status Codes:

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "count": 1,
    "next": "https://example.com",
    "previous": "https://example.com",
    "results": [
        {
            "id": 1,
            "ec2_iam_role_status": true,
            "timezone": "Africa/Abidjan",
            "auto_update": true,
            "auto_update_time": "string",
            "discovery_mode": true,
            "uuid_blacklist": "string",
            "uuid_whitelist": "string"
        }
    ]
}

PATCH /api/config/{id}¶

Update Config

Parameters:

id (integer)

Example request:

PATCH /api/config/{id} HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "timezone": "Africa/Abidjan",
    "auto_update": true,
    "auto_update_time": "string",
    "discovery_mode": true,
    "uuid_blacklist": "string",
    "uuid_whitelist": "string"
}

Status Codes:

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "ec2_iam_role_status": true,
    "timezone": "Africa/Abidjan",
    "auto_update": true,
    "auto_update_time": "string",
    "discovery_mode": true,
    "uuid_blacklist": "string",
    "uuid_whitelist": "string"
}

group¶

GET /api/group¶

List or create Groups

Query Parameters:

page (integer) – A page number within the paginated result set.

Example request:

GET /api/group HTTP/1.1
Host: example.com

Status Codes:

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "count": 1,
    "next": "https://example.com",
    "previous": "https://example.com",
    "results": [
        {
            "name": "string",
            "user_set": [
                1
            ],
            "permissions": [
                1
            ]
        }
    ]
}

POST /api/group¶

List or create Groups

Example request:

POST /api/group HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "name": "string",
    "user_set": [
        1
    ],
    "permissions": [
        1
    ]
}

Status Codes:

201 Created –

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
    "name": "string",
    "user_set": [
        1
    ],
    "permissions": [
        1
    ]
}

GET /api/group/{id}¶

Retrieve, update or delete a Group

Parameters:

id (integer)

Example request:

GET /api/group/{id} HTTP/1.1
Host: example.com

Status Codes:

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "name": "string",
    "user_set": [
        1
    ],
    "permissions": [
        1
    ]
}

PATCH /api/group/{id}¶

Retrieve, update or delete a Group

Parameters:

id (integer)

Example request:

PATCH /api/group/{id} HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "name": "string",
    "user_set": [
        1
    ],
    "permissions": [
        1
    ]
}

Status Codes:

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "name": "string",
    "user_set": [
        1
    ],
    "permissions": [
        1
    ]
}

DELETE /api/group/{id}¶

Retrieve, update or delete a Group

Parameters:

id (integer)

Status Codes:

204 No Content – No response body

ovpnclient¶

GET /api/ovpnclient/download¶

Download the EvonHub.ovpn OpenVPN configuration file for user access to this overlay network.

Example request:

GET /api/ovpnclient/download HTTP/1.1
Host: example.com

Status Codes:

200 OK –

permission¶

GET /api/permission¶

List all available permissions that can be applied to Users and Groups

Query Parameters:

page (integer) – A page number within the paginated result set.

Example request:

GET /api/permission HTTP/1.1
Host: example.com

Status Codes:

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "count": 1,
    "next": "https://example.com",
    "previous": "https://example.com",
    "results": [
        {
            "id": 1,
            "name": "string"
        }
    ]
}

ping¶

GET /api/ping¶

Ping endpoint for availability/connectivity testing of Evon Hub API

Example request:

GET /api/ping HTTP/1.1
Host: example.com

Status Codes:

ExampleResponse - example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "message": "pong"
}

policy¶

GET /api/policy¶

List or create Policies

Query Parameters:

page (integer) – A page number within the paginated result set.

Example request:

GET /api/policy HTTP/1.1
Host: example.com

Status Codes:

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "count": 1,
    "next": "https://example.com",
    "previous": "https://example.com",
    "results": [
        {
            "id": 1,
            "name": "string",
            "description": "string",
            "rules": [
                1
            ],
            "servers": [
                1
            ],
            "servergroups": [
                1
            ]
        }
    ]
}

POST /api/policy¶

List or create Policies

Example request:

POST /api/policy HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "name": "string",
    "description": "string",
    "rules": [
        1
    ],
    "servers": [
        1
    ],
    "servergroups": [
        1
    ]
}

Status Codes:

201 Created –

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
    "id": 1,
    "name": "string",
    "description": "string",
    "rules": [
        1
    ],
    "servers": [
        1
    ],
    "servergroups": [
        1
    ]
}

GET /api/policy/{id}¶

Retrieve, update or delete a Policy

Parameters:

id (integer)

Example request:

GET /api/policy/{id} HTTP/1.1
Host: example.com

Status Codes:

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "name": "string",
    "description": "string",
    "rules": [
        1
    ],
    "servers": [
        1
    ],
    "servergroups": [
        1
    ]
}

PATCH /api/policy/{id}¶

Retrieve, update or delete a Policy

Parameters:

id (integer)

Example request:

PATCH /api/policy/{id} HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "name": "string",
    "description": "string",
    "rules": [
        1
    ],
    "servers": [
        1
    ],
    "servergroups": [
        1
    ]
}

Status Codes:

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "name": "string",
    "description": "string",
    "rules": [
        1
    ],
    "servers": [
        1
    ],
    "servergroups": [
        1
    ]
}

DELETE /api/policy/{id}¶

Retrieve, update or delete a Policy

Parameters:

id (integer)

Status Codes:

204 No Content – No response body

rule¶

GET /api/rule¶

List or create Rules

Query Parameters:

page (integer) – A page number within the paginated result set.

Example request:

GET /api/rule HTTP/1.1
Host: example.com

Status Codes:

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "count": 1,
    "next": "https://example.com",
    "previous": "https://example.com",
    "results": [
        {
            "id": 1,
            "name": "string",
            "destination_protocol": "TCP",
            "destination_ports": "string",
            "source_users": [
                1
            ],
            "source_groups": [
                1
            ],
            "source_servers": [
                1
            ],
            "source_servergroups": [
                1
            ]
        }
    ]
}

POST /api/rule¶

List or create Rules

Example request:

POST /api/rule HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "name": "string",
    "destination_protocol": "TCP",
    "destination_ports": "string",
    "source_users": [
        1
    ],
    "source_groups": [
        1
    ],
    "source_servers": [
        1
    ],
    "source_servergroups": [
        1
    ]
}

Status Codes:

201 Created –

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
    "id": 1,
    "name": "string",
    "destination_protocol": "TCP",
    "destination_ports": "string",
    "source_users": [
        1
    ],
    "source_groups": [
        1
    ],
    "source_servers": [
        1
    ],
    "source_servergroups": [
        1
    ]
}

GET /api/rule/{id}¶

Retrieve, update or delete a Rule

Parameters:

id (integer)

Example request:

GET /api/rule/{id} HTTP/1.1
Host: example.com

Status Codes:

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "name": "string",
    "destination_protocol": "TCP",
    "destination_ports": "string",
    "source_users": [
        1
    ],
    "source_groups": [
        1
    ],
    "source_servers": [
        1
    ],
    "source_servergroups": [
        1
    ]
}

PATCH /api/rule/{id}¶

Retrieve, update or delete a Rule

Parameters:

id (integer)

Example request:

PATCH /api/rule/{id} HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "name": "string",
    "destination_protocol": "TCP",
    "destination_ports": "string",
    "source_users": [
        1
    ],
    "source_groups": [
        1
    ],
    "source_servers": [
        1
    ],
    "source_servergroups": [
        1
    ]
}

Status Codes:

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "name": "string",
    "destination_protocol": "TCP",
    "destination_ports": "string",
    "source_users": [
        1
    ],
    "source_groups": [
        1
    ],
    "source_servers": [
        1
    ],
    "source_servergroups": [
        1
    ]
}

DELETE /api/rule/{id}¶

Retrieve, update or delete a Rule

Parameters:

id (integer)

Status Codes:

204 No Content – No response body

server¶

GET /api/server¶

List Servers

Query Parameters:

page (integer) – A page number within the paginated result set.

Example request:

GET /api/server HTTP/1.1
Host: example.com

Status Codes:

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "count": 1,
    "next": "https://example.com",
    "previous": "https://example.com",
    "results": [
        {
            "id": 1,
            "accessible": true,
            "fqdn": "string",
            "ipv4_address": "string",
            "uuid": "string",
            "connected": true,
            "disconnected_since": "2025-08-22T11:20:38.970389",
            "last_seen": "string",
            "server_groups": [
                1
            ]
        }
    ]
}

GET /api/server/{id}¶

Retrieve, update or delete a Server

Parameters:

id (integer)

Example request:

GET /api/server/{id} HTTP/1.1
Host: example.com

Status Codes:

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "accessible": true,
    "fqdn": "string",
    "ipv4_address": "string",
    "uuid": "string",
    "connected": true,
    "disconnected_since": "2025-08-22T11:20:38.970389",
    "last_seen": "string",
    "server_groups": [
        1
    ]
}

PATCH /api/server/{id}¶

Retrieve, update or delete a Server

Parameters:

id (integer)

Example request:

PATCH /api/server/{id} HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "server_groups": [
        1
    ]
}

Status Codes:

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "accessible": true,
    "fqdn": "string",
    "ipv4_address": "string",
    "uuid": "string",
    "connected": true,
    "disconnected_since": "2025-08-22T11:20:38.970389",
    "last_seen": "string",
    "server_groups": [
        1
    ]
}

DELETE /api/server/{id}¶

Retrieve, update or delete a Server

Parameters:

id (integer)

Status Codes:

204 No Content – No response body

servergroup¶

GET /api/servergroup¶

List or create Server Group

Query Parameters:

page (integer) – A page number within the paginated result set.

Example request:

GET /api/servergroup HTTP/1.1
Host: example.com

Status Codes:

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "count": 1,
    "next": "https://example.com",
    "previous": "https://example.com",
    "results": [
        {
            "id": 1,
            "server_set": [
                1
            ],
            "name": "string",
            "description": "string"
        }
    ]
}

POST /api/servergroup¶

List or create Server Group

Example request:

POST /api/servergroup HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "server_set": [
        1
    ],
    "name": "string",
    "description": "string"
}

Status Codes:

201 Created –

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
    "id": 1,
    "server_set": [
        1
    ],
    "name": "string",
    "description": "string"
}

GET /api/servergroup/{id}¶

Retrieve, update or delete a Server Group

Parameters:

id (integer)

Example request:

GET /api/servergroup/{id} HTTP/1.1
Host: example.com

Status Codes:

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "server_set": [
        1
    ],
    "name": "string",
    "description": "string"
}

PATCH /api/servergroup/{id}¶

Retrieve, update or delete a Server Group

Parameters:

id (integer)

Example request:

PATCH /api/servergroup/{id} HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "server_set": [
        1
    ],
    "name": "string",
    "description": "string"
}

Status Codes:

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "server_set": [
        1
    ],
    "name": "string",
    "description": "string"
}

DELETE /api/servergroup/{id}¶

Retrieve, update or delete a Server Group

Parameters:

id (integer)

Status Codes:

204 No Content – No response body

user¶

GET /api/user¶

List or create Users

Query Parameters:

page (integer) – A page number within the paginated result set.

Example request:

GET /api/user HTTP/1.1
Host: example.com

Status Codes:

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "count": 1,
    "next": "https://example.com",
    "previous": "https://example.com",
    "results": [
        {
            "id": 1,
            "userprofile_id": "string",
            "username": "string",
            "password": "string",
            "is_superuser": true,
            "first_name": "string",
            "last_name": "string",
            "email": "name@example.com",
            "is_active": true,
            "groups": [
                1
            ],
            "user_permissions": [
                1
            ]
        }
    ]
}

POST /api/user¶

List or create Users

Example request:

POST /api/user HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "username": "string",
    "password": "string",
    "is_superuser": true,
    "first_name": "string",
    "last_name": "string",
    "email": "name@example.com",
    "is_active": true,
    "groups": [
        1
    ],
    "user_permissions": [
        1
    ]
}

Status Codes:

201 Created –

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
    "id": 1,
    "userprofile_id": "string",
    "username": "string",
    "password": "string",
    "is_superuser": true,
    "first_name": "string",
    "last_name": "string",
    "email": "name@example.com",
    "is_active": true,
    "groups": [
        1
    ],
    "user_permissions": [
        1
    ]
}

GET /api/user/{id}¶

Retrieve, update or delete a User

Parameters:

id (integer)

Example request:

GET /api/user/{id} HTTP/1.1
Host: example.com

Status Codes:

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "userprofile_id": "string",
    "username": "string",
    "password": "string",
    "is_superuser": true,
    "first_name": "string",
    "last_name": "string",
    "email": "name@example.com",
    "is_active": true,
    "groups": [
        1
    ],
    "user_permissions": [
        1
    ]
}

PATCH /api/user/{id}¶

Retrieve, update or delete a User

Parameters:

id (integer)

Example request:

PATCH /api/user/{id} HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "username": "string",
    "password": "string",
    "is_superuser": true,
    "first_name": "string",
    "last_name": "string",
    "email": "name@example.com",
    "is_active": true,
    "groups": [
        1
    ],
    "user_permissions": [
        1
    ]
}

Status Codes:

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "userprofile_id": "string",
    "username": "string",
    "password": "string",
    "is_superuser": true,
    "first_name": "string",
    "last_name": "string",
    "email": "name@example.com",
    "is_active": true,
    "groups": [
        1
    ],
    "user_permissions": [
        1
    ]
}

DELETE /api/user/{id}¶

Retrieve, update or delete a User

Parameters:

id (integer)

Status Codes:

204 No Content – No response body

userprofile¶

GET /api/userprofile/{user}¶

Retrieve or update a UserProfile

Parameters:

user (integer) – A unique value identifying this user profile.

Example request:

GET /api/userprofile/{user} HTTP/1.1
Host: example.com

Status Codes:

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "shared": true,
    "ipv4_address": "string"
}

PATCH /api/userprofile/{user}¶

Retrieve or update a UserProfile

Parameters:

user (integer) – A unique value identifying this user profile.

Example request:

PATCH /api/userprofile/{user} HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "shared": true
}

Status Codes:

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "shared": true,
    "ipv4_address": "string"
}