Skip to main content

API Overview

The Cirrostratus API is a RESTful interface that provides programmatic access to all Cirrostratus services. Everything you can do through the dashboard can be automated through our API.

Base URL​

All API requests should be made to:

https://api.cirrosys.com/v1

Authentication​

All API requests require authentication using an API key. You can create and manage API keys in your dashboard.

Using API Keys​

Include your API key in the Authorization header:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.cirrosys.com/v1/instances

API Key Best Practices​

  • Never share your API keys in public repositories
  • Use environment variables to store keys
  • Rotate keys regularly for security
  • Use separate keys for different environments

Rate Limits​

API requests are rate limited to ensure fair usage:

  • Standard: 1,000 requests per hour
  • Pro: 10,000 requests per hour
  • Enterprise: Custom limits

Rate limit information is included in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Common Endpoints​

Compute​

List Instances​

GET /v1/instances

Create Instance​

POST /v1/instances
Content-Type: application/json

{
  "name": "web-server-01",
  "type": "m5.large",
  "region": "us-east-1",
  "image": "ubuntu-22.04"
}

Storage​

List Volumes​

GET /v1/volumes

Create Volume​

POST /v1/volumes
Content-Type: application/json

{
  "name": "data-volume-01",
  "size": 100,
  "type": "ssd",
  "region": "us-east-1"
}

Networking​

List Networks​

GET /v1/networks

Create VPC​

POST /v1/networks/vpc
Content-Type: application/json

{
  "name": "production-vpc",
  "cidr": "10.0.0.0/16",
  "region": "us-east-1"
}

Response Format​

All API responses return JSON with the following structure:

Success Response​

{
  "status": "success",
  "data": {
    // Response data
  },
  "meta": {
    "request_id": "req_123456",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Error Response​

{
  "status": "error",
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid instance type specified",
    "details": {
      "field": "type",
      "value": "invalid.type"
    }
  },
  "meta": {
    "request_id": "req_123456",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Error Codes​

CodeDescription
INVALID_REQUESTRequest validation failed
UNAUTHORIZEDInvalid or missing API key
FORBIDDENInsufficient permissions
NOT_FOUNDResource not found
RATE_LIMITEDRate limit exceeded
SERVER_ERRORInternal server error

Pagination​

List endpoints support pagination using limit and offset parameters:

GET /v1/instances?limit=20&offset=40

Paginated responses include metadata:

{
  "data": [...],
  "meta": {
    "total": 100,
    "limit": 20,
    "offset": 40,
    "has_more": true
  }
}

Filtering​

Most list endpoints support filtering:

# Filter by status
GET /v1/instances?status=running

# Filter by region
GET /v1/instances?region=us-east-1

# Multiple filters
GET /v1/instances?status=running&region=us-east-1&type=m5.large

SDKs​

Official SDKs are available for popular languages:

Python​

pip install cirrostratus
import cirrostratus

client = cirrostratus.Client(api_key="YOUR_API_KEY")
instances = client.instances.list()

JavaScript/Node.js​

npm install @cirrostratus/sdk
const Cirrostratus = require('@cirrostratus/sdk');

const client = new Cirrostratus({ apiKey: 'YOUR_API_KEY' });
const instances = await client.instances.list();

Go​

go get git.cirrosys.com/cirrosys/cirrostratus-go
import "git.cirrosys.com/cirrosys/cirrostratus-go"

client := cirrostratus.NewClient("YOUR_API_KEY")
instances, err := client.Instances.List()

Webhooks​

Configure webhooks to receive real-time notifications:

POST /v1/webhooks
Content-Type: application/json

{
  "url": "https://your-app.com/webhooks/cirrostatus",
  "events": ["instance.created", "instance.deleted"],
  "secret": "your-webhook-secret"
}

API Changelog​

Stay updated with API changes:

  • v1.2.0 (2024-01-15): Added Kubernetes API endpoints
  • v1.1.0 (2023-12-01): Added filtering support
  • v1.0.0 (2023-10-01): Initial release

Need Help?​

API Playground

Try out API calls directly in your browser using our API Playground.