API Reference

Complete reference documentation for the Cloudheed API.

Base URL

https://api.cloudheed.com

Authentication

All API requests require authentication via Bearer token:

curl https://api.cloudheed.com/v1/databases \
  -H "Authorization: Bearer YOUR_TOKEN"

Rate Limits

Plan	Requests/minute	Requests/day
Free	60	1,000
Pro	1,000	100,000
Enterprise	10,000	Unlimited

Rate limit headers are included in every response:

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

Request Format

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

Response Format

Success Response

{
  "data": { ... },
  "meta": {
    "request_id": "req-abc123"
  }
}

Error Response

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request parameters",
    "details": [
      {
        "field": "name",
        "message": "Name must be at least 3 characters"
      }
    ]
  },
  "meta": {
    "request_id": "req-abc123"
  }
}

HTTP Status Codes

Code	Description
`200`	OK - Request successful
`201`	Created - Resource created
`204`	No Content - Resource deleted
`400`	Bad Request - Invalid syntax
`401`	Unauthorized - Invalid or missing token
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Resource doesn't exist
`409`	Conflict - Resource already exists
`422`	Unprocessable Entity - Validation error
`429`	Too Many Requests - Rate limited
`500`	Internal Server Error

Error Codes

Code	Description
`invalid_token`	Token is invalid or expired
`insufficient_permissions`	Token lacks required scopes
`validation_error`	Request failed validation
`resource_not_found`	Requested resource doesn't exist
`resource_conflict`	Resource already exists
`rate_limit_exceeded`	Too many requests
`payment_required`	Account requires payment
`maintenance_mode`	API temporarily unavailable

Pagination

List endpoints support pagination:

curl "https://api.cloudheed.com/v1/databases?page=1&per_page=20" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response includes pagination metadata:

{
  "data": [...],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 45,
    "total_pages": 3
  }
}

Versioning

The API is versioned via URL path:

Current: v1
All endpoints use /v1/ prefix

SDKs

Official SDKs are available:

Node.js: npm install @cloudheed/sdk
Python: pip install cloudheed
Go: go get github.com/cloudheed/cloudheed-go

Team Management Authentication