Spheron API

Spheron API is an API that gives users access over our platform, providing all the resources that are available to you, exposed as HTTPS endpoints.

API style

REST API

REST API is called “Representational State Transfer,” and it makes the APIs relatively easy to use and discover. Spheron API is a REST-styled API that makes all data available. REST makes data and functionality available as resources using unique URLs. To request data or resources, you just need to provide its URL.

API Basics

Our API is exposed as an HTTP/1 and HTTP/2 service over SSL. All endpoints live under the URL https://api-v2.spheron.network and follow the REST architecture.

HTTP and TLS

The API supports HTTP versions 1, 1.1, and 2, although HTTP/2 is preferred. TLS versions 1.2 and 1.3 are supported with resumption.

Content Type

All requests made to the API must be encoded as JSON with the Content-Type: application/json header. If not otherwise specified, responses from the Spheron API, including errors, are encoded exclusively as JSON as well.

For new users

Before creating an access token for authentication, you need to sync your GitHub or GitLab account to give Spheron access. Click here for more instructions about granting access to your repository.

Authentication

Spheron Access Tokens are required to authenticate and use the Spheron API.

Authorization: Bearer <TOKEN>

Creating an Access Token

Access Tokens can be created and managed from inside your account settings.

1. From your Spheron dashboard, Click on your profile icon.
2. Click "Settings" to go to your settings page and navigate to Tokens.
3. Click "Create Token" to create a new Access Token.
4. Enter a descriptive name and select the type of service for your token.
5. Choose the scope from the list of Organizations in the drop-down menu, and select an expiration date for the token.
6. Click "Create" to create the token.

The scope ensures that only your specified Organization can use an Access Token. Once you've created an Access Token, securely store the value, as it will not be shown again.

Expiration

Setting an expiration date on an Access Token is highly recommended and is considered one of the standard security practices that helps keep your information secure. You can select from a default list of expiration dates ranging from 1 day to 1 year. You can view the expiration date of your Access Tokens on the tokens page.

Failed Authentication

If authentication is unsuccessful for a request, the error status code 403 is returned.

Versioning

All endpoints and examples are designated with a specific version. Versions vary per endpoint and are not global. The response shape of a certain endpoint is not guaranteed to be fixed over time. In particular, we might add new keys to responses without bumping a version endpoint, which will be noted in the changelog.

To ensure the security and correctness of your application, make sure to only read the keys from the response that your application needs. Don't proxy entire responses to third parties without validation. Old versions of each endpoint are supported for as long as possible. When we intend to deprecate, we will notify users in the changelog section.

Endpoint versions follow the base URL and come before the endpoint. For example:

https://api-v2.spheron.network/v1/deployments

API response codes

REST APIs use the Status-Line part of an HTTP response message to inform clients of their request’s overarching result. Spheron API uses standardized status codes from 100 to 511.

API Reference

We have generated swagger documentation (opens in a new tab) for all the API endpoints that developers can access using their API token.