API Reference

Programmatic access to the CapaCloud platform

Overview

CapaCloud provides a REST API for programmatic access to the platform. All API endpoints are prefixed with /api.

Authentication

Most API endpoints require wallet authentication. Include your wallet address in requests as specified by each endpoint.

Endpoints

Authentication

POST /api/auth/login- Login/register with wallet

GET /api/auth/user- Get user information

Account

GET /api/account/balance- Get account balance

POST /api/account/balance- Top up or claim balance

GET /api/account/settings- Get account settings

PUT /api/account/settings- Update account settings

Machines

GET /api/machines/list- List available machines

GET /api/machines/pending- List pending machines

POST /api/machines/register- Register a machine

GET /api/machines/[machineId]- Get machine details

GET /api/machines/check-active-rentals- Check for active rentals

Rentals

GET /api/rentals/list- List user rentals

POST /api/rentals/create- Create a rental

GET /api/rentals/[rentalId]- Get rental details

PATCH /api/rentals/[rentalId]- Update rental (pause/resume/stop)

POST /api/rentals/[rentalId]/console- Execute console command

Worker

POST /api/worker/register- Register worker (heartbeat)

Example Requests

Get Account Balance

GET /api/account/balance?walletAddress=YOUR_WALLET_ADDRESS

List Available Machines

GET /api/machines/list

Create Rental

POST /api/rentals/create
{
  "machineId": "machine_id",
  "renterWalletAddress": "wallet_address"
}

Response Format

All API responses follow a consistent format:

{
  "success": true,
  "data": { ... },
  "error": null
}

Error Handling

Errors are returned with appropriate HTTP status codes:

400

Bad Request (missing/invalid parameters)

401

Unauthorized (wallet not connected)

403

Forbidden (insufficient permissions)

404

Not Found

500

Internal Server Error

Rate Limiting

API rate limiting may apply to prevent abuse. Contact support if you need higher limits.