Tunnels API
A tunnel gives your agent a stable public URL — {tunnel_name}.inkboxwire.com — that routes inbound HTTP, WebSocket, and raw-TCP traffic from third parties to your agent over a single persistent connection. No public IP, firewall hole, or reverse proxy needed on your end.
API base URL:
https://inkbox.ai/api/v1/tunnelsQuick start
Create an account and get your API key from the Inkbox console:
Get API keyX-API-Key: YOUR_API_KEYTunnel naming rules
Pick a name when you create the tunnel — it becomes the subdomain at {tunnel_name}.inkboxwire.com.
- 3–63 characters
- lowercase letters, digits, and hyphens only
- must start and end with a letter or digit
- no consecutive hyphens
Some names are reserved; you'll get a 409 if you pick one. Names are unique across all Inkbox customers within an environment.
Lifecycle states
A tunnel always has one of four status values:
| Status | Meaning |
|---|---|
awaiting_cert | Passthrough mode only. The tunnel is provisioned but you haven't signed a CSR yet. |
active | Routable end-to-end. Inbound traffic flows to your agent. |
delete_pending | You called DELETE. Inbound traffic stops immediately. The name stays reserved for 24 hours so you can restore if it was a mistake. |
deleted | Terminal. The name is released and may be claimed by anyone. |
TLS modes
Choose at creation time; immutable afterwards.
| Mode | Who terminates TLS | Setup | When to use |
|---|---|---|---|
edge (default) | Inkbox at our edge, with a managed cert | Zero — active immediately | Most users. Webhooks, real-time APIs, simple integrations. |
passthrough | You, in your own agent | Sign a CSR via /sign-csr; we issue a 90-day cert | Compliance constraints requiring TLS to terminate inside your network, or client-side cert pinning. |
See Passthrough TLS for the full passthrough flow.
Connecting your agent
When you create a tunnel, the response includes a one-time connect_secret. Your agent uses this secret to open a persistent connection to your tunnel hostname; once connected, inbound traffic from third parties is routed to your agent in real time.
The connect_secret is shown once at creation — store it securely. If you lose it, rotate it via Connect secret.
SDK helpers for the agent-side connection are coming soon. For early access to the connection protocol, contact us.
Manage tunnels
Create tunnel
POSTProvision a new tunnel and receive its connect secret
/api/v1/tunnelsList tunnels
GETList all tunnels in your organization
/api/v1/tunnelsGet tunnel
GETGet a single tunnel by ID, including live connection status
/api/v1/tunnels/{tunnel_id}Update tunnel
PATCHUpdate description or metadata (name and TLS mode are immutable)
/api/v1/tunnels/{tunnel_id}Delete tunnel
DELETETake a tunnel offline; restorable for 24 hours
/api/v1/tunnels/{tunnel_id}Restore tunnel
POSTUndo a delete during the 24-hour grace window
/api/v1/tunnels/{tunnel_id}/restoreForce-delete tunnel
DELETESkip the grace window and finalize a pending delete (admin only)
/api/v1/tunnels/{tunnel_id}/force