API Overview

The ShellHub API provides programmatic access to manage your clouds, agents, and chains. Use it for CI/CD pipelines, automation scripts, and custom integrations.

Dashboard First

Most users manage everything through the ShellHub Dashboard — no API or CLI needed. The API is optional and designed for automation, CI/CD pipelines, and building custom integrations.

// Base URL

https://api.shellhub.app/v1

All API requests must be made over HTTPS. Calls made over plain HTTP will be rejected.

// Authentication

Authenticate using Bearer tokens in the Authorization header:

curl https://api.shellhub.app/v1/clouds \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Security: Never expose your API key in client-side code. Always make API calls from your backend.

// Response Format

All responses are returned in JSON format:

{
  "success": true,
  "data": {
    "id": "cloud_abc123",
    "name": "my-cloud",
    "region": "us-east-1",
    "status": "running"
  },
  "meta": {
    "request_id": "req_xyz789",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

// Error Handling

Errors follow a consistent format:

{
  "success": false,
  "error": {
    "code": "CLOUD_NOT_FOUND",
    "message": "The specified cloud does not exist",
    "details": {
      "cloud_id": "cloud_invalid"
    }
  },
  "meta": {
    "request_id": "req_xyz789"
  }
}

HTTP Status Codes

Code	Meaning
`200`	Success
`201`	Created
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Resource doesn't exist
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error

// Rate Limits

Tier	Requests/min	Requests/day
Starter	60	10,000
Pro	300	100,000
Enterprise	1,000+	Unlimited

Rate limit headers are included in every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1705312800

// Official SDKs

Python

pip install shellhub

Available

Node.js

npm install @shellhub/sdk

Available

Go

go get github.com/shellhub/go-sdk

Coming Soon