Hubfly spaceDocs
Console

Managed Streams API · Dashboard

Inputs & stream keys

Push inputs for encoders (RTMP, RTMPS, SRT, WHIP, Icecast) and pull inputs, with primary and backup keys.

Base URL: https://api.hubfly.space. Use a Dashboard bearer token authorized for the project. Replace :projectId in each path with the Dashboard project ID. JSON routes use Content-Type: application/json.

Stream servers live in a project of type managed; other projects return 409 MANAGED_PROJECT_REQUIRED. Replace :instanceId with the stream server ID from the instance list. Each endpoint lists the permission it needs; a token scoped to the stream permissions must hold that exact permission.

How to use these endpoints

  1. Create a push input with the protocols your encoders use, or a pull input with a public source URL. Ask for backupKey: true to get a second key for a backup encoder.
  2. Keys are returned once on create; reads show only keyHints. Get the per-protocol URLs from the input's connection.
  3. Reveal keys only when you configure an encoder; rotating a key disconnects the encoder that uses the old one.
  4. An input that a channel, mixer or destination still uses cannot be deleted (STREAM_IN_USE lists what refers to it).

Create a push input with a backup key

curl
curl -X POST "https://api.hubfly.space/api/v1/projects/$PROJECT_ID/managed/instances/$INSTANCE_ID/stream/inputs/create" \
  -H "Authorization: Bearer $HUBFLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Studio encoder","kind":"push","protocols":["rtmps","srt"],"backupKey":true,"maxBitrateKbps":12000}'

The response uses the standard Dashboard envelope: ok, data, and meta on success. On failure, use the returned error code and message to decide whether to correct the request or retry. The exact schema and response codes for each operation are below.

Endpoint reference

Dashboard endpoints (7)

These JSON routes are served by the Hubfly space Dashboard API and use Dashboard project authorization.

Open interactive API explorer
POSTCreate a stream inputDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/stream/inputs/create

Create a push input, which encoders publish to over RTMP, RTMPS, SRT, WHIP or Icecast with a stream key, or a pull input, which the server fetches from pull.url. A push input gets a primary key, plus a backup key with backupKey: true. Returns the input with its connection details, the keys and the configuration sync status.

  • Requires stream:admin.
  • The hfls_… keys are returned once, with cache-control: no-store; read them again later with the reveal call. Pull inputs have no keys (keys is null).
  • Push inputs accept every protocol unless protocols narrows them; maxBitrateKbps is 100–80,000 (default 20,000). Pull URLs use rtmp, rtmps, rtsp, rtsps, srt or https (HLS); an SRT passphrase is 10–79 characters.
  • A server holds up to 50 inputs. Invalid values return 422 STREAM_INVALID with details; a duplicate name returns 409 STREAM_NAME_TAKEN.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
namestringYes
kindpush | pullYes
enabledbooleanNo
protocolsrtmp | rtmps | srt | whip | icecast[]No
backupKeybooleanNo
srtPassphrasestringNo
pullobjectNo
maxBitrateKbpsnumberNo
allowedCidrsstring[]No
Complete request schema
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "kind": {
      "type": "string",
      "enum": [
        "push",
        "pull"
      ]
    },
    "enabled": {
      "type": "boolean"
    },
    "protocols": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "rtmp",
          "rtmps",
          "srt",
          "whip",
          "icecast"
        ]
      }
    },
    "backupKey": {
      "type": "boolean"
    },
    "srtPassphrase": {
      "type": "string",
      "nullable": true
    },
    "pull": {
      "type": "object",
      "properties": {
        "url": {
          "type": "string"
        },
        "transport": {
          "type": "string",
          "enum": [
            "auto",
            "tcp",
            "udp"
          ]
        },
        "reconnect": {
          "type": "boolean"
        }
      },
      "required": [
        "url"
      ],
      "additionalProperties": false,
      "nullable": true
    },
    "maxBitrateKbps": {
      "type": "number"
    },
    "allowedCidrs": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "name",
    "kind"
  ],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "input": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "kind": {
                  "type": "string",
                  "enum": [
                    "push",
                    "pull"
                  ]
                },
                "enabled": {
                  "type": "boolean"
                },
                "protocols": {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "enum": [
                      "rtmp",
                      "rtmps",
                      "srt",
                      "whip",
                      "icecast"
                    ]
                  }
                },
                "maxBitrateKbps": {
                  "type": "number"
                },
                "allowedCidrs": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "createdAt": {
                  "type": "string"
                },
                "updatedAt": {
                  "type": "string"
                },
                "revision": {
                  "type": "number"
                },
                "keyHints": {
                  "type": "object",
                  "properties": {
                    "primary": {
                      "type": "string"
                    },
                    "backup": {
                      "type": "string"
                    }
                  },
                  "required": [],
                  "additionalProperties": false
                },
                "keyFingerprints": {
                  "type": "object",
                  "properties": {
                    "primary": {
                      "type": "string"
                    },
                    "backup": {
                      "type": "string"
                    }
                  },
                  "required": [],
                  "additionalProperties": false
                },
                "hasSrtPassphrase": {
                  "type": "boolean"
                },
                "pull": {
                  "type": "object",
                  "properties": {
                    "urlHint": {
                      "type": "string"
                    },
                    "transport": {
                      "type": "string",
                      "enum": [
                        "auto",
                        "tcp",
                        "udp"
                      ]
                    },
                    "reconnect": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "urlHint",
                    "transport",
                    "reconnect"
                  ],
                  "additionalProperties": false,
                  "nullable": true
                },
                "connection": {
                  "type": "object",
                  "properties": {
                    "rtmp": {
                      "type": "object",
                      "properties": {
                        "server": {
                          "type": "string"
                        },
                        "streamKey": {
                          "type": "string"
                        },
                        "url": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "server",
                        "streamKey",
                        "url"
                      ],
                      "additionalProperties": false
                    },
                    "rtmps": {
                      "type": "object",
                      "properties": {
                        "server": {
                          "type": "string"
                        },
                        "streamKey": {
                          "type": "string"
                        },
                        "url": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "server",
                        "streamKey",
                        "url"
                      ],
                      "additionalProperties": false
                    },
                    "srt": {
                      "type": "object",
                      "properties": {
                        "url": {
                          "type": "string"
                        },
                        "uri": {
                          "type": "string"
                        },
                        "streamId": {
                          "type": "string"
                        },
                        "passphrase": {
                          "type": "string",
                          "nullable": true
                        }
                      },
                      "required": [
                        "url",
                        "uri",
                        "streamId",
                        "passphrase"
                      ],
                      "additionalProperties": false
                    },
                    "whip": {
                      "type": "object",
                      "properties": {
                        "url": {
                          "type": "string"
                        },
                        "bearerToken": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "url",
                        "bearerToken"
                      ],
                      "additionalProperties": false
                    },
                    "icecast": {
                      "type": "object",
                      "properties": {
                        "url": {
                          "type": "string"
                        },
                        "host": {
                          "type": "string"
                        },
                        "port": {
                          "type": "number"
                        },
                        "mount": {
                          "type": "string"
                        },
                        "username": {
                          "type": "string"
                        },
                        "password": {
                          "type": "string"
                        },
                        "httpsPutUrl": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "url",
                        "host",
                        "port",
                        "mount",
                        "username",
                        "password",
                        "httpsPutUrl"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "rtmp",
                    "rtmps",
                    "srt",
                    "whip",
                    "icecast"
                  ],
                  "additionalProperties": false,
                  "nullable": true
                }
              },
              "required": [
                "id",
                "name",
                "kind",
                "enabled",
                "protocols",
                "maxBitrateKbps",
                "allowedCidrs",
                "createdAt",
                "updatedAt",
                "revision",
                "keyHints",
                "keyFingerprints",
                "hasSrtPassphrase",
                "pull",
                "connection"
              ],
              "additionalProperties": false
            },
            "keys": {
              "type": "object",
              "properties": {
                "primary": {
                  "type": "string"
                },
                "backup": {
                  "type": "string"
                }
              },
              "required": [
                "primary"
              ],
              "additionalProperties": false,
              "nullable": true
            },
            "sync": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "string",
                  "enum": [
                    "pending",
                    "applied"
                  ]
                },
                "generation": {
                  "type": "number"
                },
                "error": {
                  "type": "string",
                  "nullable": true
                },
                "warnings": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "path": {
                        "type": "string"
                      },
                      "code": {
                        "type": "string"
                      },
                      "message": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "path",
                      "code",
                      "message"
                    ],
                    "additionalProperties": false
                  }
                }
              },
              "required": [
                "status",
                "generation",
                "error",
                "warnings"
              ],
              "additionalProperties": false
            }
          },
          "required": [
            "input",
            "keys",
            "sync"
          ],
          "additionalProperties": false
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": {
        "input": {
          "id": "string",
          "name": "string",
          "kind": "push",
          "enabled": true,
          "protocols": [
            "rtmp"
          ],
          "maxBitrateKbps": 0,
          "allowedCidrs": [
            "string"
          ],
          "createdAt": "string",
          "updatedAt": "string",
          "revision": 0,
          "keyHints": {
            "primary": "string",
            "backup": "string"
          },
          "keyFingerprints": {
            "primary": "string",
            "backup": "string"
          },
          "hasSrtPassphrase": true,
          "pull": {
            "urlHint": "string",
            "transport": "auto",
            "reconnect": true
          },
          "connection": {
            "rtmp": {
              "server": "string",
              "streamKey": "string",
              "url": "string"
            },
            "rtmps": {
              "server": "string",
              "streamKey": "string",
              "url": "string"
            },
            "srt": {
              "url": "string",
              "uri": "string",
              "streamId": "string",
              "passphrase": "string"
            },
            "whip": {
              "url": "string",
              "bearerToken": "string"
            },
            "icecast": {
              "url": "string",
              "host": "string",
              "port": 0,
              "mount": "string",
              "username": "string",
              "password": "string",
              "httpsPutUrl": "string"
            }
          }
        },
        "keys": {
          "primary": "string",
          "backup": "string"
        },
        "sync": {
          "status": "pending",
          "generation": 0,
          "error": "string",
          "warnings": [
            {
              "path": "string",
              "code": "string",
              "message": "string"
            }
          ]
        }
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
GETList stream inputsDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/stream/inputs

List the server's push and pull inputs with their protocols, bitrate cap, allowed networks, keyHints and keyFingerprints per key role, and for pull inputs a pull.urlHint without credentials or path. Keys are never returned here.

  • Requires stream:read.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "kind": {
                "type": "string",
                "enum": [
                  "push",
                  "pull"
                ]
              },
              "enabled": {
                "type": "boolean"
              },
              "protocols": {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "rtmp",
                    "rtmps",
                    "srt",
                    "whip",
                    "icecast"
                  ]
                }
              },
              "maxBitrateKbps": {
                "type": "number"
              },
              "allowedCidrs": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "createdAt": {
                "type": "string"
              },
              "updatedAt": {
                "type": "string"
              },
              "revision": {
                "type": "number"
              },
              "keyHints": {
                "type": "object",
                "properties": {
                  "primary": {
                    "type": "string"
                  },
                  "backup": {
                    "type": "string"
                  }
                },
                "required": [],
                "additionalProperties": false
              },
              "keyFingerprints": {
                "type": "object",
                "properties": {
                  "primary": {
                    "type": "string"
                  },
                  "backup": {
                    "type": "string"
                  }
                },
                "required": [],
                "additionalProperties": false
              },
              "hasSrtPassphrase": {
                "type": "boolean"
              },
              "pull": {
                "type": "object",
                "properties": {
                  "urlHint": {
                    "type": "string"
                  },
                  "transport": {
                    "type": "string",
                    "enum": [
                      "auto",
                      "tcp",
                      "udp"
                    ]
                  },
                  "reconnect": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "urlHint",
                  "transport",
                  "reconnect"
                ],
                "additionalProperties": false,
                "nullable": true
              }
            },
            "required": [
              "id",
              "name",
              "kind",
              "enabled",
              "protocols",
              "maxBitrateKbps",
              "allowedCidrs",
              "createdAt",
              "updatedAt",
              "revision",
              "keyHints",
              "keyFingerprints",
              "hasSrtPassphrase",
              "pull"
            ],
            "additionalProperties": false
          }
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": [
        {
          "id": "string",
          "name": "string",
          "kind": "push",
          "enabled": true,
          "protocols": [
            "rtmp"
          ],
          "maxBitrateKbps": 0,
          "allowedCidrs": [
            "string"
          ],
          "createdAt": "string",
          "updatedAt": "string",
          "revision": 0,
          "keyHints": {
            "primary": "string",
            "backup": "string"
          },
          "keyFingerprints": {
            "primary": "string",
            "backup": "string"
          },
          "hasSrtPassphrase": true,
          "pull": {
            "urlHint": "string",
            "transport": "auto",
            "reconnect": true
          }
        }
      ],
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
DELETEDelete a stream inputDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/stream/inputs/:inputId/delete

Delete an input and its keys. The node drops it when it applies the new configuration.

  • Requires stream:admin.
  • Refused with 409 STREAM_IN_USE while a channel, mixer or destination still uses the input; the error lists the referrers.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
inputIdpathYesstring—
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "deleted": {
              "const": true,
              "type": "boolean"
            },
            "sync": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "string",
                  "enum": [
                    "pending",
                    "applied"
                  ]
                },
                "generation": {
                  "type": "number"
                },
                "error": {
                  "type": "string",
                  "nullable": true
                },
                "warnings": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "path": {
                        "type": "string"
                      },
                      "code": {
                        "type": "string"
                      },
                      "message": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "path",
                      "code",
                      "message"
                    ],
                    "additionalProperties": false
                  }
                }
              },
              "required": [
                "status",
                "generation",
                "error",
                "warnings"
              ],
              "additionalProperties": false
            }
          },
          "required": [
            "deleted",
            "sync"
          ],
          "additionalProperties": false
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": {
        "deleted": true,
        "sync": {
          "status": "pending",
          "generation": 0,
          "error": "string",
          "warnings": [
            {
              "path": "string",
              "code": "string",
              "message": "string"
            }
          ]
        }
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
GETRead a stream inputDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/stream/inputs/:inputId

Return one input with its settings and key hints and, for push inputs, connection: server, stream key field and full URL for RTMP and RTMPS, the SRT URL and stream id, the WHIP URL and bearer token, and Icecast mount and credentials. Keys inside connection are masked; pull inputs have no connection.

  • Requires stream:read.
  • Use the reveal call for the full keys.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
inputIdpathYesstring—
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "kind": {
              "type": "string",
              "enum": [
                "push",
                "pull"
              ]
            },
            "enabled": {
              "type": "boolean"
            },
            "protocols": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "rtmp",
                  "rtmps",
                  "srt",
                  "whip",
                  "icecast"
                ]
              }
            },
            "maxBitrateKbps": {
              "type": "number"
            },
            "allowedCidrs": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "createdAt": {
              "type": "string"
            },
            "updatedAt": {
              "type": "string"
            },
            "revision": {
              "type": "number"
            },
            "keyHints": {
              "type": "object",
              "properties": {
                "primary": {
                  "type": "string"
                },
                "backup": {
                  "type": "string"
                }
              },
              "required": [],
              "additionalProperties": false
            },
            "keyFingerprints": {
              "type": "object",
              "properties": {
                "primary": {
                  "type": "string"
                },
                "backup": {
                  "type": "string"
                }
              },
              "required": [],
              "additionalProperties": false
            },
            "hasSrtPassphrase": {
              "type": "boolean"
            },
            "pull": {
              "type": "object",
              "properties": {
                "urlHint": {
                  "type": "string"
                },
                "transport": {
                  "type": "string",
                  "enum": [
                    "auto",
                    "tcp",
                    "udp"
                  ]
                },
                "reconnect": {
                  "type": "boolean"
                }
              },
              "required": [
                "urlHint",
                "transport",
                "reconnect"
              ],
              "additionalProperties": false,
              "nullable": true
            },
            "connection": {
              "type": "object",
              "properties": {
                "rtmp": {
                  "type": "object",
                  "properties": {
                    "server": {
                      "type": "string"
                    },
                    "streamKey": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "server",
                    "streamKey",
                    "url"
                  ],
                  "additionalProperties": false
                },
                "rtmps": {
                  "type": "object",
                  "properties": {
                    "server": {
                      "type": "string"
                    },
                    "streamKey": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "server",
                    "streamKey",
                    "url"
                  ],
                  "additionalProperties": false
                },
                "srt": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": "string"
                    },
                    "uri": {
                      "type": "string"
                    },
                    "streamId": {
                      "type": "string"
                    },
                    "passphrase": {
                      "type": "string",
                      "nullable": true
                    }
                  },
                  "required": [
                    "url",
                    "uri",
                    "streamId",
                    "passphrase"
                  ],
                  "additionalProperties": false
                },
                "whip": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": "string"
                    },
                    "bearerToken": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "url",
                    "bearerToken"
                  ],
                  "additionalProperties": false
                },
                "icecast": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": "string"
                    },
                    "host": {
                      "type": "string"
                    },
                    "port": {
                      "type": "number"
                    },
                    "mount": {
                      "type": "string"
                    },
                    "username": {
                      "type": "string"
                    },
                    "password": {
                      "type": "string"
                    },
                    "httpsPutUrl": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "url",
                    "host",
                    "port",
                    "mount",
                    "username",
                    "password",
                    "httpsPutUrl"
                  ],
                  "additionalProperties": false
                }
              },
              "required": [
                "rtmp",
                "rtmps",
                "srt",
                "whip",
                "icecast"
              ],
              "additionalProperties": false,
              "nullable": true
            }
          },
          "required": [
            "id",
            "name",
            "kind",
            "enabled",
            "protocols",
            "maxBitrateKbps",
            "allowedCidrs",
            "createdAt",
            "updatedAt",
            "revision",
            "keyHints",
            "keyFingerprints",
            "hasSrtPassphrase",
            "pull",
            "connection"
          ],
          "additionalProperties": false
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": {
        "id": "string",
        "name": "string",
        "kind": "push",
        "enabled": true,
        "protocols": [
          "rtmp"
        ],
        "maxBitrateKbps": 0,
        "allowedCidrs": [
          "string"
        ],
        "createdAt": "string",
        "updatedAt": "string",
        "revision": 0,
        "keyHints": {
          "primary": "string",
          "backup": "string"
        },
        "keyFingerprints": {
          "primary": "string",
          "backup": "string"
        },
        "hasSrtPassphrase": true,
        "pull": {
          "urlHint": "string",
          "transport": "auto",
          "reconnect": true
        },
        "connection": {
          "rtmp": {
            "server": "string",
            "streamKey": "string",
            "url": "string"
          },
          "rtmps": {
            "server": "string",
            "streamKey": "string",
            "url": "string"
          },
          "srt": {
            "url": "string",
            "uri": "string",
            "streamId": "string",
            "passphrase": "string"
          },
          "whip": {
            "url": "string",
            "bearerToken": "string"
          },
          "icecast": {
            "url": "string",
            "host": "string",
            "port": 0,
            "mount": "string",
            "username": "string",
            "password": "string",
            "httpsPutUrl": "string"
          }
        }
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
POSTReveal input keysDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/stream/inputs/:inputId/keys/reveal

Return an input's full secrets: the primary and backup stream keys of a push input, its srtPassphrase, or a pull input's full pullUrl. Only keys the node currently accepts are returned; a removed backup key is never shown again.

  • Requires stream:admin.
  • The response carries secrets and is sent with cache-control: no-store; every reveal is recorded in the audit log.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
inputIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
Complete request schema
{
  "type": "object",
  "properties": {},
  "required": [],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "primary": {
              "type": "string"
            },
            "backup": {
              "type": "string"
            },
            "srtPassphrase": {
              "type": "string"
            },
            "pullUrl": {
              "type": "string"
            }
          },
          "required": [],
          "additionalProperties": false
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": {
        "primary": "string",
        "backup": "string",
        "srtPassphrase": "string",
        "pullUrl": "string"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
POSTRotate an input keyDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/stream/inputs/:inputId/keys/rotate

Replace the primary or backup key of a push input and return the new key, or with remove: true delete the backup key (key is then null). The old key stops working, and a publisher using it is disconnected, when the node applies the change.

  • Requires stream:admin.
  • The new key is returned once, with cache-control: no-store. No revision is needed.
  • The primary key cannot be removed and pull inputs have no keys: 422 STREAM_INVALID (code kind_mismatch). Removing a backup key the input does not have returns 409 STREAM_KEY_MISSING.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
inputIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
roleprimary | backupYes
removebooleanNo
Complete request schema
{
  "type": "object",
  "properties": {
    "role": {
      "type": "string",
      "enum": [
        "primary",
        "backup"
      ]
    },
    "remove": {
      "type": "boolean"
    }
  },
  "required": [
    "role"
  ],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "key": {
              "type": "string",
              "nullable": true
            },
            "input": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "kind": {
                  "type": "string",
                  "enum": [
                    "push",
                    "pull"
                  ]
                },
                "enabled": {
                  "type": "boolean"
                },
                "protocols": {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "enum": [
                      "rtmp",
                      "rtmps",
                      "srt",
                      "whip",
                      "icecast"
                    ]
                  }
                },
                "maxBitrateKbps": {
                  "type": "number"
                },
                "allowedCidrs": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "createdAt": {
                  "type": "string"
                },
                "updatedAt": {
                  "type": "string"
                },
                "revision": {
                  "type": "number"
                },
                "keyHints": {
                  "type": "object",
                  "properties": {
                    "primary": {
                      "type": "string"
                    },
                    "backup": {
                      "type": "string"
                    }
                  },
                  "required": [],
                  "additionalProperties": false
                },
                "keyFingerprints": {
                  "type": "object",
                  "properties": {
                    "primary": {
                      "type": "string"
                    },
                    "backup": {
                      "type": "string"
                    }
                  },
                  "required": [],
                  "additionalProperties": false
                },
                "hasSrtPassphrase": {
                  "type": "boolean"
                },
                "pull": {
                  "type": "object",
                  "properties": {
                    "urlHint": {
                      "type": "string"
                    },
                    "transport": {
                      "type": "string",
                      "enum": [
                        "auto",
                        "tcp",
                        "udp"
                      ]
                    },
                    "reconnect": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "urlHint",
                    "transport",
                    "reconnect"
                  ],
                  "additionalProperties": false,
                  "nullable": true
                }
              },
              "required": [
                "id",
                "name",
                "kind",
                "enabled",
                "protocols",
                "maxBitrateKbps",
                "allowedCidrs",
                "createdAt",
                "updatedAt",
                "revision",
                "keyHints",
                "keyFingerprints",
                "hasSrtPassphrase",
                "pull"
              ],
              "additionalProperties": false
            },
            "sync": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "string",
                  "enum": [
                    "pending",
                    "applied"
                  ]
                },
                "generation": {
                  "type": "number"
                },
                "error": {
                  "type": "string",
                  "nullable": true
                },
                "warnings": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "path": {
                        "type": "string"
                      },
                      "code": {
                        "type": "string"
                      },
                      "message": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "path",
                      "code",
                      "message"
                    ],
                    "additionalProperties": false
                  }
                }
              },
              "required": [
                "status",
                "generation",
                "error",
                "warnings"
              ],
              "additionalProperties": false
            }
          },
          "required": [
            "key",
            "input",
            "sync"
          ],
          "additionalProperties": false
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": {
        "key": "string",
        "input": {
          "id": "string",
          "name": "string",
          "kind": "push",
          "enabled": true,
          "protocols": [
            "rtmp"
          ],
          "maxBitrateKbps": 0,
          "allowedCidrs": [
            "string"
          ],
          "createdAt": "string",
          "updatedAt": "string",
          "revision": 0,
          "keyHints": {
            "primary": "string",
            "backup": "string"
          },
          "keyFingerprints": {
            "primary": "string",
            "backup": "string"
          },
          "hasSrtPassphrase": true,
          "pull": {
            "urlHint": "string",
            "transport": "auto",
            "reconnect": true
          }
        },
        "sync": {
          "status": "pending",
          "generation": 0,
          "error": "string",
          "warnings": [
            {
              "path": "string",
              "code": "string",
              "message": "string"
            }
          ]
        }
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
PUTUpdate a stream inputDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/stream/inputs/:inputId/update

Change an input's name, enabled state, protocols, bitrate cap, allowed networks, SRT passphrase or pull settings. Omitted fields keep their value; the input's kind cannot change, and keys change through the rotate call.

  • Requires stream:admin.
  • Send revision equal to the input's current revision; if it changed meanwhile you get 409 STREAM_REVISION_CONFLICT.
  • A disabled input keeps its configuration but refuses publishers. srtPassphrase: null removes the passphrase; a new pull.url is stored encrypted and shown only as urlHint.
  • Invalid values return 422 STREAM_INVALID with details.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
inputIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
namestringNo
enabledbooleanNo
protocolsrtmp | rtmps | srt | whip | icecast[]No
srtPassphrasestringNo
pullobjectNo
maxBitrateKbpsnumberNo
allowedCidrsstring[]No
revisionnumberYes
Complete request schema
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "enabled": {
      "type": "boolean"
    },
    "protocols": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "rtmp",
          "rtmps",
          "srt",
          "whip",
          "icecast"
        ]
      }
    },
    "srtPassphrase": {
      "type": "string",
      "nullable": true
    },
    "pull": {
      "type": "object",
      "properties": {
        "url": {
          "type": "string"
        },
        "transport": {
          "type": "string",
          "enum": [
            "auto",
            "tcp",
            "udp"
          ]
        },
        "reconnect": {
          "type": "boolean"
        }
      },
      "required": [],
      "additionalProperties": false
    },
    "maxBitrateKbps": {
      "type": "number"
    },
    "allowedCidrs": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "revision": {
      "type": "number"
    }
  },
  "required": [
    "revision"
  ],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "input": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "kind": {
                  "type": "string",
                  "enum": [
                    "push",
                    "pull"
                  ]
                },
                "enabled": {
                  "type": "boolean"
                },
                "protocols": {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "enum": [
                      "rtmp",
                      "rtmps",
                      "srt",
                      "whip",
                      "icecast"
                    ]
                  }
                },
                "maxBitrateKbps": {
                  "type": "number"
                },
                "allowedCidrs": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "createdAt": {
                  "type": "string"
                },
                "updatedAt": {
                  "type": "string"
                },
                "revision": {
                  "type": "number"
                },
                "keyHints": {
                  "type": "object",
                  "properties": {
                    "primary": {
                      "type": "string"
                    },
                    "backup": {
                      "type": "string"
                    }
                  },
                  "required": [],
                  "additionalProperties": false
                },
                "keyFingerprints": {
                  "type": "object",
                  "properties": {
                    "primary": {
                      "type": "string"
                    },
                    "backup": {
                      "type": "string"
                    }
                  },
                  "required": [],
                  "additionalProperties": false
                },
                "hasSrtPassphrase": {
                  "type": "boolean"
                },
                "pull": {
                  "type": "object",
                  "properties": {
                    "urlHint": {
                      "type": "string"
                    },
                    "transport": {
                      "type": "string",
                      "enum": [
                        "auto",
                        "tcp",
                        "udp"
                      ]
                    },
                    "reconnect": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "urlHint",
                    "transport",
                    "reconnect"
                  ],
                  "additionalProperties": false,
                  "nullable": true
                },
                "connection": {
                  "type": "object",
                  "properties": {
                    "rtmp": {
                      "type": "object",
                      "properties": {
                        "server": {
                          "type": "string"
                        },
                        "streamKey": {
                          "type": "string"
                        },
                        "url": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "server",
                        "streamKey",
                        "url"
                      ],
                      "additionalProperties": false
                    },
                    "rtmps": {
                      "type": "object",
                      "properties": {
                        "server": {
                          "type": "string"
                        },
                        "streamKey": {
                          "type": "string"
                        },
                        "url": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "server",
                        "streamKey",
                        "url"
                      ],
                      "additionalProperties": false
                    },
                    "srt": {
                      "type": "object",
                      "properties": {
                        "url": {
                          "type": "string"
                        },
                        "uri": {
                          "type": "string"
                        },
                        "streamId": {
                          "type": "string"
                        },
                        "passphrase": {
                          "type": "string",
                          "nullable": true
                        }
                      },
                      "required": [
                        "url",
                        "uri",
                        "streamId",
                        "passphrase"
                      ],
                      "additionalProperties": false
                    },
                    "whip": {
                      "type": "object",
                      "properties": {
                        "url": {
                          "type": "string"
                        },
                        "bearerToken": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "url",
                        "bearerToken"
                      ],
                      "additionalProperties": false
                    },
                    "icecast": {
                      "type": "object",
                      "properties": {
                        "url": {
                          "type": "string"
                        },
                        "host": {
                          "type": "string"
                        },
                        "port": {
                          "type": "number"
                        },
                        "mount": {
                          "type": "string"
                        },
                        "username": {
                          "type": "string"
                        },
                        "password": {
                          "type": "string"
                        },
                        "httpsPutUrl": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "url",
                        "host",
                        "port",
                        "mount",
                        "username",
                        "password",
                        "httpsPutUrl"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "rtmp",
                    "rtmps",
                    "srt",
                    "whip",
                    "icecast"
                  ],
                  "additionalProperties": false,
                  "nullable": true
                }
              },
              "required": [
                "id",
                "name",
                "kind",
                "enabled",
                "protocols",
                "maxBitrateKbps",
                "allowedCidrs",
                "createdAt",
                "updatedAt",
                "revision",
                "keyHints",
                "keyFingerprints",
                "hasSrtPassphrase",
                "pull",
                "connection"
              ],
              "additionalProperties": false
            },
            "sync": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "string",
                  "enum": [
                    "pending",
                    "applied"
                  ]
                },
                "generation": {
                  "type": "number"
                },
                "error": {
                  "type": "string",
                  "nullable": true
                },
                "warnings": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "path": {
                        "type": "string"
                      },
                      "code": {
                        "type": "string"
                      },
                      "message": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "path",
                      "code",
                      "message"
                    ],
                    "additionalProperties": false
                  }
                }
              },
              "required": [
                "status",
                "generation",
                "error",
                "warnings"
              ],
              "additionalProperties": false
            }
          },
          "required": [
            "input",
            "sync"
          ],
          "additionalProperties": false
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": {
        "input": {
          "id": "string",
          "name": "string",
          "kind": "push",
          "enabled": true,
          "protocols": [
            "rtmp"
          ],
          "maxBitrateKbps": 0,
          "allowedCidrs": [
            "string"
          ],
          "createdAt": "string",
          "updatedAt": "string",
          "revision": 0,
          "keyHints": {
            "primary": "string",
            "backup": "string"
          },
          "keyFingerprints": {
            "primary": "string",
            "backup": "string"
          },
          "hasSrtPassphrase": true,
          "pull": {
            "urlHint": "string",
            "transport": "auto",
            "reconnect": true
          },
          "connection": {
            "rtmp": {
              "server": "string",
              "streamKey": "string",
              "url": "string"
            },
            "rtmps": {
              "server": "string",
              "streamKey": "string",
              "url": "string"
            },
            "srt": {
              "url": "string",
              "uri": "string",
              "streamId": "string",
              "passphrase": "string"
            },
            "whip": {
              "url": "string",
              "bearerToken": "string"
            },
            "icecast": {
              "url": "string",
              "host": "string",
              "port": 0,
              "mount": "string",
              "username": "string",
              "password": "string",
              "httpsPutUrl": "string"
            }
          }
        },
        "sync": {
          "status": "pending",
          "generation": 0,
          "error": "string",
          "warnings": [
            {
              "path": "string",
              "code": "string",
              "message": "string"
            }
          ]
        }
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }

Related guides

Something unclear or out of date? Emailsupport@hubfly.spaceBack to top