API Reference

Overview

The API Reference describes the planned HTTP interface for managing StrataGateway infrastructure. It provides a structured overview of the planned API surface across all resource families.

The API is intended to eventually cover:

StrataGateway tooling is expected to build on the same core platform API:

All endpoint examples on this page must be clearly treated as Preview, Illustrative, Planned, or In Development unless the existing project explicitly marks them as finalized.

Base URL

The planned base URL for the StrataGateway API:

https://api.stratagateway.com/v1

The final production API hostname and versioning strategy will be confirmed before public release. Do not imply that api.stratagateway.com is currently a live production API.

Illustrative request:

GET https://api.stratagateway.com/v1/instances

Authentication

The StrataGateway API is planned to use Bearer token authentication. Include the token in the Authorization header on every request.

Authorization: Bearer $STRATA_API_TOKEN

curl \
  -H "Authorization: Bearer $STRATA_API_TOKEN" \
  https://api.stratagateway.com/v1/instances

Request format

All request bodies use JSON. Include the following headers:

Authorization: Bearer $STRATA_API_TOKEN
Content-Type: application/json
Accept: application/json

Illustrative create-instance request:

POST /v1/instances

{
  "name": "web-prod-01",
  "region": "fra-1",
  "plan": "compute-standard",
  "image": "ubuntu-24.04-lts",
  "ssh_keys": ["key_8f3a9b1c"]
}

Clearly label: Illustrative request schema. Do not claim these exact fields are finalized.

Response format

Illustrative response:

{
  "id": "inst_7a91c2",
  "name": "web-prod-01",
  "status": "provisioning",
  "region": "fra-1",
  "created_at": "2026-07-28T18:30:00Z"
}

Resource identifiers

StrataGateway uses stable, prefixed identifiers for all resources. Illustrative examples:

Prefixes and identifier formats are illustrative. Stable identifiers are useful for:

Pagination

Collection endpoints are expected to support pagination.

GET /v1/instances?limit=25

Illustrative response

{
  "data": [
    {
      "id": "inst_example",
      "name": "web-01"
    }
  ],
  "pagination": {
    "limit": 25,
    "next": "cursor_example"
  }
}

Errors

The API is planned to return a consistent error structure:

{
  "error": {
    "code": "resource_not_found",
    "message": "The requested resource could not be found.",
    "request_id": "req_example"
  }
}

Illustrative HTTP status codes:

Do not claim the final API will use every status code exactly this way.

Compute

Manage Cloud Compute resources and lifecycle operations.

Illustrative create instance request:

POST /v1/instances

{
  "name": "web-prod-01",
  "region": "fra-1",
  "plan": "compute-standard",
  "image": "ubuntu-24.04-lts",
  "ssh_keys": ["key_8f3a9b1c"]
}

Networks

Manage network resources.

Illustrative create request:

{
  "name": "production-private",
  "region": "fra-1",
  "cidr": "10.10.0.0/24"
}

Do not invent advanced networking resources. Use Preview / Illustrative statuses.

Firewalls

Manage firewall policies and rules.

Illustrative create request:

{
  "name": "web-production",
  "rules": [
    {
      "direction": "inbound",
      "protocol": "tcp",
      "port": "443",
      "source": "0.0.0.0/0",
      "action": "allow"
    }
  ]
}

SSH Keys

Manage SSH keys for instance access.

Illustrative create request:

{
  "name": "Personal Laptop",
  "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI..."
}

Backups

Manage backup resources and restore operations.

Use Illustrative / Planned statuses. Do not claim backup endpoints currently exist.

Monitoring

Retrieve metrics and events for resources.

DDoS Events

Retrieve DDoS event data and protection state.

Rate limits

API rate limiting is expected for:

Potential illustrative headers:

RateLimit-Limit: 100
RateLimit-Remaining: 99
RateLimit-Reset: 1706454000

Clearly label: Illustrative header model. Do not claim those header names are final.

Versioning

Versioning is intended to provide a stable API contract.

/v1/

Conceptual goals:

Control-plane mutations

API v1 supports JSON create, partial update, and delete operations for the current Compute, Networking, and Storage control-plane records. These operations use the same resource model as the dashboard and require a project API credential.

POST  /api/v1/compute
PATCH /api/v1/compute/{instanceId}
DELETE /api/v1/compute/{instanceId}

POST  /api/v1/networking
PATCH /api/v1/networking/{networkId}
DELETE /api/v1/networking/{networkId}

POST  /api/v1/storage
PATCH /api/v1/storage/{volumeId}
DELETE /api/v1/storage/{volumeId}

POST /api/v1/compute
Authorization: Bearer sg_live_...
Content-Type: application/json
Idempotency-Key: 2f7b1b58-0f11-4e90-8a75-1b3c3bb2f6d1

{
  "name": "web-01",
  "region": "fra-1",
  "image": "ubuntu-24-04",
  "plan": "shared-1"
}

{
  "instance": {
    "publicId": "7d9c2c5d-2b29-4ec5-9af4-4a8f1d9f4e12",
    "name": "web-01",
    "regionKey": "fra-1",
    "imageKey": "ubuntu-24-04",
    "planKey": "shared-1",
    "status": "queued",
    "customerStatus": {
      "status": "pending",
      "reasonCode": "provisioning_pending",
      "severity": "info",
      "actionability": "wait",
      "guidance": "wait",
      "operation": { "type": "create", "state": "queued" },
      "actions": { "edit": true, "delete": true, "start": false, "stop": false, "reboot": false, "snapshot": false, "firewall": false, "reverseDns": false }
    }
  }
}

Creates currently record control-plane state only. They do not provision a VPS, allocate an IP, attach physical storage, or deploy a network route.

Idempotency

All Phase 2 resource mutations require an Idempotency-Key header. The key is scoped to the authenticated project, method, and route.

Idempotency-Key: example-request-key

Reusing a key with the same canonical JSON request replays the original response. Reusing it with a different request returns 409 idempotency_conflict. Mutation errors use the standard JSON error model and responses are marked no-store.

Request IDs

Request identifiers are planned for troubleshooting and support.

X-Request-ID: req_example

Potential uses:

API Reference Status Matrix

Compact overview of resource reference and implementation status:

Inspect the actual shared project status data. If existing status values differ, use the project's real shared status configuration. Do not create contradictory hardcoded statuses.

REST API guide

This page complements rather than replaces the REST API guide:

Do not duplicate full article content.

SDKs and tooling

The conceptual relationship between tooling and the API:

Application
→ SDK / CLI / Terraform
→ StrataGateway REST API
→ Control Plane

Link to verified routes:

Next steps