Introduction

Welcome to the Verge AI API Documentation. You can use our API to manage projects, experiments, jobs, devices, user permissions, and API keys.

Documentation is provided for all language bindings that we offer. You can view code examples in the dark area to the right, and you can switch the language to use in the examples with the tabs in the top right.

Getting Started

import vergeai
vergeai.api_key = "...Your API Key Here..."

# You can now make API requests here!

Client setup requires an API key and an installation of your preferred language binding.

Response Object Data

Depending on the language binding, data will be returned using different formats. Each format is demonstrated here.

# make a call to the API
response = vergeai.Object.method(...parameters...)

# HTTP status code
response.status_code

# JSON data
response.data

When displaying response information throughout this documentation, the raw JSON response will be displayed.

• In the Python language bindings, the "body" element in the response JSON is mapped to the data attribute of the response object. The status code in the response JSON is mapped to the status code attribute in the response object.

FAQ

1. Sometimes the API returns stale information.

Due to the distributed nature of the computation, data can sometimes take a few seconds to propagate through our system. As a result, queries can occasionally return stale data. Such errors will resolve within a few seconds in most cases. If you notice persistent issues, please reach out to support.

Authentication

Create API Key

import vergeai
vergeai.api_key = "...API Key Here..."

response = vergeai.APIKey.create()

Returns:

{
    "statusCode": 200,
    "body": {
        "key": "...key plaintext value here..."
    }
}

POST /v1/auth/create

This endpoint creates a new API key. The new API key will provide programmatic access to all resources the user (specified by the auth token included in the request) is authorized for.

Projects

A Project contains all resources associated with one Federated Learning deployment, including Experiments, Jobs, and Devices. Additionally, users can be configured on a per-project level.

Create

import vergeai
vergeai.api_key = "...API Key Here..."

response = vergeai.Project.create(project_name="My Friendly Project Name")

Returns:

{
    "statusCode": 200,
    "body": {
        'project_id': '92cae23fa2754c5982866471c9b43fb7'
    }
}

POST /v1/project/create

Create a new Project.

Request Body

Parameter	Description
project_name	Friendly name of the project

Delete

import vergeai
vergeai.api_key = "...API Key Here..."

response = vergeai.Project.delete(project_id="...Project ID...")

Returns:

{
    "statusCode": 200,
    "body": {}
}

POST /v1/project/delete

Delete a Project.

Request Body

Parameter	Description
project_id	Project ID

Get

import vergeai
vergeai.api_key = "...API Key Here..."

response = vergeai.Project.get(project_id="...Project ID...")

Returns:

{
    "statusCode": 200,
    "body": {
        'name': 'my_name',
        'ID': 'cdace1ad391e444aa5ade2ce7f04c5e6',
        'devices': {},
        'experiments': {
            '9148548012074b068ba6d260f675ab50': {
                'is_active': False,
                'start_model': {},
                'jobs': [],
                'hyperparameters': {},
                'ID': '9148548012074b068ba6d260f675ab50',
                'current_job': 'NONE',
                'current_model': {}
            }
        },
        'members': {
            '123123': {
                'permission_level': 100
            }
        },
        'billing': {}
    }
}

GET /v1/project/get/<project_id>

Get a Project.

Request Body

Parameter	Description
project_id	Project ID

Get active jobs

import vergeai
vergeai.api_key = "...API Key Here..."

response = vergeai.Project.active_jobs(project_id="...Project ID...")

Returns:

{
    "statusCode": 200,
    "body": {
        'job_ids': ['3800a892631b4c75b41f035e304c36c4']
    }
}

GET /v1/project/active_jobs/<project_id>

Get a list of active Jobs in a Project.

Request Body

Parameter	Description
project_id	Project ID

Experiments

An experiment represents a single model + hyperparameter configuration, and is comprised of a series of Jobs, which are executed sequentially to train the provided model with the specified hyperparameters.

Create Experiment

import vergeai
vergeai.api_key = "...API Key Here..."

response = vergeai.Experiment.create(project_id="...Project ID...")

Returns:

{
    "statusCode": 204,
    "body": {
        'ID': '64fb44b25e0d48d2b74e120513687bd7',
        'jobs': [],
        'hyperparameters': {},
        'current_job': 'NONE',
        'start_model': {},
        'current_model': {},
        'is_active': False
    }
}

POST /v1/experiment/create

Create a new experiment.

Request Body

Parameter	Description
project_id	Project ID

Get Experiment

import vergeai
vergeai.api_key = "...API Key Here..."

response = vergeai.Experiment.get(project_id="...Project ID...",
                                  experiment_id="...Experiment ID...")

Returns:

{
    "statusCode": 204,
    "body": {
        'ID': 'e627ffd92d6449e9a411b6462b47b47d',
        'jobs': [],
        'hyperparameters': {
            'learning_rate': 0.01
        },
        'current_job': 'NONE',
        'start_model': {
            'entity_id': 'e627ffd92d6449e9a411b6462b47b47d',
            'name': 'ace0e5d0f50c40ec89e38f770c23eedd/e627ffd92d6449e9a411b6462b47b47d/start_model',
            'size': '403693'
        },
        'current_model': {
            'entity_id': 'e627ffd92d6449e9a411b6462b47b47d',
            'name': 'ace0e5d0f50c40ec89e38f770c23eedd/e627ffd92d6449e9a411b6462b47b47d/start_model',
            'size': '403693'
        },
        'is_active': False
    }
}

GET /v1/experiment/get/<project_id>/<experiment_id>

Get an experiment.

URL Parameters

Parameter	Description
project_id	Project ID
experiment_id	The experiment that this start model will be submitted to

Submit start model

import vergeai
vergeai.api_key = "...API Key Here..."

response = vergeai.Experiment.submit_start_model(model={...},
                                                 project_id="...Project ID...",
                                                 experiment_id="...Experiment ID...",
                                                 block=True)

Returns:

{
    "statusCode": 204,
    "body": {}
}

POST /v1/experiment/submit_start_model

Submit an experiment's start model.

Request Body

Parameter	Description
model	dictionary
project_id	Project ID
experiment_id	The experiment that this start model will be submitted to
block	True/False whether or not we should wait to prevent stale data

Jobs

Each Job represents one execution of training at the edge and aggregation.

Create Job

import vergeai
vergeai.api_key = "...API Key Here..."

response = vergeai.Job.create(project_id="...Project ID...",
                              device_selection_strategy="RANDOM",
                              experiment_id="...Experiment ID...",
                              num_devices=1,
                              num_buffer_devices=0,
                              termination_criteria=[])

Returns:

{
    "statusCode": 200,
    "body": {
        'ID': 'a9ef7a04d05a4bf9a779738f8d695696',
        'status': 'IN_PROGRESS',
        'devices': [
            'dg-vG9lw5qTBzc2cDwfUdl3CtXKfTfUT'
        ],
        'aggregate_model': {},
        'start_model': {
            'entity_id': 'd157244577c04b1a83943b425a04f63a',
            'name': 'e0e24bf5128c46308e578fa1e19783ef/d157244577c04b1a83943b425a04f63a/start_model',
            'size': '403693'
        },
        'configuration': {
            'num_devices': '1',
            'num_buffer_devices': '0',
            'device_selection_strategy': 'RANDOM',
            'termination_criteria': []
        },
        'models': {},
        'created_on': '1593979876.5036337',
        'billable_size': '0',
        'project_id': 'e0e24bf5128c46308e578fa1e19783ef',
        'experiment_id': 'd157244577c04b1a83943b425a04f63a'
    }
}

POST /v1/job/create

Create a new Job.

Request Body

Parameter	Description
project_id	Project the new Job belongs to
experiment_id	Experiment the new Job belongs to
device_selection_strategy	strategy to use when selecting devices to use in a learning round. Can be one of: "RANDOM"
num_devices	number of submitted device models required for successful round completion
num_buffer_devices	number of extra devices to select for training. Reduces likelihood of Job failure due to devices that fail
termination_criteria	list of termination criteria for the Job. Should be an empty list ([]) if the Job should wait for manual termination or successful completion.

Cancel Job

import vergeai
vergeai.api_key = "...API Key Here..."

response = vergeai.Job.cancel(project_id="...Project ID...",
                              job_id="...Job ID...")

Returns:

{
    "statusCode": 200,
    "body": {}
}

POST /v1/job/cancel

Cancel a Job.

Request Body

Parameter	Description
project_id	Project ID
job_id	Job to cancel

Get Job

import vergeai
vergeai.api_key = "...API Key Here..."

response = vergeai.Job.get(project_id="...Project ID...",
                           job_id="...Job ID...")

Returns:

{
    "statusCode": 200,
    "body": {
        'ID': 'a9ef7a04d05a4bf9a779738f8d695696',
        'status': 'IN_PROGRESS',
        'devices': [
            'dg-vG9lw5qTBzc2cDwfUdl3CtXKfTfUT'
        ],
        'aggregate_model': {},
        'start_model': {
            'entity_id': 'd157244577c04b1a83943b425a04f63a',
            'name': 'e0e24bf5128c46308e578fa1e19783ef/d157244577c04b1a83943b425a04f63a/start_model',
            'size': '403693'
        },
        'configuration': {
            'num_devices': '1',
            'num_buffer_devices': '0',
            'device_selection_strategy': 'RANDOM',
            'termination_criteria': []
        },
        'models': {},
        'created_on': '1593979876.5036337',
        'billable_size': '0',
        'project_id': 'e0e24bf5128c46308e578fa1e19783ef',
        'experiment_id': 'd157244577c04b1a83943b425a04f63a'
    }
}

GET /v1/job/get/<project_id>/<job_id>

Retrieve a Job.

URL Parameters

Parameter	Description
project_id	Project that this Job belongs to
job_id	Job to retrieve

Get aggregate model

import vergeai
vergeai.api_key = "...API Key Here..."

response = vergeai.Job.get_aggregate_model(project_id="...Project ID...",
                                           job_id="...Job ID...")

Returns:

{
    ...
}

GET /v1/job/aggregate_model/<project_id>/<job_id>

Retrieve a Job's aggregate model state dictionary.

URL Parameters

Parameter	Description
project_id	Project ID
job_id	Job ID

Get start model

import vergeai
vergeai.api_key = "...API Key Here..."

response = vergeai.Job.get_start_model(project_id="...Project ID...",
                                       job_id="...Job ID...")

Returns:

{
    ...
}

GET /v1/job/start_model/<project_id>/<job_id>

Retrieve a Job's start model state dictionary.

URL Parameters

Parameter	Description
project_id	Project ID
job_id	Job ID

Devices

Each Device represents an authenticated edge system in a Project.

Is device active?

import vergeai
vergeai.api_key = "...API Key Here..."

response = vergeai.Device.is_active(project_id="...Project ID...",
                                    job_id="...Job ID...",
                                    device_id="...Device ID...")

Returns:

{
    "statusCode": 200,
    "body": {
        "is_device_active": True
    }
}

GET /v1/device/is_active/<project_id>/<job_id>/<device_id>

Returns a boolean value whether or not the specified Device is active in a specified Job.

If this API endpoint is called using a device's API key, it will only be able to view status information about itself (and not other devices). If a user owns the API key, they will be able to view status information on all devices.

URL Parameters

Parameter	Description
project_id	project ID (the Project that the device belongs to)
job_id	job ID (the Job to check for status)
device_id	device ID

Register

import vergeai
vergeai.api_key = "...API Key Here..."

response = vergeai.Device.register(project_id="...Project ID...")

Returns:

{
    "statusCode": 200,
    "body": {
        "device_id": "...Device ID...",
        "device_api_key": "...Device API Key"
    }
}

POST /v1/device/create

Creates a new device & registers it to the specified Project.

Request Body

Parameter	Description
project_id	Project that the device will belong to

Submit Model

import vergeai
vergeai.api_key = "...API Key Here..."

response = vergeai.Device.submit_model(model={},
                                       project_id="...Project ID...",
                                       job_id="...Job ID...")

Returns:

{
    "statusCode": 200,
    "body": {
        "device_id": "...Device ID...",
        "device_api_key": "...Device API Key"
    }
}

POST /v1/device/submit_model_update

Uploads the device's model contribution for a specified Job.

Users cannot call this endpoint with their account API keys. Only Devices are allowed to make calls to this endpoint. Additionally, Devices can only submit a model to a Job that is active, and which includes the device in it.

Request Body

Parameter	Description
model	The dictionary state_dict representation of the neural network
project_id	Project that the device will belong to
job_id	Job to submit the model to

Errors

Error Code	Meaning
400	Bad Request -- Your request is invalid.
403	Forbidden -- You are not authorized to access this resource.
429	Too Many Requests -- You're being rate limited.
500	Internal Server Error -- We had a problem with our server. Try again later.

Logging

The Verge AI language bindings provide configurable logging.

Configuring the log level

import vergeai
vergeai.initialize_logger("WARNING")

Set the log level.

Request Body

Parameter	Description
log_lvl	One of: "DEBUG", "INFO", "WARNING", "ERROR"