Perform an action on a host

Requires the master token. Cordon and uncordon change where the scheduler will place work, so they are operator actions. An API-key principal gets 403.

POST/v1/hosts/{hostId}

Authorization

AuthorizationBearer token · headerrequired

`Authorization: Bearer <token>` — either the static master token (`ORCH_AUTH_TOKEN`) or a revocable API key issued via /v1/api-keys (API keys require Postgres; without a database only the master token is accepted). Master-only surfaces (exec, attach, API key management) refuse API keys with 403. **Authentication can be disabled entirely.** When neither `ORCH_AUTH_TOKEN` nor an API key store (`DATABASE_URL`) is configured — the default local-development posture — the bearer middleware becomes a pass-through: every operation this document marks as secured is reachable with no credentials, requests carry no principal, and master-only surfaces therefore admit everyone. Never run that configuration on a reachable network; set `ORCH_REQUIRE_AUTH=true` to make the orchestrator refuse to start without a master token.

fuse_sessionAPI key · cookierequired

HttpOnly session cookie set by POST /login for browser callers. Consulted only when no Authorization header is present.

Path parameters

hostIdstringrequired

Host identifier assigned by the caller.

Query parameters

actionstringrequired

The action to perform on the host. - cordon: Mark the host unschedulable for new environments. Existing VMs keep running; cordon only stops new placements. - uncordon: Return the host to active scheduling. Also reactivates a host in the `draining` state.

Allowed:cordonuncordon

Responses

204Action succeeded.

400Malformed request.

errorobjectrequired

Show properties

codestringrequired

Stable machine-readable code. `route_not_found` (404) means the URL matches no route this server exposes — usually a wrong host, port, or path prefix — as opposed to `not_found`, where the route exists but the resource does not. `forbidden` is emitted only by CIDR-allowlist rejections; master-only refusals (exec, attach, API key management) return 403 with code `unauthorized`.

Allowed:not_foundroute_not_foundconflictinvalid_argumentunauthorizedforbiddenunavailableinternalunimplemented

messagestringrequired

Human-readable description.

detailsobject

Optional stable, non-sensitive metadata (e.g. ids, counts). Omitted when empty.

404Resource does not exist. Note the distinct code `route_not_found`, returned when the URL matches no registered route at all (wrong host, port, or path prefix) rather than a known route with a missing resource.

errorobjectrequired

Show properties

codestringrequired

Allowed:not_foundroute_not_foundconflictinvalid_argumentunauthorizedforbiddenunavailableinternalunimplemented

messagestringrequired

Human-readable description.

detailsobject

Optional stable, non-sensitive metadata (e.g. ids, counts). Omitted when empty.

500Unexpected server error.

errorobjectrequired

Show properties

codestringrequired

Allowed:not_foundroute_not_foundconflictinvalid_argumentunauthorizedforbiddenunavailableinternalunimplemented

messagestringrequired

Human-readable description.

detailsobject

Optional stable, non-sensitive metadata (e.g. ids, counts). Omitted when empty.

Request

curl -X POST "http://localhost:8080/v1/hosts/string?action=cordon" \
  -H "Authorization: Bearer YOUR_TOKEN"

const response = await fetch("http://localhost:8080/v1/hosts/string?action=cordon", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN"
  }
});

import requests

response = requests.post(
    "http://localhost:8080/v1/hosts/string?action=cordon",
    headers={
        "Authorization": "Bearer YOUR_TOKEN"
    },
)

Response

Action succeeded.