Creating the Kit App stream#

../../_images/ovas_api_banner_thin.png

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): Version of the application. Defaults to latest.

  • 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": "latest"
}'

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

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": [
      {
        "description": "signaling",
        "destination_port": 32452,
        "protocol": "TCP",
        "source_port": 31000
      },
      {
        "description": "media",
        "destination_port": 32433,
        "protocol": "UDP",
        "source_port": 31001
      }
    ]
  },
  "status": {
    "condition": "ready",
    "message": "Session is active",
    "status": true
  }
}

Response Schema:

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique session ID"
    },
    "routes": {
      "type": "object",
      "description": "Connection details (host and ports)"
    },
    "status": {
      "type": "object",
      "description": "The current status of the session"
    }
  },
  "required": ["id", "routes", "status"]
}

The session is being prepared.

{
  "id": "82a67a28-66e2-4f01-bdf8-2a20971f2457",
  "status": {
    "condition": "pending",
    "message": "Session is being prepared",
    "status": false
  }
}

Response Schema:

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique session ID"
    },
    "status": {
      "type": "object",
      "properties": {
        "condition": {
          "type": "string",
          "enum": ["pending", "ready"],
          "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"]
}

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

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.

All of the STATUS codes are documented and can be used for proper error-handling and reporting.

202 - 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": [
      {
        "description": "signaling",
        "destination_port": 32452,
        "protocol": "TCP",
        "source_port": 31000
      },
      {
        "description": "media",
        "destination_port": 32433,
        "protocol": "UDP",
        "source_port": 31001
      }
    ]
  },
  "status": {
    "condition": "ready",
    "message": "Session is active",
    "status": true
  }
}

The streaming session id is returned by the id property.

The routes dictionary uses a simple dictionary structure, where each item’s key is the IP address of the streaming Kit App and each item is its own an array of dictionaries containing the information on the ports.

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

202 - Polling waiting for the stream#

example 202 response body#
{
  "id": "82a67a28-66e2-4f01-bdf8-2a20971f2457",
  "status": {
    "condition": "pending",
    "message": "Session is being prepared",
    "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.

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": [
      {
        "description": "signaling",
        "destination_port": 32452,
        "protocol": "TCP",
        "source_port": 12574
      }
    ]
  },
  "status": {
    "condition": "ready",
    "message": "Session is active",
    "status": true
  }
}

You do not have permission to access this session.

The requested session was not found.

The request contained invalid input.

Use a polling strategy that fits your particular operational profile.

Additional resources:
On this page