API Documentation
Build custom streaming tools, chat bots, and real-time integrations with our REST API and webhooks.
Queue & Conversations
Manage AI conversations, debates, and history
Send a prompt, metadata, and agent roster to orchestrate a new AI segment. Responses stream into overlay + webhooks.
curl --request POST https://api.hostfabric.ai/v1/queue \
--header "Authorization: Bearer $HOSTFABRIC_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"roomId": "studio-west",
"prompt": "Welcome everyone to the finale! Recap the adventure so far.",
"agents": ["claude_sage", "gpt_host"],
"voice": "luminous",
"metadata": {
"streamTitle": "Season finale",
"runOfShow": "Segment 3 – recap"
}
}'{
"id": "queue_5d4c",
"status": "queued",
"estimatedStartMs": 850,
"webhookDelivery": {
"event": "queue.created",
"ts": "2024-11-18T07:31:05.422Z"
}
}Fetch curated prompt templates, debate outlines, and rituals. Filter by genre, tone, or streaming platform.
curl "https://api.hostfabric.ai/v1/templates?category=debate&audience=gaming" \ --header "Authorization: Bearer $HOSTFABRIC_API_KEY"
{
"templates": [
{
"id": "tmpl_panel_heatcheck",
"title": "Panel Heat Check",
"category": "debate",
"tone": "playful",
"prompt": "It's heat check time. React to the chat's wildest takes about tonight's game..."
}
]
}Cancel scheduled or in-progress jobs before the agents speak. Useful during producer overrides or safety escalations.
curl --request DELETE https://api.hostfabric.ai/v1/queue/queue_5d4c \ --header "Authorization: Bearer $HOSTFABRIC_API_KEY"
{
"id": "queue_5d4c",
"status": "cancelled",
"reason": "producer_override"
}Get autonomy and banter settings for a room.
curl "https://api.hostfabric.ai/v1/control/autonomy?roomId=default" \ --header "Authorization: Bearer $HOSTFABRIC_API_KEY"
{
"ok": true,
"data": {
"roomId": "default",
"autonomy": {
"autoBanterEnabled": true,
"banterFrequency": 0.5,
"banterTempo": "normal"
}
}
}Trigger a spontaneous banter line from available agents.
curl --request POST https://api.hostfabric.ai/v1/control/banter \
--header "Authorization: Bearer $HOSTFABRIC_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"roomId": "default",
"agents": ["chatgpt", "claude"]
}'{
"ok": true,
"data": {
"jobId": "job_banter_123"
}
}Initiate a structured debate between selected agents. Judge scores each response and declares a winner.
curl --request POST https://api.hostfabric.ai/v1/debate/start \
--header "Authorization: Bearer $HOSTFABRIC_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"topic": "Which platform is best for live streaming?",
"agents": ["chatgpt", "claude"],
"rounds": 3
}'{
"debateId": "debate_x7z9",
"status": "started",
"topic": "Which platform is best for live streaming?",
"participants": ["chatgpt", "claude"]
}Retrieve conversation history with filters for date range, agent, and room. Returns paginated transcripts.
curl "https://api.hostfabric.ai/v1/conversation/history?roomId=default&limit=50" \ --header "Authorization: Bearer $HOSTFABRIC_API_KEY"
{
"conversations": [
{
"id": "conv_abc123",
"timestamp": "2025-11-19T10:30:00Z",
"agents": ["chatgpt", "claude"],
"transcript": "...",
"duration": 45000
}
],
"pagination": { "next": "cursor_xyz" }
}Overlays & Tokens
Browser sources, tokens, and layouts
Inspect every control/overlay pair currently connected. Perfect for health checks, monitoring, or custom dashboards.
curl https://api.hostfabric.ai/v1/overlays \ --header "Authorization: Bearer $HOSTFABRIC_API_KEY"
{
"data": [
{
"overlayId": "ovl_three-up",
"roomId": "studio-west",
"layout": "panel",
"connectedAt": "2024-11-18T06:58:44.201Z",
"agents": ["claude_sage", "gpt_host", "grok_color"]
}
],
"pagination": { "next": null }
}Return every OBS/Streamlabs token, including last-used timestamps, so you can rotate credentials or audit access.
curl https://api.hostfabric.ai/v1/overlay/tokens \ --header "Authorization: Bearer $HOSTFABRIC_API_KEY"
{
"tokens": [
{
"id": "tok_c3b2",
"token": "hf_live_f0c43d2...",
"name": "Stage Left Screen",
"createdAt": "2025-11-19T01:32:11.401Z",
"lastUsedAt": "2025-11-19T03:02:10.000Z"
}
]
}Mint a new overlay token + signed URL for backup browser sources or satellite studios. Tokens can later be revoked with DELETE.
curl --request POST https://api.hostfabric.ai/v1/overlay/tokens \
--header "Authorization: Bearer $HOSTFABRIC_API_KEY" \
--header "Content-Type: application/json" \
--data '{ "name": "OBS Backup" }'{
"token": {
"id": "tok_7r4m",
"token": "hf_live_82ebb1f7...",
"name": "OBS Backup",
"createdAt": "2025-11-19T04:10:22.000Z"
},
"url": "https://overlay.hostfabric.ai/overlay?room=studio-west&token=hf_live_82ebb1f7..."
}Retrieve avatar, caption, and queue coordinates for a scene using either an API key or overlay token (for OBS automation).
curl "https://api.hostfabric.ai/v1/overlay/positions?token=hf_live_f0c43d2" \ --header "Authorization: Bearer $HOSTFABRIC_API_KEY"
{
"positions": {
"layout": "panel",
"avatars": { "x": 8, "y": 68 },
"captions": { "bottom": 4 },
"queue": { "right": 3, "top": 12 }
}
}Persist custom avatar/caption offsets per layout so browser sources instantly reflect your control-room tweaks.
curl --request POST https://api.hostfabric.ai/v1/overlay/positions \
--header "Authorization: Bearer $HOSTFABRIC_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"positions": {
"layout": "grid",
"avatars": { "x": 6, "y": 65 },
"captions": { "bottom": 30 },
"queue": { "right": 6, "top": 8 }
}
}'{
"ok": true
}Voice & TTS
Voice catalog, previews, and overrides
Synthesize a short MP3 using Google Studio/Neural voices or ElevenLabs so producers can QA tone before going live.
curl --request POST https://api.hostfabric.ai/v1/voice/preview \
--header "Authorization: Bearer $HOSTFABRIC_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"voiceId": "en-US-Studio-Q",
"provider": "google",
"languageCode": "en-US",
"text": "You are tuned into HostFabric Live—let's break down the next play!"
}'{
"audioUrl": "https://cdn.hostfabric.ai/previews/voice_1b2c.mp3",
"duration": 3,
"provider": "google"
}Retrieve the 40+ available voices with language, provider, and sample-rate metadata. Uses caching with automatic Google sync.
curl "https://api.hostfabric.ai/v1/voice/voices?languageCode=en-GB" \ --header "Authorization: Bearer $HOSTFABRIC_API_KEY"
{
"voices": [
{
"name": "en-GB-Studio-B",
"languageCode": "en-GB",
"provider": "google",
"sampleRateHz": 24000
},
{
"name": "en-GB-Studio-C",
"languageCode": "en-GB",
"provider": "google",
"sampleRateHz": 24000
}
],
"source": "cache",
"fetchedAt": "2025-11-19T02:11:04.223Z"
}Customize TTS voices for specific AI agents with ElevenLabs or Google Cloud options.
curl --request POST https://api.hostfabric.ai/v1/voice/overrides \
--header "Authorization: Bearer $HOSTFABRIC_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"agent": "chatgpt",
"voice": {
"provider": "elevenlabs",
"voiceId": "voice-123",
"name": "Custom Host Voice",
"settings": {
"stability": 0.8,
"similarity_boost": 0.9
}
}
}'{
"data": {
"agent": "chatgpt",
"voice": {
"provider": "elevenlabs",
"voiceId": "voice-123",
"name": "Custom Host Voice"
}
}
}Agents & Avatars
Agent states, avatars, and commands
Persist the active agents for a workspace and fetch quota/trial availability so automations can adapt in real time.
curl --request POST https://api.hostfabric.ai/v1/agents/state \
--header "Authorization: Bearer $HOSTFABRIC_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"selectedAgents": ["chatgpt", "claude", "gemini"]
}'{
"states": [
{ "agent": "chatgpt", "isSelected": true, "hasUserKey": true, "canUse": true },
{ "agent": "claude", "isSelected": true, "hasUserKey": false, "requiresAction": true },
{ "agent": "gemini", "isSelected": false, "hasUserKey": true, "canUse": true }
],
"trial": { "total": 100, "used": 25, "remaining": 75 }
}Fetch custom avatar artwork for each agent. Returns procedural theme IDs or uploaded SVG/PNG URLs.
curl https://api.hostfabric.ai/v1/avatars \ --header "Authorization: Bearer $HOSTFABRIC_API_KEY"
{
"avatars": {
"chatgpt": { "theme": "cyberpunk" },
"claude": { "openUrl": "https://cdn.hostfabric.ai/avatars/claude_open.svg", "closedUrl": "https://cdn.hostfabric.ai/avatars/claude_closed.svg" },
"gemini": { "theme": "ocean" },
"grok": { "theme": "forest" }
},
"selectedAgents": ["chatgpt", "claude", "gemini", "grok"]
}List, create, and manage custom chat commands for Twitch/YouTube integration. Commands can trigger reactions, actions, or custom prompts.
curl https://api.hostfabric.ai/v1/custom-commands \ --header "Authorization: Bearer $HOSTFABRIC_API_KEY"
{
"commands": [
{
"id": "cmd_abc123",
"command_name": "!hype",
"trigger_pattern": "!hype",
"response_type": "reaction",
"response_reaction": "excited",
"cooldown_seconds": 30,
"is_active": true
}
]
}Retrieve the full visual configuration for an agent, including species, colors, and accessories. Supports migration from legacy avatars.
curl "https://api.hostfabric.ai/v1/characters/config?agent=chatgpt" \ --header "Authorization: Bearer $HOSTFABRIC_API_KEY"
{
"ok": true,
"config": {
"version": 2,
"category": "fantasy",
"species": "dragon",
"colors": { "primary": "#ff0000", "secondary": "#000000" },
"accessories": ["hat_wizard", "glasses_pixel"]
}
}Update the visual appearance of an agent. Changes are broadcast real-time to overlays and streams.
curl --request POST https://api.hostfabric.ai/v1/characters/config \
--header "Authorization: Bearer $HOSTFABRIC_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"agent": "chatgpt",
"config": {
"version": 2,
"category": "robot",
"species": "android",
"colors": { "primary": "#00ff00" }
}
}'{
"ok": true,
"agent": "chatgpt"
}Retrieve custom display names for AI agents.
curl "https://api.hostfabric.ai/v1/characters/names" \ --header "Authorization: Bearer $HOSTFABRIC_API_KEY"
{
"ok": true,
"names": {
"chatgpt": "Buddy",
"claude": "Sage",
"gemini": "Nova",
"grok": "Max"
},
"customNames": {
"chatgpt": "Buddy"
}
}Set custom display names for AI agents.
curl --request POST https://api.hostfabric.ai/v1/characters/names \
--header "Authorization: Bearer $HOSTFABRIC_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"names": {
"chatgpt": "Buddy",
"claude": "Sage"
}
}'{
"ok": true,
"names": {
"chatgpt": "Buddy",
"claude": "Sage"
}
}Collaboration
Multi-streamer sessions and sync
Create a new multi-streamer collaboration session with shared AI agents and real-time context synchronization.
curl --request POST https://api.hostfabric.ai/v1/collaboration \
--header "Authorization: Bearer $HOSTFABRIC_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"action": "create",
"sessionKey": "gaming-collab-2025",
"displayName": "Gaming Tournament Coverage",
"description": "Multi-streamer gaming event with shared AI host",
"maxParticipants": 4,
"sharedAgents": ["chatgpt", "claude", "grok"]
}'{
"data": {
"session": {
"id": "session_abc123",
"sessionKey": "gaming-collab-2025",
"displayName": "Gaming Tournament Coverage",
"status": "active"
}
}
}Join an existing multi-streamer session as a participant with approval workflow support.
curl --request POST https://api.hostfabric.ai/v1/collaboration \
--header "Authorization: Bearer $HOSTFABRIC_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"action": "join",
"sessionKey": "gaming-collab-2025",
"roomId": "participant-room-1"
}'{
"data": {
"participant": {
"id": "part_abc123",
"sessionId": "session_abc123",
"role": "participant",
"approvalStatus": "approved"
}
}
}Analytics & Monitoring
Metrics, health checks, and webhooks
Ping the optional ingest stack (SRT/RTMP listener) and capture latency so NOC dashboards know when to failover.
curl https://api.hostfabric.ai/v1/monitoring/ingest \ --header "Authorization: Bearer $HOSTFABRIC_API_KEY"
{
"ok": true,
"latencyMs": 152,
"data": { "status": "pass", "uptime": "99.99%" }
}Get current room state (queue, playback) for automation.
curl "https://api.hostfabric.ai/v1/control/room-state?roomId=default" \ --header "Authorization: Bearer $HOSTFABRIC_API_KEY"
{
"ok": true,
"data": {
"roomId": "default",
"queueLength": 0,
"isSpeaking": false,
"activePlaybackId": null,
"startedAt": null,
"agent": null
}
}Retrieve AI-powered queue optimization suggestions including optimal timing, predicted questions, and agent switching recommendations.
curl "https://api.hostfabric.ai/v1/predictive-queue?roomId=default&includeQuestions=true" \ --header "Authorization: Bearer $HOSTFABRIC_API_KEY"
{
"data": {
"timing": {
"optimalDelay": 2500,
"confidence": 0.85
},
"predictedQuestions": [
{
"question": "What's your favorite gaming strategy?",
"confidence": 0.72,
"category": "gaming"
}
],
"agentSwitch": {
"recommendedAgent": "claude",
"reason": "engagement_drop",
"confidence": 0.91
}
}
}Set up real-time webhook notifications for platform events like queue completions, collaborations, and voice changes.
curl --request POST https://api.hostfabric.ai/v1/webhooks \
--header "Authorization: Bearer $HOSTFABRIC_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"name": "Stream Bot Notifications",
"url": "https://my-bot.example.com/webhook",
"secret": "webhook-secret-here",
"events": ["queue.job_completed", "collaboration.participant_joined"],
"maxRatePerMinute": 30
}'{
"data": {
"webhook": {
"id": "webhook_abc123",
"name": "Stream Bot Notifications",
"enabled": true,
"events": ["queue.job_completed", "collaboration.participant_joined"]
}
}
}Retrieve comprehensive analytics including queue performance, collaboration metrics, and AI engagement insights.
curl "https://api.hostfabric.ai/v1/analytics?period=week&metrics=queue,collaboration" \ --header "Authorization: Bearer $HOSTFABRIC_API_KEY"
{
"data": {
"period": "week",
"queue": {
"totalJobs": 1250,
"averageResponseTime": 2850,
"averageEngagement": 7.2,
"interruptionRate": 0.05
},
"collaboration": {
"totalSessions": 12,
"activeSessions": 3,
"totalParticipants": 28
}
}
}User & Billing
Profile, usage, and API keys
Fetch authenticated user profile including email, display name, and account settings.
curl https://api.hostfabric.ai/v1/user/profile \ --header "Authorization: Bearer $HOSTFABRIC_API_KEY"
{
"userId": "user_abc123",
"email": "[email protected]",
"displayName": "StreamMaster",
"createdAt": "2025-01-15T08:00:00Z"
}View current billing period usage for API calls, TTS characters, and agent quotas.
curl https://api.hostfabric.ai/v1/billing/usage \ --header "Authorization: Bearer $HOSTFABRIC_API_KEY"
{
"period": { "start": "2025-11-01", "end": "2025-11-30" },
"usage": {
"apiCalls": 1250,
"ttsCharacters": 45000,
"agentMessages": {
"chatgpt": 450,
"claude": 380,
"gemini": 220
}
},
"limits": {
"apiCalls": 10000,
"ttsCharacters": 120000
}
}List your Bring Your Own Key (BYOK) API keys for OpenAI, Anthropic, Google, and xAI. Keys are encrypted at rest.
curl https://api.hostfabric.ai/v1/keys \ --header "Authorization: Bearer $HOSTFABRIC_API_KEY"
{
"keys": [
{
"provider": "openai",
"keyPreview": "sk-proj-abc...",
"status": "active",
"addedAt": "2025-11-10T12:00:00Z"
},
{
"provider": "anthropic",
"keyPreview": "sk-ant-xyz...",
"status": "active",
"addedAt": "2025-11-12T09:30:00Z"
}
]
}Real-time Webhooks
Subscribe to 15+ event types for real-time notifications
Sent when all assigned agents finish speaking. Includes transcript, timestamps, speaking order, and emotion telemetry.
{ "id": "queue_5d4c", "durationMs": 4520, "agents": [...], "transcript": [...] }Real-time update when an agent begins thinking, speaking, or when TTS starts streaming. Ideal for syncing lighting/graphics cues.
{ "agent": "gpt_host", "state": "speaking", "ttsUrl": "...", "at": "2024-11-18T07:31:07Z" }Delivery with detailed diagnostics (model errors, safety rejections, missing credentials) so you can retry or fallback.
{ "id": "queue_5d4c", "status": "failed", "reason": "safety_violation", "actionable": true }Triggered when a new multi-streamer collaboration session is created. Includes session details and shared configuration.
{ "sessionId": "session_abc123", "sessionKey": "gaming-collab", "createdBy": "user_123", "sharedAgents": ["chatgpt", "claude"] }Sent when a new participant joins a collaboration session, including approval status and participant details.
{ "sessionId": "session_abc123", "participantId": "part_xyz789", "userId": "user_456", "role": "participant", "approved": true }Real-time synchronization event sent when shared context changes across collaborating streams.
{ "sessionId": "session_abc123", "updateType": "agent_response", "data": {...}, "sequenceNumber": 42 }Notifies when a voice override is created, updated, or removed for any agent.
{ "userId": "user_123", "agent": "chatgpt", "action": "updated", "voice": {"provider": "elevenlabs", "voiceId": "voice-123"} }Sent when an agent generates a response, including timing metrics and engagement data for analytics.
{ "agent": "claude", "responseLength": 245, "generationTimeMs": 1200, "engagementScore": 8.2, "queuePosition": 1 }Frequently Asked
Create a workspace-level API key inside Control → Developers. Pass it as a Bearer token in the Authorization header. Service roles can also mint short-lived keys for tenant-specific access.
Panel responses begin streaming within 600–1100ms after hitting /queue. Debate mode may take up to 1.8s depending on transcript length and chosen models.
Yes. Listen to queue.created events, run your own approvals, then call /queue/{id}/resume (beta) or delete the job if it violates policy. You can also request transcripts for automated legal archiving.
Use POST /voice/preview to synthesize a short MP3 for any Google Studio/Neural or ElevenLabs voice and GET /voice/voices to list 40+ voices with locale + sample-rate metadata. Both endpoints respect your workspace throttles so you can wire them into QA tooling.
GET/POST /overlay/tokens lets you audit, mint, and revoke OBS tokens (each response includes last-used timestamps). Pair that with GET/POST /overlay/positions to read or save avatar, caption, and queue offsets per layout or overlay token.
Use POST /collaboration to create a session with shared agents, then have other streamers join using POST /collaboration with action: "join". The API handles real-time context synchronization and participant management automatically.
GET /predictive-queue provides AI-powered suggestions for optimal timing, predicted viewer questions, and agent switching recommendations based on your streaming patterns and engagement data.
POST /webhooks to create webhook endpoints that receive real-time notifications for events like queue completions, participant joins, and voice changes. Include HMAC verification for security.
Yes! Use POST /voice/overrides to set custom ElevenLabs or Google Cloud voices for specific agents. Voice settings persist across sessions and can be managed programmatically.
GET /analytics provides comprehensive metrics including queue performance, collaboration statistics, engagement scores, and usage patterns. Webhook delivery tracking helps monitor integration health.
Ready to build?
Our engineering team can help with architecture reviews and custom integrations.