API reference

Operator API

For the people who run the service: suspend an organization or lift a suspension, and review the abuse guard's flags. These routes need the operator token.

View as Markdown

Suspend an organization (operators): POST /v1/operator/organizations/{organization_id}/suspend
Lift a suspension (operators): POST /v1/operator/organizations/{organization_id}/resume
List abuse flags (operators): GET /v1/operator/abuse-flags
Resolve an abuse flag (operators): POST /v1/operator/abuse-flags/{flag_id}/resolve

Suspend an organization (operators)

POST /v1/operator/organizations/{organization_id}/suspend

Suspend an organization (the kill switch): its machines are stopped, new creates, starts, and restarts are refused, nothing may run commands or open terminals or desktops in it (403 organization_suspended), and its open terminal and desktop tickets and channels are revoked. Its data is kept. Suspending a suspended organization changes nothing.

Authentication: none on this route.
Who: Service operators (operator token).

Parameters

Name	In	Type	Required	Description
`organization_id`	path	`string (uuid)`	Yes
`X-VMYard-Operator-Token`	header	`string`	Yes	Operator token from the service configuration

Request body (application/json, OperatorActionRequest)

Field	Type	Required	Description
`operator`	`string`	Yes	The individual operator acting (a name or work email), recorded in the audit log; 1-200 characters.
`reason`	`string`	Yes	Why; recorded in the audit log, 1-500 characters. A suspension's reason is shown to operators only.

Responses

Status	Description	Body
`200`	—	`SuspensionDto`
`401`	Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`).	`ProblemDetails`
`404`	operator access is not configured or the organization is unknown	`ProblemDetails`
`422`	Invalid request (`invalid_request`); `field_errors` names the fields.	`ProblemDetails`

Request

curl -X POST "$VMYARD_API_URL/v1/operator/organizations/$ORGANIZATION_ID/suspend" \
  -H "X-VMYard-Operator-Token: $X_VMYARD_OPERATOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "operator": "string",
  "reason": "string"
}'

Response 200

{
  "already_suspended": false,
  "channels_revoked": 0,
  "machines_stopping": 0,
  "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "reason": "string",
  "suspended_at": "string",
  "tickets_revoked": 0
}

Lift a suspension (operators)

POST /v1/operator/organizations/{organization_id}/resume

Lift a suspension. Machines it stopped stay stopped until members start them.

Authentication: none on this route.
Who: Service operators (operator token).

Parameters

Name	In	Type	Required	Description
`organization_id`	path	`string (uuid)`	Yes
`X-VMYard-Operator-Token`	header	`string`	Yes	Operator token from the service configuration

Request body (application/json, OperatorActionRequest)

Field	Type	Required	Description
`operator`	`string`	Yes	The individual operator acting (a name or work email), recorded in the audit log; 1-200 characters.
`reason`	`string`	Yes	Why; recorded in the audit log, 1-500 characters. A suspension's reason is shown to operators only.

Responses

Status	Description	Body
`200`	—	`ResumeDto`
`401`	Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`).	`ProblemDetails`
`404`	operator access is not configured or the organization is unknown	`ProblemDetails`
`422`	Invalid request (`invalid_request`); `field_errors` names the fields.	`ProblemDetails`

Request

curl -X POST "$VMYARD_API_URL/v1/operator/organizations/$ORGANIZATION_ID/resume" \
  -H "X-VMYard-Operator-Token: $X_VMYARD_OPERATOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "operator": "string",
  "reason": "string"
}'

Response 200

{
  "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "resumed": false
}

List abuse flags (operators)

GET /v1/operator/abuse-flags

The sustained-CPU guard's flags, newest first, for review.

Authentication: none on this route.
Who: Service operators (operator token).

Parameters

Name	In	Type	Required	Description
`status`	query	`AbuseFlagStatusDto`	No	`open` (default) or `all`.
`limit`	query	`integer`	No	1-500, default 100; newest first.
`X-VMYard-Operator-Token`	header	`string`	Yes	Operator token from the service configuration

Responses

Status	Description	Body
`200`	—	`AbuseFlagPage`
`401`	Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`).	`ProblemDetails`
`404`	operator access is not configured	`ProblemDetails`

Request

curl "$VMYARD_API_URL/v1/operator/abuse-flags" \
  -H "X-VMYard-Operator-Token: $X_VMYARD_OPERATOR_TOKEN"

Response 200

{
  "items": [
    {
      "action": "string",
      "created_at": "string",
      "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "kind": "string",
      "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "min_cpu_permille": 0,
      "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "resolution": "string",
      "resolution_note": "string",
      "resolved_at": "string",
      "stop_operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "window_seconds": 0,
      "window_start": "string"
    }
  ]
}

Resolve an abuse flag (operators)

POST /v1/operator/abuse-flags/{flag_id}/resolve

Resolve a flag after review. A resolved flag stays resolved; a second resolution changes nothing and returns it as it is.

Authentication: none on this route.
Who: Service operators (operator token).

Parameters

Name	In	Type	Required	Description
`flag_id`	path	`string (uuid)`	Yes
`X-VMYard-Operator-Token`	header	`string`	Yes	Operator token from the service configuration

Request body (application/json, ResolveAbuseFlagRequest)

Field	Type	Required	Description
`note`	`string`	Yes	What the review found, 1-500 characters.
`operator`	`string`	Yes	The individual operator acting, 1-200 characters.
`resolution`	`FlagResolutionDto`	Yes

Responses

Status	Description	Body
`200`	—	`AbuseFlagDto`
`401`	Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`).	`ProblemDetails`
`404`	operator access is not configured or the flag is unknown	`ProblemDetails`
`422`	Invalid request (`invalid_request`); `field_errors` names the fields.	`ProblemDetails`

Request

curl -X POST "$VMYARD_API_URL/v1/operator/abuse-flags/$FLAG_ID/resolve" \
  -H "X-VMYard-Operator-Token: $X_VMYARD_OPERATOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "note": "string",
  "operator": "string",
  "resolution": "dismissed"
}'

Response 200

{
  "action": "string",
  "created_at": "string",
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "kind": "string",
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "min_cpu_permille": 0,
  "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "resolution": "string",
  "resolution_note": "string",
  "resolved_at": "string",
  "stop_operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "window_seconds": 0,
  "window_start": "string"
}