Introduction

Welcome to Algorithmia's API documentation. Here you will find examples of how to manage algorithms, data, and admin resources using Algorithmia's REST API and Python client library.

If this is your first time trying Algorithmia, you might find it useful to start with our Getting Started guide, which can be found alongside many other resources in the Algorithmia Developer Center.

Base URL

import Algorithmia

# When passing a custom API endpoint to our Python client, you 
# may omit the `v1` path prefix, as it will be supplied automatically.
client = Algorithmia.client('API_KEY', 'https://api.example.com')

By default, we provide examples using the https://api.algorithmia.com/v1 base URL, but if you are using an enterprise version of Algorithmia hosted under a different domain, you should ensure you modify any code samples as necessary.

Per our versioning scheme, ensure that you supply the appropriate version prefix in addition to the REST API endpoint you wish to use. Thus, if your Algorithmia instance was hosted at example.com, your base URL would be https://api.example.com/v1. If using a client library, ensure you properly pass your custom endpoint as a parameter when initializing the client.

Authentication

curl https://api.algorithmia.com/v1/scms
  -H 'Authorization: Simple API_KEY'

import Algorithmia

client = Algorithmia.client('API_KEY')

If you are interacting directly with Algorithmia's REST API, provide your API key via an Authorization header with the prefix Simple. If you are using one of our client libraries, follow the instructions specific to that client library. This holds true for both standard and admin API keys. Learn more about API keys in our devcenter.

Ensure that you enable algorithm management capabilities for your API key if you wish to create, edit, or delete algorithms.

Errors

{
  "id": "dc7daff0-37e7-549e-b469-d9da822a4092",
  "code": 5005,
  "message": "This feature doesn't exist yet."
}

Should an error occur while fulfilling a request, you will be returned an object possessing the following attributes:

Attribute	Type	Description
id	String	An optional identifier for the error that can be provided to Algorithmia customer support to aid debugging.
code	Number	The specific code pertaining to the error. See the expandable section below for details about available error codes.
message	String	A human-readable explanation of the error's cause.

The full list of error codes can be viewed by expanding the list below:

Error Codes

Code	Description
1000	The requested algorithm was not found.
1001	An algorithm with the requested name does not exist.
1002	An algorithm with the requested name already exists.
1003	The package set does not exist.
1004	The package set build doest not exist.
1005	The package does not exist.
1006	Unable to update package set.
1007	Version already published. Please compile your algorithm.
1008	Failed to create algorithm on backing SCM.
1009	An algorithm with the requested ID does not exist.
2001	Caller is not authorized to perform the operation.
2002	Unknown or invalid API key.
2011	A package with that name already exists.
2012	Invalid build status.
2013	Invalid JSON.
2014	Invalid build image.
2015	Invalid request.
2016	Invalid JSON for package set contents.
2017	The status is invalid or the operation is not valid for a package set with its status.
2018	Request body is invalid, missing field: 'owner'.
3000	The requested user was not found.
3001	Malformed user JSON in request.
3003	The username is already taken.
3004	The email address is already taken by a different username.
3005	Not all required fields have been provided.
3007	The username in the request body does not match the username in the request path.
3008	Updating the email of a user is not allowed.
3009	Invalid sign-up form.
3010	Invalid JSON to create a package.
3100	The requested organization was not found.
3101	An organization already exists with this name.
3102	Unable to remove the last owner of an organization.
3104	Failed to reserve an organization user while adding an organization.
3103	Malformed organization JSON in request.
3105	Favicon cannot exceed maximum size.
3106	Invalid file to upload.
3107	Logo cannot exceed maximum size.
4001	The request algorithm language is not known.
4002	The requested algorithm language does not support this feature.
4003	Malformed package set JSON in request.
4004	The requested machine type is not supported.
4005	A package set with the requested name already exists.
4006	A package set with the requested name does not exist.
4007	The package set contents contain duplicate items.
4008	The SCM OAuth token was not found.
4009	The SCM configuration was not found.
4010	Required parameter start_date or end_date is missing.
4011	Only algorithms backed with the internal SCM can modify code through Algorithmia APIs.
4012	Internal SCM does not support webhooks.
4020	The provided SCM configuration is invalid.
4021	Malformed update SCM payload.
4040	Unable to delete SCM configuration.
4041	Unable to perform specified action on the default SCM.
4042	Unable to perform specified action on a disabled SCM.
4043	Unable to delete SCM configuration in use.
4044	Duplicate SCM exists that has the same id or matches provider, OAuth client ID, and web URL.
4045	Unable to modify the referenced SCM configuration.
4050	Unable to start OAuth flow.
4051	Unable to finish OAuth flow.
4070	Webhook payload malformed.
4080	SCM provider is not authorized.
4084	Failed communicating with SCM.
5001	There was an internal error.
5002	Invalid marker used.
5003	Limit must be between 1 and the system-configured page size limit.
5004	Requested configuration entry could not be found.
5005	Feature not implemented.
6001	The request is invalid.
7000	Request ID was not found.

Pagination

{
    "marker": "eyJvcmdOYW1lIjoiQnVnQmFzaE9yZzEifQ",
    "next_link": "http://api.algorithmia.com/v1/organizations?limit=50&marker=eyJvcmdOYW1lIjoiQnVnQmFzaE9yZzEifQ",
    "results": [
      // ...
    ]
}

If you are querying a collection of objects, and there are more results available than can be displayed in a single response, you may paginate results with markers.

A collection response will contain two properties that allow you to fetch additional pages of results: marker and next_link. marker can be supplied as a query parameter to a subsequent request, informing the API that you wish to obtain the next page of results for your prior query. Conveniently, the next_link property contains the preconstructed URL for you to make just such a query.

If there are no additional results for a particular collection query, both the marker and next_link properties will be null.

Versioning

The latest version of the Algorithmia API is v1, and endpoints supported in this version fall under the /v1 path prefix.

Algorithmia will update this path prefix in the future should we release a new version of the Algorithmia API.

Client Libraries

Algorithmia offers client libraries in several languages. While nearly all client libraries offer the ability to invoke algorithms and manage data connectors, we recommend using our Python client library as it exposes additional functionality for managing algorithms.

Language	Client Library	Documentation
C#/.NET	algorithmia-c-sharp	Guide
CLI	algorithmia-cli	Guide
Go	algorithmia-go	Guide
Java	algorithmia-java	Guide
JavaScript	algorithmia-js	Guide
Node.js	algorithmia-nodejs	Guide
PHP	algorithmia-php	Guide
Python	algorithmia-python	Guide
R	algorithmia-r	Guide
Ruby	algorithmia-ruby	Guide
Rust	algorithmia-rust	Guide
Scala	algorithmia-scala	Guide
Swift	algorithmia-swift	Guide

Algorithms

The algorithm object

{
  "build": {
    "build_id": "j85f8087db281388d79fb224853864da73bff865",
    "commit_sha": "j85f8087db281388d79fb224853864da73bff865",
    "finished_at": "2019-05-07T21:16:43.121Z",
    "resource_type": "algorithm_build",
    "started_at": "2019-05-07T21:16:40.148Z",
    "status": "succeeded",
    "version_info": {
      "semantic_version": "0.1.0"
    }
  },
  "compilation": {
    "output": "Building algorithm...\nSuccess!",
    "successful": true
  },
  "details": {
    "label": "Greeting Algorithm",
    "summary": "This algorithm accepts text and returns a string of the form 'Hello ${text}!'",
    "tagline": "Returns a greeting"
  },
  "name": "Hello",
  "resource_type": "algorithm",
  "settings": {
    "algorithm_callability": "private",
    "environment": "cpu",
    "language": "python3-1",
    "license": "apl",
    "network_access": "full",
    "pipeline_enabled": true,
    "source_visibility": "closed"
  },
  "self_link": "https://api.algorithmia.com/v1/algorithms/algorithmiahq/Hello/versions/a501ed74fd91548dedd50dffa59e9f0e53ce49a3",
  "source": {
    "repository_https_url": "https://github.com/algorithmiahq/hello",
    "repository_name": "hello",
    "repository_owner": "algorithmiahq",
    "repository_ssh_url": "ssh://git@github.com:algorithmiahq/hello.git", 
    "scm": {
      "id": "1d48d16c-18cb-4336-8d0c-03a36f3120e1",
      "provider": "github",
      "default": false,
      "enabled": true,
      "oauth": {
        "client_id": "a727e54cb1fb30cde4b6"
      },
      "urls": {
        "api": "https://api.github.com",
        "ssh": "ssh://git@github.com",
        "web": "https://github.com"
      }
    }
  },
  "version_info": {
    "git_hash": "a501ed74fd91548dedd50dffa59e9f0e53ce49a3",
    "release_notes": "Fixed a bug that resulted in overly-enthusiastic greetings.",
    "sample_input": "Mia",
    "sample_output": "Hello Mia!",
    "semantic_version": "0.1.0"
  }
}

Attribute	Type	Description
build	Object	The algorithm build which resulted in the present algorithm version.
compilation.output	String	The logs for the algorithm's most recent build.
compilation.successful	Boolean	Whether the algorithm's most recent build succeeded or failed.
details.label	String	The human-readable name for an algorithm.
details.summary	String	A full description of an algorithm's capabilitities. Can contain HTML for rendering in an algorithm's "Docs" tab. Note that, if an algorithm's README.md file is updated, this value will be overwritten with the HTML equivalent of that file.
details.tagline	String	A short description of an algorithm for display under an algorithm's label.
name	String	The unique ID for an algorithm.
resource_type	String	Set to algorithm for algorithm objects.
self_link	String	A URL that can be used to retrieve the present algorithm version.
settings.algorithm_callability	String	Whether the latest version of an algorithm can be called by users other than the algorithm's owner (or if the algorithm's owner is an organization, the organization's members). One of public or private. Is initially set to private, even if an algorithm has no versions.
settings.environment	String	The hardware your algorithm will run on. One of cpu or gpu. Not set if settings.package_set is specified.
settings.language	String	The language an algorithm is authored in. One of java, javascript, python2-lackpack (Python 2), python3-1 (Python 3), r, ruby, rust, or scala. Not set if settings.package_set is specified.
settings.license	String	The license for an algorithm's source code. One of apl, apache2, gpl3 or mit. Only apl supports closed-source algorithms.
settings.network_access	String	Specifies whether an algorithm has access to the public internet upon execution. One of full or isolated.
settings.package_set	String	Specifies the package set that defines an algorithm's build and runtime environments. Not set if settings.language is specified.
settings.pipeline_enabled	Boolean	Specifies whether this algorithm is allowed to call other algorithms on the platform.
settings.source_visbility	String	Specifies whether the source code for this algorithm will be viewable by any user of the platform. One of open or closed. Must be set to open unless license chosen is apl.
source.repository_https_url	String	The HTTPS URL of the algorithm's Git repository (if the repository is hosted externally to the Algorithmia platform).
source.repository_name	String	The name of the Git repository that was created for the algorithm's source code (if the repository is hosted externally to the Algorithmia platform).
source.repository_owner	String	The username of the SCM user that owns the Git repository for this algorithm (if the repository is hosted externally to the Algorithmia platform).
source.repository_ssh_url	String	The SSH URL of the algorithm's Git repository (if the repository is hosted externally to the Algorithmia platform).
source.scm	Object	The SCM object representing the repository host for this algorithm.
version_info.git_hash	String	The Git SHA of the algorithm's most recent version.
version_info.release_notes	String	If this version of the algorithm has been published, this field informs consumers of any new changes in the algorithm that accompany the published version.
version_info.sample_input	String	An example of a valid text input to the algorithm. Only configurable for algorithm versions that have been published publicly or privately.
version_info.sample_output	String	An example of what the algorithm's output would be given the text provided in version_info.sample_input.
version_info.semantic_version	String	If this version of the algorithm has been published publicly or privately, this is semantic version that can be used to call said published version.

Create an algorithm

curl https://api.algorithmia.com/v1/algorithms/:username \
  -H 'Authorization: Simple API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "details": {
      "label": "My First Algorithm"
    },
    "name": "my_first_algorithm",
    "settings": {
      "environment": "cpu",
      "language": "python3-1",
      "license": "apl",
      "network_access": "full",
      "pipeline_enabled": true,
      "source_visibility": "closed" 
    }
  }'

import Algorithmia

client = Algorithmia.client('API_KEY')

algo = client.algo(':username/my_first_algorithm')

algo.create(
  details = {
    "label": "My First Algorithm"
  },
  settings = {
    "language": "python3-1",
    "source_visibility": "closed",
    "license": "apl",
    "network_access": "full",
    "pipeline_enabled": True,
    "environment": "cpu"
  }
)

POST /algorithms/:username

Path Parameters

Parameter	Type	Description
username	String	Required. The username of the user or organization that will own this algorithm.

Payload Parameters

Parameter	Type	Description
details.label	String	Required. The human-readable name for your algorithm.
details.summary	String	A full description of your algorithm's capabilitities. HTML is accepted for rendering in the algorithm's "Docs" tab.
details.tagline	String	A short description of your algorithm for display under the algorithm's label.
name	String	Required. The unique ID for your algorithm. Only alphanumeric characters and underscores are permitted. Must begin with a letter.
settings.environment	String	Required if language specified. The hardware your algorithm will run on. Choose from cpu or gpu.
settings.language	String	Required if package_set not specified. The language you wish to develop your algorithm in. Choose from java, javascript, python2-lackpack (Python 2), python3-1 (Python 3), r, ruby, rust, or scala.
settings.license	String	Required. The license for your algorithm's source code. Choose from apl, apache2, gpl3 or mit. Select apl if you wish for your algorithm's source code to be closed-source.
settings.network_access	String	Required. Specifies whether the algorithm will have access to the public internet upon execution. Choose from full or isolated.
settings.package_set	String	Required if language not specified. Specifies the package set that should define the algorithm's build and runtime environments.
settings.pipeline_enabled	Boolean	Required. Specifies whether this algorithm is allowed to call other algorithms on the platform.
settings.source_visbility	String	Required. Specifies whether the source code for this algorithm will be viewable by any user of the platform. If creating an algorithm with an external repository host, such as GitHub, determines whether the created repository is public or private. Choose from open or closed.
source.repository_name	String	Specifies the name of the Git repository that will be created for your algorithm's source code (if using an external SCM). Defaults to your algorithm's name property.
source.repository_owner	String	The username of the SCM user you wish to own your algorithm. Defaults to the user you performed SCM authorization with.
source.scm	String	The ID of the SCM you wish to host your algorithm's source code. Defaults to the default SCM for your Algorithmia instance.

{
  "name": "my_first_algorithm",
  "details": {
    "label": "My First Algorithm"
  },
  "settings": {
    "algorithm_callability": "private",
    "source_visibility": "closed",
    "language": "python3-1",
    "environment": "cpu",
    "license": "apl",
    "network_access": "full",
    "pipeline_enabled": true
  },
  "source": {
    "scm": {
      "id": "internal",
      "provider": "internal",
      "default": true,
      "enabled": true
    }
  },
  "resource_type": "algorithm"
}

Returns

If the request is successful, an algorithm object representing the created algorithm will be returned to you, otherwise an error.

Invoke an algorithm

curl https://api.algorithmia.com/v1/algo/demo/Hello \
  -X POST \
  -H 'Authorization: Simple API_KEY' \
  -H 'Content-Type: text/plain' \
  -d 'Neo'

import Algorithmia

client = Algorithmia.client('API_KEY')
# If you have not yet published a version of your algorithm,
# be certain to specify the specific SHA you wish to call.
algo = client.algo('demo/Hello') 

# Query parameters can be set via set_options.
algo.set_options(timeout=60, stdout=False)

result = algo.pipe("Neo")

print(result.result)    # Hello Neo
print(result.metadata)  # Metadata(content_type='text',duration=0.0002127)

POST /algo/:username/:algoname/[:version]

Path Parameters

Parameter	Type	Description
username	String	Required. The username of the user or organization that owns the algorithm.
algoname	String	Required. The name of the algorithm you wish to invoke.
version	String	The specific version of the algorithm you wish to invoke. The following are valid values for this parameter: - latestPrivate: Resolves to the latest version you have published privately. -<Git SHA>: Resolves to the built version of your algorithm for a specific Git SHA. Useful for testing an unpublished algorithm build. - 1.1.1: Fully specified semantic version. - 1.2.*: Specified to the minor level. Will resolve to the latest publicly published version with a minor version of 1.2 Defaults to latest publicly published version of your algorithm.

Query Parameters

Parameter	Type	Description
output	String	Determines how the algorithm's response is handled. Choose from raw (response is returned without a JSON wrapper) or void (algorithm call is made asynchronously and no output is returned).
stdout	Boolean	Whether the stdout of the algorithm should be returned in the response. Only available to the owner of the algorithm (or, if the algorithm is owned by an organization, the organization's members). Defaults to false.
timeout	Number	Duration, in seconds, that should pass before the invocation should timeout. Defaults to 300 (5 minutes). Maximum value is 3000 (50 minutes).

Payload Parameters

Both binary data and text may be passed as algorithm input data. To ensure your algorithm is passed the input data correctly, supply one of the following values for the Content-Type header when calling your algorithm (client libraries handle this automatically):

Content-Type	Description
application/json	body specifies JSON input data (UTF-8 encoded)
application/text	body specifies text input data (UTF-8 encoded)
application/octet-stream	body specifies binary input data (raw bytes)

Returns

{
  "result": "Hello Neo",
  "metadata": {
    "content_type": "text",
    "duration": 0.0002127,
    "stdout": "Picked up JAVA_TOOL_OPTIONS: -Dfile.encoding=UTF8"
  }
}

Depending on the configuration of the output query parameter, you may either receive an invocation result object or the raw output of the algorithm.

Invocation Result Object

Attribute	Type	Description
async	Boolean	Specifies whether the invocation was run asynchronously, e.g. if the output query parameter was set to void.
error.message	String	A human-readable message describing the error encountered while running the algorithm, if any.
error.stacktrace	String	The stacktrace of the error encountered while running the algorithm, if any. Only returned if the caller has access to the algorithm's source code.
metadata.content_type	String	One of binary, json, text, or void (if the algorithm provided no response).
metadata.duration	Number	The duration of the algorithm invocation, in seconds.
metadata.stdout	String	The data piped to the algorithms stdout stream during execution. Only provided if the stdout query parameter was set to true and the caller is the algorithm's owner.
request_id	String	The unique ID for the invocation request.
result	String or Object	The result of the algorithm invocation if output was not set to either void or raw. Returned as a string if metadata.content_type is set to text, a JSON object if metadata.content_type is set to json, or as a Base64-encoded string if metadata.content_type is set to binary.

Get an algorithm

curl https://api.algorithmia.com/v1/algorithms/:username/:algoname \
  -H 'Authorization: Simple API_KEY'

import Algorithmia

client = Algorithmia.client('API_KEY')

algo = client.algo(':username/:algoname')

print(algo.info()) # Prints an algorithm object

GET /algorithms/:username/:algoname

Path Parameters

Parameter	Type	Description
username	String	Required. The username of the user or organization that owns the algorithm.
algoname	String	Required. The name of the algorithm you wish to retrieve.

Returns

{
  "name": "my_first_algorithm",
  "details": {
    "label": "My First Algorithm"
  },
  "settings": {
    "algorithm_callability": "private",
    "source_visibility": "closed",
    "language": "python3-1",
    "environment": "cpu",
    "license": "apl",
    "network_access": "full",
    "pipeline_enabled": true
  },
  "source": {
    "scm": {
      "id": "internal",
      "provider": "internal",
      "default": true,
      "enabled": true
    }
  },
  "resource_type": "algorithm"
}

An algorithm object upon success, otherwise an error.

Update an algorithm

curl https://api.algorithmia.com/v1/algorithms/:username/:algoname \
  -X PUT
  -H 'Authorization: Simple API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "details": {
      "label": "My Updated Algorithm"
    },
    "settings": {
      "environment": "gpu",
      "license": "apl",
      "network_access": "full",
      "pipeline_enabled": true,
      "source_visibility": "closed"
    }
  }'

import Algorithmia

client = Algorithmia.client('API_KEY')

algo = client.algo(':username/:algoname')

algo.update(
  details = {
    "label": "My Updated Algorithm"
  },
  settings = {
    "environment": "gpu",
    "license": "apl",
    "network_access": "full",
    "pipeline_enabled": True,
    "source_visibility": "closed"
  }
)

PUT /algorithms/:username/:algoname

Path Parameters

Parameter	Type	Description
username	String	Required. The username of the user or organization that owns the algorithm.
algoname	String	Required. The name of the algorithm you wish to update.

Payload Parameters

Parameter	Type	Description
details.label	String	The human-readable name for your algorithm.
details.summary	String	A full description of your algorithm's capabilitities. HTML is accepted for rendering in the algorithm's "Docs" tab.
details.tagline	String	A short description of your algorithm for display under the algorithm's label.
settings.environment	String	Required if settings.language is specified. The hardware your algorithm will run on. Choose from cpu or gpu.
settings.license	String	Required. The license for your algorithm's source code. Choose from apl, apache2, gpl3 or mit. Select apl if you wish for your algorithm's source code to be closed-source.
settings.network_access	String	Required. Specifies whether the algorithm will have access to the public internet upon execution. Choose from full or isolated.
settings.package_set	String	Required if settings.package_set was previously specified. Specifies the package set that should define the algorithm's build and runtime environments.
settings.pipeline_enabled	Boolean	Required. Specifies whether this algorithm is allowed to call other algorithms on the platform.
settings.source_visibility	String	Required. Specifies whether the source code for this algorithm will be viewable by any user of the platform. Note that, if your algorithm's source code is hosted externally to the platform, updating this value will not result in changes to the backing repository's visibility. For example, updating this value for an algorithm will not change a GitHub repository from private to public or vice-versa.

Returns

{
  "name": "my_algorithm",
  "details": {
    "label": "My Updated Algorithm"
  },
  "settings": {
    "algorithm_callability": "private",
    "source_visibility": "closed",
    "language": "python3-1",
    "environment": "gpu",
    "license": "apl",
    "network_access": "full",
    "pipeline_enabled": true
  },
  "source": {
    "scm": {
      "id": "internal",
      "provider": "internal",
      "default": true,
      "enabled": true
    }
  },
  "resource_type": "algorithm"
}

The updated algorithm object upon success, otherwise an error.

Compile an algorithm

curl https://api.algorithmia.com/v1/algorithms/:username/:algoname/compile \
  -X POST
  -H 'Authorization: Simple API_KEY'

import Algorithmia

client = Algorithmia.client('API_KEY')

algo = client.algo(':username/:algoname')

algo.compile() # Returns an algorithm object upon successful compilation.

POST /algorithms/:username/:algoname/compile

Path Parameters

Parameter	Type	Description
username	String	Required. The username of the user or organization that owns the algorithm.
algoname	String	Required. The name of the algorithm you wish to compile.

Returns

{
    "name": "Hello",
    "details": {
      "label": "Greeting Algorithm"
    },
    "settings": {
      "algorithm_callability": "public",
      "source_visibility": "closed",
      "language": "python3-1",
      "environment": "gpu",
      "license": "apl",
      "network_access": "full",
      "pipeline_enabled": true
    },
    "version_info": {
      "git_hash": "6d50c89cb1d9eef506f9339af0c47f384ba71258"
    },
    "source": {
      "scm": {
        "id": "internal",
        "provider": "internal",
        "default": true,
        "enabled": true
      }
    },
    "compilation": {
      "successful": true,
      "output": "Building algorithm ..."
    },
    "self_link": "http://api.algorithmia.com/v1/algorithms/demo/Hello/versions/6d50c72cb1d9eef507f9339af0c47f484ba71258",
    "resource_type": "algorithm"
}

An algorithm object upon successful compilation, otherwise an error. Note that the values contained within the compilation object will have been updated.

Delete an algorithm

curl https://api.algorithmia.com/v1/algorithms/:username/:algoname \
  -X DELETE \
  -H 'Authorization: Simple API_KEY'

# Deleting an algorithm is not yet supported by our Python client library.

DELETE /algorithms/:username/:algoname

Path Parameters

Parameter	Type	Description
username	String	Required. The username of the user or organization that owns the algorithm.
algoname	String	Required. The name of the algorithm you wish to delete.

Returns

An empty response upon success, otherwise an error.

Get algorithm SCM status

curl https://api.algorithmia.com/v1/algorithms/:username/:algoname/scm/status \
  -H 'Authorization: Simple API_KEY'

# Obtaining an algorithm's SCM status is not yet supported via our Python client library.

GET /algorithms/:username/:algoname/scm/status

Path Parameters

Parameter	Type	Description
username	String	Required. The username of the user or organization that owns the algorithm.
algoname	String	Required. The name of the algorithm you wish to check the SCM status for.

Returns

{
    "scm_connection_status": "active",
    "repository_public_deploy_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCr2Hmsh5aTeHab+zMARTWpfUGk8Dfff0IicY7L8wMuQETyTSHcphN7CdJtCl3/nk45cz+DqH3tn1lOPXGPJghXYajtWJwwsGt5JS1y/gRiYvx67yYEy6RrSVV6JeMpbWasdfhjMdS533fjOnsFSkZPKv3GeVT5uOM4r29pjpTfQbZxC//iA0sv4Y/wECGOYnJWCmc6eU1faOaocsXW4pasdtAfC9D//eDfVbryBKisaStWPO5a5x1y45H1+0Ne4Rq5NV5BLaiISAP7L3i9A9O9mgddW3SufEZ+dt8cP8QmDgl2K39G7zfqD2TNhAHd7ToU8/7n9dp",
    "repository_webhook_secret": "8f63faa1-8e61-4272-8335-1aafb4a2b9289",
    "repository_webhook_url": "http://api.algorithmia.com/v1/algorithms/:username/:algoname/scm/webhook"
}

An object describing the algorithm's connection to its repository host, otherwise an error. Be advised that, if your algorithm's repository is hosted externally, this payload will contain sensitive data about your algorithm's connection (such as the repository_webhook_secret).

Attribute	Type	Description
scm_connection_status	String	The health of the algorithm's connection to its repository host. One of active (healthy), deploy_key_error (deploy key removed), or provider_internal_error (unknown error).
repository_public_deploy_key	String	The public deploy key used to establish secure SSH connections with the algorithm's external Git repository. Only present for algorithms with externally hosted Git repositories. Useful for reestablishing Algorithmia's ability to pull source code if the deploy key is accidentally deleted. Click here to learn more.
repository_webhook_secret	String	The secret used to verify webhook payloads generated by an external repository host. Click here to learn more.
repository_webhook_url	String	The URL called by an external repository host in the case that a change occurs to the repository (such as a commit or change to the default branch). Click here to learn more.

Algorithm Builds

The algorithm build object

{
  "build_id": "132298b7-8ca4-40ca-bd2a-84254fd67a81",
  "commit_sha": "d2f4112966eb5bcc2a54693249d634372d8b788a",
  "finished_at": "2020-04-07T16:45:10.096Z",
  "resource_type": "algorithm_build",
  "started_at": "2020-04-07T16:45:10.096Z",
  "status": "succeeded",
  "version_info": {
    "semantic_version": "1.0.0"
  }
}

Attribute	Type	Description
build_id	String	The unique identifier for this algorithm build.
commit_sha	String	The specific Git commit SHA that was built for this algorithm.
finished_at	String	The ISO 8601 datetime at which the build completed.
resource_type	String	Set to algorithm_build for algorithm build objects.
started_at	String	The ISO 8601 datetime at which the build began.
status	String	One of failed, in-progress, or succeeded.
version_info.semantic_version	String	The semantic version that this build was published as. Absent unless the build has been published as a public or private version.

List algorithm builds

curl https://api.algorithmia.com/v1/algorithms/:username/:algoname/builds \
  -H 'Authorization: Simple API_KEY'

# Listing algorithm builds is not yet supported via our Python client library.

GET /algorithms/:username/:algoname/builds

Path Parameters

Parameter	Type	Description
username	String	Required. The username of the user or organization that owns the algorithm.
algoname	String	Required. The name of the algorithm you wish to retrieve builds for.

Query Parameters

Parameter	Type	Description
limit	Number	The maximum number of items to return in the response. Defaults to 50.
marker	String	Used for paginating results from previous queries. See the pagination section above.

Returns

{
  "marker": null,
  "next_link": null,
  "results": [{
    "build_id": "132298b7-8ca4-40ca-bd2a-84254fd67a81",
    "commit_sha": "d2f4112966eb5bcc2a54693249d634372d8b788a",
    "finished_at": "2020-04-07T16:45:10.096Z",
    "resource_type": "algorithm_build",
    "started_at": "2020-04-07T16:45:10.096Z",
    "status": "succeeded",
    "version_info": {
      "semantic_version": "1.0.0"
    }
  }]
}

A collection of zero or more algorithm builds, otherwise an error.

Attribute	Type	Description
marker	String	If more results are available than can be shown based on the supplied limit, this value can be used to paginate results. See the pagination section above.
next_link	String	A link to the next page of results, if more results exist.
results	Array	A list of zero or more algorithm build objects for the algorithm.

Get an algorithm build

curl https://api.algorithmia.com/v1/algorithms/:username/:algoname/builds/:build_id \
  -H 'Authorization: Simple API_KEY'

# Obtaining an algorithm build is not yet supported via our Python client library.

GET /algorithms/:username/:algoname/builds/:build_id

Parameter	Type	Description
username	String	Required. The username of the user or organization that owns the algorithm.
algoname	String	Required. The name of the algorithm you wish to retrieve a build for.
build_id	String	Required. The ID of the specific build you wish to retrieve.

Returns

{
  "build_id": "132298b7-8ca4-40ca-bd2a-84254fd67a81",
  "commit_sha": "d2f4112966eb5bcc2a54693249d634372d8b788a",
  "finished_at": "2020-04-07T16:45:10.096Z",
  "resource_type": "algorithm_build",
  "started_at": "2020-04-07T16:45:10.096Z",
  "status": "succeeded",
  "version_info": {
    "semantic_version": "1.0.0"
  }
}

An algorithm build object, otherwise an error.

Get algorithm build logs

curl https://api.algorithmia.com/v1/algorithms/:username/:algoname/builds/:build_id/logs \
  -H 'Authorization: Simple API_KEY'

# Obtaining an algorithm build's logs is not yet supported via our Python client library.

GET /algorithms/:username/:algoname/builds/:build_id/logs

Parameter	Type	Description
username	String	Required. The username of the user or organization that owns the algorithm.
algoname	String	Required. The name of the algorithm you wish to retrieve a build for.
build_id	String	Required. The ID of the specific build you wish to retrieve logs for.

Returns

{
  "logs": "Building algorithm..."
}

An object containing the logs for an algorithm build, otherwise an error. Note that, until a build's status attribute transitions to either succeeded or failed, logs will not be available, and requesting logs for a build will result in a 404 response.

Attribute	Type	Description
logs	String	The logs for the algorithm build.

Algorithm Versions

The algorithm version object

{
  "build": {
    "build_id": "j85f8087db281388d79fb224853864da73bff865",
    "commit_sha": "j85f8087db281388d79fb224853864da73bff865",
    "finished_at": "2019-05-07T21:16:43.121Z",
    "resource_type": "algorithm_build",
    "started_at": "2019-05-07T21:16:40.148Z",
    "status": "succeeded",
    "version_info": {
      "semantic_version": "0.1.0"
    }
  },
  "compilation": {
    "output": "Algorithm building...",
    "successful": true
  },
  "details": {
    "label": "Greeting Algorithm"
  },
  "name": "Hello",
  "resource_type": "algorithm",
  "settings": {
    "algorithm_callability": "public",
    "source_visibility": "closed",
    "language": "python3-1",
    "environment": "gpu",
    "license": "apl",
    "network_access": "full",
    "pipeline_enabled": true
  },
  "source": {
    "scm": {
      "id": "internal",
      "provider": "internal",
      "default": true,
      "enabled": true
    }
  },
  "version_info": {
    "git_hash": "j85f8087db281388d79fb224853864da73bff865",
    "release_notes": "A few bug fixes",
    "sample_input": "testing",
    "semantic_version": "0.1.0"
  }
}

Algorithm version objects are identical to algorithm objects, with the sole difference being that algorithm versions must return values for the build, compilation, self_link, and version_info properties, given that they represent compiled, call-able instances of the algorithm.

Publish an algorithm version

curl https://api.algorithmia.com/v1/algorithms/:username/:algoname/versions \
  -X POST \
  -H 'Authorization: Simple API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "settings": {
      "algorithm_callability": "private"
    },
    "version_info": {
      "version_type": "minor",
      "release_notes": "A few bug fixes.",
      "sample_input": "42"
    }
  }'

import Algorithmia

client = Algorithmia.client('API_KEY')

algo = client.algo(':username/:algoname')

algo.publish(
  settings = {
    "algorithm_callability": "private"
  },
  version_info = {
    "release_notes": "A few bug fixes.",
    "sample_input": "testing",
    "version_type": "minor"
  }
)

POST /algorithms/:username/:algoname/versions

Path Parameters

Parameter	Type	Description
username	String	Required. The username of the user or organization that owns the algorithm.
algoname	String	Required. The name of the algorithm you wish to publish.

Payload Parameters

Parameter	Type	Description
settings.algorithm_callability	String	Required. Whether this algorithm version will remain call-able by only the owner of the algorithm (either organization members or individual user), or whether it will be freely call-able by all Algorithmia platform users. Choose from public or private.
version_info.release_notes	String	Describes any changes introduced by this version.
version_info.sample_input	String	An example of a valid text input to the algorithm.
version_info.version_type	String	Required. The increase in semantic version you would like to be attributable to the version. Choose from major, minor, or patch. Note that, depending on changes you've made recently to algorithm, you may be required to choose minor or major. Read our algorithm versioning docs to learn more.

Returns

{
  "build": {
    "build_id": "j85f8087db281388d79fb224853864da73bff865",
    "commit_sha": "j85f8087db281388d79fb224853864da73bff865",
    "finished_at": "2019-05-07T21:16:43.121Z",
    "resource_type": "algorithm_build",
    "started_at": "2019-05-07T21:16:40.148Z",
    "status": "succeeded",
    "version_info": {
      "semantic_version": "0.1.0"
    }
  },
  "compilation": {
    "output": "Algorithm building...",
    "successful": true
  },
  "details": {
    "label": "Greeting Algorithm"
  },
  "name": "Hello",
  "resource_type": "algorithm",
  "settings": {
    "algorithm_callability": "public",
    "source_visibility": "closed",
    "language": "python3-1",
    "environment": "gpu",
    "license": "apl",
    "network_access": "full",
    "pipeline_enabled": true
  },
  "source": {
    "scm": {
      "id": "internal",
      "provider": "internal",
      "default": true,
      "enabled": true
    }
  },
  "version_info": {
    "git_hash": "j85f8087db281388d79fb224853864da73bff865",
    "release_notes": "A few bug fixes",
    "sample_input": "testing",
    "semantic_version": "0.1.0"
  }
}

Returns an algorithm object representing the published version, with its version_info.semantic_version property having been incremented appropriately from the previous published version (if any). If the request was unsuccessful, and error will be returned.

List algorithm versions

curl https://api.algorithmia.com/v1/algorithms/:username/:algoname/versions \
  -H 'Authorization: Simple API_KEY'

import Algorithmia

client = Algorithmia.client('API_KEY')

algo = client.algo(':username/:algoname')

# Query parameters may be passed as options.
# Prints the last ten versions of the algorithm.
print(algo.versions(limit=10))

GET /algorithms/:username/:algoname/versions

Path Parameters

Parameter	Type	Description
username	String	Required. The username of the user or organization that owns the algorithm.
algoname	String	Required. The name of the algorithm you wish to retrieve versions for.

Query Parameters

Parameter	Type	Description
callable	Boolean	Whether to return only public or private algorithm versions. true maps to algorithm versions with algorithm_callability set to public, whereas false maps to private. Omitting this parameter results in versions with both public and private being returned.
limit	Number	The maximum number of items to return in the response. Defaults to 50.
published	Boolean	Whether to return only versions that have been published (e.g. have an associated semantic version). true will return only published versions, and false will return only unpublished versions. Omitting this parameter results in both published and unpublished versions being returned.
marker	String	Used for paginating results from previous queries. See the versioning section above.

Returns

{
  "marker": null,
  "next_link": null,
  "results": [{
    "build": {
      "build_id": "j85f8087db281388d79fb224853864da73bff865",
      "commit_sha": "j85f8087db281388d79fb224853864da73bff865",
      "finished_at": "2019-05-07T21:16:43.121Z",
      "started_at": "2019-05-07T21:16:40.148Z",
      "status": "succeeded",
      "version_info": {
        "semantic_version": "0.1.0"
      }
    },
    "compilation": {
      "output": "Algorithm building...",
      "successful": true
    },
    "details": {
      "label": "Greeting Algorithm"
    },
    "name": "Hello",
    "resource_type": "algorithm",
    "settings": {
      "algorithm_callability": "public",
      "source_visibility": "closed",
      "language": "python3-1",
      "environment": "gpu",
      "license": "apl",
      "network_access": "full",
      "pipeline_enabled": true
    },
    "source": {
      "scm": {
        "id": "internal",
        "provider": "internal",
        "default": true,
        "enabled": true
      }
    },
    "version_info": {
      "git_hash": "j85f8087db281388d79fb224853864da73bff865",
      "release_notes": "A few bug fixes",
      "sample_input": "testing",
      "semantic_version": "0.1.0"
    }
  }]
}

A collection of algorithm objects, otherwise an error.

Attribute	Type	Description
marker	String	If more results are available than can be shown based on the supplied limit, this value can be used to paginate results. See the versioning section above.
next_link	String	A link to the next page of results, if more results exist.
results	Array	A list of algorithm objects representing versions of the algorithm.

Get algorithm version

curl https://api.algorithmia.com/v1/algorithms/:username/:algoname/versions/:git_hash \
  -H "Authorization: Simple API_KEY"

# Querying information about a single build is not currently supported in our Python client library.

GET /algorithms/:username/:algoname/versions/:git_hash

Path Parameters

Parameter	Type	Description
username	String	Required. The username of the user or organization that owns the algorithm.
algoname	String	Required. The name of the algorithm you wish to retrieve a version for.
git_hash	String	Required. The Git hash of the specific version you to retrieve (e.g. version_info.git_hash).

Returns

{
  "build": {
    "build_id": "j85f8087db281388d79fb224853864da73bff865",
    "commit_sha": "j85f8087db281388d79fb224853864da73bff865",
    "finished_at": "2019-05-07T21:16:43.121Z",
    "started_at": "2019-05-07T21:16:40.148Z",
    "status": "succeeded",
    "version_info": {
      "semantic_version": "0.1.0"
    }
  },
  "compilation": {
    "output": "Algorithm building...",
    "successful": true
  },
  "details": {
    "label": "Greeting Algorithm"
  },
  "name": "Hello",
  "resource_type": "algorithm",
  "settings": {
    "algorithm_callability": "public",
    "source_visibility": "closed",
    "language": "python3-1",
    "environment": "gpu",
    "license": "apl",
    "network_access": "full",
    "pipeline_enabled": true
  },
  "source": {
    "scm": {
      "id": "internal",
      "provider": "internal",
      "default": true,
      "enabled": true
    }
  },
  "version_info": {
    "git_hash": "j85f8087db281388d79fb224853864da73bff865",
    "release_notes": "A few bug fixes",
    "sample_input": "testing",
    "semantic_version": "0.1.0"
  }
}

A single algorithm object representing the specific version you wished to retrieve, otherwise an error.

Data

Connectors

Connectors offer you a convenient API by which to access data stored across multiple storage providers, from Algorithmia's built-in data store to Amazon S3. You can learn more about the connectors Algorithmia supports in our documentation. The various connector types are identified as follows:

• data: Algorithmia's built-in data storage solution.
• azureblob: Microsoft Azure Blob Storage
• dropbox: Dropbox
• gs: Google Cloud Storage
• s3: Amazon S3

With the exception of data, connectors may also be identified by a label, or no label if a specific connector is the default for its connector type. These options can be configured for a given connector in your data portal.

For example, if you create an S3 data connector with the label test, you would identify it to the API as s3+test. However, if a specific connector is the default for its type, you can omit the label and simply use the connector's type instead. Thus, your default S3 connector would be identified to the API as simply s3.

Data URIs

# Identifies a file housed by Algorithmia's internal storage provider (data://),
# which belongs to the user "demo" within their "example" collection.
data://demo/example/test.png

# Identifies a file housed in S3 (connected to via an S3 connector labeled "test"),
# which resides in the "my_bucket" bucket and "example" directory.
s3+test://my_bucket/example/test.png

# Identifies a file housed in a user's default Azure Blob data connector,
# which resides under the "example" directory within the relevant blob container.
azureblob://example/test.png

Algorithmia supports a data URI notation for identifying files and directories across connectors. To construct a data URI, take the unique identifer of a given connector (such as data, azureblob, or s3+test) and supply that as the URI's protocol. Then append the path to the file or directory you wish to act on. See examples to the right.

Algorithmia will return data URIs to you identifying new files or directories you may create, and you can use these in any of our client libraries (including our Python client library) to act on those resources.

Paths are contextual to the data connector you are interacting with. For example, paths for the data connector must begin first with the username of user who owns the collection you wish to interact with (or .my to refer to the calling user), then the collection name, then the file (data does not support directories within collections). However, when interacting with an s3 connector, you must supply the name of the bucket as the first component of the data. Ensure you carefully read the documentation for the connector you are working with.

The file object

{
  "filename": "example.txt",
  "last_modified": "2020-03-18T17:00:33.000Z",
  "size": 20002
}

Attribute	Type	Description
filename	String	The name of the file.
last_modified	String	The ISO 8601 datetime at which the file was last modified.
size	Number	The size of the file in bytes.

The folder object

{
  "name": "example_folder"
}

Attribute	Type	Description
name	String	The name of the folder.

Create a directory

curl https://api.algorithmia.com/v1/connector/data/demo \
  -X POST \
  -H 'Authorization: Simple API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "example_collection",
    "acl": {
      "read": [
        "user://*"
      ]
    }
  }'

import Algorithmia
from Algorithmia.acl import ReadAcl

client = Algorithmia.client('API_KEY')

example_collection = client.dir("data://demo/example_collection")

example_collection.create(ReadAcl.public)

POST /connector/:connector_id/:connector_path

Path Parameters

Parameter	Type	Description
connector_id	String	The ID of the specific connector you wish to create directory within. Learn more in the connectors section above.
connector_path	String	The path under which you wish to create the directory. Note that this path is contextual to the type of connector you are interacting with.

Payload Parameters

Parameter	Type	Description
name	String	Required. The name of the directory you wish to create at the location specified by connector_path.
acl.read	Array	Used to set the ACL for hosted data collections only. Choose from [] (only you may access), ["algo://.my/*"] (only your algorithms may access), and ["user://*"] (any user may access).

Returns

{
  "result": "data://demo/example_collection"
}

Returns the following JSON payload upon successful directory creation, otherwise an error.

Attribute	Type	Description
result	String	The data URI of the resulting directory.

Get a file or directory

curl https://api.algorithmia.com/v1/connector/data/demo/example.png \
  -H 'Authorization: Simple API_KEY'

import Algorithmia

client = Algorithmia.client('API_KEY')

# Download file and get the file handle
exampleFile = client.file("data://demo/example_collection/example.png").getFile()

# Get file's contents as a string
exampleText = client.file("data://demo/example_collection/example.txt").getString()

# Get local file's contents as a string
exampleText = client.file("file://example.txt").getString()

# Get file's contents as JSON
exampleJson =  client.file("data://demo/example_collection/example.txt").getJson()

# Get file's contents as a byte array
exampleBytes = client.file("data://demo/example_collection/example.png").getBytes()

GET /connector/:connector_id/:connector_path

Path Parameters

Parameter	Type	Description
connector_id	String	The ID of the specific connector you wish to retrieve data from. Learn more in the connectors section above.
connector_path	String	The connector path for which you wish to retrieve contents.

Returns

If the connector_path identifies a file, the file's contents will be returned to you, and a X-Data-Type response header will be returned with the value file.

If the connector_path identifies a folder, the folder's contents will be described by the following JSON structure, and a X-Data-Type response header will be returned with the value directory.

Attribute	Type	Description
folders	String	A list of zero or more folders stored at this path.
files	String	A list of zero or more files stored at this path.

Otherwise, an error object will be returned to you.

Update collection ACL

curl https://api.algorithmia.com/v1/connector/data/demo/example_collection \
  -X PATCH \
  -H 'Authorization: Simple API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "acl": {
      "read": []
    }
  }'

import Algorithmia
from Algorithmia.acl import ReadAcl

client = Algorithmia.client('API_KEY')

example_collection = client.dir("data://demo/example_collection")

example_collection.update_permissions(ReadAcl.private)

POST /connector/data/:username/:collection

Path Parameters

Parameter	Type	Description
username	String	The unique ID of the user or organization who owns the collection you wish to update.
collection	String	The name of the hosted data collection you wish to update.

Payload Parameters

Parameter	Type	Description
acl.read	Array	Required. Choose from [] (only you may access), ["algo://.my/*"] (only your algorithms may access), and ["user://*"] (any user may access).

Returns

An empty response upon success, accompanied by a 200 status code, otherwise an error.

Upload a file

# Uploading text
curl https://api.algorithmia.com/v1/connector/data/demo/example_collection/example.txt \
  -X PUT \
  -H 'Authorization: Simple API_KEY' \
  -d 'Leader of the Autobots'

# Uploading a local file
curl https://api.algorithmia.com/v1/connector/data/demo/example_collection/example.png \
  -X PUT \
  -H 'Authorization: Simple API_KEY' \
  --data-binary @example.png

import Algorithmia
from Algorithmia.acl import ReadAcl

client = Algorithmia.client('API_KEY')

# Uploading a local file
client.file("data://demo/example_collection/example.png").putFile("/my/local/path")

# Uploading text
client.file("data://demo/example_collection/example.txt").put("Hello world!")

# Uploading a dict as JSON
client.file("data://demo/example_collection/example.json").putJson({"hello": "world"})

PUT /connector/:connector_id/:connector_path

Path Parameters

Parameter	Type	Description
connector_id	String	The ID of the specific connector you wish to create interact with. Learn more in the connectors section above.
connector_path	String	The path at which your new file should exist. Note that this path is contextual to the type of connector you are interacting with.

Payload Parameters

The body of the request will become the contents of the file that is created.

Returns

{
  "result": "data://demo/example_collection/example.png"
}

Returns the following JSON payload upon successful upload, otherwise an error.

Attribute	Type	Description
result	String	The data URI of the resulting file.

Verify file existence

curl https://api.algorithmia.com/v1/connector/data/demo/example.png \
  -I \
  -H 'Authorization: Simple API_KEY'

import Algorithmia

client = Algorithmia.client('API_KEY')

if client.file("data://demo/example_collection/example.png").exists():
  print("File exists!")

HEAD /connector/:connector_id/:connector_path

Path Parameters

Parameter	Type	Description
connector_id	String	The ID of the specific connector you wish to create interact with. Learn more in the connectors section above.
connector_path	String	The path to the file or directory you wish to verify. Note that this path is contextual to the type of connector you are interacting with.

Returns

Returns an affirmative response if the file exists (such as a 200 status code), otherwise an error.

Delete a file or directory

curl https://api.algorithmia.com/v1/connector/data/demo/example_collection/example.txt \
  -X DELETE \
  -H 'Authorization: Simple API_KEY'

import Algorithmia

client = Algorithmia.client('API_KEY')

exampleFile = client.file("data://demo/example_collection/example.png")

exampleFile.delete()

DELETE /connector/:connector_id/:connector_path

Path Parameters

Parameter	Type	Description
connector_id	String	The ID of the specific connector you wish to create interact with. Learn more in the connectors section above.
connector_path	String	The path to the file or directory you wish to delete. Note that this path is contextual to the type of connector you are interacting with.

Query Parameters

Parameter	Type	Description
force	Boolean	If attempting to delete a non-empty directory, forces deletion. Defaults to false.

Returns

A JSON payload of the following structure if the request succeeds (or succeeds partially), otherwise an error.

Attribute	Type	Description
result.deleted	Number	If the deletion is successful, the total number of files deleted.
error.deleted	Number	If an error occurred during deletion, this property indicates how many files were deleted before the error occurred.

Organizations

The organization object

{
  "org_contact_name": "Algorithmia Support",
  "org_email": "support@algorithmia.com",
  "org_label": "Algorithmia",
  "org_name": "algorithmiahq",
  "org_url": "https://algorithmia.com",
  "resource_type": "organization",
  "self_link": "http://api.algorithmia.com/v1/organizations/algorithmiahq"
}

Attribute	Type	Description
org_contact_name	String	The individual who can be contacted with any questions about the organization.
org_email	String	The email address by which the organization's contact may be reached.
org_label	String	The human-readable name for the organization.
org_name	String	The unique identifier for this organization.
org_url	String	The URL for the organization's website.
resource_type	String	Always set to organization for organization objects.
self_link	String	The URL that can be used to retrieve this specific organization via the REST API.

Create an organization

curl https://api.algorithmia.com/v1/organizations \
  -X POST \
  -H 'Authorization: Simple ADMIN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "org_contact_name": "Example User",
    "org_email": "support@example.com",
    "org_label": "Example Organization",
    "org_name": "example_organization",
    "org_url": "https://example.com"
  }'

# Creating an organization is not yet supported by our Python client library.

POST /organizations

Authorization

In order to interact with this endpoint you must pass an admin API key. Visit our documentation to learn more.

Payload Parameters

Parameter	Type	Description
org_name	String	Required. The unique identifier for this organization. Only letters, numbers, and underscores are permitted. Must start with a letter.
org_label	String	Required. The human-readable name for the organization.
org_contact_name	String	Required. The individual who can be contacted with any questions about the organization.
org_email	String	Required. The email address by which the organization may be contacted.
org_url	String	The URL for the organization's website.

Returns

{
  "org_contact_name": "Example User",
  "org_email": "support@example.com",
  "org_label": "Example Organization",
  "org_name": "example_organization",
  "org_url": "https://example.com",
  "resource_type": "organization",
  "self_link": "http://api.algorithmia.com/v1/organizations/algorithmiahq"
}

A single organization object representing the newly created organization, otherwise an error.

List organizations

curl https://api.algorithmia.com/v1/organizations \
  -H 'Authorization: Simple ADMIN_API_KEY'

# Listing organizations is not yet supported by our Python client library.

GET /organizations

Authorization

In order to interact with this endpoint you must pass an admin API key. Visit our documentation to learn more.

Query Parameters

Parameter	Type	Description
limit	Number	The maximum number of items to return in the response. Defaults to 50.
marker	String	Used for paginating results from previous queries. See the pagination section above.

Returns

{
  "marker": null,
  "next_link": null,
  "results": [{
    "org_contact_name": "Algorithmia Support",
    "org_email": "support@algorithmia.com",
    "org_label": "Algorithmia",
    "org_name": "algorithmiahq",
    "org_url": "https://algorithmia.com",
    "resource_type": "organization",
    "self_link": "http://api.algorithmia.com/v1/organizations/algorithmiahq"
  }]
}

A collection of zero or more organization objects, otherwise an error.

Attribute	Type	Description
marker	String	If more results are available than can be shown based on the supplied limit, this value can be used to paginate results. See the pagination section above.
next_link	String	A link to the next page of results, if more results exist.
results	Array	A list of zero or more organization objects.

Get an organization

curl https://api.algorithmia.com/v1/organizations/:org_name \
  -H 'Authorization: Simple ADMIN_API_KEY'

# Getting an organization is not yet supported by our Python client library.

GET /organizations/:org_name

Authorization

In order to interact with this endpoint you must pass an admin API key. Visit our documentation to learn more.

Path Parameters

Parameter	Type	Description
org_name	String	Required. The the unique org_name for the organization you wish to retrieve.

Returns

{
  "org_contact_name": "Algorithmia Support",
  "org_email": "support@algorithmia.com",
  "org_label": "Algorithmia",
  "org_name": "algorithmiahq",
  "org_url": "https://algorithmia.com",
  "resource_type": "organization",
  "self_link": "http://api.algorithmia.com/v1/organizations/algorithmiahq"
}

A single organization object if a valid org_name was provided, otherwise an error.

Delete an organization

curl https://api.algorithmia.com/v1/organizations/:org_name \
  -X DELETE \
  -H 'Authorization: Simple ADMIN_API_KEY'

# Deleting an organization is not yet supported by our Python client library.

DELETE /organizations/:org_name

Authorization

In order to interact with this endpoint you must pass an admin API key. Visit our documentation to learn more.

Path Parameters

Parameter	Type	Description
org_name	String	Required. The the unique org_name for the organization you wish to delete.

Returns

An empty response upon success, otherwise an error.

Organization Members

The organization member object

{
  "username": "example_user",
  "role": "owner",
  "user_link": "https://api.algorithmia.com/v1/user/example_user",
  "resource_type": "organization_member"
}

Attribute	Type	Description
role	String	One of owner or member. Owners have the ability to add and remove organization members, promote or demote other owners, and publish algorithms publicly on behalf of the organization.
resource_type	String	Always set to organization_member for organization member objects.
user_link	String	A link to the user object for the organization member.
username	String	The user's unique identifer.

List organization members

curl https://api.algorithmia.com/v1/organizations/:org_name/members \
  -H 'Authorization: Simple ADMIN_API_KEY'

# Querying organization members is not yet supported by our Python client library.

GET /organizations/:org_name/members

Authorization

In order to interact with this endpoint you must pass an admin API key. Visit our documentation to learn more.

Path Parameters

Parameter	Type	Description
org_name	String	Required. The the unique org_name of the organization you wish to retrieve members for.

Query Parameters

Parameter	Type	Description
limit	Number	The maximum number of items to return in the response. Defaults to 50.
marker	String	Used for paginating results from previous queries. See the pagination section above.

Returns

{
  "marker": null,
  "next_link": null,
  "results": [{
    "username": "example_user",
    "role": "owner",
    "user_link": "https://api.algorithmia.com/v1/user/example_user",
    "resource_type": "organization_member"
  }]
}

A collection of organization member objects, otherwise an error.

Attribute	Type	Description
marker	String	If more results are available than can be shown based on the supplied limit, this value can be used to paginate results. See the pagination section above.
next_link	String	A link to the next page of results, if more results exist.
results	Array	A list of one or more organization member objects.

Add organization member

curl https://api.algorithmia.com/v1/organizations/:org_name/members/:username \
  -X PUT \
  -H 'Authorization: Simple ADMIN_API_KEY'

# Adding organization members is not yet supported by our Python client library.

PUT /organizations/:org_name/members/:username

Authorization

In order to interact with this endpoint you must pass an admin API key. Visit our documentation to learn more.

Parameter	Type	Description
org_name	String	Required. The the unique org_name of the organization you wish to retrieve members for.
username	String	Required. The username of the specific user you wish to add to the organization.

Returns

No content if the operation was successful, otherwise an error.

Delete organization member

curl https://api.algorithmia.com/v1/organizations/:org_name/members/:username \
  -X DELETE \
  -H 'Authorization: Simple ADMIN_API_KEY'

# Deleting organization members is not yet supported by our Python client library.

DELETE /organizations/:org_name/members/:username

Authorization

In order to interact with this endpoint you must pass an admin API key. Visit our documentation to learn more.

Path Parameters

Parameter	Type	Description
org_name	String	Required. The the unique org_name of the organization for which you wish to delete a member.
username	String	Required. The username of the specific user you wish to remove from the organization.

Returns

No content if the operation was successful, otherwise an error.

SCMs

The SCM object

{
  "default": true,
  "enabled": true,
  "id": "5d48d16c-15cb-4336-8d0c-05l36f3170e1",
  "oauth": {
    "client_id": "89fsdy7hsdf8tsgd6"
  },
  "provider": "github",
  "urls": {
    "api": "https://api.github.com",
    "ssh": "ssh://git@github.com",
    "web": "https://github.com"
  }
}

Attribute	Type	Description
default	Boolean	Whether this SCM is the default choice for users creating an algorithm.
enabled	Boolean	Whether Algorithmia platform users may create algorithms with this SCM.
id	String	The unique identifier for this SCM, represented as a UUID.
oauth.client_id	String	If SCM is external to the Algorithmia platform, the ID of the OAuth client that can be used to authenticate Algorithmia platform users with the SCM.
provider	String	Represents the type of SCM. Choose from internal or github.
urls.api	String	If using an external SCM, such as github, the URL to the SCM's API endpoint.
urls.api	String	If using an external SCM, such as github, the URL to the SCM's SSH endpoint.
urls.web	String	If using an external SCM, such as github, the URL to the SCM's website.

Create an SCM

curl https://api.algorithmia.com/v1/admin/scms \
  -X POST \
  -H 'Authorization: Simple ADMIN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "enabled": false,
    "id": "github",
    "oauth": {
      "client_id": "89fsdy7hsdf8tsgd6",
      "client_secret": "..."
    },
    "provider": "github",
    "urls": {
      "api": "https://api.github.com",
      "ssh": "ssh://git@github.com",
      "web": "https://github.com"
    }
  }'

# Creating an SCM is not yet supported by our Python client library.

POST /admin/scms

Authorization

In order to interact with this endpoint you must pass an admin API key. Visit our documentation to learn more.

Payload Parameters

Attribute	Type	Description
enabled	Boolean	Whether this SCM should be enabled for Algorithmia platform users on creation.
id	String	If provided, allows the configuration of a vanity ID. Otherwise, a UUID will be generated for this attribute.
oauth.client_id	String	Required. The ID of the OAuth client that can be used to authenticate Algorithmia platform users with the SCM. Learn more about creating OAuth apps in our documentation.
oauth.client_secret	String	Required. The secret of the OAuth client that can be used to authenticate Algorithmia platform users with the SCM. Learn more about creating OAuth apps in our documentation.
provider	String	Required. Represents the type of SCM you wish to create. github is the only available option at the present time.
urls.api	String	Required. The URL to the SCM's API endpoint.
urls.api	String	Required. The URL to the SCM's SSH endpoint.
urls.web	String	Required. The URL to the SCM's website.

Returns

{
  "default": true,
  "enabled": true,
  "id": "5d48d16c-15cb-4336-8d0c-05l36f3170e1",
  "oauth": {
    "client_id": "89fsdy7hsdf8tsgd6"
  },
  "provider": "github",
  "urls": {
    "api": "https://api.github.com",
    "ssh": "ssh://git@github.com",
    "web": "https://github.com"
  }
}

A single SCM object if a valid SCM payload was provided, otherwise an error.

List SCMs

curl https://api.algorithmia.com/v1/scms \
  -H 'Authorization: Simple API_KEY'

# Listing SCMs is not yet supported by our Python client library.

GET /scms

Returns

{
  "results": [{
    "default": true,
    "enabled": true,
    "id": "5d48d16c-15cb-4336-8d0c-05l36f3170e1",
    "oauth": {
      "client_id": "89fsdy7hsdf8tsgd6"
    },
    "provider": "github",
    "urls": {
      "api": "https://api.github.com",
      "ssh": "ssh://git@github.com",
      "web": "https://github.com"
    }
  }]
}

A collection of SCM objects if the request was successful, otherwise an error.

Attribute	Type	Description
results	Array	A list of one or more SCM objects. An SCM of the type internal will always be a member of the returned collection.

Get an SCM

curl https://api.algorithmia.com/v1/scms/:scm_id \
  -H 'Authorization: Simple API_KEY'

# Getting an SCM is not yet supported by our Python client library.

GET /scms/:scm_id

Path Parameters

Parameter	Type	Description
scm_id	String	The the unique id for the SCM you wish to retrieve.

Returns

{
  "default": true,
  "enabled": true,
  "id": "5d48d16c-15cb-4336-8d0c-05l36f3170e1",
  "oauth": {
    "client_id": "89fsdy7hsdf8tsgd6"
  },
  "provider": "github",
  "urls": {
    "api": "https://api.github.com",
    "ssh": "ssh://git@github.com",
    "web": "https://github.com"
  }
}

A single SCM object if a valid identifier was passed, otherwise an error.

Update an SCM

curl https://api.algorithmia.com/v1/admin/scms/:scm_id \
  -X PATCH \
  -H 'Authorization: Simple ADMIN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "enabled": true
  }'

# Updating an SCM is not yet supported by our Python client library.

PATCH /admin/scms/:scm_id

Authorization

In order to interact with this endpoint you must pass an admin API key. Visit our documentation to learn more.

Path Parameters

Parameter	Type	Description
scm_id	String	The the unique id for the SCM you wish to update.

Payload Parameters

Parameter	Type	Description
enabled	Boolean	If specified, determines whether the specified SCM should be available for Algorithmia platform users to create algorithms. You cannot set enabled to false if an SCM's default property is also set to true. To accomplish this, make sure you make another SCM the default SCM.

Returns

{
  "default": true,
  "enabled": true,
  "id": "5d48d16c-15cb-4336-8d0c-05l36f3170e1",
  "oauth": {
    "client_id": "89fsdy7hsdf8tsgd6"
  },
  "provider": "github",
  "urls": {
    "api": "https://api.github.com",
    "ssh": "ssh://git@github.com",
    "web": "https://github.com"
  }
}

An SCM object representing the updated SCM if the payload was valid, otherwise an error.

Set the default SCM

curl https://api.algorithmia.com/v1/admin/scms/:scm_id/default \
  -X POST \
  -H 'Authorization: Simple ADMIN_API_KEY'

# Setting the default SCM is not yet supported by our Python client library.

POST /admin/scms/:scm_id/default

Authorization

In order to interact with this endpoint you must pass an admin API key. Visit our documentation to learn more.

Path Parameters

Parameter	Type	Description
scm_id	String	The the unique id for the SCM you wish to set as the default SCM.

Returns

No content if the operation was successful, otherwise an error. Note that a disabled SCM cannot become the default SCM for the platform: it must be enabled first.

Delete an SCM

curl https://api.algorithmia.com/v1/admin/scms/:scm_id \
  -X DELETE \
  -H 'Authorization: Simple ADMIN_API_KEY'

# Deleting an SCM is not yet supported by our Python client library.

DELETE /admin/scms/:scm_id

Authorization

In order to interact with this endpoint you must pass an admin API key. Visit our documentation to learn more.

Path Parameters

Parameter	Type	Description
scm_id	String	The the unique id for the SCM you wish to delete.

Returns

No content if the operation was successful, otherwise an error. Note that, once an SCM has been used to create an algorithm, it may not be deleted, only disabled.

Users

The user object

{
  "id": "123e4567-e89b-12d3-a456-426655440000",
  "company_name": "Algorithmia",
  "company_role": "Example User",
  "email": "me@example.com",
  "fullname": "Example User",
  "resource_type": "user",
  "self_link": "https://api.algorithmia.com/v1/users/example_user",
  "username": "example_user"
}

Attribute	Type	Description
id	String	The unique identifier for this user.
company_name	String	The name of the user's employer.
company_role	String	The user's occupation.
email	String	The user's email address.
fullname	String	The user's full name.
resource_type	String	Always set to user for users.
self_link	String	The URL that can be used to retrieve this specific user via the REST API.
username	String	The unique alias for this user.

Create a user

curl https://api.algorithmia.com/v1/users \
  -X POST \
  -H 'Authorization: Simple ADMIN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "company_name": "Algorithmia",
    "company_role": "Example User",
    "email": "example@example.com",
    "fullname": "Example User",
    "username": "example_user"
  }'

# Creating a user is not yet supported by our Python client library.

POST /users

Authorization

In order to interact with this endpoint you must provide an admin API key. Visit our documentation to learn more.

Payload Parameters

Parameter	Type	Description
company_name	String	The name of the user's employer.
company_role	String	The user's occupation.
email	String	Required. The user's email address. Must not already be in use by another user on the platform.
fullname	String	Required. The user's full name.
username	String	Required. The unique identifier for this user. Only letters, numbers, and underscores are permitted, and must begin with a letter.

Returns

{
  "id": "123e4567-e89b-12d3-a456-426655440000",
  "company_name": "Algorithmia",
  "company_role": "Example User",
  "email": "me@example.com",
  "fullname": "Example User",
  "resource_type": "user",
  "self_link": "https://api.algorithmia.com/v1/users/example_user",
  "username": "example_user"
}

A single user object if a valid user payload was provided, otherwise an error.

List users

curl https://api.algorithmia.com/v1/users \
  -H 'Authorization: Simple ADMIN_API_KEY'

# Listing users is not yet supported by our Python client library.

GET /users

Authorization

In order to interact with this endpoint you must provide an admin API key. Visit our documentation to learn more.

Query Parameters

Parameter	Type	Description
limit	Number	The maximum number of items to return in the response. Defaults to 50.
marker	String	Used for paginating results from previous queries. See the versioning section above.

Returns

{
  "marker": null,
  "next_link": null,
  "results": [{
    "id": "123e4567-e89b-12d3-a456-426655440000",
    "company_name": "Algorithmia",
    "company_role": "Example User",
    "email": "me@example.com",
    "fullname": "Example User",
    "resource_type": "user",
    "self_link": "https://api.algorithmia.com/v1/users/example_user",
    "username": "example_user"
  }]
}

A collection of user objects, otherwise an error.

Attribute	Type	Description
marker	String	If more results are available than can be shown based on the supplied limit, this value can be used to paginate results. See the versioning section above.
next_link	String	A link to the next page of results, if more results exist.
results	Array	A list of one or more user objects.

Get a user

curl https://api.algorithmia.com/v1/users/:username \
  -H 'Authorization: Simple ADMIN_API_KEY'

# Retrieving a user is not yet supported by our Python client library.

GET /users/:username

Authorization

In order to interact with this endpoint you must provide an admin API key. Visit our documentation to learn more.

Path Parameters

Parameter	Type	Description
username	String	Required. The the unique username for the user you wish to retrieve.

Returns

A single user object upon success, otherwise an error.

Update a user

curl https://api.algorithmia.com/v1/users/example_user \
  -X PUT \
  -H 'Authorization: Simple ADMIN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "company_name": "Algorithmia",
    "company_role": "Example User",
    "email": "example@example.com",
    "fullname": "Example User",
    "username": "example_user"
  }'

# Updating a user is not yet supported by our Python client library.

PUT /users/:username

Authorization

In order to interact with this endpoint you must provide an admin API key. Visit our documentation to learn more.

Path Parameters

Parameter	Type	Description
username	String	Required. The the unique username for the user you wish to update.

Payload Parameters

Parameter	Type	Description
company_name	String	The name of the user's employer.
company_role	String	The user's occupation.
email	String	Required. The user's email address. If no change desired, supply the previous value of user's email property.
fullname	String	Required. The user's full name. If no change desired, supply the previous value of user's fullname property.
username	String	Required. The user's unique identifier for this user. Must be supplied, but cannot be used to change a user's username.

Returns

{
  "id": "123e4567-e89b-12d3-a456-426655440000",
  "company_name": "Algorithmia",
  "company_role": "Example User",
  "email": "me@example.com",
  "fullname": "Example User",
  "resource_type": "user",
  "self_link": "https://api.algorithmia.com/v1/users/example_user",
  "username": "example_user"
}

The updated user object if a valid user payload was provided, otherwise an error.

Delete a user

curl https://api.algorithmia.com/v1/users/:username \
  -X DELETE \
  -H 'Authorization: Simple ADMIN_API_KEY'

# Deleting a user is not yet supported by our Python client library.

DELETE /users/:username

Authorization

In order to interact with this endpoint you must provide an admin API key. Visit our documentation to learn more.

Returns

An empty response upon success, otherwise an error.