Full API Reference

Backend API

Available Endpoints

Resource

Operation

Description

GET /api/v1/tags/(int:id)/

PUT /api/v1/tags/(int:id)/

DELETE /api/v1/tags/(int:id)/

Authentication

POST /api/v1/auth/login/

Log user in.

GET /api/v1/auth/token/

Refresh a token.

Models

GET /api/v1/models/

Get a collection of models.

POST /api/v1/models/

Upload a new model.

GET /api/v1/models/(int:id)/

Get a single model.

PUT /api/v1/models/(int:id)/

Update a single model. (Not implemented)

DELETE /api/v1/models/(int:id)/

Delete a single model.

Projects

GET /api/v1/projects/

Get a collection of projects.

POST /api/v1/projects/

Create a new project.

GET /api/v1/projects/(int:id)/

Get a single project.

PUT /api/v1/projects/(int:id)/

Update a single project. (Not implemented)

DELETE /api/v1/projects/(int:id)/

Delete a single project.

Users

GET /api/v1/users/

Get a collection of users.

POST /api/v1/users/

Create a new user.

GET /api/v1/users/(int:id)/

Get a single user.

PUT /api/v1/users/(int:id)/

Update a single user. (Not implemented)

DELETE /api/v1/users/(int:id)/

Delete a single user.

Workspaces

GET /api/v1/workspaces/

Get a collection of workspaces.

POST /api/v1/workspaces/

Create a new workspace.

GET /api/v1/workspaces/(int:id)/

Get a single workspace.

PUT /api/v1/workspaces/(int:id)/

Update a single workspace. (Not implemented)

DELETE /api/v1/workspaces/(int:id)/

Delete a single workspace.

API Details

POST /api/v1/auth/login/

Logs the user in by parsing a POST request containing user credentials and issuing a JWT token.

$ curl http://localhost:5000/api/v1/auth/login/ -X POST \
  -d '{"login":"zofiakochutek", "password":"clechay"}'
GET /api/v1/auth/token/

Refreshes an existing JWT by creating a new one that is a copy of the old except that it has a refreshed access expiration.

$ curl http://localhost:5000/api/v1/auth/token/ -X GET \
  -H "Authorization: Bearer <your_token>"
GET /api/v1/models/

Lists all models that satisfy certain conditions.

Every parameter can be appended multiple times.

Parameters
  • workspace – search for models only in this workspace

  • project – search for models only in this project

  • hyperparam – search for models that have this hyperparameter

  • param – search for models that have this parameter

Returns

a list of objects

POST /api/v1/models/

Uploads a model.

Parameters
  • name – human-readable name of the model

  • dataset_name – name used to identify the dataset

  • dataset_description – description used to provide more context

  • project_id – id of the project the model belongs to

  • hyperparameters – a dictionary of hyperparameters

  • parameters – a dictionary of parameters

  • metrics – a dictionary of metrics

  • tags – a list of tags in form of a single string separated by commas

  • git_active_branch – an active branch of the uploaded model

  • git_commit_hash – hash of the most recent commit

  • file – contents of the file selected to upload

  • private – whether to mark the model as private

Returns

a newly uploaded model

GET /api/v1/models/(int: id)/

Returns data about a requested model.

Parameters
  • id – id of a requested model

Returns

a single object

PUT /api/v1/models/(int: id)/

Modifies a selected model.

Parameters
  • id – id of the model to update

  • payload – the data to override the model with

Returns

the updated model

DELETE /api/v1/models/(int: id)/

Removes a selected model.

Parameters
  • id – id of a requested model

Returns

whether the operation has been successful

GET /api/v1/projects/

Lists all projects.

Parameters
  • search – lists only projects that contain the name like search

Return

a list of projects

POST /api/v1/projects/

Creates a new project.

Parameters
  • name – a name/title for the project

  • description – a description of the project and it’s purpose

  • workspace_id – id of the workspace that contains this project

Returns

a newly created project

GET /api/v1/projects/(int: id)/

Returns data about a requested project.

Parameters
  • id – id of a requested project

Request Headers
Status Codes
Returns

a single object

PUT /api/v1/projects/(int: id)/

Modifies a selected project.

Parameters
  • id – id of the project to update

  • payload – the data to override the project with

Returns

the updated project

DELETE /api/v1/projects/(int: id)/

Removes a selected project.

Parameters
  • id – id of a requested project

Request Headers
Status Codes
  • 200 OK – when project exists and was deleted

  • 404 Not Found – when requested project does not exist

Returns

whether the operation has been successful

GET /api/v1/tags/(int: id)/

Returns data about a requested tag.

Parameters
  • id – id of a requested tag

Returns

a single object

PUT /api/v1/tags/(int: id)/

Modifies a selected tag.

Parameters
  • id – id of the tag to update

  • payload – the data to override the tag’s with

Returns

the updated tag object

DELETE /api/v1/tags/(int: id)/

Removes a selected tag.

Parameters
  • id – id of a requested tag

Returns

whether the operation has been successful

GET /api/v1/users/

Lists all users.

Return

a list of users

POST /api/v1/users/

Creates a new user.

Parameters
  • login – login for the new user

  • password – password for the new user

  • full_name – full name for the new user (optional)

  • email – an email address for the new user (optional)

Returns

a newly created user

GET /api/v1/users/(int: id)/

Returns data about a requested user.

Parameters
  • id – id of a requested user

Returns

a single object

PUT /api/v1/users/(int: id)/

Modifies a selected user.

Parameters
  • id – id of the user to update

  • payload – the data to override the user with

Returns

the updated user

DELETE /api/v1/users/(int: id)/

Removes a selected user.

Parameters
  • id – id of a requested user

Returns

whether the operation has been successful

GET /api/v1/workspaces/

Lists all workspaces.

Parameters
  • search – lists only workspaces that contain the name like search

Return

a list of workspaces

POST /api/v1/workspaces/

Creates a new workspaces.

Parameters
  • name – a name/title for the workspace

  • description – a description of the workspace and it’s purpose

Returns

a newly created workspace

GET /api/v1/workspaces/(int: id)/

Returns data about a requested workspace.

Parameters
  • id – id of a requested workspace

Returns

a single object

PUT /api/v1/workspaces/(int: id)/

Modifies a selected workspace.

Parameters
  • id – id of the workspace to update

  • payload – the data to override the workspace with

Returns

the updated project

DELETE /api/v1/workspaces/(int: id)/

Removes a selected workspace.

Parameters
  • id – id of a requested workspace

Returns

whether the operation has been successful

Client API

Main Package Modules

class maisie.resources.models.Models(config=None)

Represents an action for managing models.

download(id)

Downloads requested model.

Parameters

id (int) – id of the model to download

get(id)

Fetches a single model.

Parameters

id (int) – id of the model to get

Return type

list

Returns

requested model

get_all(query=None, page=None, per_page=None)

Fetches all models that satisfy some condition.

Parameters
  • query – query string

  • page – number of the page used in pagination

  • per_page – number of the items to be fetched

Returns

a list of returned models

update(id, data)

Update selected model.

Parameters
  • id (int) – id of the model to put

  • data (dict) – dictionary

upload(name, filename, hyperparameters, parameters, metrics, private=False, dataset_name='', dataset_description='')

Posts a single model.

Parameters
  • name (str) – name of model to upload

  • filename (str) – path to file with a model

  • hyperparameters (Union[str, dict]) – dictionary or path to file with hyperparameters

  • metrics (Union[str, dict]) – dictionary or path to file with metrics

  • private (bool) –

  • dataset_name (str) –

  • dataset_description (str) –

Returns

posted model

class maisie.resources.projects.Projects(config=None)
create(name, description, git_url)

Creates and posts a new project

Parameters
  • name (str) – name of a project to create

  • desription – description of a project to create

  • git_url (str) – path to git repository with the project

Returns

created project

delete(id)

Deletes selected project. :type id: int :param id: id of the project to delete

Returns

deleted project

get(id)

Fetches a single project

Parameters

id (int) – id of the project to get

Returns

requested project

get_all(query=None, page=None, per_page=None)

Fetches all projects that satisfy some condition.

Parameters
  • query – query string

  • page – number of the page used in pagination

  • per_page – number of the items to be fetched

Returns

a list of returned projects

selected
update(id, data)

Updates selected project. :type id: int :param id: id of project to update :type data: dict :param data: dictionary

Returns

updated project

class maisie.resources.users.Users(config=None)
create(login, name, email, password)

Creates and posts a new user

Parameters
  • login – login of a user to create

  • name – name of a user to create

  • email – email of user to create

  • password – password of user to create

Returns

created user

detele(id)

Deletes selected user. :type id: int :param id: id of the user to delete

Returns

deleted user

get(id)

Fetches a single user

Parameters

id (int) – id of the user to get

Returns

requested user

get_all(query=None, page=None, per_page=None)

Fetches all users that satisfy some condition.

Parameters
  • query – query string

  • page – number of the page used in pagination

  • per_page – number of the items to be fetched

Returns

a list of returned users

update(id, data)

Updates selected user. :type id: int :param id: id of user to update :type data: dict :param data: dictionary

Returns

updated user

class maisie.resources.workspaces.Workspaces(config=None)
create(name, description)
delete(id)
get(id)
get_all(page=None, per_page=None)
selected
update(id, data)

Additional Package Modules

class maisie.core.BaseAction(config=None)

Base class for actions exposed both in package and for CLI.

_BaseAction__check_config(config)
class maisie.core.Config(filename=None, dictionary=None)

Manages and pre-loads configuration from all available sources.

_fetch_from_dict(dictionary)

Populates the Config() object with attributes loaded from a given dictionary.

Parameters

dictionary (dict) – a structured key-value paired configuration object. Keys not present in PERMITTED_SETTINGS will be omitted.

Return type

None

_fetch_from_env_variables()

Populates the Config() object with attributes loaded from the system’s envioronment variables.

Return type

None

_fetch_from_file(filename)

Populates the Config() object with attributes loaded from a given file.

Parameters

filename (str) – path to the configuration file. Use of an absolute instead of a relative path is recommended.

Return type

None

_fetch_scan_directory()

Traverses the local directory tree in search of compatible configuration files.

Return type

None

static _setsource(key, value)
auth

Authenticates and returns an instance of AuthManager.

Return type

AuthManager

fetch(filename=None, dictionary=None, disable_env=False)

Populates the Config() object with attributes from multiple sources.

When both filename and dicionary are provided, the configuration file is processed first and then the keys from the dictionary will be evaluated.

Parameters
  • filename (Optional[str]) – path to the configuration file. Use of an absolute instead of a relative path is recommended.

  • dictionary (Optional[dict]) – a structured key-value paired configuration object. Keys not present in PERMITTED_SETTINGS will be omitted.

  • disable_env (bool) – whether to disable fetching configuration from environment variables.

Return type

None

static getsource(key)
headers

Returns HTTP Headers present in all requests sent to the specified target url.

class maisie.utils.auth.AuthManager(api_url, login, password=None, app_token=None, ssh_key=None, enforce_ssh=False)
_auth_via_app_token()
_auth_via_password()
_auth_via_ssh_key()
logged_in
Return type

bool

perform_auth(channels=['ssh_key', 'app_token', 'password'])
refresh_token(old_token)

Refreshes the token using the old one.

Parameters

old_token (str) –

Return type

str

Returns

a refreshed JWT.

retrieve_token()

Retrieves the token via available authentication methods.

Return type

None

token
Return type

str

token_active
Return type

bool

user_id
Return type

int

class maisie.utils.git.GitProvider(path=None)

Provides an interface for interacting with git repositories.

active_branch

Returns the name of the active branch.

Return type

str

is_dirty

Checks whether there are uncommited changes in the repository.

Return type

bool

latest_commit

Returns the hash of a latest commit in the active branch.

Return type

str

remotes(include_name=True, include_url=True)

Retrieves a list of remotes defined in the repository.

Parameters
  • include_name – whether to include the names of remotes

  • include_url – whether to include the urls of remotes

Return type

list

Returns

a list of remotes in a requested schema

repository

Returns the GitPython object of a selected repository.

Return type

object