FugokuFugoku Docs
Mask

API Reference

RESTful API for programmatic infrastructure management

API Reference

The Fugoku API is a RESTful HTTP API for managing compute, storage, and networking resources programmatically.

Base URL

https://api.fugoku.com/v1

All API requests must use HTTPS. HTTP requests will be rejected.

Authentication

Use Bearer token authentication with your API token.

Get API Token

Via Console: Account → API Credentials → Create New Token

Via CLI:

fugoku auth token

Making Authenticated Requests

Include token in Authorization header:

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

Security: Never commit tokens to version control. Use environment variables or secret management.

Rate Limits

  • Authenticated requests: 1000 requests/hour
  • Burst limit: 100 requests/minute
  • Unauthenticated requests: 10 requests/hour (for public endpoints only)

Rate limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1646064000

If rate limited, API returns 429 Too Many Requests.

Response Format

All responses are JSON.

Success response:

{
  "data": {
    "id": "inst-abc123",
    "name": "web-1",
    "status": "running"
  },
  "meta": {
    "request_id": "req-xyz789"
  }
}

Error response:

{
  "error": {
    "code": "resource_not_found",
    "message": "Instance 'web-1' not found",
    "details": {
      "resource_type": "instance",
      "resource_id": "web-1"
    }
  },
  "meta": {
    "request_id": "req-xyz789"
  }
}

HTTP Status Codes

CodeMeaning
200OK - Request succeeded
201Created - Resource created
202Accepted - Request accepted, processing async
204No Content - Request succeeded, no body
400Bad Request - Invalid parameters
401Unauthorized - Missing or invalid token
403Forbidden - Valid token, insufficient permissions
404Not Found - Resource doesn't exist
409Conflict - Resource state conflict
422Unprocessable Entity - Validation failed
429Too Many Requests - Rate limit exceeded
500Internal Server Error - Server error
503Service Unavailable - Temporary outage

Pagination

List endpoints support pagination.

Request:

curl "https://api.fugoku.com/v1/instances?page=2&per_page=50" \
  -H "Authorization: Bearer $FUGOKU_API_TOKEN"

Response includes pagination meta:

{
  "data": [ /* instances */ ],
  "meta": {
    "pagination": {
      "page": 2,
      "per_page": 50,
      "total_pages": 5,
      "total_count": 234
    }
  },
  "links": {
    "first": "https://api.fugoku.com/v1/instances?page=1",
    "prev": "https://api.fugoku.com/v1/instances?page=1",
    "next": "https://api.fugoku.com/v1/instances?page=3",
    "last": "https://api.fugoku.com/v1/instances?page=5"
  }
}

Defaults:

  • page: 1
  • per_page: 25 (max 100)

Compute Instances

List Instances

GET /v1/instances

Query parameters:

  • region - Filter by region
  • status - Filter by status (running, stopped, provisioning)
  • tag - Filter by tag

Example:

curl "https://api.fugoku.com/v1/instances?region=lagos-1&status=running" \
  -H "Authorization: Bearer $FUGOKU_API_TOKEN"

Get Instance

GET /v1/instances/:id

Example:

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

Response:

{
  "data": {
    "id": "inst-abc123",
    "name": "web-1",
    "region": "lagos-1",
    "plan": "standard-2",
    "image": "ubuntu-22.04",
    "status": "running",
    "public_ip": "102.89.45.178",
    "private_ip": "10.10.0.5",
    "created_at": "2024-02-25T10:30:00Z",
    "tags": ["production", "web"],
    "specs": {
      "vcpu": 2,
      "ram_gb": 4,
      "disk_gb": 80
    }
  }
}

Create Instance

POST /v1/instances

Request body:

{
  "name": "web-1",
  "region": "lagos-1",
  "plan": "standard-2",
  "image": "ubuntu-22.04",
  "ssh_keys": ["laptop"],
  "tags": ["production"],
  "user_data": "#cloud-config\n...",
  "private_networks": ["backend-net"],
  "backups": true
}

Example:

curl -X POST https://api.fugoku.com/v1/instances \
  -H "Authorization: Bearer $FUGOKU_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web-1",
    "region": "lagos-1",
    "plan": "standard-2",
    "image": "ubuntu-22.04"
  }'

Instance Actions

POST /v1/instances/:id/actions

Actions:

  • start - Start stopped instance
  • stop - Stop running instance
  • reboot - Reboot instance
  • rebuild - Reinstall OS
  • resize - Change plan

Example (reboot):

curl -X POST https://api.fugoku.com/v1/instances/web-1/actions \
  -H "Authorization: Bearer $FUGOKU_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type": "reboot"}'

Example (resize):

curl -X POST https://api.fugoku.com/v1/instances/web-1/actions \
  -H "Authorization: Bearer $FUGOKU_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "resize",
    "plan": "standard-4"
  }'

Delete Instance

DELETE /v1/instances/:id

Example:

curl -X DELETE https://api.fugoku.com/v1/instances/web-1 \
  -H "Authorization: Bearer $FUGOKU_API_TOKEN"

Block Storage

List Volumes

GET /v1/volumes

Create Volume

POST /v1/volumes

Request body:

{
  "name": "my-data",
  "size_gb": 100,
  "region": "lagos-1",
  "snapshot_id": "snap-abc123"  // optional
}

Attach Volume

POST /v1/volumes/:id/attach

Request body:

{
  "instance_id": "web-1"
}

Detach Volume

POST /v1/volumes/:id/detach

Snapshots

Create Snapshot

POST /v1/volumes/:volume_id/snapshots

Request body:

{
  "name": "before-upgrade"
}

List Snapshots

GET /v1/snapshots

Networking

Create Network

POST /v1/networks

Request body:

{
  "name": "backend-net",
  "subnet": "10.10.0.0/24",
  "region": "lagos-1",
  "dhcp_enabled": true
}

Attach Instance to Network

POST /v1/networks/:id/attach

Request body:

{
  "instance_id": "web-1"
}

Create Floating IP

POST /v1/floating-ips

Request body:

{
  "region": "lagos-1"
}

Assign Floating IP

POST /v1/floating-ips/:ip/assign

Request body:

{
  "instance_id": "web-1"
}

Load Balancers

Create Load Balancer

POST /v1/load-balancers

Request body:

{
  "name": "api-lb",
  "region": "lagos-1",
  "algorithm": "round_robin",
  "protocol": "http",
  "port": 80,
  "backend_port": 8080,
  "health_check": {
    "path": "/health",
    "interval": 10,
    "timeout": 5,
    "unhealthy_threshold": 3
  }
}

Add Backend

POST /v1/load-balancers/:id/backends

Request body:

{
  "instance_id": "api-1",
  "weight": 100
}

Firewalls

List Rules

GET /v1/instances/:id/firewall/rules

Add Rule

POST /v1/instances/:id/firewall/rules

Request body:

{
  "direction": "inbound",
  "protocol": "tcp",
  "port": 80,
  "source": "0.0.0.0/0"
}

Account & Billing

Get Account Info

GET /v1/account

Get Usage

GET /v1/account/usage

Query parameters:

  • start_date - ISO 8601 date (default: start of current month)
  • end_date - ISO 8601 date (default: now)

Example:

curl "https://api.fugoku.com/v1/account/usage?start_date=2024-02-01&end_date=2024-02-29" \
  -H "Authorization: Bearer $FUGOKU_API_TOKEN"

Response:

{
  "data": {
    "period": {
      "start": "2024-02-01T00:00:00Z",
      "end": "2024-02-29T23:59:59Z"
    },
    "summary": {
      "compute": 47.20,
      "storage": 14.00,
      "networking": 5.00,
      "total": 66.20
    },
    "breakdown": {
      "instances": [
        {
          "id": "inst-abc123",
          "name": "web-1",
          "hours": 720,
          "cost": 12.00
        }
      ],
      "volumes": [ /* ... */ ],
      "bandwidth": { /* ... */ }
    }
  }
}

Webhooks

Receive notifications for events.

Coming Q3 2026.

Planned events:

  • instance.created
  • instance.deleted
  • instance.started
  • instance.stopped
  • snapshot.completed
  • snapshot.failed

SDKs

Official SDKs:

Node.js / TypeScript:

npm install @fugoku/sdk
const Fugoku = require('@fugoku/sdk');
const client = new Fugoku({ apiToken: process.env.FUGOKU_API_TOKEN });

async function createInstance() {
  const instance = await client.instances.create({
    name: 'web-1',
    region: 'lagos-1',
    plan: 'standard-2',
    image: 'ubuntu-22.04'
  });
  console.log(`Created instance: ${instance.id}`);
}

Python:

pip install fugoku
import fugoku

client = fugoku.Client(api_token=os.environ['FUGOKU_API_TOKEN'])

instance = client.instances.create(
    name='web-1',
    region='lagos-1',
    plan='standard-2',
    image='ubuntu-22.04'
)
print(f'Created instance: {instance.id}')

Go:

go get github.com/fugoku/fugoku-go
import "github.com/fugoku/fugoku-go"

client := fugoku.NewClient(os.Getenv("FUGOKU_API_TOKEN"))

instance, err := client.Instances.Create(&fugoku.InstanceCreateRequest{
    Name:   "web-1",
    Region: "lagos-1",
    Plan:   "standard-2",
    Image:  "ubuntu-22.04",
})

Error Handling

Always check status codes and parse error responses.

Example (Node.js):

try {
  const instance = await client.instances.create({ /* ... */ });
} catch (error) {
  if (error.status === 422) {
    console.error('Validation failed:', error.body.error.details);
  } else if (error.status === 429) {
    console.error('Rate limited, retry after:', error.headers['x-ratelimit-reset']);
  } else {
    console.error('API error:', error.body.error.message);
  }
}

Best Practices

  1. Use SDKs when available - Handle auth, retries, pagination automatically
  2. Store tokens securely - Environment variables, not code
  3. Implement exponential backoff - For 429 and 5xx errors
  4. Use webhook events - Instead of polling for status changes (when available)
  5. Validate input locally - Reduce API calls for validation errors
  6. Cache responses - When data doesn't change frequently
  7. Use request IDs - Include in support requests for debugging

Support

Next Steps:

Networking

Private networks, floating IPs, load balancers, and firewalls

CLI Tool

Command-line interface for managing Fugoku Cloud infrastructure

On this page

API Reference
Base URL
Authentication
Get API Token
Making Authenticated Requests
Rate Limits
Response Format
HTTP Status Codes
Pagination
Compute Instances
List Instances
Get Instance
Create Instance
Instance Actions
Delete Instance
Block Storage
List Volumes
Create Volume
Attach Volume
Detach Volume
Snapshots
Create Snapshot
List Snapshots
Networking
Create Network
Attach Instance to Network
Create Floating IP
Assign Floating IP
Load Balancers
Create Load Balancer
Add Backend
Firewalls
List Rules
Add Rule
Account & Billing
Get Account Info
Get Usage
Webhooks
SDKs
Error Handling
Best Practices
Support