Introduction
Welcome to Algorithmia's API documentation. Here you will find examples of how to manage algorithms, data, and admin resources using Algorithmia's REST API and Python client library.
If this is your first time trying Algorithmia, you might find it useful to start with our Getting Started guide, which can be found alongside many other resources in the Algorithmia Developer Center.
Base URL
import Algorithmia
# When passing a custom API endpoint to our Python client, you
# may omit the `v1` path prefix, as it will be supplied automatically.
client = Algorithmia.client('API_KEY', 'https://api.example.com')
By default, we provide examples using the https://api.algorithmia.com/v1
base URL, but if you are using an enterprise version of Algorithmia hosted under a different domain, you should ensure you modify any code samples as necessary.
Per our versioning scheme, ensure that you supply the appropriate version prefix in addition to the REST API endpoint you wish to use. Thus, if your Algorithmia instance was hosted at example.com
, your base URL would be https://api.example.com/v1
. If using a client library, ensure you properly pass your custom endpoint as a parameter when initializing the client.
Authentication
curl https://api.algorithmia.com/v1/scms
-H 'Authorization: Simple API_KEY'
import Algorithmia
client = Algorithmia.client('API_KEY')
If you are interacting directly with Algorithmia's REST API, provide your API key via an Authorization
header with the prefix Simple
. If you are using one of our client libraries, follow the instructions specific to that client library. This holds true for both standard and admin API keys. Learn more about API keys in our devcenter.
Ensure that you enable algorithm management capabilities for your API key if you wish to create, edit, or delete algorithms.
Errors
{
"id": "dc7daff0-37e7-549e-b469-d9da822a4092",
"code": 5005,
"message": "This feature doesn't exist yet."
}
Should an error occur while fulfilling a request, you will be returned an object possessing the following attributes:
Attribute | Type | Description |
---|---|---|
id |
String | An optional identifier for the error that can be provided to Algorithmia customer support to aid debugging. |
code |
Number | The specific code pertaining to the error. See the expandable section below for details about available error codes. |
message |
String | A human-readable explanation of the error's cause. |
The full list of error codes can be viewed by expanding the list below:
Error Codes
Code | Description |
---|---|
1000 | The requested algorithm was not found. |
1001 | An algorithm with the requested name does not exist. |
1002 | An algorithm with the requested name already exists. |
1003 | The package set does not exist. |
1004 | The package set build 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 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.2Defaults 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:
data
: Algorithmia's built-in data storage solution.azureblob
: Microsoft Azure Blob Storagedropbox
: Dropboxgs
: Google Cloud Storages3
: Amazon S3
With the exception of data
, connectors may also be identified by a label, or no label if a specific connector is the default for its connector type. These options can be configured for a given connector in your data portal.
For example, if you create an S3 data connector with the label test
, you would identify it to the API as s3+test
. However, if a specific connector is the default for its type, you can omit the label and simply use the connector's type instead. Thus, your default S3 connector would be identified to the API as simply s3
.
Data URIs
# Identifies a file housed by Algorithmia's internal storage provider (data://),
# which belongs to the user "demo" within their "example" collection.
data://demo/example/test.png
# Identifies a file housed in S3 (connected to via an S3 connector labeled "test"),
# which resides in the "my_bucket" bucket and "example" directory.
s3+test://my_bucket/example/test.png
# Identifies a file housed in a user's default Azure Blob data connector,
# which resides under the "example" directory within the relevant blob container.
azureblob://example/test.png
Algorithmia supports a data URI notation for identifying files and directories across connectors. To construct a data URI, take the unique identifer of a given connector (such as data
, azureblob
, or s3+test
) and supply that as the URI's protocol. Then append the path to the file or directory you wish to act on. See examples to the right.
Algorithmia will return data URIs to you identifying new files or directories you may create, and you can use these in any of our client libraries (including our Python client library) to act on those resources.
Paths are contextual to the data connector you are interacting with. For example, paths for the data
connector must begin first with the username of user who owns the collection you wish to interact with (or .my
to refer to the calling user), then the collection name, then the file (data
does not support directories within collections). However, when interacting with an s3
connector, you must supply the name of the bucket as the first component of the data. Ensure you carefully read the documentation for the connector you are working with.
The file object
{
"filename": "example.txt",
"last_modified": "2020-03-18T17:00:33.000Z",
"size": 20002
}
Attribute | Type | Description |
---|---|---|
filename |
String | The name of the file. |
last_modified |
String | The ISO 8601 datetime at which the file was last modified. |
size |
Number | The size of the file in bytes. |
The folder object
{
"name": "example_folder"
}
Attribute | Type | Description |
---|---|---|
name |
String | The name of the folder. |
Create a directory
curl https://api.algorithmia.com/v1/connector/data/demo \
-X POST \
-H 'Authorization: Simple API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"name": "example_collection",
"acl": {
"read": [
"user://*"
]
}
}'
import Algorithmia
from Algorithmia.acl import ReadAcl
client = Algorithmia.client('API_KEY')
example_collection = client.dir("data://demo/example_collection")
example_collection.create(ReadAcl.public)
POST /connector/:connector_id/:connector_path
Path Parameters
Parameter | Type | Description |
---|---|---|
connector_id |
String | The ID of the specific connector you wish to create directory within. Learn more in the connectors section above. |
connector_path |
String | The path under which you wish to create the directory. Note that this path is contextual to the type of connector you are interacting with. |
Payload Parameters
Parameter | Type | Description |
---|---|---|
name |
String | Required. The name of the directory you wish to create at the location specified by connector_path . |
acl.read |
Array | Used to set the ACL for hosted data collections only. Choose from [] (only you may access), ["algo://.my/*"] (only your algorithms may access), and ["user://*"] (any user may access). |
Returns
{
"result": "data://demo/example_collection"
}
Returns the following JSON payload upon successful directory creation, otherwise an error.
Attribute | Type | Description |
---|---|---|
result |
String | The data URI of the resulting directory. |
Get a file
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.