Is this page helpful?

Creating the Kit App Stream#

OVAS API banner for Kit application streaming creation

You can use the following POST /stream endpoint documentation to understand how to request a new Kit App stream.

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"]
}

Requesting a Stream#

The request requires the application id, profile and optionally, version.

The response STATUS notifies you if the request was successful:

  • 200 indicates that a stream is created and ready.

  • 202 means that a stream is in the process of being prepared.

  • Any other status implies an error of some kind.

The common STATUS codes are documented below and can be used for proper error-handling and reporting. POST /stream can additionally return 404 (the id, version, and profile combination did not resolve) and 429 (the deployment’s session_capacity is exhausted).

200 - Streaming Is Ready#

The response body contains all of the information you need to connect to the WebRTC stream.

example 200 response body#
{
  "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
  }
}

The streaming session id is returned by the id property.

In the routes dictionary, each key is the IP address (or DNS name when WSS is enabled) of the streaming Kit App, and each value is an object with a routes array of port entries; for example routes["<host>"].routes[0].source_port. Entries beyond signaling and media, such as health, may be present; select entries by their description.

You will need the id, ip address, signaling source_port and media source_port to connect to the WebRTC stream.

202 - Poll While Waiting for the Stream#

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

If you receive a 202, your code should enter a polling loop, calling the GET /stream/{session_id} endpoint until a status of 200 is returned. Poll on the HTTP status code and the boolean status.status; routes is populated only once the session is ready, and status.condition values beyond ready should be treated as non-terminal. A 424 is terminal: the session has failed (for example an image pull or startup error) and will not recover, so stop polling, delete the session, and create a new one (see Streaming Session Readiness Probes). Ignore the Location header on 202 responses; it is not a resolvable path in this release.

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.

Use a polling strategy that fits your particular operational profile.

Additional resources: