Is this page helpful?

Application Streaming API#

Overview#

The Application Streaming API is mainly used to query which application streams are active for a given deployment or to initiate and manage a new application stream for developers desiring to embed Omniverse on DGX Cloud application streams into their own custom applications or environments.

Stream Management#

All application streams for a deployment are initiated by the Application Streaming API and can be introspected via the same API, regardless of whether they are initiated via a custom application or environment.

Developer Use Case#

The primary reason to use the Application Streaming API is if you, as a developer, want to embed a streamed Omniverse application into your own application. An example use case would be leveraging the graphics and computing power of a remote node to stream a high-quality interactive render of a USD scene into your own application​

Streaming APIs#

GET /stream - Return application streaming sessions

Retrieve metadata information about application streaming sessions.

Response Details by Status

The request was successful. Below is the response body and schema.

{
  "offset": 0,
  "limit": 50,
  "count": 2,
  "items": [
    {
      "id": "session-id-123",
      "routes": {
        "10.0.0.1": {
          "routes": [
            {
              "description": "signaling",
              "destination_port": 32452,
              "protocol": "TCP",
              "source_port": 12574
            },
            {
              "description": "media",
              "destination_port": 32433,
              "protocol": "UDP",
              "source_port": 10521
            }
          ]
        }
      },
      "status": {
        "condition": "ready",
        "message": "",
        "status": true
      }
    }
  ]
}

Response Schema:

{
  "type": "object",
  "properties": {
    "offset": {
      "type": "integer",
      "description": "Offset used as part of query"
    },
    "limit": {
      "type": "integer",
      "description": "Limit used as part of query"
    },
    "count": {
      "type": "integer",
      "description": "Number of results returned"
    },
    "items": {
      "type": "array",
      "description": "List of streams",
      "items": {
        "$ref": "#/components/schemas/StreamResponse"
      }
    }
  }
}

The request is forbidden due to insufficient permissions.

The requested resource was not found.

POST /stream - Create a streaming session

Initiate a streaming session for a specified application using its id, profile, and optional version.

Request Parameters

The request body accepts the following parameters:

  • id (string, required): Unique identifier of the application to stream.

  • profile (string, required): Predefined runtime profile for the application.

  • version (string, optional): The bare application version (for example 110.1.3), as returned by GET /cfg/apps/{id}/versions. Do not pass the ApplicationVersion resource name (usd-viewer-110.1.3): the service composes <id>-<version> internally, so the full name fails with 404 not a valid combination. When omitted, the value defaults to the literal string default, which resolves only if an application version named <id>-default exists.

  • arguments (object, optional): Custom arguments to modify the behavior of the stream (e.g., usd_stage_uri).

    • usd_stage_uri (string, optional): URI of the USD stage to load.

curl -X POST https://api.example.com/stream \
-H "Content-Type: application/json" \
-d '{
   "id": "usd-viewer",
   "profile": "default",
   "version": "110.1.3"
}'

{
  "id": "usd-viewer",
  "profile": "default",
  "version": "110.1.3"
}

Request Schema:

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the application"
    },
    "profile": {
      "type": "string",
      "description": "Predefined runtime profile for the application"
    },
    "version": {
      "type": "string",
      "description": "Version of the application (optional)"
    },
    "arguments": {
      "type": "object",
      "properties": {
        "usd_stage_uri": {
          "type": "string",
          "description": "URI of the USD stage to load"
        }
      }
    }
  },
  "required": ["id", "profile"]
}

Response Details by Status

The session is ready. Below is the response body and schema.

{
  "id": "82a67a28-66e2-4f01-bdf8-2a20971f2457",
  "routes": {
    "25.124.78.14": {
      "routes": [
        {
          "description": "signaling",
          "destination_port": 32452,
          "protocol": "TCP",
          "source_port": 31000
        },
        {
          "description": "media",
          "destination_port": 32433,
          "protocol": "UDP",
          "source_port": 31001
        }
      ]
    }
  },
  "status": {
    "condition": "ready",
    "message": "",
    "status": true
  }
}

Response Schema:

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique session ID"
    },
    "routes": {
      "type": "object",
      "description": "Connection details. Each key is the host (IP address, or DNS name when WSS is enabled) and each value is an object with a routes array of port entries, i.e. routes[<host>].routes[0].source_port. Entries beyond signaling and media, such as health, may be present; select by description. Empty {} on 202 responses from POST /stream; a 202 from GET /stream/{id} may already carry routes when readiness checks are enabled, so always gate on status.status."
    },
    "status": {
      "type": "object",
      "description": "The current status of the session"
    }
  },
  "required": ["id", "routes", "status"]
}

The session is being prepared. Poll GET /stream/{id} using the id from the response body; rely on the HTTP status code and the boolean status.status rather than status.condition, and treat unrecognised condition values as non-terminal. Ignore the Location header returned with 202 responses; it is not a resolvable path in this release.

{
  "id": "82a67a28-66e2-4f01-bdf8-2a20971f2457",
  "routes": {},
  "status": {
    "condition": "reconciling",
    "message": "",
    "status": false
  }
}

Response Schema:

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique session ID"
    },
    "routes": {
      "type": "object",
      "description": "Connection details; empty {} until the session is ready"
    },
    "status": {
      "type": "object",
      "properties": {
        "condition": {
          "type": "string",
          "enum": ["reconciling", "ready", "failed", "released", "installfailed", "upgradefailed", "retriesexceeded", "testfailed", "artifactfailed", "remediationfailed", "chartunavailable", "stalled", "unknown"],
          "description": "State of the session"
        },
        "message": {
          "type": "string",
          "description": "Status message"
        },
        "status": {
          "type": "boolean",
          "description": "Whether the session is ready"
        }
      }
    }
  },
  "required": ["id", "status"]
}

You do not have permission to create this session.

{
  "detail": "You do not have permission to access this resource."
}

Response Schema:

{
  "type": "object",
  "properties": {
    "detail": {
      "type": "string",
      "description": "Error message describing why the request was forbidden"
    }
  },
  "required": ["detail"]
}

The id, version, and profile combination did not resolve to a registered application (“not a valid combination. Failed to resolve”). Verify each value with the Application and Profile APIs; version must be the bare version label, not the ApplicationVersion resource name.

There was a validation error in the request.

{
  "detail": [
    {
      "loc": ["body", "id"],
      "msg": "Invalid application ID format",
      "type": "value_error"
    }
  ]
}

Response Schema:

{
  "type": "object",
  "properties": {
    "detail": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "loc": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Location of the error"
          },
          "msg": {
            "type": "string",
            "description": "Error message"
          },
          "type": {
            "type": "string",
            "description": "Type of the error"
          }
        }
      }
    }
  }
}

The deployment’s configured session_capacity is exhausted. Terminate stale sessions or retry later.

An internal server error occurred.

{
  "detail": "An unexpected error occurred. Please try again later."
}

Response Schema:

{
  "type": "object",
  "properties": {
    "detail": {
      "type": "string",
      "description": "Error message describing the internal server error"
    }
  },
  "required": ["detail"]
}
DELETE /stream - Terminate a streaming session

Terminate a specific streaming session. The session id goes in the request body, not the URL path; a DELETE sent to the session path (.../stream/<id>) returns 405 Method Not Allowed, because only GET is registered there.

curl -X DELETE https://api.example.com/stream \
-H "Content-Type: application/json" \
-d '{"id": "<session-uuid>"}'

Response Details by Status

The session was successfully terminated.

You do not have permission to terminate this session.

The requested session was not found.

The request contained invalid input.

GET /stream/{session_id} - Retrieve details of a specific session

Retrieve metadata details for a specific streaming session by its unique identifier.

Response Details by Status

{
  "id": "session-1234",
  "routes": {
    "10.0.0.1": {
      "routes": [
        {
          "description": "signaling",
          "destination_port": 32452,
          "protocol": "TCP",
          "source_port": 12574
        }
      ]
    }
  },
  "status": {
    "condition": "ready",
    "message": "",
    "status": true
  }
}

The session exists but is not ready yet. Keep polling; gate on the HTTP status code and the boolean status.status (on this endpoint condition may already read ready while status is false).

{
  "id": "session-1234",
  "routes": {},
  "status": {
    "condition": "ready",
    "message": "",
    "status": false
  }
}

You do not have permission to access this session.

The requested session was not found.

The request contained invalid input.

The session has failed and will not recover (for example an image pull or startup error). Stop polling, delete the session, and create a new one. This status is returned only when the deployment enables session readiness checks; see Streaming Session Readiness Probes.