Strettch Cloud API Introduction

Welcome

Use the Strettch Cloud API to provision compute instances, automate infrastructure workflows, and integrate cloud resources directly into your applications — all through a single REST interface. Our API is organized around REST principles and returns JSON-encoded responses. Every request is authenticated, versioned, traced, and designed for reliable use in production systems.

Base URL

All API requests should be made to:

https://api.strettch.cloud/api/v1

There is no sandbox environment. All API requests interact with live resources. Use caution when testing destructive operations.

Authentication

All endpoints require authentication via an API key passed as a Bearer token.

Authorization: Bearer <your_api_key>

You can generate and manage your API keys from the Strettch Cloud Console.

API Key Scopes

API keys inherit the permission level (Owner, Admin, or Member) of the team member who created them. This means a key can perform any action allowed by the creator’s role across the team’s resources. Refer to the Team Roles & Permissions guide for a detailed breakdown of what each role can perform.

In the future, you will be able to further restrict API keys to specific granular scopes (e.g., compute:read only). Currently, they operate with full role-level access.

Keep your API keys secure. Do not share them in publicly accessible areas such as GitHub repositories, client-side code, or online forums. If a key is compromised, revoke it immediately from the Console.

Common Authentication Errors

Status	Code	Cause
`401`	`UNAUTHORIZED`	Key is missing, malformed, or revoked.
`403`	`FORBIDDEN`	Key lacks permission (scope) for this action.

Request Format

For all POST, PUT, and PATCH requests, set the Content-Type header:

Content-Type: application/json

Response Format

All responses return JSON with a consistent top-level structure.

Success Response

{
  "success": true,
  "message": "Operation successful",
  "data": { ... },
  "requestId": "59ea8f7e-...",
  "timestamp": "2024-01-15T10:00:00Z"
}

Error Response

{
  "success": false,
  "code": "RESOURCE_NOT_FOUND",
  "message": "The requested compute instance does not exist.",
  "requestId": "59ea8f7e-...",
  "timestamp": "2024-01-15T10:00:00Z"
}

The code field is a stable, machine-readable string you can use for programmatic error handling. Common error codes:

Code	HTTP Status	Description
`BAD_REQUEST`	`400`	Request body or parameters are malformed.
`FORBIDDEN`	`403`	You do not have permission to perform this action.
`RESOURCE_NOT_FOUND`	`404`	The requested resource does not exist.
`TOO_MANY_REQUESTS`	`429`	Too many requests — see Rate Limiting.
`INTERNAL_SERVER_ERROR`	`500`	Unexpected server-side error.

Pagination

List endpoints (e.g., GET /computes) are paginated. Use the following query parameters:

Parameter	Type	Default	Description
`page`	integer	`1`	Page number to retrieve.
`limit`	integer	`20`	Items per page (max `100`).

Paginated responses include a meta object that provides context for the current result set:

Field	Type	Description
`total`	integer	The total number of items matching the query across all pages.
`page`	integer	The current page number.
`limit`	integer	The maximum number of items returned in this page.

{
  "success": true,
  "data": [...],
  "meta": {
    "total": 42,
    "page": 1,
    "limit": 20
  }
}

Idempotency

POST endpoints that create resources support idempotency to prevent duplicate actions on network retries (e.g., accidentally provisioning two servers). Pass a unique UUID v4 in the Idempotency-Key header:

Idempotency-Key: <unique_uuid_v4>

Behaviour:

A retry with the same key returns the original response — no duplicate action is performed.
The response status on a replayed request is 202, regardless of the original status code.

Rate Limiting

All API requests are subject to rate limits to ensure platform stability and fair usage.

Tier	Limit
All Requests	2 requests / second per API key

When a rate limit is exceeded, the API returns 429 Too Many Requests. Use the response headers to manage your request cadence efficiently:

x-ratelimit-limit: 2
x-ratelimit-remaining: 1
x-ratelimit-reset: 1776410380

Header	Description
`x-ratelimit-limit`	Total request allowance per window.
`x-ratelimit-remaining`	Requests remaining in the current window.
`x-ratelimit-reset`	The Unix timestamp when the current rate limit window expires and the quota resets.

If your system requires higher throughput for specific use cases, contact our team at cloud@strettch.com.

Versioning

The current API version is v1, reflected in every endpoint path. Breaking changes will be introduced under a new version (e.g., /api/v2). When a new version is released, the previous version will continue to receive support for a defined deprecation period, communicated via email and the changelog. Non-breaking additions (new fields, new endpoints) may be made to the current version without notice.

Getting Started

Computes

Specifications

Images

Regions

System

Strettch Cloud API Introduction

Welcome

Base URL

Authentication

API Key Scopes

Common Authentication Errors

Request Format

Response Format

Success Response

Error Response

Idempotency

Rate Limiting

Versioning

​Welcome

​Base URL

​Authentication

​API Key Scopes

​Common Authentication Errors

​Request Format

​Response Format

​Success Response

​Error Response

​Pagination

​Idempotency

​Rate Limiting

​Versioning

Welcome

Base URL

Authentication

API Key Scopes

Common Authentication Errors

Request Format

Response Format

Success Response

Error Response

Pagination

Idempotency

Rate Limiting

Versioning