Skip to content

api-reference.md

Latest commit

 

History

History
1132 lines (878 loc) · 20.2 KB

api-reference.md

File metadata and controls

1132 lines (878 loc) · 20.2 KB

API Reference

Authentication

Rate Limiting: Auth endpoints are rate-limited to 5 requests per minute per IP to prevent brute-force attacks.

POST /auth/register

Register a new user account.

Request:

{
  "email": "user@example.com",
  "password": "password",
  "name": "User Name"
}

Response:

{
  "message": "user created successfully",
  "user_id": "uuid"
}

POST /auth/login

Login to obtain an API Key.

Request:

{
  "email": "user@example.com",
  "password": "password"
}

Response:

{
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "name": "User Name"
  },
  "api_key": "thecloud_xxxxx"
}

POST /auth/forgot-password

Request a password reset token (rate limited: 5 requests/minute).

Request:

{
  "email": "user@example.com"
}

Response:

{
  "message": "If the email exists, a reset token has been sent."
}

POST /auth/reset-password

Reset password using a valid token (rate limited: 5 requests/minute).

Request:

{
  "token": "reset-token-from-email",
  "new_password": "new-secure-password"
}

Response:

{
  "message": "password updated successfully"
}

API Key Management

Headers Required: X-API-Key: <your-api-key>

POST /auth/keys

Create a new API key.

Request:

{
  "name": "Production Key"
}

Response:

{
  "id": "uuid",
  "user_id": "user-uuid",
  "name": "Production Key",
  "key": "thecloud_xxxxx",
  "created_at": "2026-01-05T23:00:00Z",
  "last_used": "2026-01-05T23:00:00Z"
}

GET /auth/keys

List all API keys for the authenticated user.

DELETE /auth/keys/:id

Revoke an API key.

POST /auth/keys/:id/rotate

Rotate an API key (creates new key, deletes old one).

POST /auth/keys/:id/regenerate

Regenerate an API key (alias for rotate).

Tenants & Organizations 🆕

Headers Required: X-API-Key: <your-api-key>

GET /tenants

List all tenants (organizations) the authenticated user belongs to.

POST /tenants

Create a new tenant. Request:

{
  "name": "Acme Corp",
  "slug": "acme"
}

POST /tenants/:id/switch

Switch the user's active/default tenant. This affects which resources are visible in subsequent requests.

POST /tenants/:id/members

Add a new member to a tenant. Request:

{
  "user_id": "uuid",
  "role": "member"
}

System Health

GET /health/live

Liveness probe. Returns 200 OK if the process is running. Response: {"status": "ok"}

GET /health/ready

Readiness probe. Checks connections to Database and Docker daemon. Response (200 OK):

{
  "status": "UP",
  "checks": { "database": "CONNECTED", "docker": "CONNECTED" },
  "time": "..."
}

Response (503 Service Unavailable):

{
  "status": "DEGRADED",
  "checks": { "database": "DISCONNECTED", ... }
}

Compute Instances

Headers Required: X-API-Key: <your-api-key>

GET /instances

List all instances owned by the authenticated user.

POST /instances

Launch a new instance.

{
  "name": "web-01",
  "image": "nginx",
  "instance_type": "basic-2",
  "vpc_id": "vpc-uuid",
  "subnet_id": "subnet-uuid",
  "ports": "80:80",
  "volumes": [
    { "volume_id": "vol-uuid", "mount_path": "/data" }
  ]
}

GET /instance-types

List all available instance types. Response:

[
  {
    "id": "basic-2",
    "name": "Basic 2",
    "vcpus": 1,
    "memory_mb": 1024,
    "disk_gb": 10,
    "network_mbps": 1000,
    "price_per_hour": 0.02,
    "category": "general-purpose"
  }
]

GET /instances/:id

Get details of a specific instance.

PUT /instances/:id

Update instance (e.g., status).

DELETE /instances/:id

Terminate an instance.

GET /instances/:id/console

Get the VNC console URL for the instance. Response:

{
  "console_url": "vnc://127.0.0.1:5901"
}

Networks (VPC)

Headers Required: X-API-Key: <your-api-key>

GET /vpcs

List all VPCs.

POST /vpcs

Create a new VPC.

{
  "name": "prod-vpc"
}

DELETE /vpcs/:id

Delete a VPC.

VPC Peering 🆕

Headers Required: X-API-Key: <your-api-key>

GET /vpc-peerings

List all VPC peering connections for the tenant.

POST /vpc-peerings

Initiate a new VPC peering request.

{
  "requester_vpc_id": "uuid",
  "accepter_vpc_id": "uuid"
}

Response (201 Created):

{
  "id": "uuid",
  "status": "pending-acceptance",
  "requester_vpc_id": "uuid",
  "accepter_vpc_id": "uuid",
  "arn": "arn:thecloud:vpc-peering:..."
}

GET /vpc-peerings/:id

Get details of a specific peering connection.

POST /vpc-peerings/:id/accept

Accept a pending peering request. This activates cross-bridge routing via OVS.

POST /vpc-peerings/:id/reject

Reject a pending peering request.

DELETE /vpc-peerings/:id

Delete a peering connection and remove all associated network routes.

Security Groups

Headers Required: X-API-Key: <your-api-key>

GET /security-groups

List all security groups. Query params: ?vpc_id=<vpc-uuid> (required)

POST /security-groups

Create a new security group.

{
  "vpc_id": "vpc-uuid",
  "name": "web-tier",
  "description": "Port 80 and 443 allowed"
}

GET /security-groups/:id

Get details and rules for a security group.

DELETE /security-groups/:id

Delete a security group.

POST /security-groups/:id/rules

Add a firewall rule.

{
  "direction": "ingress",
  "protocol": "tcp",
  "port_min": 80,
  "port_max": 80,
  "cidr": "0.0.0.0/0",
  "priority": 100
}

DELETE /security-groups/rules/:rule_id

Remove a firewall rule.

POST /security-groups/attach

Attach a security group to an instance.

{
  "instance_id": "inst-uuid",
  "group_id": "sg-uuid"
}

POST /security-groups/detach

Detach a security group from an instance.

{
  "instance_id": "inst-uuid",
  "group_id": "sg-uuid"
}

Subnets

Headers Required: X-API-Key: <your-api-key>

GET /vpcs/:vpc_id/subnets

List all subnets in a VPC.

POST /vpcs/:vpc_id/subnets

Create a new subnet.

{
  "name": "private-subnet-1",
  "cidr_block": "10.0.1.0/24",
  "availability_zone": "us-east-1a"
}

GET /subnets/:id

Get details of a specific subnet.

DELETE /subnets/:id

Delete a subnet.

Elastic IPs (Static IPs) 🆕

Headers Required: X-API-Key: <your-api-key>

GET /elastic-ips

List all allocated elastic IPs for the tenant.

POST /elastic-ips

Allocate a new elastic IP. No body required. Response:

{
  "id": "uuid",
  "public_ip": "100.64.x.y",
  "status": "allocated",
  "arn": "arn:thecloud:vpc:local:tenant:eip/uuid"
}

GET /elastic-ips/:id

Get details of a specific elastic IP.

DELETE /elastic-ips/:id

Release an elastic IP back to the pool. Fails if still associated.

POST /elastic-ips/:id/associate

Associate an elastic IP with a compute instance. Request:

{
  "instance_id": "inst-uuid"
}

POST /elastic-ips/:id/disassociate

Disassociate an elastic IP from its current instance.

Pipelines (CI/CD) 🆕

Headers Required: X-API-Key: <your-api-key> for protected endpoints.

GET /pipelines

List pipelines for the authenticated user.

POST /pipelines

Create a pipeline definition.

{
  "name": "lint-thecloud",
  "repository_url": "https://github.com/poyrazK/thecloud.git",
  "branch": "main",
  "webhook_secret": "your-secret",
  "config": {
    "stages": [
      {
        "name": "lint",
        "steps": [
          {
            "name": "golangci",
            "image": "golang:1.24",
            "commands": [
              "git clone https://github.com/poyrazK/thecloud.git /workspace/thecloud",
              "cd /workspace/thecloud",
              "go install github.com/golangci/golangci-lint/cmd/golangci-lint@v1.60.3",
              "/go/bin/golangci-lint run ./..."
            ]
          }
        ]
      }
    ]
  }
}

GET /pipelines/:id

Get a pipeline by ID.

PUT /pipelines/:id

Update mutable fields of a pipeline.

DELETE /pipelines/:id

Delete a pipeline.

POST /pipelines/:id/runs

Trigger a manual run.

{
  "commit_hash": "abc123",
  "trigger_type": "MANUAL"
}

GET /pipelines/:id/runs

List runs for a pipeline.

GET /pipelines/runs/:buildID

Get run details.

GET /pipelines/runs/:buildID/steps

List step results for a run.

GET /pipelines/runs/:buildID/logs?limit=200

List logs for a run.

POST /pipelines/:id/webhook/:provider

Public webhook trigger endpoint.

  • provider: github or gitlab
  • No API key required (validated by webhook secret/signature).

GitHub headers

  • X-GitHub-Event (supported: push)
  • X-Hub-Signature-256 (HMAC SHA-256)
  • X-GitHub-Delivery (used for idempotency)

GitLab headers

  • X-Gitlab-Event (supported: Push Hook)
  • X-Gitlab-Token
  • X-Gitlab-Event-UUID (used for idempotency)

Webhook response behavior

  • 202 accepted with build payload when a run is queued.
  • 202 accepted with { "status": "ignored" } for duplicate/non-matching events.

Cloud Storage (S3-Compatible)

Headers Required: X-API-Key: <your-api-key>

GET /storage/buckets

List all buckets owned by or accessible to the tenant.

POST /storage/buckets

Create a new storage bucket.

{
  "name": "my-assets",
  "is_public": false
}

DELETE /storage/buckets/:bucket

Delete a bucket. Fails if the bucket is not empty unless ?force=true is provided.

PATCH /storage/buckets/:bucket/versioning

Enable or disable versioning for a bucket.

{
  "enabled": true
}

GET /storage/:bucket

List all objects in a bucket (latest versions only).

PUT /storage/:bucket/*key

Upload an object. The request body is the raw file data. Response:

{
  "id": "uuid",
  "bucket": "my-bucket",
  "key": "test.txt",
  "size_bytes": 1024,
  "content_type": "text/plain",
  "checksum": "sha256-hex-hash",
  "upload_status": "AVAILABLE",
  "version_id": "null",
  "created_at": "2026-03-04T17:00:00Z"
}

GET /storage/:bucket/*key

Download an object (latest version).

DELETE /storage/:bucket/*key

Soft-delete an object (latest version).

GET /storage/versions/:bucket/*key

List all versions of a specific object.

GET /storage/cluster/status

Get health and node status of the distributed storage cluster.

Multipart Uploads

POST /storage/multipart/init/:bucket/*key

Initiate a multipart upload session. Response: {"id": "upload-uuid", ...}

PUT /storage/multipart/upload/:id/parts?part=1

Upload a part for a multipart session.

POST /storage/multipart/complete/:id

Finalize a multipart upload and assemble the object.

DELETE /storage/multipart/abort/:id

Abort a multipart upload and clean up uploaded parts.

Lifecycle Rules

GET /storage/buckets/:bucket/lifecycle

List lifecycle rules for a bucket.

POST /storage/buckets/:bucket/lifecycle

Create a new lifecycle rule.

{
  "prefix": "logs/",
  "expiration_days": 30
}

DELETE /storage/buckets/:bucket/lifecycle/:id

Delete a lifecycle rule.

DELETE /elastic-ips/:id

Release an elastic IP back to the pool. Fails if still associated.

POST /elastic-ips/:id/associate

Associate an elastic IP with a compute instance. Request:

{
  "instance_id": "inst-uuid"
}

POST /elastic-ips/:id/disassociate

Disassociate an elastic IP from its current instance.

Volumes

Headers Required: X-API-Key: <your-api-key>

GET /volumes

List all volumes.

POST /volumes

Create a new volume.

{
  "name": "data-vol",
  "size_gb": 10
}

Managed Databases (RDS)

Headers Required: X-API-Key: <your-api-key>

GET /databases

List all managed databases.

POST /databases

Provision a new primary database.

{
  "name": "prod-db",
  "engine": "postgres",
  "version": "16",
  "vpc_id": "vpc-uuid",
  "allocated_storage": 20,
  "pooling_enabled": true,
  "metrics_enabled": true,
  "parameters": {
    "max_connections": "100"
  }
}

GET /databases/:id

Get details of a specific database.

PATCH /databases/:id

Modify an existing database configuration.

{
  "allocated_storage": 40,
  "pooling_enabled": false,
  "metrics_enabled": true,
  "parameters": {
    "max_connections": "200"
  }
}

DELETE /databases/:id

Terminate a database instance.

GET /databases/:id/connection

Get the connection string for the database.

POST /databases/:id/replicas

Create a read-replica for a primary database.

{
  "name": "prod-db-replica-1"
}

POST /databases/:id/promote

Promote a replica to a standalone primary database.

Global Load Balancers 🆕

Headers Required: X-API-Key: <your-api-key>

GET /global-lb

List all global load balancers owned by the authenticated user.

POST /global-lb

Create a new global load balancer.

{
  "name": "api-global",
  "hostname": "api.myapp.com",
  "policy": "LATENCY",
  "health_check": {
    "protocol": "HTTP",
    "port": 80,
    "path": "/health"
  }
}

GET /global-lb/:id

Get details of a GLB including its endpoints.

DELETE /global-lb/:id

Delete a global load balancer and its DNS records. Only the owner can delete the resource.

POST /global-lb/:id/endpoints

Add a regional endpoint to the GLB.

{
  "region": "us-east-1",
  "target_type": "IP",
  "target_ip": "1.2.3.4",
  "weight": 100
}

DELETE /global-lb/:id/endpoints/:epID

Remove an endpoint from the GLB.

Auto-Scaling Groups

Headers Required: X-API-Key: <your-api-key>

GET /autoscaling/groups

List auto-scaling groups.

POST /autoscaling/groups

Create an ASG.

Cloud Gateway

Headers Required: X-API-Key: <your-api-key>

GET /routes

List all registered routes.

POST /routes

Register a new gateway route. Supports advanced pattern matching and HTTP method filtering.

Request:

{
  "name": "users-api",
  "path_prefix": "/users/{id}",
  "target_url": "http://user-service:8080",
  "methods": ["GET", "PUT"],
  "strip_prefix": true,
  "priority": 10
}

Fields:

  • path_prefix: The pattern to match (e.g., /api/*, /users/{id}, /id/{id:[0-9]+}).
  • methods: Array of allowed HTTP methods (empty/null = all).
  • priority: Higher values take precedence when multiple patterns match.
  • strip_prefix: If true, the matched part of the path is removed before forwarding.

Extracted Parameters: Matched parameters like {id} are made available to downstream services as headers (in the future) and are currently injected into the gateway context.

DELETE /routes/:id

Remove a route.

Cloud Functions

Headers Required: X-API-Key: <your-api-key>

GET /functions

List all deployed functions.

POST /functions

Create a new function.

{
  "name": "hello-world",
  "runtime": "nodejs20",
  "code_zip": "<base64>"
}

POST /functions/:id/invoke

Invoke a function.

{
  "payload": { "foo": "bar" },
  "async": false
}

GET /functions/:id/logs

Get execution logs.

CloudLogs (Persistent Logs) 🆕

Headers Required: X-API-Key: <your-api-key>

GET /logs

Search and filter historical platform logs.

Query Parameters:

  • resource_id: Filter by specific resource UUID.
  • resource_type: Filter by type (instance, function).
  • level: Filter by severity (INFO, WARN, ERROR).
  • search: Keyword search in log messages.
  • start_time: RFC3339 start timestamp.
  • end_time: RFC3339 end timestamp.
  • limit: Max results (default 100).
  • offset: Pagination offset.

GET /logs/:resource_id

Get historical logs for a specific resource.

Parameters:

Name In Type Required Description
resource_id path string Yes The UUID of the resource (instance or function)
limit query integer No Max logs to return

Example:

curl -H "X-API-Key: $API_KEY" http://api.thecloud.local/logs/a1b2c3d4-5678-90ab-cdef-1234567890ab?limit=10

Cloud Cache (Redis)

Headers Required: X-API-Key: <your-api-key>

GET /caches

List all cache instances.

POST /caches

Provision a new Redis cache.

{
  "name": "my-cache",
  "memory_mb": 256
}

DELETE /caches/:id

Terminate a cache instance.

Cloud Queue

Headers Required: X-API-Key: <your-api-key>

GET /queues

List all queues.

POST /queues

Create a new message queue.

{
  "name": "task-queue",
  "visibility_timeout": 30
}

POST /queues/:id/messages

Send a message.

{
  "body": "payload-data"
}

GET /queues/:id/messages

Receive messages. Query params: ?count=1

Cloud Notify (Pub/Sub)

Headers Required: X-API-Key: <your-api-key>

GET /topics

List topics.

POST /topics

Create a new topic.

POST /subscriptions

Subscribe to a topic.

{
  "topic_id": "uuid",
  "protocol": "webhook",
  "endpoint": "http://my-api/hook"
}

Cloud Cron

Headers Required: X-API-Key: <your-api-key>

GET /cron

List scheduled jobs.

POST /cron

Create a scheduled job.

{
  "name": "daily-cleanup",
  "schedule": "0 0 * * *",
  "target_url": "http://my-service/cleanup"
}

POST /cron/:id/pause

Pause a job.

POST /cron/:id/resume

Resume a job.

Cloud IAM (Policies) 🆕

Headers Required: X-API-Key: <your-api-key> Constraint: These endpoints require PermissionFullAccess (Admin).

GET /iam/policies

List all IAM policies.

POST /iam/policies

Create a new granular IAM policy.

{
  "name": "ReadOnlyS3",
  "statements": [
    {
      "effect": "Allow",
      "action": ["storage:list", "storage:get"],
      "resource": ["*"]
    }
  ]
}

GET /iam/policies/:id

Get details of a specific policy.

DELETE /iam/policies/:id

Delete a policy.

POST /iam/users/:userId/policies/:policyId

Attach a policy to a specific user.

DELETE /iam/users/:userId/policies/:policyId

Detach a policy from a user.

GET /iam/users/:userId/policies

List all policies attached to a specific user.

Accounting & Billing 🆕

Headers Required: X-API-Key: <your-api-key>

GET /billing/summary

Get billing summary for the current period.

Response:

{
  "period_start": "2026-01-01T00:00:00Z",
  "period_end": "2026-01-31T23:59:59Z",
  "total_amount": 150.25,
  "currency": "USD",
  "usage_by_type": {
    "compute": 45.50,
    "storage": 12.75,
    "database": 92.00
  }
}

GET /billing/usage

List detailed usage records.

Audit Logs 🆕

Headers Required: X-API-Key: <your-api-key>

GET /audit

List platform audit logs for the authenticated user/tenant.

Query Parameters:

  • limit: Max results (default 50).

Response:

[
  {
    "id": "uuid",
    "timestamp": "2026-01-05T23:00:00Z",
    "actor": "user@example.com",
    "action": "INSTANCE_LAUNCH",
    "resource": "instance/a1b2c3d4",
    "status": "success",
    "ip_address": "1.2.3.4"
  }
]

Managed Kubernetes (KaaS)

Headers Required: X-API-Key: <your-api-key>

GET /clusters

List all Kubernetes clusters.

POST /clusters

Create a new Kubernetes cluster (Asynchronous).

{
  "name": "my-cluster",
  "vpc_id": "vpc-uuid",
  "version": "v1.29.0",
  "workers": 3,
  "ha": true
}

GET /clusters/:id

Get detailed information and status.

DELETE /clusters/:id

Delete a cluster (Asynchronous).

GET /clusters/:id/kubeconfig

Download the admin kubeconfig.

GET /clusters/:id/health

Get operational health (nodes ready, api server reachability).

POST /clusters/:id/upgrade

Upgrade cluster version (Asynchronous).

{
  "version": "v1.30.0"
}

POST /clusters/:id/scale

Scale worker nodes.

{
  "workers": 5
}

POST /clusters/:id/repair

Re-run bootstrap scripts on nodes.

POST /clusters/:id/backups

Trigger an etcd backup.

POST /clusters/:id/restore

Restore etcd state from path.

{
  "backup_path": "/backups/etcd-snapshot.db"
}

Error Codes

Status Code Description
200/201 Success
400 Bad Request (Invalid input)
401 Unauthorized (Missing/Invalid API Key)
403 Forbidden (Access denied to resource)
404 Not Found
429 Too Many Requests (Rate limit exceeded)
500 Internal Server Error