API Docs

Authentication

Every request must include a valid API key. Generate one from the API Keys section of your dashboard.

Pass your key in the Authorization header using the Bearer scheme:

Authorization: Bearer YOUR_API_KEY

Example:

curl https://dashboard.bithost.io/api/v1/user \
  -H "Authorization: Bearer YOUR_API_KEY"

API keys cost $10.00 and remain valid for 3 months from the date of purchase.

Base URL

All endpoints are served over HTTPS under a versioned path:

https://dashboard.bithost.io/api/v1

Responses & Errors

All responses are JSON. Successful responses wrap data in a named key matching the resource type. Single-object responses use the singular form; collection responses use the plural.

// Collection
{ "servers": [...] }

// Single object
{ "server": { ... } }

// Error
{
  "errors": [
    { "code": "insufficient_funds", "message": "Insufficient funds to create server" },
    { "code": "blank", "message": "can't be blank", "field": "name" }
  ]
}

HTTP Status Codes

Error Codes

Pagination

Collection endpoints return up to 50 items per page. Navigate pages with the page query parameter. Every paginated response includes a meta.pagination object:

{
  "servers": [...],
  "meta": {
    "pagination": {
      "page": 2,
      "has_previous_page": true,
      "has_next_page": false
    }
  }
}

Use has_next_page to determine whether additional pages are available.

User

Returns the profile and account balance of the authenticated user.

curl https://dashboard.bithost.io/api/v1/user \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "user": {
    "email": "[email protected]",
    "full_name": "John Doe",
    "balance": 42.50,
    "server_limit": 10
  }
}

Servers

Servers are the core resource in the bithost API. Each server represents a cloud instance running on one of the supported providers.

Server object

Returns a paginated list of all servers. Accepts a page query parameter.

curl https://dashboard.bithost.io/api/v1/servers \
  -H "Authorization: Bearer YOUR_API_KEY"

Returns the details of a single server.

curl https://dashboard.bithost.io/api/v1/servers/123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Provisions a new server. The server is created asynchronously - it will appear immediately with status: "pending" and transition to "active" once the provider finishes provisioning.

Requirements: confirmed email, at least one SSH key, sufficient balance to cover 5 days of usage at the selected size's hourly rate, and must not exceed the server limit.

curl -X POST https://dashboard.bithost.io/api/v1/servers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web-prod-02",
    "size_id": 5,
    "region_id": 10,
    "image_id": 20,
    "provider": "digital_ocean",
    "key_ids": [1, 2],
    "backups_enabled": true,
    "terms": true
  }'

Common errors: insufficient_funds, no_keys, quota_exceeded, unconfirmed.

Destroys a server. This action is irreversible - all data on the server will be permanently lost.

curl -X DELETE https://dashboard.bithost.io/api/v1/servers/123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Controls the power state of a server. Returns the updated server object.

Enables or disables automatic backups. Returns the updated server object.

Rebuilds a server with a new OS image. Wipes all existing data and reinstalls the OS. The image must belong to the same provider as the server. Returns the updated server object with pending: true.

Resizes a server to a different instance type. By default the resize is flexible and can be reversed. Set permanent to true for a permanent disk resize. Returns the updated server object with pending: true.

Creates a point-in-time snapshot of the server asynchronously. The server will enter a pending state while the snapshot is being taken. Returns a busy error if the server is already processing another operation.

Clears the status message on a server. Useful after acknowledging an error or informational message. Returns the server object with message: null.

Providers

Returns the list of cloud providers available to the authenticated user. Use the slug value when referencing a provider in other endpoints.

curl https://dashboard.bithost.io/api/v1/providers \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "providers": [
    { "id": 1, "name": "DigitalOcean", "slug": "digital_ocean" },
    { "id": 2, "name": "Linode",       "slug": "linode" },
    { "id": 4, "name": "Vultr",        "slug": "vultr" }
  ],
  "meta": { "pagination": { "page": 1, "has_previous_page": false, "has_next_page": false } }
}

Available provider slugs: digital_ocean, linode, hetzner, vultr.

SSH Keys

SSH keys are installed on new servers during provisioning. You must have at least one SSH key on your account before creating a server.

Returns a paginated list of the SSH keys on your account.

curl https://dashboard.bithost.io/api/v1/keys \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "keys": [
    { "id": 1, "label": "macbook-pro",  "key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA..." },
    { "id": 2, "label": "work-desktop", "key": "ssh-rsa AAAAB3NzaC1yc2EAAAA..." }
  ],
  "meta": { "pagination": { "page": 1, "has_previous_page": false, "has_next_page": false } }
}

Adds a new SSH public key to your account. The key is passed inside a nested key object.

curl -X POST https://dashboard.bithost.io/api/v1/keys \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": {
      "label": "deploy-server",
      "key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIExample..."
    }
  }'

Sizes

Sizes represent the hardware configuration (CPU, memory, disk, bandwidth) for a server. Available sizes vary by provider and region.

Returns a paginated list of available instance sizes. When server_id is provided, returns only the sizes that the specified server can be resized to.

curl "https://dashboard.bithost.io/api/v1/sizes?provider=digital_ocean®ion_id=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Size object

Regions

Regions represent physical datacenter locations where servers can be deployed. Each region belongs to a single provider.

Returns a paginated list of regions for a given provider. Each region includes an available_size_slugs array you can use to check which instance sizes can be deployed there.

curl "https://dashboard.bithost.io/api/v1/regions?provider=digital_ocean" \
  -H "Authorization: Bearer YOUR_API_KEY"

Region object

Images

Images are the OS templates used when creating or rebuilding a server. Bithost supports three image types: STANDARD (stock OS images maintained by the provider), CUSTOM (provider-specific custom images), and SNAPSHOT (point-in-time snapshots you created from your own servers).

Returns a paginated list of available images for a provider. When type is SNAPSHOT, only snapshots owned by the authenticated user are returned.

curl "https://dashboard.bithost.io/api/v1/images?provider=digital_ocean" \
  -H "Authorization: Bearer YOUR_API_KEY"

Returns the details of a single image by ID. Returns a 404 with a not_found error if the image does not exist or has been disabled.

curl https://dashboard.bithost.io/api/v1/images/20 \
  -H "Authorization: Bearer YOUR_API_KEY"

Image object

Interactive API explorer: dashboard.bithost.io/api/docs