Documentation
The Suburban Cloud REST API provides programmatic access to the same operations available in the console, including compute instances, applications, databases, storage, networking and domains. Requests are authenticated with scoped API keys and recorded in your organisation's audit log.
Getting Started
The following steps prepare an account for programmatic access.
Create an Account
Register for a Suburban Cloud account and create or join an organisation.
Generate an API Key
In the console, open Settings, then API Keys, and create a key limited to the services your integration requires.
Identify Your Organisation and Project
Note the organisation and project identifiers shown in the console. Resources are created within the project specified on each request.
Make Your First Request
Send an authenticated request to the API, as shown in the Authentication section below.
Authentication
Every request is made over HTTPS and carries the following headers.
| Header | Value | Description |
|---|---|---|
Authorization | Bearer <api-key> | Required on every request. Store API keys in a secrets manager and never commit them to source control. |
X-Organization-Id | <organisation-id> | The organisation on whose behalf the request is made. Required where a user or key belongs to more than one organisation. |
X-Project-Id | <project-id> | The project within the organisation. Resources such as instances and applications are created in this project. |
Example Authenticated Request
curl https://api.suburbancloud.ng/v2/compute/instances \
-H "Authorization: Bearer $SUBURBAN_TOKEN" \
-H "X-Organization-Id: $SUBURBAN_ORG" \
-H "X-Project-Id: $SUBURBAN_PROJECT"API Reference
The API accepts and returns JSON. All endpoints are versioned under a common base URL.
| Item | Detail |
|---|---|
| Base URL | https://api.suburbancloud.ng/v2 |
| Format | JSON request and response bodies |
| Response envelope | Each response contains success, data and error fields |
| Status codes | Standard HTTP status codes indicate the outcome of each request |
| API keys | Console, Settings, API Keys |
Common Endpoints
| Method | Path | Description |
|---|---|---|
| GET | /compute/instances | List Virtual Machine instances in the project |
| POST | /compute/instances | Create a Virtual Machine instance |
| GET | /apps | List App Engine applications |
| POST | /apps | Create an App Engine application from a Git repository |
| GET | /domains/check/{domain} | Check the availability and price of a domain name |
Example: Create an Instance
curl -X POST https://api.suburbancloud.ng/v2/compute/instances \
-H "Authorization: Bearer $SUBURBAN_TOKEN" \
-H "X-Organization-Id: $SUBURBAN_ORG" \
-H "X-Project-Id: $SUBURBAN_PROJECT" \
-H "Content-Type: application/json" \
-d '{
"name": "web-01",
"region": "ng-abuja-1",
"image": "ubuntu-24.04",
"flavor": "c2.large",
"sshKeyIds": ["key_123"],
"publicIp": true
}'Example: Error Response
{
"success": false,
"data": null,
"error": { "code": "VALIDATION_ERROR", "message": "flavor is required" }
}On success, success is true and data contains the requested resource or list. On failure, error.message describes the problem.
Request bodies show commonly used fields only. The full field list for each endpoint is available in the Knowledge Base or from our support team.
Command-Line Interface
The Suburban CLI provides access to the REST API from a terminal or a CI/CD pipeline.
Availability