--- title: "Ports and terminal · API reference · Promigence" description: "The Promigence API's ports and terminal routes: 8 in all, with parameters, request bodies and answers." url: "https://www.promigence.ai/docs/reference/api/ports-and-terminal" site: "Promigence" --- [API reference](https://www.promigence.ai/docs/reference/api) # Ports and terminal 8 routes of the published API contract, generated from it. ### GET/v1/sandboxes/{id}/ports Auth: API key List this sandbox's preview URLs. #### Parameters idrequiredpath · string #### Answer 200 · PortList · application/json portsrequiredPort[] sandbox_idrequiredstring ### POST/v1/sandboxes/{id}/ports Auth: API key Mint a preview URL for a port in the sandbox. Anyone holding the URL can reach the port — it is a bearer token in a link, so pass `ttl_s` to make it stop working on its own rather than relying on someone remembering to revoke it. `url` is the form to use; `path_url` and `host_url` are always returned by name, so a client that needs one specifically never has to parse `url`. #### Parameters idrequiredpath · string #### Request body PortOpen · application/json portrequiredinteger 1–65535. #### Answer 200 · Port · application/json created_unix_nsinteger | null Unix nanoseconds. host_url_labelstring | null The same publication addressed by name rather than by path. Apps that emit absolute paths need this form. portinteger | null The port inside the sandbox. sandbox_idrequiredstring tokenstring | null The token the URL carries. Pass it to `DELETE /v1/sandboxes/{id}/ports/{token_or_port}` to revoke this one URL. urlstring | null The URL to open. ### DELETE/v1/sandboxes/{id}/ports/{token_or_port} Auth: API key Revoke one URL by its token, or every URL for a port by the port number. #### Parameters idrequiredpath · string token_or_portrequiredpath · string #### Answer 200 · PortsRevoked · application/json okrequiredboolean revokedrequiredstring[] The tokens that were revoked. Revoking by port number revokes every URL minted for that port, so this can hold more than one. sandbox_idrequiredstring ### GET/v1/sandboxes/{id}/pty Auth: API key · upgrades to a WebSocket A WebSocket terminal, relayed byte for byte. `?cols=&rows=&cmd=`. Authenticated by the `Authorization` header, never a query string. Its `open` event carries `resume`: send it back in the `promigence-resume` header (from a browser, as the subprotocol `promigence.resume.`), with `?received=` the output bytes you have, to pick the same terminal up where it left off after a dropped connection or a service update. If some of its output was not kept meanwhile, the `open` event's `dropped` says how many bytes. One that can no longer be picked up again answers 404. #### Parameters idrequiredpath · string cmdquery · string colsquery · integer receivedquery · integer rowsquery · integer ### GET/v1/sandboxes/{id}/ssh Auth: API key The keys this sandbox will accept over SSH, and for how long. #### Parameters idrequiredpath · string #### Answer 200 · SshAccessList · application/json host_keystring | null Absent when the sandbox has never been asked for SSH access. host_key_fingerprintstring | null idle_timeout_srequiredinteger keysrequiredSshKey[] sandbox_idrequiredstring ### POST/v1/sandboxes/{id}/ssh Auth: API key Authorise an `ssh-ed25519` public key for this sandbox and mint the short-lived credential an SSH connection to it uses. The login name is the sandbox id; the answer carries the sandbox's own host key, so a client can pin it instead of turning host verification off. #### Parameters idrequiredpath · string #### Request body SshAccessRequest · application/json idle_timeout_sinteger | null Seconds an idle connection is kept. public_keyrequiredstring An OpenSSH public key line. ttl_sinteger | null Seconds the key is accepted. #### Answer 200 · SshAccess · application/json expires_atrequiredstring When the key and the token both stop working (RFC 3339). fingerprintrequiredstring `SHA256:…` of the public key that was authorised, as `ssh-keygen -lf` prints it. hostrequiredstring The host to give `ssh`. It is an alias resolved by the tunnel, not a routable name. host_keyrequiredstring The sandbox's own host key, as a `known_hosts` line body (`ssh-ed25519 AAAA…`). Pin it instead of turning host verification off; it is minted for this sandbox and dies with it. host_key_fingerprintrequiredstring `SHA256:…` of `host_key`, which is what `ssh` prints on a first connection. idle_timeout_srequiredinteger Seconds of inactivity after which an open session is closed. key_idrequiredstring Identifier for the authorised key, for revoking it later. proxy_commandrequiredstring The `ProxyCommand` that carries the connection: `promigence sandbox ssh --proxy`. sandbox_idrequiredstring The sandbox this access is for. ssh_commandrequiredstring A complete `ssh` command line, for pasting. tokenrequiredstring The short-lived credential the tunnel authenticates with. Shown once. userrequiredstring The login name to use. It is the sandbox id: a key is authorised for one name only. ### DELETE/v1/sandboxes/{id}/ssh/{key_id} Auth: API key Revoke one key by id or fingerprint, and the access credential issued with it. Idempotent: `revoked: false` means neither existed. #### Parameters idrequiredpath · string key_idrequiredpath · string #### Answer 200 · SshRevoked · application/json key_idrequiredstring revokedrequiredboolean sandbox_idrequiredstring ### GET/v1/sandboxes/{id}/ssh/connect Auth: API key · upgrades to a WebSocket A WebSocket carrying the SSH byte stream, relayed byte for byte. Accepts either an API key or the short-lived per-sandbox credential from `POST /v1/sandboxes/:id/ssh`, in the `Authorization` header. This is what `promigence sandbox ssh --proxy` speaks; you do not call it by hand. #### Parameters idrequiredpath · string [Every route](https://www.promigence.ai/docs/reference/api) · [what each error means and whether it was billed](https://www.promigence.ai/docs/errors)