A small API that does the obvious thing.

Base URL and versioning

https://api.byteroast.com/v1

All requests use JSON. The version is part of the path. Breaking changes ship as a new version; additive changes do not.

Authentication

Create a token under Account → API tokens and send it as a bearer token:

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

Tokens are scoped to a team and can be read-only. Treat them like passwords. We store only a hash, so a lost token cannot be recovered — revoke it and create a new one.

Endpoints

Method	Path	Purpose
GET	/servers	List servers
POST	/servers	Create a server
GET	/servers/:id	Retrieve a server
PATCH	/servers/:id	Rename or resize
DELETE	/servers/:id	Destroy a server
POST	/servers/:id/actions	Power, reboot or rebuild
GET	/snapshots	List snapshots
POST	/servers/:id/snapshots	Create a snapshot
GET	/domains	List domains
POST	/domains/:name/records	Create a DNS record
GET	/regions	List regions and plans

Create a server

curl -X POST https://api.byteroast.com/v1/servers \
  -H "Authorization: Bearer $BR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "api-prod",
    "region": "ruh1",
    "plan": "growth",
    "image": "ubuntu-24.04",
    "ssh_keys": ["key_123"],
    "tags": ["production", "api"]
  }'

The response includes the server ID and initial credentials:

{
  "id": "srv_9f3k2",
  "name": "api-prod",
  "status": "provisioning",
  "region": "ruh1",
  "plan": "growth",
  "ipv4": "203.0.113.10",
  "ipv6": "2001:db8::10/64",
  "created_at": "2026-10-20T09:12:44Z"
}

Provisioning is asynchronous. Poll GET /servers/srv_9f3k2 until status is running, or use the CLI, which waits for you.

Errors

Errors use standard HTTP status codes and a consistent body:

{"error": {"code": "invalid_plan", "message": "Plan 'mega' is not available in region ruh1"}}

• 400 malformed request
• 401 missing or invalid token
• 403 token lacks permission
• 404 resource not found
• 409 state conflict, such as resizing a running server
• 422 validation failed
• 429 rate limited

Rate limits

Requests are limited to 120 per minute per token. Responses include X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. A 429 includes Retry-After. Use exponential backoff on 429 and 5xx responses.

Pagination

List endpoints return up to 50 items by default and accept ?limit= and ?cursor=. The response includes next_cursor; pass it back to continue. Cursors are opaque.

Support

Found something inconsistent? Email api@byteroast.com with the request ID from the response headers. We answer API questions directly.