temperDocs
QuickstartAPItemper.im
Menu

API reference

Environments

Environments: one microVM plus one data disk per end user; environment events.

List environments

GET/v1/environments

Includes destroyed environments. Paginated in ascending order of created_at, id.

Parameters

ParameterInTypeDescription
statequeryEnvironmentState

Only list environments whose actual state is this value. The value is not validated; an unknown state gives an empty list.

limitqueryinteger

Items per page, default 50; values outside 1–200 are clamped into that range (no error).

afterquerystring

The previous page's next.

Responses

  • 200A page of environments EnvironmentList
  • 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
  • 500Internal error (details are recorded only in server logs)

Create an environment

POST/v1/environments

An end user can have only one environment that has not been destroyed; creating another returns 409 environment_exists with the existing environment's id in environment_id. To retry safely after a timeout, send an Idempotency-Key header: a retry with the same key returns the environment the first request created, with status 200. Keys are scoped to the developer and stay bound to that environment until it is destroyed; reusing a key for a different end user returns 409 idempotency_key_reused. If agent_version is omitted, the developer's default version is used (PUT /v1/agent/default; it is also updated when a rollout completes); if there is none, it is null. template picks a template version (name:version); it must be ready, otherwise 409 template_not_ready. A version that does not exist returns 400. Without it the environment uses the platform's default runtime. A new environment has desired_state = running and state = pending; it becomes running once the scheduler places it on a host and the host daemon has started the VM.

Parameters

ParameterInTypeDescription
Idempotency-Keyheaderstring

1–255 visible ASCII characters, for example a UUID generated by the client per logical create.

Request body application/json · CreateEnvironmentRequest

FieldTypeDescription
end_user_idrequiredstring

Your own id for the end user

agent_versionstring | null

If omitted, the developer's default version is used. Whether the version has been uploaded is not checked.

resourcesResourcesInput

All optional; defaults are 2 vCPUs, a 4096 MiB memory limit, 1024 MiB base memory and a 10 GiB disk.

idleIdleSettingsInput

Idle thresholds (seconds); 0 = this tier is never applied automatically, otherwise 60–7776000 (90 days). Both thresholds count from the last activity: by default an environment is suspended after 6 hours idle and stopped after 7 days idle, so keep stop_after_secs larger than suspend_after_secs. With suspension turned off (0) the environment is never stopped either.

envConfigEnv

Environment variables, at most 100 and 32 KiB in total. Names are letters, digits and _, not starting with a digit, up to 128 characters. The platform's proxy and certificate variables (HTTP_PROXY, HTTPS_PROXY, NO_PROXY, ALL_PROXY, SSL_CERT_FILE, SSL_CERT_DIR, REQUESTS_CA_BUNDLE, CURL_CA_BUNDLE, NODE_EXTRA_CA_CERTS, GIT_SSL_CAINFO, in any case), HOME, USER, LOGNAME and names starting with TEMPER_ are reserved. Values are up to 4096 bytes, without single quotes or control characters other than tab.

filesConfigFiles

Files by name, at most 20 and 256 KiB in total (decoded). Names are letters, digits, ., _ and -, not starting with . or -, up to 128 characters.

secretsmap of PutSecretRequest

Environment-level secrets by name (an environment can have at most 100; so can the developer level), created in the same transaction as the environment (same fields and rules as PUT /v1/environments/{id}/secrets/{name}). If any is invalid, nothing is created. Their placeholders exist before the VM first starts.

egress_allowarray of string

The environment's own egress allowlist (same as allow in PUT /v1/environments/{id}/egress). Omitted = use the developer-level list.

templatestring | null

Template version as name:version (see createTemplateVersion); it must be ready. Omitted or null = the platform's default runtime. An environment stays on its template version; changing it means moving the environment to a new VM, like an Agent upgrade.

Responses

  • 200A retry with the same `Idempotency-Key`; the environment the first request created Environment
  • 201Created Environment
  • 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)

Create environments in bulk

POST/v1/environments/batch

1–200 environments, created one by one; one failure does not affect the others. Results are returned in request order, with HTTP status 200. Parameter errors for a single environment (the 400 kind) and conflicts are reported in that item's result; if the request as a whole does not match the schema (for example, one item has an unknown field), the response is 422 and nothing is created.

Request body application/json · BatchCreateRequest

FieldTypeDescription
environmentsrequiredarray of CreateEnvironmentRequest

Responses

  • 200The result for each item BatchCreateResponse
  • 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)

Get an environment

GET/v1/environments/{id}

Responses

  • 200Environment Environment
  • 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)

Destroy an environment

DELETE/v1/environments/{id}

Sets the desired state to destroyed; the host daemon deletes the VM, the data disk and the backups. Returns 200 with the environment (not 204). Calling it again on a destroyed environment still succeeds. After destruction, the same end user can create a new environment.

Responses

  • 200Environment (desired_state = destroyed) Environment
  • 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)

Suspend (memory snapshot)

POST/v1/environments/{id}/suspend

Only an environment whose desired state is running can be suspended; one that is already suspended is returned unchanged; stopped / destroyed returns 409 invalid_state_transition.

Responses

  • 200Environment Environment
  • 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/environments/{id}/resume

suspended / stopped → running; one that is already running is returned unchanged; destroyed returns 409. Unlike wake, this does not count as activity.

Responses

  • 200Environment Environment
  • 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)

Get an environment's configuration

GET/v1/environments/{id}/config

The non-secret environment variables and files set at creation or with PUT. Empty objects if none were set.

Responses

  • 200Configuration EnvironmentConfig
  • 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)

Replace an environment's configuration

PUT/v1/environments/{id}/config

Replaces env and files as a whole (send {} to clear them). Does not wake a suspended environment and does not replace the VM. A running environment sees the new files within about 10 seconds. New environment variables apply to processes started afterwards (each exec, and the Agent the next time it starts); a process that is already running keeps its environment. A destroyed environment gives 409 environment_destroyed.

Request body application/json · EnvironmentConfig

FieldTypeDescription
envConfigEnv

Environment variables, at most 100 and 32 KiB in total. Names are letters, digits and _, not starting with a digit, up to 128 characters. The platform's proxy and certificate variables (HTTP_PROXY, HTTPS_PROXY, NO_PROXY, ALL_PROXY, SSL_CERT_FILE, SSL_CERT_DIR, REQUESTS_CA_BUNDLE, CURL_CA_BUNDLE, NODE_EXTRA_CA_CERTS, GIT_SSL_CAINFO, in any case), HOME, USER, LOGNAME and names starting with TEMPER_ are reserved. Values are up to 4096 bytes, without single quotes or control characters other than tab.

filesConfigFiles

Files by name, at most 20 and 256 KiB in total (decoded). Names are letters, digits, ., _ and -, not starting with . or -, up to 128 characters.

Responses

  • 200The stored configuration EnvironmentConfig
  • 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)

Environment events

GET/v1/environments/{id}/events

State changes, desired-state changes, idle tiers, scheduled wakeups, Agent upgrades, actions registered by the Agent itself, and so on, in ascending id order (that is, chronological). Destroyed environments can be queried too. Pagination uses an integer cursor: pass next back as after; next is non-null only when the page is full (its item count equals limit).

Parameters

ParameterInTypeDescription
afterqueryinteger (int64)

The previous page's next (the id of the last event on that page). 400 if it is not an integer.

limitqueryinteger

Items per page, default 100; values outside 1–200 are clamped into that range (no error).

kindquerystring

Only return this kind of event (for example created, desired_suspended, agent_upgrade). The value is not validated.

Responses

  • 200A page of events EnvironmentEventList
  • 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`
  • 500Internal error (details are recorded only in server logs)