REST API

Overview

The StrataGateway REST API is being designed around resource-oriented endpoints, predictable HTTP semantics, and JSON request and response bodies.

Base URL

https://api.stratagateway.com/v1

The final production API hostname and versioning strategy may change before public release. Do not interpret this endpoint as currently available.

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 "https://api.stratagateway.com/v1/instances" \
  -H "Authorization: Bearer $STRATA_API_TOKEN"

Request format

All request bodies use JSON. Include the following headers:

Content-Type: application/json
Accept: application/json

Illustrative request body for creating an instance:

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

The example above is illustrative. Field names, types, and requirements may change before public release.

Resource model

The API follows a resource-oriented structure. Planned resource collections include:

Resources are identified by prefixed IDs. The format below is illustrative.

Not every resource exists today. Respect the documentation status badges on individual resource documentation pages.

Creating an instance

Provision a new compute instance using the planned instances collection.

curl -X POST "https://api.stratagateway.com/v1/instances" \
  -H "Authorization: Bearer $STRATA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web-prod-01",
    "region": "fra-1",
    "plan": "compute-standard",
    "image": "ubuntu-24.04-lts",
    "ssh_keys": ["key_8f3a9b1c"]
  }'

Illustrative response preview

{
  "id": "inst_7a91c2",
  "name": "web-prod-01",
  "status": "provisioning",
  "region": "fra-1",
  "plan": "compute-standard",
  "image": "ubuntu-24.04-lts"
}

Retrieving resources

List all instances or retrieve a single instance by its identifier.

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

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

{
  "id": "inst_7a91c2",
  "name": "web-prod-01",
  "status": "running",
  "region": "fra-1",
  "ipv4": "203.0.113.10"
}

Updating resources

Partial updates are planned using PATCH. The set of editable fields is still being finalized.

curl -X PATCH "https://api.stratagateway.com/v1/instances/inst_7a91c2" \
  -H "Authorization: Bearer $STRATA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web-prod-primary"
  }'

Deleting resources

Delete an instance by its identifier.

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

Errors

The API is planned to return a consistent error structure:

{
  "error": {
    "code": "validation_error",
    "message": "The region field is required.",
    "request_id": "req_91ab3c"
  }
}

Example HTTP status codes (illustrative):

The error schema is not finalized and may change before public release.

Pagination

List endpoints are expected to use cursor-based pagination:

GET /v1/instances?limit=50&cursor=...

Illustrative response

{
  "data": [],
  "pagination": {
    "next_cursor": "cursor_example",
    "has_more": false
  }
}

Final pagination semantics are still under development.

Rate limits

The control plane enforces technical rate limits to protect reliability and prevent abuse. These are internal safety controls, not customer resource quotas or a commercial request allowance.

Idempotency

Infrastructure creation endpoints are intended to support idempotency keys to prevent accidental duplicate resource creation on retries.

Idempotency-Key: deploy-web-prod-01

Repeated requests using the same key are intended to return the original response without creating additional infrastructure. This behavior is planned and not yet implemented.

API versioning

The preview API path uses explicit versioning:

/v1

API versioning is intended to allow the platform to evolve without silently breaking integrations. Breaking changes will be introduced in new versions. Indefinite backwards compatibility is not guaranteed.

SDK and tooling

Planned developer tooling integrates with the REST API:

Next steps