API: Tunnels

Base URL: https://tunnel.nullbore.com/v1

All endpoints require authentication via Authorization: Bearer nbk_your_key.

Create a tunnel

POST /v1/tunnels

Request

{
  "local_port": 3000,
  "name": "myapp",
  "ttl": "1h",
  "idle_ttl": true
}

Field	Type	Required	Description
`local_port`	int	yes	Local port to tunnel (1-65535)
`name`	string	no	Custom subdomain name (Hobby+ plans). 2-63 chars, lowercase alphanumeric + hyphens.
`ttl`	string	no	Time to live (Go duration: `30m`, `4h`, `168h`). Default: `1h`.
`idle_ttl`	bool	no	If true, TTL resets on activity (idle timeout mode). Default: `false`.

Response

{
  "id": "b1d0df1b-9b8c-43e1-b193-e1b3ff24e986",
  "slug": "myapp",
  "client_id": "client-1",
  "local_port": 3000,
  "name": "myapp",
  "ttl": "1h0m0s",
  "mode": "relay",
  "created_at": "2026-03-30T14:30:00Z",
  "expires_at": "2026-03-30T15:30:00Z",
  "idle_ttl": true,
  "bytes_in": 0,
  "bytes_out": 0,
  "requests": 0
}

The tunnel URL will be https://{slug}.tunnel.nullbore.com (or https://tunnel.nullbore.com/t/{slug}).

Errors

Status	Error	Cause
400	`invalid request body`	Malformed JSON
400	`local_port must be 1-65535`	Port out of range
400	`invalid ttl format`	Bad duration string
400	`tunnel name must be...`	Name validation failed
409	`name already in use`	Another tunnel has this name
429	`rate limit exceeded`	Too many creates (10/min/client)

List tunnels

GET /v1/tunnels

Response

{
  "tunnels": [
    {
      "id": "b1d0df1b-...",
      "slug": "myapp",
      "local_port": 3000,
      "ttl": "1h0m0s",
      "created_at": "2026-03-30T14:30:00Z",
      "expires_at": "2026-03-30T15:30:00Z",
      "bytes_in": 1024,
      "bytes_out": 2048,
      "requests": 42
    }
  ]
}

Get a tunnel

GET /v1/tunnels/{id}

Returns the same tunnel object as create.

Close a tunnel

DELETE /v1/tunnels/{id}

Response

{"status": "closed"}

Extend a tunnel

PUT /v1/tunnels/{id}/extend

Request

{
  "ttl": "4h"
}

Extends the tunnel's expiry by the given duration.

Rate limits

Tunnel creation is rate-limited to 10 per minute per client, with a burst of 5. Other endpoints are not rate-limited.

NullBore Documentation