grey.ooo
someones.computer
Pricing Install
Sign in

Reading an address

GET /cli/applications/{slug}/endpoints

Where an application's services can be reached from outside the cluster — host, port and protocol, for HTTP and non-HTTP services alike.

This is the call to make when your program has to write an address down: a .ovpn profile carries a literal remote <host> <port>, and so does a game client's server list, a DNS record you publish, or a QR code you hand a user.

A service on a raw port

{
    "application": "vpn",
    "deployment": "main",
    "sequence": 1,
    "status": "running",
    "endpoints": [
        {
            "service": "openvpn",
            "protocol": "udp",
            "host": "gateway.example.net",
            "port": 30000,
            "targetPort": 1194,
            "assigned": true,
            "edgeRouted": false,
            "url": null,
            "hostUnknownReason": null
        }
    ]
}

assigned: true says the platform picked the port rather than the compose file naming it — so this is a number you must read back rather than one you already knew. It will be the same on the next deploy.

An HTTP service

{
    "application": "web",
    "deployment": "main",
    "sequence": 1,
    "status": "running",
    "endpoints": [
        {
            "service": "web",
            "protocol": "tcp",
            "host": "web-acme.someones.computer",
            "port": 443,
            "targetPort": 80,
            "assigned": false,
            "edgeRouted": true,
            "url": "https://web-acme.someones.computer",
            "hostUnknownReason": null
        }
    ]
}

edgeRouted: true means the address reaches the service through the platform's edge, which terminates TLS and routes by hostname. Every custom domain pointed at the service appears as an additional entry with the same service name — they are more addresses for one service, not more services.

Fields

Field Meaning
service The compose service name, as your file spells it
protocol tcp or udp
host What to connect to. Null means the platform does not know
port What to connect to. Null exactly when host is
targetPort The container port traffic arrives at
assigned Whether the platform chose the published port
edgeRouted Whether this address goes through the HTTP edge
url A URL where the protocol has one; null for UDP
hostUnknownReason Why there is no address, or null

Before the first deploy

An application with no running revision is not an error — it has no addresses yet, which is what a consumer polling until one appears should read:

{
    "application": "vpn",
    "deployment": null,
    "endpoints": []
}

Ask about a specific revision instead with ?deployment=<name>, which is how you read a preview environment's address before promoting it. A name that does not exist answers as though there were no revision at all, rather than falling back to a different one.

When the platform does not know

A raw published port answers at whatever address the operator points at the cluster, and nothing on the platform can derive that. If nobody has recorded one, the endpoint says so rather than guessing:

{
    "application": "vpn",
    "deployment": "main",
    "sequence": 1,
    "status": "running",
    "endpoints": [
        {
            "service": "openvpn",
            "protocol": "udp",
            "host": null,
            "port": null,
            "targetPort": 1194,
            "assigned": true,
            "edgeRouted": false,
            "url": null,
            "hostUnknownReason": "No public address is recorded for the context this application runs on; an operator has to set one before this port can be reached by name."
        }
    ]
}

A guess that looked plausible would be a connection failure somebody has to debug from the far end, which is strictly worse than an honest null. Treat this as "ask the operator", not as a transient error to retry.

← All developer pages