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.

If using code from one of the samples provided in this documentation, ensure that you replace API_KEY with your personal API key.

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 does 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 requested 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 capabilities. 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_visibility`	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 the 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 capabilities. 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` is 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_visibility`	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 capabilities. 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"
  },
    details = {
        "label": "Algorithm Display Name"
  }
)

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.
`details.label`	String	Required. The display name that shows up on the algorithm's homepage; unlike the algorithm's name, this may contain spaces.

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 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 through 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.
s3: Amazon Simple Storage Service (S3)
azureblob: Microsoft Azure Blob Storage
dropbox: Dropbox
gs: Google Cloud Storage

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 hosted 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 hosted in S3 (connected to via an S3 connector labeled "test"),
# which resides in the "my_bucket" bucket and "example" folder.
s3+test://my_bucket/example/test.png

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

Algorithmia supports a data URI notation for identifying files and folders across connectors. To construct a data URI, take the unique identifier 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 folder you wish to act on. See examples to the right.

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

Each connector type requires a specific connector path structure. For example, paths for the data connector must begin with the username of the target collection's owner (or .my to refer to the calling user), then the collection name, and then the file name (data does not support folders within collections). However, when interacting with an s3 connector, you must supply the name of the bucket as the first component of the connector path. See the documentation for the exact specifications for the connector you are using.

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 folder

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 within which you wish to create the folder. Learn more in the connectors section above.
`connector_path`	String	The path under which you wish to create the folder. Note that the format of this path is specific to the type of connector with which you are interacting.

Payload Parameters

Parameter	Type	Description
`name`	String	Required. The name of the folder 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"
}

The following JSON payload upon successful folder creation, otherwise an error.

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

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 from which you wish to retrieve data.

Returns

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

List folder 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 folder's contents as a string
exampleText = client.file("data://demo/example_collection").getString()

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

# Get folder'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 from which you wish to retrieve data.

Returns

The folder's contents described by the following JSON structure, and a X-Data-Type response header with the value directory, otherwise an error.

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.

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 with which you wish to interact. Learn more in the connectors section above.
`connector_path`	String	The path at which your new file should exist. Note that the format of this path is specific to the type of connector with which you are interacting.

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"
}

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 with which you wish to interact. Learn more in the connectors section above.
`connector_path`	String	The path to the file or folder you wish to verify. Note that the format of this path is specific to the type of connector with which you are interacting.

Returns

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

Delete a file or folder

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 with which you wish to interact. Learn more in the connectors section above.
`connector_path`	String	The path to the file or folder you wish to delete. Note that this path is contextual to the type of connector with which you are interacting.

Query Parameters

Parameter	Type	Description
`force`	Boolean	If attempting to delete a non-empty folder, 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, the total number of files 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",
  "external_admin_group": "sample external admin group",
  "external_member_group": "sample external member group",
  "external_id": "sampleExternalId",
  "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.
`external_admin_group`	String	The name of the admin group from the external identity system when using external organization membership management.
`external_member_group`	String	The name of the member group from the external identity system when using external organization membership management.
`external_id`	String	A custom identifier which can be used to synchronize with external systems, such as an identitiy provider.
`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",
    "external_admin_group": "sample external admin group",
    "external_member_group": "sample external member group",
    "external_id": "sampleExternalId",
  }'

# 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.
`external_admin_group`	String	The name of the admin group from the external identity system when using external organization membership management.
`external_member_group`	String	The name of the member group from the external identity system when using external organization membership management.
`external_id`	String	The identifier for this organization in the external identity system when using external organization membership management.

Returns

{
  "org_contact_name": "Example User",
  "org_email": "support@example.com",
  "org_label": "Example Organization",
  "org_name": "example_organization",
  "org_url": "https://example.com",
  "external_admin_group": "sample external admin group",
  "external_member_group": "sample external member group",
  "external_id": "sampleExternalId",
  "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",
    "external_admin_group": "sample external admin group",
    "external_member_group": "sample external member group",
    "external_id": "sampleExternalId",
    "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 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",
  "external_admin_group": "sample external admin group",
  "external_member_group": "sample external member group",
  "external_id": "sampleExternalId",
  "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.

Get an organization through external ID

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

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

GET /organizations/externalId/:external_id

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
`external_id`	String	Required. The unique `external_id` which has been updated to match the ID manually supplied to this organization during creation and/or update.

Returns

{
  "org_contact_name": "Algorithmia Support",
  "org_email": "support@algorithmia.com",
  "org_label": "Algorithmia",
  "org_name": "algorithmiahq",
  "org_url": "https://algorithmia.com",
  "external_admin_group": "sample external admin group",
  "external_member_group": "sample external member group",
  "external_id": "sampleExternalId",
  "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 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 identifier.

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 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 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 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 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 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 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 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 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 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.