DigitalOcean API (unofficial showcase)
GET/v2/agents/sessions/{session_id}/ingress

GetIngressURL returns the public HTTPS URL of the session's OpenHands Agent Server.

Publishes the URL on first call and returns it. Idempotent while the session runs: the same URL is returned until the session is paused, locked or rolled back, after which the next call returns a new hostname (pause and lock revoke the URL; rollback moves the session to a new sandbox, so re-fetch after resume, unlock or rollback). The URL fronts guest port 8000 (the OpenHands Agent Server, HTTP + WebSocket) and replaces the port-forward bridge for browser clients. Requests to the URL carry the caller's DO token as a Bearer header. Poll until state is INGRESS_URL_STATE_READY; there is no failed state. Only OpenHands sessions support ingress, and it is gated per team.

1 parameter
session_idstringrequired
The session UUID.

10 status codes
200A successful response.
ingress_urlobjectoptional
A publicly routable HTTPS URL to one guest port of the session's sandbox. The hostname is stable while the session runs; it is revoked on pause and lock, and rollback moves the session to a new sandbox, so re-fetch after resume, unlock or rollback. Requests must carry the caller's DO token as a Bearer header.
401Authentication failed due to invalid credentials.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
403Session belongs to another team.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
404The resource was not found.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
409Session is not running.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
423This session is unavailable; contact support.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
429The API rate limit has been exceeded.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
500There was a server error.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
501Public ingress is not supported for this agent kind or sandbox substrate.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
defaultThere was an unexpected error.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Error handling

A 401 is returned: Authentication failed due to invalid credentials. A 403 is returned: Session belongs to another team. A 404 is returned: The resource was not found. A 409 is returned: Session is not running. A 423 is returned: This session is unavailable; contact support. A 429 is returned: The API rate limit has been exceeded. A 500 is returned: There was a server error. A 501 is returned: Public ingress is not supported for this agent kind or sandbox substrate. Any other status is an error: There was an unexpected error.