at.happyproto.admin.listHosts Documentation (EN)

main query

Every host, with what its tenants hold. Staff only.

Output

Encodingapplication/json

hosts array Required

No description available.

unplaceablePlans array Optional

Plans open for new instances that fit on no active host, smallest first. A new instance on one of these fails with NoCapacity. Absent from a provisioner that does not report it.

Errors

AuthRequired This endpoint requires an authenticated caller.

Forbidden The caller is not HappyProto staff, or the provisioner does not treat them as staff.

InvalidRequest The provisioner refused the request as malformed. Not expected from this read; declared because every provisioner refusal is mapped the same way.

NotFound Passed through from the provisioner.

InvalidSlug Passed through from the provisioner.

SlugTaken Passed through from the provisioner.

NotEntitled Passed through from the provisioner.

InstanceLimit Passed through from the provisioner.

NoCapacity Passed through from the provisioner.

OperationInProgress Passed through from the provisioner.

Upstream The provisioner is unreachable, not configured, or answered with an error it does not explain to callers.

Try It

Requests are sent directly from your browser. Some servers may block requests due to CORS.

Service Endpoint Base URL for XRPC calls (e.g., https://api.bsky.social)

View raw schema

{
  "description": "Every host, with what its tenants hold. Staff only.",
  "errors": [
    {
      "description": "This endpoint requires an authenticated caller.",
      "name": "AuthRequired"
    },
    {
      "description": "The caller is not HappyProto staff, or the provisioner does not treat them as staff.",
      "name": "Forbidden"
    },
    {
      "description": "The provisioner refused the request as malformed. Not expected from this read; declared because every provisioner refusal is mapped the same way.",
      "name": "InvalidRequest"
    },
    {
      "description": "Passed through from the provisioner.",
      "name": "NotFound"
    },
    {
      "description": "Passed through from the provisioner.",
      "name": "InvalidSlug"
    },
    {
      "description": "Passed through from the provisioner.",
      "name": "SlugTaken"
    },
    {
      "description": "Passed through from the provisioner.",
      "name": "NotEntitled"
    },
    {
      "description": "Passed through from the provisioner.",
      "name": "InstanceLimit"
    },
    {
      "description": "Passed through from the provisioner.",
      "name": "NoCapacity"
    },
    {
      "description": "Passed through from the provisioner.",
      "name": "OperationInProgress"
    },
    {
      "description": "The provisioner is unreachable, not configured, or answered with an error it does not explain to callers.",
      "name": "Upstream"
    }
  ],
  "output": {
    "encoding": "application/json",
    "schema": {
      "properties": {
        "hosts": {
          "items": {
            "ref": "#host",
            "type": "ref"
          },
          "type": "array"
        },
        "unplaceablePlans": {
          "description": "Plans open for new instances that fit on no active host, smallest first. A new instance on one of these fails with NoCapacity. Absent from a provisioner that does not report it.",
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      },
      "required": [
        "hosts"
      ],
      "type": "object"
    }
  },
  "type": "query"
}

host object

A host. Never carries its addresses or agent certificate.

Properties

cpuMillis integer Required

No description available.

diskGb integer Required

No description available.

freeDiskGb integer Optional

diskGb less reservedDiskGb. Negative when the host is over-committed.

freeMemoryMb integer Optional

memoryMb less reservedMemoryMb. Negative when the host is over-committed.

id string Required

A UUID.

lastSeenAt string datetime Optional

When its agent last answered. Absent if it never has.

memoryMb integer Required

No description available.

name string Required

No description available.

placeablePlans array of string Optional

Plans open for new instances that fit in this host's free memory and disk, smallest first. Empty unless the host is active.

reservedDiskGb integer Required

Disk held by the plans of instances placed here and not yet purged. A deleted instance keeps its disk through its recovery window.

reservedMemoryMb integer Required

Memory those instances' plans hold.

state string Required

No description available.

Known values: active, draining, degraded, retired

tenantCount integer Required

Instances placed here and not deleted.

View raw schema

{
  "description": "A host. Never carries its addresses or agent certificate.",
  "properties": {
    "cpuMillis": {
      "type": "integer"
    },
    "diskGb": {
      "type": "integer"
    },
    "freeDiskGb": {
      "description": "diskGb less reservedDiskGb. Negative when the host is over-committed.",
      "type": "integer"
    },
    "freeMemoryMb": {
      "description": "memoryMb less reservedMemoryMb. Negative when the host is over-committed.",
      "type": "integer"
    },
    "id": {
      "description": "A UUID.",
      "type": "string"
    },
    "lastSeenAt": {
      "description": "When its agent last answered. Absent if it never has.",
      "format": "datetime",
      "type": "string"
    },
    "memoryMb": {
      "type": "integer"
    },
    "name": {
      "type": "string"
    },
    "placeablePlans": {
      "description": "Plans open for new instances that fit in this host's free memory and disk, smallest first. Empty unless the host is active.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "reservedDiskGb": {
      "description": "Disk held by the plans of instances placed here and not yet purged. A deleted instance keeps its disk through its recovery window.",
      "type": "integer"
    },
    "reservedMemoryMb": {
      "description": "Memory those instances' plans hold.",
      "type": "integer"
    },
    "state": {
      "knownValues": [
        "active",
        "draining",
        "degraded",
        "retired"
      ],
      "type": "string"
    },
    "tenantCount": {
      "description": "Instances placed here and not deleted.",
      "type": "integer"
    }
  },
  "required": [
    "id",
    "name",
    "state",
    "memoryMb",
    "cpuMillis",
    "diskGb",
    "tenantCount",
    "reservedMemoryMb",
    "reservedDiskGb"
  ],
  "type": "object"
}