Hitorino Streams API — List, Retrieve, and Schedule

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

string

Filter by stream status. Accepted values: live, scheduled, ended. Omit to return streams of all statuses.

string

Return only streams belonging to the creator with this user ID.

string

Filter streams by category slug (e.g., gaming, music, talk). Category slugs are lowercase and hyphen-separated.

integer

Maximum number of streams to return. Defaults to 20. Maximum is 100.

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"

const params = new URLSearchParams({ status: 'live', limit: '10' });

const response = await fetch(`https://api.hitorino.tv/v1/streams?${params}`, {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' },
});

const { data, pagination } = await response.json();
console.log(data);       // array of stream objects
console.log(pagination); // { next_cursor, has_more }

import requests

params = {'status': 'live', 'limit': 10}
headers = {'Authorization': 'Bearer YOUR_API_KEY'}

response = requests.get('https://api.hitorino.tv/v1/streams', params=params, headers=headers)
result = response.json()
print(result['data'])
print(result['pagination'])

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

array

Array of stream objects matching the query.

Show stream object fields

string

Unique identifier for the stream, prefixed with str_.

string

Display title of the stream.

string

Optional description provided by the creator.

string

Current status: live, scheduled, or ended.

string

Category slug assigned to the stream.

string

Visibility setting: public or private.

string

ID of the creator who owns the stream.

integer

Number of current concurrent viewers. null for scheduled or ended streams.

string

ISO 8601 timestamp of when the stream went live. null for scheduled streams.

string

ISO 8601 timestamp of the planned start time. null for streams that were not pre-scheduled.

string

URL of the stream thumbnail image.

string

Public watch page URL for the stream.

string

ISO 8601 timestamp of when the stream resource was created.

object

Pagination metadata for fetching subsequent pages.

Show pagination fields

string

Pass this value as the cursor query parameter in your next request. null when has_more is false.

boolean

true if additional results exist beyond the current page.

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

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"

const streamId = 'str_01HXYZ1234';

const response = await fetch(`https://api.hitorino.tv/v1/streams/${streamId}`, {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' },
});

const stream = await response.json();
console.log(stream);

import requests

stream_id = 'str_01HXYZ1234'
headers = {'Authorization': 'Bearer YOUR_API_KEY'}

response = requests.get(
    f'https://api.hitorino.tv/v1/streams/{stream_id}',
    headers=headers,
)
stream = response.json()
print(stream)

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

integer

Highest concurrent viewer count recorded during the stream’s lifetime.

string

ISO 8601 timestamp of when the stream ended. null if the stream is still live or scheduled.

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

string

required

Display title for the stream. Maximum 120 characters.

string

Optional description visible to viewers. Maximum 2,000 characters.

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.

string

Category slug for the stream (e.g., gaming, music, coding, talk). Must match a valid Hitorino category.

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

const response = await fetch('https://api.hitorino.tv/v1/streams', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Sunday Watercolor Session',
    description: 'Painting a mountain landscape from scratch.',
    scheduled_at: '2024-07-07T14:00:00Z',
    category: 'art',
    privacy: 'public',
  }),
});

const stream = await response.json();
console.log(stream.id); // "str_01HNEW5678"

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
}

payload = {
    'title': 'Sunday Watercolor Session',
    'description': 'Painting a mountain landscape from scratch.',
    'scheduled_at': '2024-07-07T14:00:00Z',
    'category': 'art',
    'privacy': 'public',
}

response = requests.post(
    'https://api.hitorino.tv/v1/streams',
    json=payload,
    headers=headers,
)
stream = response.json()
print(stream['id'])

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.

​List Streams

​Query Parameters

​Request Examples

​Response

​Get Stream

​Path Parameters

​Request Examples

​Response

​Create Stream

​Request Body

​Request Examples

​Response

List Streams

Query Parameters

Request Examples

Response

Get Stream

Path Parameters

Request Examples

Response

Create Stream

Request Body

Request Examples

Response