> ## Documentation Index
> Fetch the complete documentation index at: https://strettch-make-section-id-optional.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Strettch Cloud API Introduction

> Authenticate, make requests, and explore the Strettch Cloud REST API for provisioning compute, managing DNS, and automating infrastructure workflows.

## 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:

```bash theme={null}
https://api.strettch.cloud/api/v1
```

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

## Authentication

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

```http theme={null}
Authorization: Bearer <your_api_key>
```

You can generate and manage your API keys from the [Strettch Cloud Console](https://cloud.strettch.com/p/settings/api-keys).

### 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](/services/teams/overview#team-roles-and-permissions) guide for a detailed breakdown of what each role can perform.

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

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

### 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:

```http theme={null}
Content-Type: application/json
```

## Response Format

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

### Success Response

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

### Error Response

```json theme={null}
{
  "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.             |

```json theme={null}
{
  "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:

```http theme={null}
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:

```http theme={null}
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](mailto: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](/changelog).

Non-breaking additions (new fields, new endpoints) may be made to the current version without notice.