API Overview¶

The b'nerd cloud API is a RESTful HTTP API that lets you manage every resource on the platform — compute, networking, DNS, Kubernetes, object storage, billing, and more. All endpoints are available under version prefix / (no explicit /api/v1/ path segment; versioning is handled at the host level).

Base URLs¶

Environment	Base URL
Production	`https://api.bnerd.cloud`

The API Reference is rendered from the OpenAPI 3.0 specification — browse every endpoint with its parameters, request/response schemas, and examples.

Request conventions¶

All request and response bodies are JSON (Content-Type: application/json).
UUIDs are used as resource identifiers throughout.
PATCH is used for partial updates; send only the fields you want to change.
Write operations that accept a nested object wrap it under the resource key (e.g. { "project": { "name": "..." } }). The RGW user control-plane endpoints are an exception — they use flat top-level params as documented in the Object Storage reference.

Authentication¶

Every endpoint (except public invitation lookup) requires an Authorization header. Two token types are accepted:

Authorization: Bearer <jwt-or-static-token>

See Authentication for how to obtain tokens.

Error envelope¶

All error responses share a common envelope:

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "errors": [
    {
      "code": "validation_failed",
      "message": "Validation failed",
      "status": 422,
      "field": "name",
      "source": {
        "service": "rgw",
        "operation": "create"
      },
      "meta": {
        "validation_errors": { "name": ["has already been taken"] }
      }
    }
  ]
}

Field	Description
`request_id`	UUID that correlates this response to server logs. Quote it in support tickets.
`errors[].code`	Machine-readable error code (e.g. `not_found`, `forbidden`, `validation_failed`, `rate_limited`).
`errors[].status`	HTTP status code mirrored inside the body.
`errors[].field`	Present when the error relates to a specific input field.
`errors[].source`	Identifies the service and operation that generated the error.
`errors[].meta`	Additional structured detail (validation messages, schema errors, etc.).

Pagination¶

List endpoints that support pagination accept these query parameters:

Parameter	Default	Description
`page`	`1`	Page number (1-indexed).
`per_page`	`25`	Items per page.
`order_by`	resource-specific	Field to sort on.
`order_dir`	`asc`	Sort direction: `asc` or `desc`.

The response body is a JSON array of resource objects. There is no envelope wrapper on list responses; use the page/per_page params to walk pages.

Rate limits¶

API requests are throttled per bearer token:

Scope	Limit
Authenticated API requests (per token)	300 requests / 60 seconds
Login attempts (per IP)	5 requests / 60 seconds
Password reset requests (per IP)	3 requests / 60 seconds

When a limit is exceeded the API returns 429 Too Many Requests with the standard error envelope:

{
  "request_id": null,
  "errors": [
    {
      "code": "rate_limited",
      "message": "Too many requests. Retry later.",
      "status": 429
    }
  ]
}

Back off and retry after the Retry-After header value (seconds) if present.