Manage Tunnels

A read-mostly surface on tunnel resources: list, get, and update metadata. Tunnels are provisioned and destroyed via the identity surface — see Create identity and Delete identity. See the Tunnels API overview for naming rules, lifecycle states, and TLS modes.

List tunnels

GET /tunnels

List all tunnels in the caller’s organization. Each entry includes a live currently_connected flag.

Response (200)

JSON

{
  "tunnels": [
    {
      "id": "t1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "tunnel_name": "my-agent",
      "agent_identity_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "tls_mode": "edge",
      "status": "active",
      "currently_connected": true,
      "last_connected_at": "2026-04-21T12:35:00Z",
      "last_disconnected_at": "2026-04-21T12:30:00Z",
      "...": "additional fields per Tunnel object"
    }
  ]
}

Code examples

curl -X GET "https://inkbox.ai/api/v1/tunnels" \
  -H "X-API-Key: YOUR_API_KEY"

const response = await fetch("https://inkbox.ai/api/v1/tunnels", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { tunnels } = await response.json();

import requests

response = requests.get(
    "https://inkbox.ai/api/v1/tunnels",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
tunnels = response.json()["tunnels"]

Get tunnel

GET /tunnels/{tunnel_id}

Fetch a single tunnel by ID. Includes a live currently_connected flag.

Path parameters

Parameter	Type	Description
`tunnel_id`	UUID	Tunnel ID

Code examples

curl -X GET "https://inkbox.ai/api/v1/tunnels/TUNNEL_ID" \
  -H "X-API-Key: YOUR_API_KEY"

const response = await fetch(
  `https://inkbox.ai/api/v1/tunnels/${tunnelId}`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const tunnel = await response.json();

import requests

response = requests.get(
    f"https://inkbox.ai/api/v1/tunnels/{tunnel_id}",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
tunnel = response.json()

Update tunnel

PATCH /tunnels/{tunnel_id}

Update the tunnel’s metadata. The tunnel name matches its owning identity’s handle and is fixed at creation, as is the TLS mode. Sending tunnel_name in a PATCH body returns 422, including the current name or null; metadata in that rejected request is not applied.

Path parameters

Parameter	Type	Description
`tunnel_id`	UUID	Tunnel ID

Request body

Field	Type	Required	Description
`metadata`	object \| null	No	Free-form JSON object for your own use, capped at 4 KB serialized. Pass `{}` or `null` to clear; omit to leave unchanged. Returned as-is on read.

Code examples

curl -X PATCH "https://inkbox.ai/api/v1/tunnels/TUNNEL_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {"env": "staging", "owner": "agent-platform"}
  }'

const response = await fetch(
  `https://inkbox.ai/api/v1/tunnels/${tunnelId}`,
  {
      method: "PATCH",
      headers: {
          "X-API-Key": "YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      body: JSON.stringify({
          metadata: { env: "staging", owner: "agent-platform" },
      }),
  }
);
const tunnel = await response.json();

import requests

response = requests.patch(
    f"https://inkbox.ai/api/v1/tunnels/{tunnel_id}",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "metadata": {"env": "staging", "owner": "agent-platform"},
    },
)
tunnel = response.json()

Tunnel object

Field	Type	Description
`id`	UUID	Unique tunnel identifier
`organization_id`	string	Owning organization
`agent_identity_id`	UUID \| null	ID of the associated identity, or `null` when no identity is associated.
`tunnel_name`	string	Fixed subdomain label matching the owning identity’s handle. Hostname is e.g. `my-agent.inkboxwire.com`.
`public_host`	string	Fully qualified public hostname for this tunnel (e.g. `my-agent.inkboxwire.com`). The third-party-facing endpoint.
`zone`	string	Tunnel zone host (`inkboxwire.com`). Your agent connects to `https://{zone}/_system/connect`.
`tls_mode`	string	`"edge"` or `"passthrough"`. Immutable.
`cert_pem`	string \| null	Signed cert PEM (passthrough only, after first `/sign-csr`)
`cert_fingerprint_sha256`	string \| null	SHA-256 fingerprint of `cert_pem`, useful for monitoring rotations
`cert_expires_at`	string \| null	ISO 8601 expiry of `cert_pem`. Renew before this date.
`status`	string	`awaiting_cert` or `active`
`last_connected_at`	string \| null	ISO 8601 timestamp of the most recent agent connection
`last_connected_ip_addr`	string \| null	Client IP recorded at the most recent agent connection
`last_disconnected_at`	string \| null	Best-effort ISO 8601 timestamp of the most recently observed disconnect. `null` means no disconnect has been recorded.
`currently_connected`	boolean	`true` if at least one agent connection is currently registered. Resolved live on every tunnels-endpoint read.
`metadata`	object	Free-form JSON object set via PATCH; capped at 4 KB serialized. Returned as-is. Defaults to `{}`.
`created_at`	string	ISO 8601
`updated_at`	string	ISO 8601

Agent signup API

Agent identity API

Agent2Agent API

Message retries

Mail API

Phone API

iMessage API

WhatsApp API

Slack API

Webhooks API

Tunnels API

Contacts API

Notes API

Vault API

Billing API

Manage Tunnels

List tunnels

Response (200)

Code examples

Get tunnel

Path parameters

Code examples

Update tunnel

Path parameters

Request body

Code examples

Tunnel object

​List tunnels

​Response (200)

​Code examples

​Get tunnel

​Path parameters

​Code examples

​Update tunnel

​Path parameters

​Request body

​Code examples

​Tunnel object

List tunnels

Response (200)

Code examples

Get tunnel

Path parameters

Code examples

Update tunnel

Path parameters

Request body

Code examples

Tunnel object