REST API

Endpoints

Base URL

All endpoints are SSL encrypted. Endpoints should be directed to a base URL of:

  • https://nervana.auth0.com (token related requests)
  • https://helium.cloud.nervanasys.com (all other endpoints)

Each request should then be suffixed with the appropriate API version then the appropriate resource URL. Piecing this together, a complete example endpoint could look like: https://helium.cloud.nervanasys.com/api/v1/models/

Authentication

All endpoint requests require an authenticated access token, specified in the header of each request. We utilize bearer schema based JSON web tokens (JWT), passed in via the Authorization header parameter. The content of the header should look like:

Authorization: Bearer <token>

The one exception to this is the actual token request endpoint which you would initially send a POST request to to get a returned token.

Tokens last up to 24 hours, and can be revoked at any time via a DELETE request.

Any request that provides an invalid token value will result in a 401 response code and a “Not authorized” response message.

Note that the prior approach of passing a 40 character token string in the X-Auth-Token header field has now been deprecated, and should no longer be used.

Request Parameters

For endpoints that take required or optional parameters, they must be sent in as form-data as defined in RFC 2388.

Python Client

The ncloud command line tool comes with a python client library for interfacing with the REST API. The python client reads the same ncloud config files as the command line tool for loading settings like your username and password. Documentation for the Python client is not currently available except as docstrings in the source code. Here is an example which prints the results of a model list call:

from ncloud import config
from ncloud.commands import model

c = config.Config()

print model.List.call(c)

The result of which is the following:

OrderedDict([(u'models',
              [OrderedDict([(u'id', 45),
                            (u'name', u'example_model_name'),
                            (u'status', u'Completed'),
                            (u'user_email', u'email@example.com')])])])