---
title: "Update Tunnel"
method: PATCH
path: "/api/v1/tunnels/{tunnel_id}"
tags: ["Tunnels"]
---

# Update Tunnel

`PATCH /api/v1/tunnels/{tunnel_id}`

## Path parameters

- `tunnel_id` string, uuid, required

## Request body

- UpdateTunnelRequest
  - `metadata` object, 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 `200`

Successful Response

- TunnelResponse
  - `id` string, uuid, required
  - `organization_id` string, required
  - `tunnel_name` string, required
  - `agent_identity_id` string, uuid, nullable — Identifier of the identity associated with this tunnel, when available.
  - `tls_mode` 'edge' | 'passthrough', required
  - `cert_pem` string, nullable
  - `cert_fingerprint_sha256` string, nullable
  - `cert_expires_at` string, date-time, nullable
  - `status` 'awaiting_cert' | 'active' | 'deleted', required
  - `last_connected_at` string, date-time, nullable
  - `last_connected_ip_addr` string, nullable — Caller IP (leftmost X-Forwarded-For hop, falling back to the direct peer) recorded at the most recent /_system/hello.
  - `last_disconnected_at` string, 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_connected` boolean, 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_host` string, 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.
  - `zone` string, 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``.
  - `metadata` object — 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_at` string, date-time, required
  - `updated_at` string, date-time, required

## Other responses

- `422` — Validation Error
- `4XX` — Client error with Support Agent information.
- `5XX` — Server error with Support Agent information.

---

[API](https://skmtc.dev/inkbox/apis/inkbox-api.md) · [All operations](https://skmtc.dev/inkbox/apis/inkbox-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/inkbox/inkbox-api/revisions/31f357e7e6f8/schema)