API reference

Environments API

Named, versioned sets of environment variables and secret files that VMYard applies to machines.

List environments: GET /v1/environments
Create an environment: POST /v1/environments
Get an environment: GET /v1/environments/{environment_id}
Change an environment: PATCH /v1/environments/{environment_id}
Delete an environment: DELETE /v1/environments/{environment_id}
Set a variable: PUT /v1/environments/{environment_id}/vars/{key}
Remove a variable: DELETE /v1/environments/{environment_id}/vars/{key}
Set a secret file: PUT /v1/environments/{environment_id}/files
Remove a secret file: DELETE /v1/environments/{environment_id}/files
List versions: GET /v1/environments/{environment_id}/versions
Reveal values: POST /v1/environments/{environment_id}/reveal
Upgrade machines: POST /v1/environments/{environment_id}/upgrade

List environments

GET /v1/environments

API key: Authorization: Bearer vmy_… with preset read_only, use_existing, create_and_use, full_access.
Browser session: the vmyard_session cookie.
Who: Any member.

Parameters

Name	In	Type	Required	Description
`X-Organization-ID`	header	`string (uuid)`	No	Organization context. Required with a browser session. Optional with an API key, which fixes the organization; when sent it must match.

Responses

Status	Description	Body
`200`	—	`EnvironmentList`
`401`	Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`).	`ProblemDetails`

Request

curl "$VMYARD_API_URL/v1/environments" \
  -H "Authorization: Bearer $VMYARD_API_KEY"

Response 200

{
  "items": [
    {
      "created_at": "string",
      "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "current_version": {
        "change": {},
        "created_at": "string",
        "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
        "environment_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
        "files": [
          {
            "path": "notes/todo.txt",
            "size": 0
          }
        ],
        "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
        "vars": [
          "string"
        ],
        "version": 0
      },
      "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "is_default": false,
      "name": "staging",
      "safe_for_third_parties": false,
      "updated_at": "string"
    }
  ]
}

Create an environment

POST /v1/environments

API key: Authorization: Bearer vmy_… with preset full_access.
Browser session: the vmyard_session cookie and the x-csrf-token header.
Who: Owner or Admin.

Parameters

Name	In	Type	Required	Description
`X-Organization-ID`	header	`string (uuid)`	No	Organization context. Required with a browser session. Optional with an API key, which fixes the organization; when sent it must match.

Request body (application/json, CreateEnvironmentRequest)

Field	Type	Required	Description
`files`	`SecretFileInput[]`	No
`is_default`	`boolean \| null`	No	Defaults to `true` when the organization has no default environment.
`name`	`string \| null`	No	Lowercase DNS label, unique in the organization. Defaults to `base`.
`safe_for_third_parties`	`boolean`	No
`vars`	`map of string`	No	Variable names (`^[A-Za-z_][A-Za-z0-9_]{0,127}$`) to values.

Responses

Status	Description	Body
`201`	The created environment (not the list)	`EnvironmentDto`
`401`	Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`).	`ProblemDetails`
`403`	A role other than owner/admin, or an API key without full_access	`ProblemDetails`
`409`	`environment_name_taken` or `environment_limit_reached`	`ProblemDetails`
`413`	The request body is too large (`body_too_large`).	`ProblemDetails`
`422`	Invalid request (`invalid_request`); `field_errors` names the fields.	`ProblemDetails`
`503`	`environments_unavailable`: no encryption keys configured	`ProblemDetails`

Request

curl -X POST "$VMYARD_API_URL/v1/environments" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "staging",
  "vars": {
    "DATABASE_URL": "postgres://app@db.internal/app",
    "LOG_LEVEL": "info"
  },
  "files": [
    {
      "path": "secrets/service-account.json",
      "contents": "{\"type\": \"service_account\"}"
    }
  ]
}'

Response 201

{
  "created_at": "string",
  "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "current_version": {
    "change": {},
    "created_at": "string",
    "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "environment_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "files": [
      {
        "path": "notes/todo.txt",
        "size": 0
      }
    ],
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "vars": [
      "string"
    ],
    "version": 0
  },
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "is_default": false,
  "name": "staging",
  "safe_for_third_parties": false,
  "updated_at": "string"
}

Get an environment

GET /v1/environments/{environment_id}

API key: Authorization: Bearer vmy_… with preset read_only, use_existing, create_and_use, full_access.
Browser session: the vmyard_session cookie.
Who: Any member.

Parameters

Name	In	Type	Required	Description
`environment_id`	path	`string (uuid)`	Yes
`X-Organization-ID`	header	`string (uuid)`	No	Required with a browser session. Optional with an API key, which fixes the organization; when sent it must match.

Responses

Status	Description	Body
`200`	—	`EnvironmentDto`
`401`	Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`).	`ProblemDetails`
`404`	Not found in this organization (`resource_not_found`).	`ProblemDetails`

Request

curl "$VMYARD_API_URL/v1/environments/$ENVIRONMENT_ID" \
  -H "Authorization: Bearer $VMYARD_API_KEY"

Response 200

{
  "created_at": "string",
  "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "current_version": {
    "change": {},
    "created_at": "string",
    "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "environment_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "files": [
      {
        "path": "notes/todo.txt",
        "size": 0
      }
    ],
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "vars": [
      "string"
    ],
    "version": 0
  },
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "is_default": false,
  "name": "staging",
  "safe_for_third_parties": false,
  "updated_at": "string"
}

Change an environment

PATCH /v1/environments/{environment_id}

API key: Authorization: Bearer vmy_… with preset full_access.
Browser session: the vmyard_session cookie and the x-csrf-token header.
Who: Owner or Admin.

Parameters

Name	In	Type	Required	Description
`environment_id`	path	`string (uuid)`	Yes
`X-Organization-ID`	header	`string (uuid)`	No	Required with a browser session. Optional with an API key, which fixes the organization; when sent it must match.

Request body (application/json, UpdateEnvironmentRequest)

Field	Type	Required	Description
`is_default`	`boolean \| null`	No	`true` makes this the default; `false` leaves the organization without one.
`name`	`string \| null`	No
`safe_for_third_parties`	`boolean \| null`	No

Responses

Status	Description	Body
`200`	Metadata only; no new version	`EnvironmentDto`
`401`	Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`).	`ProblemDetails`
`403`	Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`).	`ProblemDetails`
`404`	Not found in this organization (`resource_not_found`).	`ProblemDetails`
`409`	Conflicts with the current state, such as a reused idempotency key with another body (`idempotency_conflict`).	`ProblemDetails`
`422`	Invalid request (`invalid_request`); `field_errors` names the fields.	`ProblemDetails`

Request

curl -X PATCH "$VMYARD_API_URL/v1/environments/$ENVIRONMENT_ID" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "is_default": true
}'

Response 200

{
  "created_at": "string",
  "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "current_version": {
    "change": {},
    "created_at": "string",
    "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "environment_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "files": [
      {
        "path": "notes/todo.txt",
        "size": 0
      }
    ],
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "vars": [
      "string"
    ],
    "version": 0
  },
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "is_default": false,
  "name": "staging",
  "safe_for_third_parties": false,
  "updated_at": "string"
}

Delete an environment

DELETE /v1/environments/{environment_id}

API key: Authorization: Bearer vmy_… with preset full_access.
Browser session: the vmyard_session cookie and the x-csrf-token header.
Who: Owner or Admin.

Parameters

Name	In	Type	Required	Description
`environment_id`	path	`string (uuid)`	Yes
`X-Organization-ID`	header	`string (uuid)`	No	Required with a browser session. Optional with an API key, which fixes the organization; when sent it must match.

Responses

Status	Description	Body
`204`	Deleted; machines keep the versions they have	—
`401`	Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`).	`ProblemDetails`
`403`	Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`).	`ProblemDetails`
`404`	Not found in this organization (`resource_not_found`).	`ProblemDetails`

Request

curl -X DELETE "$VMYARD_API_URL/v1/environments/$ENVIRONMENT_ID" \
  -H "Authorization: Bearer $VMYARD_API_KEY"

Set a variable

PUT /v1/environments/{environment_id}/vars/{key}

API key: Authorization: Bearer vmy_… with preset full_access.
Browser session: the vmyard_session cookie and the x-csrf-token header.
Who: Owner or Admin.

Parameters

Name	In	Type	Required	Description
`environment_id`	path	`string (uuid)`	Yes
`key`	path	`string`	Yes
`X-Organization-ID`	header	`string (uuid)`	No	Required with a browser session. Optional with an API key, which fixes the organization; when sent it must match.

Request body (application/json, SetVariableRequest)

Field	Type	Required	Description
`value`	`string`	Yes	At most 32 KiB without NUL.

Responses

Status	Description	Body
`200`	A new version was written	`EnvironmentDto`
`401`	Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`).	`ProblemDetails`
`403`	Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`).	`ProblemDetails`
`404`	Not found in this organization (`resource_not_found`).	`ProblemDetails`
`422`	Invalid request (`invalid_request`); `field_errors` names the fields.	`ProblemDetails`
`503`	Not available on this server.	`ProblemDetails`

Request

curl -X PUT "$VMYARD_API_URL/v1/environments/$ENVIRONMENT_ID/vars/$KEY" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "value": "info"
}'

Response 200

{
  "created_at": "string",
  "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "current_version": {
    "change": {},
    "created_at": "string",
    "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "environment_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "files": [
      {
        "path": "notes/todo.txt",
        "size": 0
      }
    ],
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "vars": [
      "string"
    ],
    "version": 0
  },
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "is_default": false,
  "name": "staging",
  "safe_for_third_parties": false,
  "updated_at": "string"
}

Remove a variable

DELETE /v1/environments/{environment_id}/vars/{key}

API key: Authorization: Bearer vmy_… with preset full_access.
Browser session: the vmyard_session cookie and the x-csrf-token header.
Who: Owner or Admin.

Parameters

Name	In	Type	Required	Description
`environment_id`	path	`string (uuid)`	Yes
`key`	path	`string`	Yes
`X-Organization-ID`	header	`string (uuid)`	No	Required with a browser session. Optional with an API key, which fixes the organization; when sent it must match.

Responses

Status	Description	Body
`200`	A new version was written	`EnvironmentDto`
`401`	Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`).	`ProblemDetails`
`403`	Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`).	`ProblemDetails`
`404`	Unknown environment or `variable_not_found`	`ProblemDetails`
`503`	Not available on this server.	`ProblemDetails`

Request

curl -X DELETE "$VMYARD_API_URL/v1/environments/$ENVIRONMENT_ID/vars/$KEY" \
  -H "Authorization: Bearer $VMYARD_API_KEY"

Response 200

{
  "created_at": "string",
  "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "current_version": {
    "change": {},
    "created_at": "string",
    "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "environment_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "files": [
      {
        "path": "notes/todo.txt",
        "size": 0
      }
    ],
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "vars": [
      "string"
    ],
    "version": 0
  },
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "is_default": false,
  "name": "staging",
  "safe_for_third_parties": false,
  "updated_at": "string"
}

Set a secret file

PUT /v1/environments/{environment_id}/files

API key: Authorization: Bearer vmy_… with preset full_access.
Browser session: the vmyard_session cookie and the x-csrf-token header.
Who: Owner or Admin.

Parameters

Name	In	Type	Required	Description
`environment_id`	path	`string (uuid)`	Yes
`X-Organization-ID`	header	`string (uuid)`	No	Required with a browser session. Optional with an API key, which fixes the organization; when sent it must match.

Request body (application/json, SecretFileInput)

Field	Type	Required	Description
`contents`	`string`	Yes
`path`	`string`	Yes	Relative to `/work`: no leading `/`, `~`, `.`, `..`, or empty components, and not under `.vmyard`.
`encoding`	`FileEncodingDto`	No

Responses

Status	Description	Body
`200`	A new version was written	`EnvironmentDto`
`401`	Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`).	`ProblemDetails`
`403`	Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`).	`ProblemDetails`
`404`	Not found in this organization (`resource_not_found`).	`ProblemDetails`
`413`	The request body is too large (`body_too_large`).	`ProblemDetails`
`422`	Invalid request (`invalid_request`); `field_errors` names the fields.	`ProblemDetails`
`503`	Not available on this server.	`ProblemDetails`

Request

curl -X PUT "$VMYARD_API_URL/v1/environments/$ENVIRONMENT_ID/files" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "path": "secrets/token.txt",
  "contents": "s3cr3t\n"
}'

Response 200

{
  "created_at": "string",
  "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "current_version": {
    "change": {},
    "created_at": "string",
    "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "environment_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "files": [
      {
        "path": "notes/todo.txt",
        "size": 0
      }
    ],
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "vars": [
      "string"
    ],
    "version": 0
  },
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "is_default": false,
  "name": "staging",
  "safe_for_third_parties": false,
  "updated_at": "string"
}

Remove a secret file

DELETE /v1/environments/{environment_id}/files

API key: Authorization: Bearer vmy_… with preset full_access.
Browser session: the vmyard_session cookie and the x-csrf-token header.
Who: Owner or Admin.

Parameters

Name	In	Type	Required	Description
`environment_id`	path	`string (uuid)`	Yes
`X-Organization-ID`	header	`string (uuid)`	No	Required with a browser session. Optional with an API key, which fixes the organization; when sent it must match.

Request body (application/json, RemoveFileRequest)

Field	Type	Required	Description
`path`	`string`	Yes

Responses

Status	Description	Body
`200`	A new version was written	`EnvironmentDto`
`401`	Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`).	`ProblemDetails`
`403`	Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`).	`ProblemDetails`
`404`	Unknown environment or `file_not_found`	`ProblemDetails`
`422`	Invalid request (`invalid_request`); `field_errors` names the fields.	`ProblemDetails`
`503`	Not available on this server.	`ProblemDetails`

Request

curl -X DELETE "$VMYARD_API_URL/v1/environments/$ENVIRONMENT_ID/files" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "path": "secrets/token.txt"
}'

Response 200

{
  "created_at": "string",
  "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "current_version": {
    "change": {},
    "created_at": "string",
    "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "environment_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "files": [
      {
        "path": "notes/todo.txt",
        "size": 0
      }
    ],
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "vars": [
      "string"
    ],
    "version": 0
  },
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "is_default": false,
  "name": "staging",
  "safe_for_third_parties": false,
  "updated_at": "string"
}

List versions

GET /v1/environments/{environment_id}/versions

API key: Authorization: Bearer vmy_… with preset read_only, use_existing, create_and_use, full_access.
Browser session: the vmyard_session cookie.
Who: Any member.

Parameters

Name	In	Type	Required	Description
`environment_id`	path	`string (uuid)`	Yes
`X-Organization-ID`	header	`string (uuid)`	No	Required with a browser session. Optional with an API key, which fixes the organization; when sent it must match.

Responses

Status	Description	Body
`200`	—	`EnvironmentVersionList`
`401`	Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`).	`ProblemDetails`
`404`	Not found in this organization (`resource_not_found`).	`ProblemDetails`

Request

curl "$VMYARD_API_URL/v1/environments/$ENVIRONMENT_ID/versions" \
  -H "Authorization: Bearer $VMYARD_API_KEY"

Response 200

{
  "items": [
    {
      "change": {},
      "created_at": "string",
      "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "environment_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "files": [
        {
          "path": "notes/todo.txt",
          "size": 0
        }
      ],
      "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "vars": [
        "string"
      ],
      "version": 0
    }
  ]
}

Reveal values

POST /v1/environments/{environment_id}/reveal

API key: Authorization: Bearer vmy_… with preset full_access.
Browser session: the vmyard_session cookie and the x-csrf-token header.
Who: Owner or Admin.

Parameters

Name	In	Type	Required	Description
`environment_id`	path	`string (uuid)`	Yes
`X-Organization-ID`	header	`string (uuid)`	No	Required with a browser session. Optional with an API key, which fixes the organization; when sent it must match.

Request body (application/json, RevealRequest)

Field	Type	Required	Description
`version_id`	`string (uuid) \| null`	No	A version of this environment; omitted reveals the current version.

Responses

Status	Description	Body
`200`	Values and file contents; audited as `environment.revealed`	`RevealedEnvironmentDto`
`401`	Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`).	`ProblemDetails`
`403`	A role other than owner/admin, or an API key without full_access	`ProblemDetails`
`404`	Not found in this organization (`resource_not_found`).	`ProblemDetails`
`503`	Not available on this server.	`ProblemDetails`

Request

curl -X POST "$VMYARD_API_URL/v1/environments/$ENVIRONMENT_ID/reveal" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response 200

{
  "environment_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "files": [
    {
      "contents": "string",
      "encoding": "text",
      "path": "notes/todo.txt"
    }
  ],
  "vars": {},
  "version": {
    "change": {},
    "created_at": "string",
    "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "environment_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "files": [
      {
        "path": "notes/todo.txt",
        "size": 0
      }
    ],
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "vars": [
      "string"
    ],
    "version": 0
  }
}

Upgrade machines

POST /v1/environments/{environment_id}/upgrade

API key: Authorization: Bearer vmy_… with preset use_existing, create_and_use, full_access.
Browser session: the vmyard_session cookie and the x-csrf-token header.
Who: Owner, Admin, or Operator.

Parameters

Name	In	Type	Required	Description
`environment_id`	path	`string (uuid)`	Yes
`X-Organization-ID`	header	`string (uuid)`	No	Required with a browser session. Optional with an API key, which fixes the organization; when sent it must match.

Request body (application/json, UpgradeEnvironmentRequest)

Field	Type	Required	Description
`machine_ids`	`string (uuid)[] \| null`	No	Machines to upgrade; omitted upgrades every running machine created with this environment. At most 100.

Responses

Status	Description	Body
`202`	One apply operation per upgraded machine; repeating the request replays them	`UpgradeEnvironmentResponse`
`401`	Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`).	`ProblemDetails`
`403`	Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`).	`ProblemDetails`
`404`	Not found in this organization (`resource_not_found`).	`ProblemDetails`
`409`	`environment_upgrade_conflict`: a machine changed meanwhile; retry	`ProblemDetails`
`422`	A machine is not one created with this environment	`ProblemDetails`

Request

curl -X POST "$VMYARD_API_URL/v1/environments/$ENVIRONMENT_ID/upgrade" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "machine_ids": [
    "0b6f6c55-2f1d-4f0e-9a51-6f0f4cba7a10"
  ]
}'

Response 202

{
  "environment_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operations": [
    {
      "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "operation_url": "/v1/operations/6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
    }
  ],
  "skipped": [
    {
      "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "reason": "not_running"
    }
  ],
  "version": 0,
  "version_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
}