Kubi API

Reach services inside a screen through its ports, and send its traffic through your own proxy.


Read a port

GET
https://api.trykubi.com/v1
/screens/{screen_id}/ports/{port}
Bearer (API key)

Needs the network permission. Answers within 2 s.

One open port, with its URL and token.

Read a port › path Parameters

screen_id
​string · maxLength: 24 · pattern: ^scr_[0-9a-z]{20}$ · required

Screen id (scr_...).

port
​integer · int32 · min: 1 · max: 65535 · required

A TCP port inside the screen, 1 to 65535.

Read a port › Headers

Kubi-Run
​string · maxLength: 100 · pattern: ^[ -~]{1,100}$

Optional label that groups calls into one run in the screen's history. It is only a label and never locks the screen. The SDK fills it from KUBI_RUN, else Claude Code's CLAUDE_CODE_SESSION_ID, else one id per client it creates.

Read a port › Responses

Success.

An open port: HTTP and WebSocket requests to `url` reach the service listening on this port inside the screen, on 127.0.0.1 or 0.0.0.0, with the request's Host kept and `X-Forwarded-Proto: https` set. Answers the port relay gives itself, in the error shape: 401 UNAUTHENTICATED (no token or a wrong one), 403 ORGANIZATION_SUSPENDED, 404 NOT_FOUND, 409 SCREEN_NOT_RUNNING, 429 RATE_LIMITED, 502 PORT_NOT_LISTENING (nothing listens on the port), 503 SCREEN_UNAVAILABLE. Every other answer is the service's.
port
​integer · int32 · min: 1 · max: 65535 · required

The TCP port inside the screen.

access
​string · enum · maxLength: 5 · required

token: every request must carry the token in Kubi-Port-Token. link: the URL alone gets in, for apps that can't add a header; anyone holding it reaches the service.

Enum values:
token
link
url
​string · uri · maxLength: 300 · required

The port's own HTTPS origin. Keep it secret with link access.

​required
screen_id
​string · maxLength: 24 · pattern: ^scr_[0-9a-z]{20}$ · required
created_at
​string · date-time · maxLength: 40 · required

Open a port

PUT
https://api.trykubi.com/v1
/screens/{screen_id}/ports/{port}
Bearer (API key)

Needs the network permission. Answers within 5 s.

Gives the service listening on this port inside the screen its own HTTPS URL, for HTTP and WebSocket requests: a dev server, an app's API, a coding agent's server. At most 3 ports per screen, included in the price. With token access (the default) every request carries the returned token in Kubi-Port-Token; your own Authorization header passes through to the service. With link access the URL alone gets in. The port stays open across stop and start, and closes with the screen. Opening a port that is already open with the same access returns it unchanged (200); with the other access it is refused, so close it first. Raw TCP (SSH, databases) is not carried.

Open a port › path Parameters

screen_id
​string · maxLength: 24 · pattern: ^scr_[0-9a-z]{20}$ · required

Screen id (scr_...).

port
​integer · int32 · min: 1 · max: 65535 · required

A TCP port inside the screen, 1 to 65535.

Open a port › Headers

Kubi-Run
​string · maxLength: 100 · pattern: ^[ -~]{1,100}$

Optional label that groups calls into one run in the screen's history. It is only a label and never locks the screen. The SDK fills it from KUBI_RUN, else Claude Code's CLAUDE_CODE_SESSION_ID, else one id per client it creates.

Open a port › Request Body optional

access
​string · enum · maxLength: 5
Enum values:
token
link
Default: token

Open a port › Responses

Already open with this access.

An open port: HTTP and WebSocket requests to `url` reach the service listening on this port inside the screen, on 127.0.0.1 or 0.0.0.0, with the request's Host kept and `X-Forwarded-Proto: https` set. Answers the port relay gives itself, in the error shape: 401 UNAUTHENTICATED (no token or a wrong one), 403 ORGANIZATION_SUSPENDED, 404 NOT_FOUND, 409 SCREEN_NOT_RUNNING, 429 RATE_LIMITED, 502 PORT_NOT_LISTENING (nothing listens on the port), 503 SCREEN_UNAVAILABLE. Every other answer is the service's.
port
​integer · int32 · min: 1 · max: 65535 · required

The TCP port inside the screen.

access
​string · enum · maxLength: 5 · required

token: every request must carry the token in Kubi-Port-Token. link: the URL alone gets in, for apps that can't add a header; anyone holding it reaches the service.

Enum values:
token
link
url
​string · uri · maxLength: 300 · required

The port's own HTTPS origin. Keep it secret with link access.

​required
screen_id
​string · maxLength: 24 · pattern: ^scr_[0-9a-z]{20}$ · required
created_at
​string · date-time · maxLength: 40 · required

Close a port

DELETE
https://api.trykubi.com/v1
/screens/{screen_id}/ports/{port}
Bearer (API key)

Needs the network permission. Answers within 2 s.

The URL stops answering, and connections open through it end within 3 seconds. Open it again for a new URL and token.

Close a port › path Parameters

screen_id
​string · maxLength: 24 · pattern: ^scr_[0-9a-z]{20}$ · required

Screen id (scr_...).

port
​integer · int32 · min: 1 · max: 65535 · required

A TCP port inside the screen, 1 to 65535.

Close a port › Headers

Kubi-Run
​string · maxLength: 100 · pattern: ^[ -~]{1,100}$

Optional label that groups calls into one run in the screen's history. It is only a label and never locks the screen. The SDK fills it from KUBI_RUN, else Claude Code's CLAUDE_CODE_SESSION_ID, else one id per client it creates.

Close a port › Responses

Closed.

No data returned

List open ports

GET
https://api.trykubi.com/v1
/screens/{screen_id}/ports
Bearer (API key)

Needs the network permission. Answers within 2 s.

The screen's open ports with their URLs and tokens.

List open ports › path Parameters

screen_id
​string · maxLength: 24 · pattern: ^scr_[0-9a-z]{20}$ · required

Screen id (scr_...).

List open ports › Headers

Kubi-Run
​string · maxLength: 100 · pattern: ^[ -~]{1,100}$

Optional label that groups calls into one run in the screen's history. It is only a label and never locks the screen. The SDK fills it from KUBI_RUN, else Claude Code's CLAUDE_CODE_SESSION_ID, else one id per client it creates.

List open ports › Responses

Success.

​Port[] · maxItems: 100 · required
​required