Skip to main content

​
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

StatusCodeCause
401UNAUTHORIZEDKey is missing, malformed, or revoked.
403FORBIDDENKey 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:
CodeHTTP StatusDescription
BAD_REQUEST400Request body or parameters are malformed.
FORBIDDEN403You do not have permission to perform this action.
RESOURCE_NOT_FOUND404The requested resource does not exist.
TOO_MANY_REQUESTS429Too many requests — see Rate Limiting.
INTERNAL_SERVER_ERROR500Unexpected server-side error.

​
Pagination

List endpoints (e.g., GET /computes) are paginated. Use the following query parameters:
ParameterTypeDefaultDescription
pageinteger1Page number to retrieve.
limitinteger20Items per page (max 100).
Paginated responses include a meta object that provides context for the current result set:
FieldTypeDescription
totalintegerThe total number of items matching the query across all pages.
pageintegerThe current page number.
limitintegerThe 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.
TierLimit
Standard (Reads)30 requests / second per API key
Mutating (Writes)5 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-second: 30
x-ratelimit-remaining-second: 29
x-ratelimit-reset-second: 1776144940
HeaderDescription
x-ratelimit-limit-secondTotal request allowance per second.
x-ratelimit-remaining-secondRequests remaining in the current second.
x-ratelimit-reset-secondThe 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.