API Reference

The Fugoku API is a RESTful JSON:API-compliant 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 are rejected.

Authentication

Authenticate requests with a Bearer token or an API key header.

Bearer Token

Include your API token in the Authorization header:

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

API Key Header

Alternatively, use the X-Fugoku-API-Key header:

curl https://api.fugoku.com/v1/servers \
  -H "X-Fugoku-API-Key: $FUGOKU_API_KEY"

Getting Credentials

Navigate to Account → API Credentials in the Console
Click Create New Token
Name your token and copy it immediately

Security

Never commit tokens to version control. Use environment variables or a secret manager.

Response Format

All responses follow the JSON:API specification.

Single Resource

{
  "data": {
    "id": "srv-abc123",
    "type": "servers",
    "attributes": {
      "name": "web-1",
      "status": "active",
      "site": "lagos-1",
      "plan": "vm-standard",
      "role": "VirtualMachine"
    }
  }
}

Collection

{
  "data": [
    {
      "id": "inst-abc123",
      "type": "instances",
      "attributes": { "name": "web-1", "status": "active" }
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "totalPages": 3
  },
  "links": {
    "first": "https://api.fugoku.com/v1/servers?page=1&limit=20",
    "last": "https://api.fugoku.com/v1/servers?page=3&limit=20",
    "prev": "https://api.fugoku.com/v1/servers?page=1&limit=20",
    "next": "https://api.fugoku.com/v1/servers?page=2&limit=20"
  }
}

Error Response

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

HTTP Status Codes

Code	Meaning
200	OK — Request succeeded
201	Created — Resource created
202	Accepted — Request accepted, processing async
204	No Content — Request succeeded, no body
400	Bad Request — Invalid parameters
401	Unauthorized — Missing or invalid token
403	Forbidden — Valid token, insufficient permissions
404	Not Found — Resource does not exist
422	Unprocessable Entity — Validation failed
429	Too Many Requests — Rate limit exceeded
500	Internal Server Error

Pagination

List endpoints support pagination via query parameters.

Parameter	Type	Default	Description
`page`	integer	`1`	Page number
`limit`	integer	`20` (max `100`)	Items per page
`sort`	string	—	Sort field (`name`, `status`, `createdAt`, `site`)
`fields[servers]`	string	—	Comma-separated list of attributes to include

Example:

curl "https://api.fugoku.com/v1/servers?page=2&limit=50&sort=name&fields[servers]=name,status,site" \
  -H "Authorization: Bearer $FUGOKU_API_TOKEN"

Idempotency

Create and action endpoints support idempotency via the Idempotency-Key header. Repeating the same request with the same key returns the cached response instead of creating a duplicate.

curl -X POST https://api.fugoku.com/v1/servers \
  -H "Authorization: Bearer $FUGOKU_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: req-unique-123" \
  -d '{ ... }'

Compute Servers

List Servers

GET /v1/servers

Query parameters:

page — Page number (default: 1)
limit — Items per page (default: 20, max: 100)
sort — Sort field (name, status, createdAt, site)
fields[servers] — Comma-separated attributes to include
status — Filter by status (creating, active, stopping, stopped, error, terminated, terminating, starting)
provider — Filter by provider ID
site — Filter by site/region
role — Filter by role (BareMetal, VirtualMachine)

Example:

curl "https://api.fugoku.com/v1/servers?status=active&site=lagos-1" \
  -H "Authorization: Bearer $FUGOKU_API_TOKEN"

Get Server

GET /v1/servers/:id

Example:

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

Response:

{
  "data": {
    "id": "srv-abc123",
    "type": "servers",
    "attributes": {
      "name": "web-1",
      "status": "active",
      "site": "lagos-1",
      "plan": "vm-standard",
      "role": "VirtualMachine",
      "provider": "latitude",
      "operating_system": "ubuntu-22.04",
      "billing": "hourly",
      "ip_address": "102.89.45.178",
      "ssh_key_fingerprint": "SHA256:abc123",
      "tags": [{ "key": "env", "value": "production" }, { "key": "team", "value": "backend" }],
      "backups_enabled": true,
      "created_at": "2024-02-25T10:30:00Z",
      "updated_at": "2024-02-25T10:31:00Z"
    }
  }
}

Create Server

POST /v1/servers

Request body:

Field	Type	Required	Description
`name`	string	Yes	Server name (1–64 chars)
`site`	string	Yes	Site/region identifier
`plan`	string	Yes	Plan/size identifier
`role`	string	Yes	Server role (`BareMetal`, `VirtualMachine`)
`provider`	string	No	Provider identifier
`operating_system`	string	No	OS image identifier
`billing`	string	No	Billing cycle (`hourly`, `monthly`)
`ssh_keys`	array	No	SSH key names
`tags`	array	No	Key-value tags
`backups_enabled`	boolean	No	Enable automatic backups
`user_data`	string	No	Cloud-init script

Example:

curl -X POST https://api.fugoku.com/v1/servers \
  -H "Authorization: Bearer $FUGOKU_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: req-unique-123" \
  -d '{
    "data": {
      "type": "servers",
      "attributes": {
        "name": "web-1",
        "site": "lagos-1",
        "plan": "vm-standard",
        "operating_system": "ubuntu-22.04",
        "billing": "hourly",
        "role": "VirtualMachine",
        "provider": "latitude",
        "ssh_keys": ["my-laptop"],
        "tags": [{ "key": "env", "value": "production" }]
      }
    }
  }'

Response (202 Accepted):

{
  "data": {
    "id": "srv-abc123",
    "type": "servers",
    "attributes": {
      "name": "web-1",
      "status": "creating",
      "site": "lagos-1",
      "plan": "vm-standard",
      "role": "VirtualMachine"
    }
  },
  "jobId": "job-create-xyz"
}

Update Server

PATCH /v1/servers/:id

Request body:

Field	Type	Required	Description
`name`	string	No	New name (1–64 chars)
`tags`	array	No	Key-value tags
`backups_enabled`	boolean	No	Enable/disable automatic backups

Example:

curl -X PATCH https://api.fugoku.com/v1/servers/srv-abc123 \
  -H "Authorization: Bearer $FUGOKU_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "servers",
      "attributes": {
        "name": "web-1-renamed"
      }
    }
  }'

Server Actions

POST /v1/servers/:id/actions

Request body:

Field	Type	Required	Description
`action`	string	Yes	Action to perform

Actions:

Action	Description
`power_on`	Start a stopped server
`power_off`	Stop a running server
`reboot`	Reboot a running server
`rebuild`	Reinstall operating system
`upgrade`	Change server plan

Example:

curl -X POST https://api.fugoku.com/v1/servers/srv-abc123/actions \
  -H "Authorization: Bearer $FUGOKU_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "actions",
      "attributes": { "action": "power_off" }
    }
  }'

Delete Server

DELETE /v1/servers/:id

Example:

curl -X DELETE https://api.fugoku.com/v1/servers/srv-abc123 \
  -H "Authorization: Bearer $FUGOKU_API_TOKEN"

Response: 204 No Content

Warning: Deletion is immediate and irreversible. Take a backup first.

Servers (Bare Metal)

List Servers

GET /v1/servers

Query parameters: page, limit

Example:

curl "https://api.fugoku.com/v1/servers?page=1&limit=20" \
  -H "Authorization: Bearer $FUGOKU_API_TOKEN"

Get Server

GET /v1/servers/:id

Example:

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

Create Server

POST /v1/servers

Request body (JSON:API format):

{
  "data": {
    "type": "servers",
    "attributes": {
      "name": "my-server",
      "hostname": "my-server.example.com",
      "project": "proj-abc",
      "site": "NYC",
      "plan": "rs4.metal.large",
      "operating_system": "ubuntu-24.04",
      "billing": "hourly",
      "ssh_keys": ["key-abc123"],
      "user_data": "#cloud-config\n...",
      "tags": [{ "key": "env", "value": "production" }]
    }
  }
}

Example:

curl -X POST https://api.fugoku.com/v1/servers \
  -H "Authorization: Bearer $FUGOKU_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "servers",
      "attributes": {
        "name": "my-server",
        "hostname": "my-server.example.com",
        "site": "NYC",
        "plan": "rs4.metal.large",
        "operating_system": "ubuntu-24.04",
        "billing": "hourly"
      }
    }
  }'

Response (201 Created):

{
  "data": {
    "id": "srv-abc123",
    "type": "servers",
    "attributes": {
      "hostname": "my-server.example.com",
      "label": "my-server",
      "status": "creating",
      "ipmiStatus": "Normal",
      "role": "Bare Metal",
      "site": "NYC"
    }
  }
}

Update Server

PATCH /v1/servers/:id

Request body:

{
  "data": {
    "type": "servers",
    "attributes": {
      "label": "new-label",
      "locked": true,
      "tags": [{ "key": "env", "value": "staging" }]
    }
  }
}

Delete Server

DELETE /v1/servers/:id

Response: 204 No Content

Server Actions

POST /v1/servers/:id/actions

Request body:

{
  "data": {
    "type": "actions",
    "attributes": {
      "action": "power_on"
    }
  }
}

Allowed actions: power_on, power_off, reboot

Example:

curl -X POST https://api.fugoku.com/v1/servers/srv-abc123/actions \
  -H "Authorization: Bearer $FUGOKU_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "actions",
      "attributes": { "action": "power_off" }
    }
  }'

Response:

{
  "data": {
    "id": "act_srv-abc123",
    "type": "actions",
    "attributes": {
      "action": "power_off",
      "status": "Powering off device"
    }
  }
}

Backups

List Server Backups

GET /v1/servers/:id/backups

Create Server Backup

POST /v1/servers/:id/backups

Request body:

{
  "data": {
    "type": "backups",
    "attributes": {
      "name": "backup-before-upgrade"
    }
  }
}

List Instance Backups

GET /v1/instances/:instanceId/backups

Create Instance Backup

POST /v1/instances/:instanceId/backups

Request body:

{
  "data": {
    "type": "backups",
    "attributes": {
      "name": "backup-before-upgrade"
    }
  }
}

Restore Backup

POST /v1/backups/:id/restore

Creates a new server or instance from a backup.

Delete Backup

DELETE /v1/backups/:id

Providers

List Providers

GET /v1/providers

Example:

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

Get Provider

GET /v1/providers/:id

Create Provider

POST /v1/providers

Request body:

Field	Type	Required	Description
`name`	string	Yes	One of: `latitude`, `skypilot`, `aws`
`apiKey`	string	Yes	Provider API key
`region`	string	No	Default region
`enabled`	boolean	No	Whether the provider is enabled (default: true)

Example:

curl -X POST https://api.fugoku.com/v1/providers \
  -H "Authorization: Bearer $FUGOKU_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "latitude",
    "apiKey": "lat_sk_abc123",
    "region": "NYC",
    "enabled": true
  }'

Update Provider

PATCH /v1/providers/:id

Delete Provider

DELETE /v1/providers/:id

Response: 204 No Content

Catalog

List Catalog (all providers)

GET /v1/catalog

Returns instance types, regions, and images for all enabled providers.

List Instance Types

GET /v1/catalog/instance-types?providerId=:id

List Regions

GET /v1/catalog/regions?providerId=:id

List Images

GET /v1/catalog/images?providerId=:id

Server Catalog

GET /v1/server-catalog/categories

List Tiers

GET /v1/server-catalog/tiers

List Macro Regions

GET /v1/server-catalog/macroregions

List Cities

GET /v1/server-catalog/cities?region=north-america

List Servers

GET /v1/server-catalog/servers?category=bare-metal&tier=standard&region=north-america

Get Server Option

GET /v1/server-catalog/servers/:id

List OS Versions

GET /v1/server-catalog/os-versions?category=bare-metal

Get Billing Options

GET /v1/server-catalog/billing-options?serverId=rs4-metal-large

Plans

List Plans

GET /v1/plans

Query parameters: page, limit

Get Plan

GET /v1/plans/:id

Regions

List Regions

GET /v1/regions

Query parameters: page, limit

Get Region

GET /v1/regions/:id

Operating Systems

List Operating Systems

GET /v1/operating_systems

Query parameters: page, limit

Also available at /v1/plans/operating_systems (Latitude alias).

Get Operating System

GET /v1/operating_systems/:id

Jobs

List Jobs

GET /v1/jobs

Query parameters:

instanceId — Filter by instance ID
status — Filter by status (pending, processing, completed, failed)

Example:

curl "https://api.fugoku.com/v1/jobs?status=failed&instanceId=inst-abc123" \
  -H "Authorization: Bearer $FUGOKU_API_TOKEN"

Get Job

GET /v1/jobs/:id

Example:

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

List Failed Jobs

GET /v1/jobs/failed

Retry Job

POST /v1/jobs/:id/retry

Example:

curl -X POST https://api.fugoku.com/v1/jobs/job-abc123/retry \
  -H "Authorization: Bearer $FUGOKU_API_TOKEN" \
  -H "Content-Type: application/json"

Response:

{
  "data": {
    "jobId": "job-abc123",
    "status": "retrying"
  }
}

SSH Keys

SSH keys are managed per-provider.

List SSH Keys

GET /v1/ssh-keys?providerId=:providerId

Example:

curl "https://api.fugoku.com/v1/ssh-keys?providerId=prov-lagos" \
  -H "Authorization: Bearer $FUGOKU_API_TOKEN"

Create SSH Key

POST /v1/ssh-keys?providerId=:providerId

Request body:

Field	Type	Required	Description
`name`	string	Yes	Key name
`publicKey`	string	Yes	Public key content

Example:

curl -X POST "https://api.fugoku.com/v1/ssh-keys?providerId=prov-lagos" \
  -H "Authorization: Bearer $FUGOKU_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "laptop",
    "publicKey": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI..."
  }'

Delete SSH Key

DELETE /v1/ssh-keys/:keyId?providerId=:providerId

Response: 204 No Content

Networking

All networking endpoints require providerId as a query parameter.

Elastic IPs

List: GET /v1/networking/elastic-ips?providerId=:id

Create: POST /v1/networking/elastic-ips?providerId=:id

Delete: DELETE /v1/networking/elastic-ips/:ipId?providerId=:id

Move: POST /v1/networking/elastic-ips/:ipId/move?providerId=:id

VLANs (Private Networks)

List: GET /v1/networking/vlans?providerId=:id

Create: POST /v1/networking/vlans?providerId=:id

Assign: POST /v1/networking/vlans/:vlanId/assign?providerId=:id

Detach: POST /v1/networking/vlans/:vlanId/detach?providerId=:id

Firewalls

List: GET /v1/networking/firewalls?providerId=:id

Create: POST /v1/networking/firewalls?providerId=:id

Update: PATCH /v1/networking/firewalls/:firewallId?providerId=:id

Delete: DELETE /v1/networking/firewalls/:firewallId?providerId=:id

Assign: POST /v1/networking/firewalls/:firewallId/assign?providerId=:id

Private Networks

List: GET /v1/networking/private-networks?providerId=:id

Create: POST /v1/networking/private-networks?providerId=:id

Attach: POST /v1/networking/private-networks/:networkId/attach?providerId=:id

Storage

All storage endpoints require providerId as a query parameter.

Volumes

List: GET /v1/storage/volumes?providerId=:id

Create: POST /v1/storage/volumes?providerId=:id

Attach: POST /v1/storage/volumes/:volumeId/attach?providerId=:id

Detach: POST /v1/storage/volumes/:volumeId/detach?providerId=:id

Delete: DELETE /v1/storage/volumes/:volumeId?providerId=:id

File Systems

List: GET /v1/storage/file-systems?providerId=:id

Create: POST /v1/storage/file-systems?providerId=:id

Object Storage Buckets

List: GET /v1/storage/object-storage/buckets?providerId=:id

Create: POST /v1/storage/object-storage/buckets?providerId=:id

Kubernetes

All Kubernetes endpoints require providerId as a query parameter.

List Clusters

GET /v1/kubernetes/clusters?providerId=:id

Create Cluster

POST /v1/kubernetes/clusters?providerId=:id

Delete Cluster

DELETE /v1/kubernetes/clusters/:clusterId?providerId=:id

Get Kubeconfig

GET /v1/kubernetes/clusters/:clusterId/kubeconfig?providerId=:id

List Versions

GET /v1/kubernetes/versions?providerId=:id

IAM & API Keys

List API Keys (Project-scoped)

GET /v1/api-keys

Create API Key

POST /v1/api-keys

Request body:

Field	Type	Required	Description
`name`	string	Yes	Key name (1–64 chars)
`expiresAt`	string (ISO 8601)	No	Expiration date

Example:

curl -X POST https://api.fugoku.com/v1/api-keys \
  -H "Authorization: Bearer $FUGOKU_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "production-api-key", "expiresAt": "2025-12-31T00:00:00Z" }'

Response:

{
  "data": {
    "id": "key-abc123",
    "name": "production-api-key",
    "prefix": "fk_live_ab",
    "createdAt": "2024-02-25T10:30:00Z",
    "key": "fk_live_abc123def456..."
  }
}

Revoke API Key

DELETE /v1/api-keys/:id

Response: 204 No Content

IAM — Team Members (Provider-scoped)

List: GET /v1/iam/team/members?providerId=:id

Add: POST /v1/iam/team/members?providerId=:id

Update: PATCH /v1/iam/team/members/:memberId?providerId=:id

Remove: DELETE /v1/iam/team/members/:memberId?providerId=:id

IAM — Usage

GET /v1/iam/usage?providerId=:id&startDate=2024-02-01&endDate=2024-02-29

IAM — Invoices

GET /v1/iam/invoices?providerId=:id

Health

Health Check

GET /v1/health/health

Response:

{
  "status": "ok",
  "service": "fugoku-cloud-api",
  "uptime": 12345.6,
  "timestamp": "2024-02-25T10:30:00Z"
}

Readiness

GET /v1/health/ready

Response:

{
  "ready": true,
  "checks": {
    "database": "ok",
    "redis": "ok",
    "queue": "ok"
  },
  "timestamp": "2024-02-25T10:30:00Z"
}

Metrics

GET /v1/health/metrics

Error Handling

Errors are returned in JSON:API format:

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

Error Codes

Code	Description
`NOT_FOUND`	Resource does not exist
`PROVIDER_NOT_FOUND`	Provider not configured or not found
`INVALID_QUERY`	Query parameter validation failed
`INVALID_PLAN`	Unknown plan identifier
`INVALID_REGION`	Unknown region/site
`INVALID_OS`	Unknown operating system
`BAD_REQUEST`	Missing required parameter
`UNSUPPORTED_PROVIDER`	Provider does not support this operation
`RETRY_FAILED`	Job retry failed
`INTERNAL_ERROR`	Unexpected server error

Retry Guidance

429 (Too Many Requests): Wait for the duration specified in the Retry-After header, then retry.
5xx errors: Retry with exponential backoff (1s, 2s, 4s, 8s...). Max 5 retries.
422 (Unprocessable Entity): Fix the request body and retry immediately.
Include request IDs in support tickets for debugging.

Rate Limiting

Limit	Value
Authenticated requests	1,000 requests/minute
Burst limit	100 requests/minute

Rate limit headers are included in every response:

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

When rate limited, the API returns 429 Too Many Requests.

Best Practices

Use idempotency keys on create and action requests to prevent duplicates
Store tokens securely — environment variables, not code
Implement exponential backoff — For 429 and 5xx errors
Use fields filtering — Request only the attributes you need with fields[servers]
Paginate efficiently — Use limit and sort to control response size
Monitor rate limits — Check X-RateLimit-Remaining before making requests
Use request IDs — Include in support requests for debugging

Support

API Issues: support@fugoku.com
Status: status.fugoku.com

Next Steps:

Getting Started — Deploy your first server
Console Guide — Learn the dashboard
Servers — Bare metal and virtual machine documentation
Jobs — Async operations and job tracking
SSH Keys — Key management
Postman Collection — Import into Postman for API exploration

Endpoints

Instances — Create, list, update, delete, and manage compute instances
Servers — Bare metal server and virtual machine operations
Backups — Create, restore, and delete backups
Providers — Manage cloud provider connections
Catalog — Plans, regions, operating systems, and server catalog
Jobs — Background job tracking and retry
SSH Keys — SSH key management
Networking — Networks, VLANs, firewalls, IPs
Storage — Volumes, snapshots, file systems, object storage
Kubernetes — Managed Kubernetes clusters
IAM — Teams, members, projects
API Keys — Project-scoped API key management
Health — Health checks and metrics

API Reference

On this page