API Reference

The Fugoku Cloud API is a RESTful JSON:API-compliant interface for managing compute, storage, networking, and platform resources programmatically.

Base URL

https://api.fugoku.com/v1

All API requests must use HTTPS. The local development base URL is http://localhost:3002/v1.

Authentication

The API supports two authentication methods:

JWT Bearer Token (Clerk)

Include the Clerk-issued JWT in the Authorization header:

  curl https://api.fugoku.com/v1/instances \
  -H "Authorization: Bearer $CLERK_JWT_TOKEN"

API Key

Include the API key in the X-Fugoku-API-Key header:

  curl https://api.fugoku.com/v1/instances \
  -H "X-Fugoku-API-Key: <generated-api-key>"

API keys are scoped to a project and can be managed in the Console under Settings → API Keys.

Response Format

All responses follow the JSON:API specification.

Success Response

{
  "data": {
    "id": "inst-abc123",
    "type": "instances",
    "attributes": {
      "name": "my-gpu-server",
      "status": "active",
      "region": "lagos-1"
    }
  }
}

Collection Response

{
  "data": [
    { "id": "inst-1", "type": "instances", "attributes": { ... } },
    { "id": "inst-2", "type": "instances", "attributes": { ... } }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "totalPages": 3
  },
  "links": {
    "first": "/v1/instances?page=1",
    "next": "/v1/instances?page=2"
  }
}

Error Handling

Errors follow JSON:API error format:

{
  "errors": [
    {
      "status": "404",
      "code": "NOT_FOUND",
      "detail": "Instance not found"
    }
  ]
}

Common Error Codes

Pagination

List endpoints support pagination via query parameters:

Example:

  curl "https://api.fugoku.com/v1/instances?page=2&limit=50&sort=name" \
  -H "X-Fugoku-API-Key: $FUGOKU_API_TOKEN"

Idempotency

Create endpoints support the Idempotency-Key header to prevent duplicate requests:

  curl -X POST https://api.fugoku.com/v1/instances \
  -H "X-Fugoku-API-Key: $FUGOKU_API_TOKEN" \
  -H "Idempotency-Key: unique-request-id-123" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

If the same Idempotency-Key is sent twice within 24 hours, the API returns the cached response.

Rate Limiting

Rate limits are enforced per project, per API key, and per IP (for unauthenticated requests):

When rate limited, the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait before retrying.

If Redis is unavailable, authenticated requests fail open (allowed through, since auth is still enforced) while unauthenticated requests fail closed (returning 503 Service Unavailable) to prevent abuse.

Endpoints

• Instances — Create, list, update, delete, and manage compute instances
• Instances — Bare metal and virtual machine operations
• Databases — Managed database instances
• Backups — Create, restore, and delete backups
• Templates — Reusable instance configuration templates
• Providers — Manage cloud provider connections
• Catalog — Plans, regions, operating systems, and server catalog
• Cost Estimates — Estimate costs before provisioning
• Jobs — Background job tracking and retry
• SSH Keys — SSH key management
• Networking — Networks, VLANs, firewalls, IPs
• Interconnections — Cross-region network connections
• Storage — Volumes, snapshots, file systems
• Files — Versioned file storage
• Kubernetes — Managed Kubernetes clusters
• IAM — Teams, members, roles
• Project IAM — Project invitations and member management
• Workspaces — Workspace member management
• API Keys — Project-scoped API key management
• AI Models — Deploy and manage AI model endpoints
• Billing API — Wallets, credits, currency conversion, checkout
• Invoices — Create, list, and download invoices
• Payments — Stripe payment initialization and verification
• Notifications — Notification endpoints and user notifications
• Support — Support ticket management
• Batch Operations — Bulk actions on resources
• Realtime — SSE and WebSocket endpoints
• Console Sessions — Web console session management
• Webhooks — Inbound webhook receiver endpoints
• KYC — Know Your Customer verification
• Admin API — Administrative platform management
• Health — Health checks and metrics

Schemas

• Instance Schema
• Server Schema
• Provider Schema
• Job Schema
• Error Schema