NAV
cURL Python

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

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:

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

curl https://api.algorithmia.com/v1/connector/data/demo/example_collection/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 from which you wish to retrieve data. Learn more in the connectors section above.
connector_path String The connector path for which you wish to retrieve contents.

Returns

The file's contents and an X-Data-Type response header with the value file.

Otherwise, an error object will be returned to you.

List directory contents

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

import Algorithmia

client = Algorithmia.client('API_KEY')

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

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

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

GET /connector/:connector_id/:connector_path

Path Parameters

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

Returns

The directory's contents described by the following JSON structure, and a X-Data-Type response header 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.

cURL Python