temperDocs
QuickstartAPItemper.im
Menu

API reference

Agent

Agent packages and gradual rollouts (Agent upgrades).

Upload an Agent package

PUT/v1/agent/packages/{version}

The request body is the squashfs file itself (it must start with the magic bytes hsqs), at most 2 GiB; the control plane computes its sha256 as it receives it. Content-Type is not checked; application/octet-stream is recommended. A version is immutable once uploaded: uploading the same content for the same version again returns 200; different content returns 409 version_exists.

Request body application/octet-stream

Responses

  • 200This version already exists with the same content Package
  • 201New version Package
  • 400Invalid parameters: validation failed, the body is not valid JSON, or the query string could not be parsed (all returned in the same JSON shape).
  • 401Missing, invalid or revoked key
  • 409State conflict; `error` holds the specific code
  • 413The request body exceeds the size limit (`payload_too_large`)
  • 500Internal error (details are recorded only in server logs)

List Agent packages and the default version

GET/v1/agent/packages

In ascending upload order, not paginated.

Responses

  • 200Packages PackageList
  • 401Missing, invalid or revoked key
  • 500Internal error (details are recorded only in server logs)

Set the default version

PUT/v1/agent/default

Used for new environments that do not specify agent_version. A version that has not been uploaded returns 400 (not 404). Existing environments are not affected; to upgrade them, use a rollout.

Request body application/json · SetDefaultVersionRequest

FieldTypeDescription
versionrequiredstring

Responses

  • 200Set DefaultVersion
  • 400Invalid parameters: validation failed, the body is not valid JSON, or the query string could not be parsed (all returned in the same JSON shape).
  • 401Missing, invalid or revoked key
  • 415Missing `Content-Type: application/json` (`unsupported_media_type`)
  • 422The JSON does not match the schema: a missing field, a wrong type or enum value, or an unknown field (`invalid_body`)
  • 500Internal error (details are recorded only in server logs)

List rollouts

GET/v1/agent/rollouts

Newest first, at most 100, not paginated (no next).

Responses

  • 200Rollouts RolloutList
  • 401Missing, invalid or revoked key
  • 500Internal error (details are recorded only in server logs)

Start a rollout

POST/v1/agent/rollouts

Upgrades percent% of environments (chosen by hash(rollout id, environment id), so the selection is stable and raising the percentage only adds environments) to version in batches: batch_size environments per batch, moving to the next batch only once the current one is healthy; if failures exceed max_failures, the rollout is rolled back automatically. Environments that are not running only have their version changed and are not woken. When the percentage is 100% and every environment has been switched, the rollout becomes completed and the developer's default version is set to it as well. Each developer can have only one active or paused rollout at a time; otherwise 409 rollout_in_progress. A version that has not been uploaded returns 400.

Request body application/json · StartRolloutRequest

FieldTypeDescription
versionrequiredstring
percentrequiredinteger
batch_sizeinteger

Number of environments switched at the same time per batch

max_failuresinteger

Roll back automatically when failures exceed this number

Responses

  • 201Started Rollout
  • 400Invalid parameters: validation failed, the body is not valid JSON, or the query string could not be parsed (all returned in the same JSON shape).
  • 401Missing, invalid or revoked key
  • 409State conflict; `error` holds the specific code
  • 415Missing `Content-Type: application/json` (`unsupported_media_type`)
  • 422The JSON does not match the schema: a missing field, a wrong type or enum value, or an unknown field (`invalid_body`)
  • 500Internal error (details are recorded only in server logs)

Get a rollout (with per-environment progress)

GET/v1/agent/rollouts/{id}

Responses

  • 200The rollout and the environments whose version it changed RolloutDetail
  • 401Missing, invalid or revoked key
  • 404Does not exist, or does not belong to this developer (`no such resource`); for a nonexistent route `message` is `no such route`
  • 500Internal error (details are recorded only in server logs)

Increase the percentage

PATCH/v1/agent/rollouts/{id}

The percentage can only be raised (equal to the current value is also allowed): lowering it amounts to a partial rollback, so use rollback instead. A value below the current one or above 100 returns 400; only active / paused rollouts can be changed; others return 409 invalid_state_transition.

Request body application/json · WidenRolloutRequest

FieldTypeDescription
percentrequiredinteger

Not lower than the current percentage

Responses

  • 200Rollout Rollout
  • 400Invalid parameters: validation failed, the body is not valid JSON, or the query string could not be parsed (all returned in the same JSON shape).
  • 401Missing, invalid or revoked key
  • 404Does not exist, or does not belong to this developer (`no such resource`); for a nonexistent route `message` is `no such route`
  • 409State conflict; `error` holds the specific code
  • 415Missing `Content-Type: application/json` (`unsupported_media_type`)
  • 422The JSON does not match the schema: a missing field, a wrong type or enum value, or an unknown field (`invalid_body`)
  • 500Internal error (details are recorded only in server logs)

Pause

POST/v1/agent/rollouts/{id}/pause

Only an active rollout can be paused; anything else (including one that is already paused) returns 409 invalid_state_transition. Not idempotent.

Responses

  • 200Rollout Rollout
  • 401Missing, invalid or revoked key
  • 404Does not exist, or does not belong to this developer (`no such resource`); for a nonexistent route `message` is `no such route`
  • 409State conflict; `error` holds the specific code
  • 500Internal error (details are recorded only in server logs)

Resume

POST/v1/agent/rollouts/{id}/resume

Only a paused rollout can be resumed; anything else (including one that is already active) returns 409 invalid_state_transition.

Responses

  • 200Rollout Rollout
  • 401Missing, invalid or revoked key
  • 404Does not exist, or does not belong to this developer (`no such resource`); for a nonexistent route `message` is `no such route`
  • 409State conflict; `error` holds the specific code
  • 500Internal error (details are recorded only in server logs)

Roll back manually

POST/v1/agent/rollouts/{id}/rollback

Switches the upgraded environments back to their original version (the host daemon replaces the VMs right away); rolling back a completed rollout also restores the previous default version. A rollout that is already rolled_back is returned unchanged. Only the developer's most recent rollout can be rolled back; otherwise 409 not_latest_rollout.

Responses

  • 200Rollout Rollout
  • 401Missing, invalid or revoked key
  • 404Does not exist, or does not belong to this developer (`no such resource`); for a nonexistent route `message` is `no such route`
  • 409State conflict; `error` holds the specific code
  • 500Internal error (details are recorded only in server logs)