Spheron API

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


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.


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

Authorization: Bearer <TOKEN>

NOTE: Use the Authorization header followed by an access 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.


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.


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:


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.

200Successfully fetch Organization information
Successfully fetch Array of coupons
Successfully fetch Array of invite users
Successfully fetch Project information
Successfully Added environment variables
Successfully Create a deployment
401This means that the request was unauthorized

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.

Spheron CLIGithub Actions