Skip to main content
The Streams API is the core of Hitorino’s platform. You can use it to retrieve real-time and scheduled stream data for display in your app, or to programmatically schedule new solo streams on behalf of authenticated creators. All three endpoints follow the standard Hitorino request/response conventions described in the API Overview.

​
List Streams

Retrieves a paginated list of streams. By default the response includes all streams regardless of status. Use the query parameters below to filter by status, creator, or category. 
GET /streams

​
Query Parameters

​
status
string
Filter by stream status. Accepted values: live, scheduled, ended. Omit to return streams of all statuses.
​
creator_id
string
Return only streams belonging to the creator with this user ID.
​
category
string
Filter streams by category slug (e.g., gaming, music, talk). Category slugs are lowercase and hyphen-separated.
​
limit
integer
Maximum number of streams to return. Defaults to 20. Maximum is 100.
​
cursor
string
Pagination cursor from the previous response’s pagination.next_cursor. Omit to start from the first page.

​
Request Examples

curl "https://api.hitorino.tv/v1/streams?status=live&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response

{
  "data": [
    {
      "id": "str_01HXYZ1234",
      "title": "Late Night Lo-Fi Coding",
      "description": "Building a side project with lo-fi beats.",
      "status": "live",
      "category": "coding",
      "privacy": "public",
      "creator_id": "usr_01HABC5678",
      "viewer_count": 142,
      "started_at": "2024-06-10T22:00:00Z",
      "scheduled_at": null,
      "thumbnail_url": "https://cdn.hitorino.tv/thumbnails/str_01HXYZ1234.jpg",
      "stream_url": "https://watch.hitorino.tv/str_01HXYZ1234",
      "created_at": "2024-06-10T21:45:00Z"
    }
  ],
  "pagination": {
    "next_cursor": "cur_01HDEF9012",
    "has_more": true
  }
}
​
data
array
Array of stream objects matching the query.
​
pagination
object
Pagination metadata for fetching subsequent pages.

​
Get Stream

Retrieves a single stream by its unique ID, including all fields from the list response plus any extended metadata. 
GET /streams/{id}

​
Path Parameters

​
id
string
required
The unique stream ID (e.g., str_01HXYZ1234).

​
Request Examples

curl https://api.hitorino.tv/v1/streams/str_01HXYZ1234 \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response

{
  "id": "str_01HXYZ1234",
  "title": "Late Night Lo-Fi Coding",
  "description": "Building a side project with lo-fi beats.",
  "status": "live",
  "category": "coding",
  "privacy": "public",
  "creator_id": "usr_01HABC5678",
  "viewer_count": 142,
  "peak_viewer_count": 189,
  "started_at": "2024-06-10T22:00:00Z",
  "ended_at": null,
  "scheduled_at": null,
  "thumbnail_url": "https://cdn.hitorino.tv/thumbnails/str_01HXYZ1234.jpg",
  "stream_url": "https://watch.hitorino.tv/str_01HXYZ1234",
  "created_at": "2024-06-10T21:45:00Z",
  "updated_at": "2024-06-10T22:00:05Z"
}
​
peak_viewer_count
integer
Highest concurrent viewer count recorded during the stream’s lifetime.
​
ended_at
string
ISO 8601 timestamp of when the stream ended. null if the stream is still live or scheduled.
​
updated_at
string
ISO 8601 timestamp of the most recent update to this stream resource.
All other response fields are identical to those returned in the list endpoint. See the List Streams section for full field descriptions.

​
Create Stream

Creates or schedules a new stream. Supply a scheduled_at timestamp to schedule the stream for a future time, or omit it to create a stream you intend to start immediately via your streaming software. 
POST /streams
This endpoint requires a write-scoped API key. Requests made with a read-scoped key return 403 Forbidden.

​
Request Body

​
title
string
required
Display title for the stream. Maximum 120 characters.
​
description
string
Optional description visible to viewers. Maximum 2,000 characters.
​
scheduled_at
string
ISO 8601 timestamp of the planned start time (e.g., 2024-07-01T18:00:00Z). Must be in the future. Omit to create an unscheduled stream ready to go live immediately.
​
category
string
Category slug for the stream (e.g., gaming, music, coding, talk). Must match a valid Hitorino category.
​
privacy
string
Visibility setting. One of public (default) or private. Private streams are accessible only via direct link.

​
Request Examples

curl -X POST https://api.hitorino.tv/v1/streams \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Sunday Watercolor Session",
    "description": "Painting a mountain landscape from scratch.",
    "scheduled_at": "2024-07-07T14:00:00Z",
    "category": "art",
    "privacy": "public"
  }'

​
Response

Returns 201 Created with the newly created stream object. 
{
  "id": "str_01HNEW5678",
  "title": "Sunday Watercolor Session",
  "description": "Painting a mountain landscape from scratch.",
  "status": "scheduled",
  "category": "art",
  "privacy": "public",
  "creator_id": "usr_01HABC5678",
  "viewer_count": null,
  "peak_viewer_count": null,
  "started_at": null,
  "ended_at": null,
  "scheduled_at": "2024-07-07T14:00:00Z",
  "thumbnail_url": null,
  "stream_url": "https://watch.hitorino.tv/str_01HNEW5678",
  "created_at": "2024-06-15T09:30:00Z",
  "updated_at": "2024-06-15T09:30:00Z"
}
After creating a scheduled stream, share the stream_url with your audience. Hitorino automatically sends a stream.started webhook event when the stream goes live — see the Webhooks reference to register your endpoint.