Skip to content
Developer portal

Send a heartbeat

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

Called by the terminal every heartbeat_interval_seconds to say it is alive. Moves the session’s last_heartbeat_at to now and changes nothing else, so it is safe to repeat. Takes no body.

A session that missed its heartbeats is recoverable_interrupted, and a heartbeat does not bring it back: resume it. A session is interrupted once 3 heartbeat intervals (90 seconds by default) have passed after its last heartbeat, so a heartbeat that arrives only at the third interval is already refused. Time is checked on every heartbeat, resume and close, whether or not the platform’s timer has run.

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, still 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": 1791000030,
  "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 takes no heartbeat now. code says where it is:

code Meaning
session_interrupted It missed its heartbeats. Resume it.
session_expired It was not resumed in time, or 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_interrupted",
    "message": "This session was interrupted. Resume it.",
    "param": null,
    "request_id": "req_5e3a9c1d7b4f"
  }
}

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"
  }
}