Sign in
Tunnels

Update Tunnel

patch/api/v1/tunnels/{tunnel_id}

Path parameters

tunnel_idstring uuid required

Request body

metadataobject nullable

Free-form metadata dict; pass null or {} to clear (both clear to {} since the underlying column is non-nullable). Capped at 4 KB serialized JSON.

Response

Successful Response

idstring uuid required
organization_idstring required
tunnel_namestring required
agent_identity_idstring uuid nullable

Identifier of the identity associated with this tunnel, when available.

tls_mode'edge' | 'passthrough' required
cert_pemstring nullable
cert_fingerprint_sha256string nullable
cert_expires_atstring date-time nullable
status'awaiting_cert' | 'active' | 'deleted' required
last_connected_atstring date-time nullable
last_connected_ip_addrstring nullable

Caller IP (leftmost X-Forwarded-For hop, falling back to the direct peer) recorded at the most recent /_system/hello.

last_disconnected_atstring date-time nullable

Best-effort timestamp of the most recently observed transition from connected to disconnected. Null means no disconnect has been recorded. Use currently_connected for current liveness.

currently_connectedboolean required

Live agent-connection state at read time: true if at least one agent connection is registered in Redis. Always resolved live on every tunnels endpoint — runtime state never appears as a stale placeholder. Identity payloads embed TunnelSummaryResponse instead, which carries no liveness.

public_hoststring required

Per-tunnel public hostname, e.g. my-agent.inkboxwire.com in production (non-production environments include the environment label in the tunnel zone, e.g. my-agent.beta.inkboxwire.com). Use this for constructing the public URL the third party hits.

zonestring required

Tunnel zone host, e.g. inkboxwire.com in production. Use this as the data-plane h2 endpoint — the agent connects to https://{zone}/_system/connect, not to https://{public_host}/_system/connect.

metadataobject

Customer-supplied free-form metadata, set via PATCH /tunnels/{id} with metadata={...}. Returned as-is on read. Empty dict ({}) when unset or cleared. Capped at 4 KB serialized JSON; over-limit writes return 422.

created_atstring date-time required
updated_atstring date-time required

Changes

No recorded changes to this endpoint across all 1 revision of this API.