temperDocs
QuickstartAPItemper.im
Menu

API reference

Idle

Idle tiers, waking, keep-awake and scheduled wakeups (suspend / wake and idle policy).

Wake (call when a request arrives)

POST/v1/environments/{id}/wake

A suspended environment is restored from its snapshot; a stopped one gets a VM from the pre-booted pool; one that is already running just records activity (pushing back last_active_at). destroyed returns 409.

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)

Keep awake

POST/v1/environments/{id}/keep-awake

For seconds seconds from now the environment will not be suspended by the idle tiers (an existing later keep_awake_until is not shortened); if it is not running, it is woken as well. Records activity and a keep_awake event.

Request body application/json · KeepAwakeRequest

FieldTypeDescription
secondsrequiredinteger

Responses

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

Update idle thresholds

PATCH/v1/environments/{id}/idle

Only the fields provided are changed. 0 = this tier is never applied automatically. A destroyed environment returns 409 environment_destroyed.

Request body application/json · IdlePatch

FieldTypeDescription
suspend_after_secsIdleSecs

0 or 60–7776000.

stop_after_secsIdleSecs

0 or 60–7776000.

Responses

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

List wakeups that have not fired or been cancelled

GET/v1/environments/{id}/wakeups

Sorted by time, not paginated.

Responses

  • 200Scheduled wakeups WakeupList
  • 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)

Schedule a one-time wakeup

POST/v1/environments/{id}/wakeups

One-time: the control plane wakes the environment a configured lead time (120 seconds by default) ahead, and counts activity at the scheduled time. For recurring work, schedule the next wakeup after each run, or let the Agent register cron rules itself (see schedules). The time can be at most 1 minute in the past (fires immediately) and at most 366 days in the future; each environment can have at most 100 pending wakeups, beyond which 429 wakeup_limit_reached is returned. A destroyed environment returns 409 environment_destroyed.

Request body application/json · CreateWakeupRequest

FieldTypeDescription
atrequiredstring (date-time)

RFC 3339, from 1 minute ago to 366 days ahead

reasonstring

Responses

  • 201Scheduled Wakeup
  • 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`)
  • 429A count limit was reached (this is not rate limiting; retrying will not help until something is released)
  • 500Internal error (details are recorded only in server logs)

Cancel a scheduled wakeup

DELETE/v1/environments/{id}/wakeups/{wakeup}

A wakeup that has already fired or been cancelled returns 404 (not idempotent).

Responses

  • 204Cancelled
  • 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)