STACKS API Guide

Overview

The STACKS API lets you manage your containers programmatically. Use it to automate deployments, integrate with CI/CD pipelines, or give your AI agents access to infrastructure — all with built-in spending controls.

Base URL: https://api.stackshosting.cloud/api/v1

Authentication

All API requests require an API key passed in the Authorization header:

Authorization: Bearer sk_stacks_your_key_here

Creating an API Key

1. Log in to your STACKS dashboard
2. Go to Account Settings → API Keys
3. Click Create New Key
4. Enter a descriptive name (e.g., “CI/CD Pipeline”, “Agent Key”)
5. Select the permissions (scopes) your key needs
6. Optionally set a monthly spending cap
7. Click Create API Key

Important: Your API key is shown only once at creation. Copy it immediately and store it securely. You will not be able to view it again.

API Key Format

STACKS API keys follow this format:

sk_stacks_{64_character_hex_string}

Security Best Practices

• Never commit API keys to version control
• Never share API keys in chat, email, or public channels
• Use the minimum scopes required for your use case
• Set spending caps on keys used by automated systems
• Rotate keys regularly and revoke unused keys immediately
• Use separate keys for different applications or environments

Permissions (Scopes)

Each API key has specific permissions that control what it can access:

A key with only containers:read cannot create, modify, or delete containers. Attempting to use an endpoint that requires a scope your key doesn’t have will return a 403 Forbidden error.

What API Keys Cannot Access

API keys are restricted to container-related operations. The following endpoints require dashboard access (JWT authentication) and cannot be accessed via API key:

• Billing and payment management
• User account settings
• API key management (create/revoke keys from the dashboard only)
• Database browser
• File manager
• IP restriction management
• External access settings

Spending Caps

When creating an API key, you can set a monthly spending cap. This limits the total cost of containers created through that key in a given calendar month.

• If a create request would exceed the spending cap, the API returns 403 Forbidden with a clear error message
• Spending caps are per-key, not per-account — different keys can have different limits
• Spending resets at the beginning of each calendar month
• Setting no spending cap allows unlimited creation (subject to account limits)

Recommended: Always set a spending cap on keys given to automated systems or AI agents.

Rate Limiting

Each API key has a configurable rate limit (default: 60 requests per minute).

When rate limited, the API returns 429 Too Many Requests. Back off and retry after a short delay.

Endpoints

List Containers

Retrieve all containers associated with your account.

GET /containers

Required scope: containers:read

Example:

curl -H "Authorization: Bearer sk_stacks_YOUR_KEY" \
  https://api.stackshosting.cloud/api/v1/containers

PowerShell:

$headers = @{"Authorization"="Bearer sk_stacks_YOUR_KEY"}
Invoke-RestMethod -Uri "https://api.stackshosting.cloud/api/v1/containers" -Headers $headers

Response:

{
  "success": true,
  "count": 3,
  "data": [
    {
      "id": "usr-abc12345-myapp",
      "name": "myapp",
      "type": "nodejs",
      "plan": "basic",
      "status": "running",
      "cpu_allocated": 1,
      "memory_allocated": 1024,
      "storage_allocated": 10240,
      "ip_address": "10.52.0.5",
      "created_at": "2026-02-25T10:30:00.000Z"
    }
  ]
}

Get Container Status

Get detailed status for a specific container.

GET /containers/status/{container_id}

Required scope: containers:read

Example:

curl -H "Authorization: Bearer sk_stacks_YOUR_KEY" \
  https://api.stackshosting.cloud/api/v1/containers/status/usr-abc12345-myapp

Response includes: status, resource allocation, storage details, IP address, version info, and more.

Get Container Credentials

Retrieve connection credentials for a container.

GET /containers/{container_id}/credentials

Required scope: containers:read

Example:

curl -H "Authorization: Bearer sk_stacks_YOUR_KEY" \
  https://api.stackshosting.cloud/api/v1/containers/usr-abc12345-mydb/credentials

Note: Returns SSH credentials for compute containers and web UI credentials for managed services (PostgreSQL, Redis, MongoDB, etc.).

Get Container Logs

Retrieve recent logs from a container.

GET /containers/{container_id}/logs?lines=100

Required scope: containers:read

Parameters:

Get Container Metrics

Retrieve CPU, memory, disk, and network metrics.

GET /containers/{container_id}/metrics

Required scope: containers:read

Create Container

Create a new container.

POST /containers

Required scope: containers:create

Request body:

{
  "name": "my-api-server",
  "template": "nodejs",
  "plan": "basic"
}

Example:

curl -X POST \
  -H "Authorization: Bearer sk_stacks_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-api","template":"nodejs","plan":"basic"}' \
  https://api.stackshosting.cloud/api/v1/containers

PowerShell:

$headers = @{
  "Authorization" = "Bearer sk_stacks_YOUR_KEY"
  "Content-Type" = "application/json"
}
$body = '{"name":"my-api","template":"nodejs","plan":"basic"}'
Invoke-RestMethod -Method Post -Uri "https://api.stackshosting.cloud/api/v1/containers" -Headers $headers -Body $body

Response: Returns the created container details including ID, assigned port, SSH credentials (if applicable), and VPC network info.

Start / Stop / Restart Container

Update a container’s running state.

PUT /containers/{container_id}/status

Required scope: containers:manage

Request body:

{
  "status": "running"
}

Example:

curl -X PUT \
  -H "Authorization: Bearer sk_stacks_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"restart"}' \
  https://api.stackshosting.cloud/api/v1/containers/usr-abc12345-myapp/status

Delete Container

Permanently delete a container and all its data.

DELETE /containers/{container_id}

Required scope: containers:delete

Warning: This action is irreversible. All container data, volumes, and backups will be permanently removed.

Example:

curl -X DELETE \
  -H "Authorization: Bearer sk_stacks_YOUR_KEY" \
  https://api.stackshosting.cloud/api/v1/containers/usr-abc12345-myapp

Download SSH Certificate

Download the SSH private key for a container.

GET /containers/{container_id}/certificate

Required scope: containers:read

Note: Only available for compute containers (Ubuntu, Node.js, Python, etc.), not managed services.

Regenerate SSH Certificate

Generate a new SSH keypair for a container.

POST /containers/{container_id}/certificate/regenerate

Required scope: containers:manage

List Available Templates

Get all container templates.

GET /containers/templates

Required scope: containers:read

Container Connections

Connect containers within your VPC network.

List available targets:

GET /containers/{container_id}/available-targets

Create a connection:

POST /containers/{source_id}/connect/{target_id}

List connections:

GET /containers/{container_id}/connections

Delete a connection:

DELETE /connections/{connection_id}

Required scopes: containers:read for listing, containers:manage for creating/deleting.

Available Templates

Container Plans

All plans include VPC network isolation, per-minute billing (capped at monthly rate), and 3x data replication.

Error Codes

Common Error Responses

Invalid API key:

{
  "error": "Invalid API key"
}

Revoked API key:

{
  "error": "API key has been revoked"
}

Insufficient scope:

{
  "error": "Insufficient API key scope",
  "required": "containers:delete",
  "hint": "This key does not have the required scope. Create a new key with 'containers:delete' permission."
}

Spending cap exceeded:

{
  "error": "Spending cap exceeded",
  "spending_cap": 10,
  "monthly_spent": 9.50,
  "hint": "This API key's monthly spending limit has been reached."
}

Endpoint blocked for API keys:

{
  "error": "This endpoint requires dashboard access (JWT authentication)",
  "hint": "API keys can only access container, deployment, and monitoring endpoints.",
  "docs": "https://docs.stackshosting.cloud/api"
}

Common Workflows

Deploy an Application via API

# 1. Create a Node.js container
curl -X POST \
  -H "Authorization: Bearer sk_stacks_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-app","template":"nodejs","plan":"basic"}' \
  https://api.stackshosting.cloud/api/v1/containers

# 2. Check status (wait for "running")
curl -H "Authorization: Bearer sk_stacks_YOUR_KEY" \
  https://api.stackshosting.cloud/api/v1/containers/status/usr-YOUR_ID-my-app

# 3. Get SSH credentials
curl -H "Authorization: Bearer sk_stacks_YOUR_KEY" \
  https://api.stackshosting.cloud/api/v1/containers/usr-YOUR_ID-my-app/credentials

# 4. Deploy your code via SSH using the returned credentials

Connect App to Database

# 1. Create a PostgreSQL database
curl -X POST \
  -H "Authorization: Bearer sk_stacks_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-db","template":"postgresql","plan":"basic"}' \
  https://api.stackshosting.cloud/api/v1/containers

# 2. Connect your app container to the database
curl -X POST \
  -H "Authorization: Bearer sk_stacks_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' \
  https://api.stackshosting.cloud/api/v1/containers/usr-YOUR_ID-my-app/connect/usr-YOUR_ID-my-db

# 3. Restart your app to pick up the connection environment variables
curl -X PUT \
  -H "Authorization: Bearer sk_stacks_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"restart"}' \
  https://api.stackshosting.cloud/api/v1/containers/usr-YOUR_ID-my-app/status

AI Agent Workflow

Give your AI agent an API key with a spending cap:

1. Create an API key with containers:read, containers:create, containers:manage scopes and a $10/month spending cap
2. Pass the key to your agent
3. The agent can create containers, deploy code, and manage infrastructure
4. If the spending cap is reached, the API rejects further container creation — your agent can’t run up the bill
5. You get billed monthly as usual through your payment method

Revoking an API Key

1. Go to Account Settings → API Keys
2. Find the key you want to revoke
3. Click the revoke button (X icon)
4. Confirm the revocation

Revocation is immediate and permanent. Any system using the revoked key will instantly lose access. There is no way to un-revoke a key — create a new one instead.

Need Help?

• Support: support@stackshosting.cloud
• Documentation: https://docs.stackshosting.cloud
• Status Page: https://status.stackshosting.cloud