API Reference

Introduction

The Aureus REST API allows you to programmatically interact with your infrastructure. All API endpoints are served under https://aureus.cx/api/v1 and return JSON responses.

The API is scoped — each key has a set of permissions that control what it can read or modify. Keys are generated per account and tied to the user who created them.

Versioning

The current version is v1. Version is included in the URL path. Breaking changes will be introduced in a new version (/api/v2) with advance notice.

Endpoints at a glance

Authentication

All API requests must include a valid API key in the Authorization header using the Bearer scheme.

Authorization: Bearer ak_live_YOUR_KEY_HERE

API keys start with ak_live_. Requests with a missing or invalid key will receive a 401 Unauthorized response.

Generating a key

You can generate API keys from your dashboard. Each key can be given a name (e.g., "CI/CD", "Terraform") and a set of scopes that limit what the key can access.

Scopes

Each key is granted one or more scopes. API calls will return 403 Forbidden if the key lacks the required scope.

Clusters

A cluster is a dedicated managed PostgreSQL + application runtime environment. Each cluster has a tier (S, M, L), a region, and a set of applications deployed on it.

List clusters

Returns all clusters owned by the authenticated user.

curl -s https://aureus.cx/api/v1/clusters \
  -H "Authorization: Bearer ak_live_..." | jq .

{
  "data": [
    {
      "id": "2ef4a1bc-...",
      "name": "production-01",
      "tier": "cluster_m",
      "status": "active",
      "region": "Frankfurt, DE",
      "ip_address": "5.78.147.161",
      "created_at": "2025-03-14T10:00:00.000Z",
      "updated_at": "2025-05-01T09:22:33.000Z"
    }
  ]
}

Get cluster

Returns a single cluster by ID, including a list of applications deployed on it.

curl -s https://aureus.cx/api/v1/clusters/2ef4a1bc-... \
  -H "Authorization: Bearer ak_live_..."

{
  "data": {
    "id": "2ef4a1bc-...",
    "name": "production-01",
    "tier": "cluster_m",
    "status": "active",
    "region": "Frankfurt, DE",
    "ip_address": "5.78.147.161",
    "notes": null,
    "applications": [
      { "id": "...", "name": "api-service", "status": "running" },
      { "id": "...", "name": "web-frontend", "status": "running" }
    ],
    "created_at": "2025-03-14T10:00:00.000Z",
    "updated_at": "2025-05-01T09:22:33.000Z"
  }
}

Apps

Applications represent deployable units running on a cluster. Each app belongs to exactly one cluster and inherits its tier limits.

List apps

curl -s https://aureus.cx/api/v1/apps \
  -H "Authorization: Bearer ak_live_..."

Get app

Create app

Required fields: cluster_id, name, tech_stack.

curl -s -X POST https://aureus.cx/api/v1/apps \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "cluster_id": "2ef4a1bc-...",
    "name": "my-api",
    "tech_stack": "Node.js",
    "repo_url": "https://github.com/acme/my-api",
    "branch": "main",
    "build_pack": "nixpacks"
  }'

{
  "data": {
    "id": "7a2b3c4d-...",
    "cluster_id": "2ef4a1bc-...",
    "name": "my-api",
    "status": "pending",
    "tech_stack": "Node.js",
    "slug": "my-api-aBcDeF",
    "branch": "main",
    "build_pack": "nixpacks",
    "base_directory": "/",
    "is_static_site": false,
    "aureus_domain_enabled": false,
    "domain": null,
    "created_at": "2026-03-14T12:00:00.000Z",
    "updated_at": "2026-03-14T12:00:00.000Z"
  }
}

Update app

Accepted fields: name, branch, build_pack, base_directory, is_static_site, description, app_notes, deployment_notes, repo_url.

curl -s -X PATCH https://aureus.cx/api/v1/apps/7a2b3c4d-... \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "branch": "release/v2.0" }'

Delete app

curl -s -X DELETE https://aureus.cx/api/v1/apps/7a2b3c4d-... \
  -H "Authorization: Bearer ak_live_..."

{ "data": { "deleted": true, "id": "7a2b3c4d-..." } }

Tickets

Support tickets allow you to open and track requests with the Aureus team directly from your automation pipelines.

List tickets

curl -s https://aureus.cx/api/v1/tickets \
  -H "Authorization: Bearer ak_live_..."

Get ticket

Returns the ticket along with any user comments and staff replies.

Create ticket

Required: title, body. Optional: category (billing | cluster_support | app_support | devops | security | addons | other), priority (low | medium | high).

curl -s -X POST https://aureus.cx/api/v1/tickets \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Deploy failed on main branch",
    "body": "The nixpacks build started failing after commit abc1234.",
    "category": "devops",
    "priority": "high"
  }'

Add comment

Required: body.

curl -s -X POST https://aureus.cx/api/v1/tickets/TICKET_ID/comments \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "body": "Confirmed — the error is in the build cache." }'

Errors

All errors follow a consistent JSON shape. The error field contains a human-readable description.

{
  "error": "Forbidden. This key does not have the read:clusters scope."
}

Status codes

Rate Limits

Rate limiting is not currently enforced, but we plan to introduce per-key limits in a future release (target: 100 requests/minute per API key).

If you hit our infrastructure unexpectedly hard during this period, your key may be temporarily suspended. Build your integrations with exponential backoff and reasonable request intervals.

Code Examples

A complete example showing how to list clusters using different clients.

# List your clusters
curl -s https://aureus.cx/api/v1/clusters \
  -H "Authorization: Bearer ak_live_YOUR_KEY" | jq .

Next steps

Once you have your key, try listing clusters to verify authentication is working. Then explore creating apps and tickets to integrate Aureus into your CI/CD pipelines and infrastructure-as-code workflows.