Developer Center

Resources to get you started with Algorithmia

Management APIs

Updated

Using the Algorithm Management APIs, you can create, publish, update, and inspect individual algorithms. Among other things, this allows you to train and deploy your models on Algorithmia completely within your preferred development environment – without ever interacting with Algorithmia’s web-based UI.

For the full specification, see the Python API for Algorithm Management. For languages other than Python, an OpenAPI Specification is available via the unofficial openapi docs or a raw openapi spec (under /algorithms).

Note that there are two different types of API Keys, used with different endpoints. All Algorithm Management APIs use Simple API Keys, which can be created under the credentials tab of your user profile. Ensure that the Key you are using has the option “Allow this key to manage my algorithms” selected:

Api Keys, Manage My Algorithms

Forward: Python Notebook or CI/CD (via Jenkins or GitHub Actions) for Publishing Algorithms

The step-by-step guide below will familiarize you with the Python and OpenAPI spec for creating Algorithms. However, a complete end-to-end Jupyter Notebook (and Google Colab Notebook) is also available. To see a working end-to-end example of training a Model, then immediately deploying it as an Algorithm within the same Notebook, see the GitHub repo with working Model Deployment Notebooks

In addition, customers using Jenkins or GitHub Actions for their CI/CD should review our CI/CD Examples for Deploying Algorithms.

For those using another CI/CD tool, or who simply wish to deploy from a simple pure-Python script, the Python scripts used in the GitHub Actions workflow can be used in any Python-capable environment; they are not specific to GitHub Actions. Read through the documentation to understand their use, then copy and modify the model_*.py files from that repo and modify them to point to your own Algorithm.

1. Create your Algorithm

First, set up an Algorithmia client using an API Key from your account, which must have “Allow this key to manage my algorithm” enabled.

Then, create your Algorithm by creating a client.algo('username/algoname) with the name you wish it to have: ‘username’ here might be your own username, or thge name of an Organization to which you belong, and ‘algoname’ can be any Algorithm name which doesn’t already exist in that userspace.

Next, we call the .create() method of that new Algorithm. The fields roughly correspond to those you’d see in the Add Algorithm user interface, butr are fully described in the API Docs.

import Algorithmia
client=Algorithmia.client('MANAGEMENT_API_KEY')
algo = client.algo('demo/Hello')
algo.create(
    details = {
        "label": "Hello World",
    },
    settings = {
        "language": "python3-1",
        "source_visibility": "closed",
        "license": "apl",
        "network_access": "full",
        "pipeline_enabled": True,
        "environment": "cpu"
    }
)

2. Edit and Build your Algorithm

Now that your Algorithm exists, you can edit the source code the Web IDE, or locally via Git (git clone https://git.algorithmia.com/git/USERNAME/ALGORITHMNAME.git) or the CLI (algo clone USERNAME/ALGORITHMNAME).

Before attempting to publish, you must either click “Build” in the Web IDE, or git push your code (which implicitly triggers a build).

3. Publish your Algorithm

Now you can publish your algorithm via a call to algo.publish

While an empty dict {} will work as the version_info parameter, you may also include any of the fields included in the API Spec:

algo.publish(
    version_info = {
        "sample_input": "world"
    }
)

4. Getting info about your Algorithm

Your Algorithm is now published and runnable. If you wish, you make also take advantage of several other management functions:

ALTERNATIVE: Creating and Publishing an Algorithm via the API, using the OpenAPI Specification

1. Create your Algorithm

First, create your algorithm by POSTing to https://api.algorithmia.com/v1/algorithms/USERNAME, where USERNAME is your user account, and sim****** is an API Key from that account with “Allow this key to manage my algorithm” enabled.

Note that the definition of the new Algorithm is in the payload of the request, and the fields roughly correspond to those you’d see in the Add Algorithm user interface:

import requests
url = 'https://api.algorithmia.com/v1/algorithms/USERNAME'
headers = {
  'Authorization': 'sim********',
  'Content-Type': 'application/json'
}
payload = {
    "details": {
        "label": "<string>", #user-readable name of the algorithm
        "summary": "<string>", #markdown describing the Algorithm, for the "docs" tab
        "tagline": "<string>" #one-liner summarizing the Algorithm's purpose
    },
    "name": "<string>", #the short algorithm name (no spaces or special characters)
    "settings": {
        "license": "<string>", #apl, apache2, gpl3, mit
        "network_access": "<string>", #isolated, full
        "pipeline_enabled": <boolean>, #can this algo call other algos?
        "source_visibility": "<string>", #open, closed
        "language": "<string>", #java, javascript, python2-langpack, python3-1, r, ruby, rust, scala
        "environment": "<string>", #cpu, gpu
        "royalty_microcredits": <integer> #0 for none
    },
    "version_info": {
        "sample_input": "<string>" #example input visible to end-user
    }
}
response = requests.request('POST', url, headers = headers, json = payload)
print(response.text)

2. Edit and Build your Algorithm

Now that your Algorithm exists, you can edit the source code the Web IDE, or locally via Git (git clone https://git.algorithmia.com/git/USERNAME/ALGORITHMNAME.git) or the CLI (algo clone USERNAME/ALGORITHMNAME).

Before attempting to publish, you must either click “Build” in the Web IDE, or git push your code (which implicitly triggers a build).

3. Publish your Algorithm

Now you can publish your algorithm via a POST to https://api.algorithmia.com/v1/algorithms/USERNAME/ALGORITHMNAME/versions

While an empty payload dict {} will work, you may consider including the payload fields shown below:

import requests
url = 'https://api.algorithmia.com/v1/algorithms/USERNAME/ALGORITHMNAME/versions'
headers = {
  'Authorization': 'sim********',
  'Content-Type': 'application/json'
}
payload = {
    "settings": {
        "algorithm_callability": "<string>" #public, private
    }
    "version_info": {
        "type": "<string>", #default, major, minor, revision
        "semantic_version": "<string>", #if blank, a minor version increment will be used
        "git_hash": "<string>", #if blank, the latest git hash will be used
        "release_notes": "<string>",
        "sample_input": "<string>",
        "sample_output": "<string>"
    }
}
response = requests.request('POST', url, headers = headers, json = payload)
print(response.text)

You can also include any “details” or “settings” fields as shown in the “Create your Algorithm” step.