Skip to content
Developer portal

Resume a terminal session

POST
/v1/terminal_sessions/{id}/resume
curl --request POST \
  --url https://terminal.api.example.com/v1/terminal_sessions/example/resume

Called by the terminal to pick an interrupted session back up, before its recovery_deadline. The session is active again and its last heartbeat moves to now. Resuming an active session answers it as it is, so it is safe to repeat. Takes no body.

Past the deadline the session has expired, and the terminal opens a new one.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string

The object’s id.

Responses

Section titled “Responses”

200

Section titled “200”

The session, active.

Media typeapplication/json
object
id
required

The session’s id, used in the path of its heartbeat, resume and close.

string
object
required
string
Allowed value: terminal_session
livemode
required

Always true. A terminal is a live device; there are no test terminals.

boolean
terminal_id
required

The terminal that opened it, the only one that can use it.

string
status
required

active while it takes heartbeats; recoverable_interrupted once it missed them, until it is resumed or its recovery_deadline passes; expired and closed are final.

string
Allowed values: active recoverable_interrupted expired closed
opened_at
required

When it was opened, as a Unix timestamp.

integer
last_heartbeat_at
required

The last time the terminal showed it was alive on it, by opening, a heartbeat or a resume, as a Unix timestamp.

integer
interrupted_at
required

When it was interrupted for missing its heartbeats, while it is recoverable_interrupted.

integer | null
recovery_deadline
required

The last moment it can be resumed, while it is recoverable_interrupted.

integer | null
expires_at
required

When it ends, however well it heartbeats, as a Unix timestamp.

integer
expired_at
required

When it expired, once it is expired.

integer | null
closed_at
required

When it was closed, once it is closed.

integer | null
Example
{
  "id": "6d0f3b8e-2c4a-4f7e-9b1d-8a5c3e7f2b10",
  "object": "terminal_session",
  "livemode": true,
  "terminal_id": "3f6c2a9e-8b41-4d7a-9e25-0c1b7d4f8a63",
  "status": "active",
  "opened_at": 1791000000,
  "last_heartbeat_at": 1791000200,
  "interrupted_at": null,
  "recovery_deadline": null,
  "expires_at": 1791043200,
  "expired_at": null,
  "closed_at": null
}

401

Section titled “401”

authentication_failure with terminal_credential_refused: the certificate does not count, or the terminal is suspended or retired. See Pairing a terminal.

Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: validation_failure authentication_failure authorization_failure not_found conflict timeout_or_in_progress policy_rejection invariant_violation rate_limited dependency_failure
code
required

A stable name for this refusal. Branch on this, never on message.

string
message
required

For the developer reading a log. May be reworded.

string
param
required

The field or parameter at fault, when there is one.

string | null
request_id
required
string | null
Example
{
  "error": {
    "type": "validation_failure"
  }
}

404

Section titled “404”

not_found with resource_missing: this terminal has no session with this id. Another terminal’s session reads the same.

Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: validation_failure authentication_failure authorization_failure not_found conflict timeout_or_in_progress policy_rejection invariant_violation rate_limited dependency_failure
code
required

A stable name for this refusal. Branch on this, never on message.

string
message
required

For the developer reading a log. May be reworded.

string
param
required

The field or parameter at fault, when there is one.

string | null
request_id
required
string | null
Example
{
  "error": {
    "type": "validation_failure"
  }
}

422

Section titled “422”

invariant_violation: the session cannot be resumed. code says where it is:

code Meaning
session_expired Its recovery window ran out, or it reached its longest lifetime. Open a new one.
session_closed It is closed. Open a new one.
Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: validation_failure authentication_failure authorization_failure not_found conflict timeout_or_in_progress policy_rejection invariant_violation rate_limited dependency_failure
code
required

A stable name for this refusal. Branch on this, never on message.

string
message
required

For the developer reading a log. May be reworded.

string
param
required

The field or parameter at fault, when there is one.

string | null
request_id
required
string | null
Example
{
  "error": {
    "type": "invariant_violation",
    "code": "session_expired",
    "message": "This session has expired. Open a new one.",
    "param": null,
    "request_id": "req_8d2f6b4a9c1e"
  }
}

503

Section titled “503”

dependency_failure with service_unavailable: the platform did not answer, or failed part-way. Whether the call took effect is not known. Retry the same request: a heartbeat is safe to repeat, and if a retry is refused because the session is already as the call would leave it (for example session_closed after a close), the first call took effect.

Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: validation_failure authentication_failure authorization_failure not_found conflict timeout_or_in_progress policy_rejection invariant_violation rate_limited dependency_failure
code
required

A stable name for this refusal. Branch on this, never on message.

string
message
required

For the developer reading a log. May be reworded.

string
param
required

The field or parameter at fault, when there is one.

string | null
request_id
required
string | null
Example
{
  "error": {
    "type": "validation_failure"
  }
}