Skip to main content
The Hitorino REST API gives you programmatic access to streams, videos, users, and webhooks on the platform. Every feature available in the Hitorino dashboard is also available through the API, so you can build fully integrated experiences — from scheduling solo streams to embedding on-demand video catalogs in your own app.

​
Base URL

All API requests target the following base URL: 
https://api.hitorino.tv/v1
Every endpoint path in this reference is relative to this base. For example, the full URL for listing streams is https://api.hitorino.tv/v1/streams.

​
Versioning

The API is versioned via the URL path (/v1). Hitorino increments the version number only for breaking changes. Non-breaking additions — such as new optional fields or new endpoints — are rolled out within the current version without notice. Subscribe to the Hitorino developer changelog to stay informed about API updates.

​
Request Format

The Hitorino API accepts JSON request bodies. When sending a request body, set the Content-Type header to application/json. 
Content-Type: application/json
Query parameters are used for filtering and pagination on GET endpoints. Request bodies are used for POST and DELETE endpoints that require a payload.

​
Response Format

All responses — including errors — are returned as JSON. Successful responses return the primary resource object or a wrapper object containing a data array for list endpoints. 
{
  "data": [
    {
      "id": "str_01HXYZ",
      "title": "Morning Coding Session",
      "status": "live"
    }
  ],
  "pagination": {
    "next_cursor": "cur_01HABC",
    "has_more": true
  }
}
Single-resource responses (e.g., GET /streams/{id}) return the object directly at the top level, without a data wrapper.

​
Rate Limits

Hitorino enforces rate limits to ensure fair usage across all integrations. The limits apply per API key for authenticated requests and per IP address for unauthenticated requests.
AuthenticationLimit
Authenticated (API key)1,000 requests per minute
Unauthenticated60 requests per minute
When you exceed the rate limit, the API returns a 429 Too Many Requests response. The following response headers are included on every API response to help you track your usage:
HeaderDescription
X-RateLimit-LimitMaximum requests allowed in the current window
X-RateLimit-RemainingRequests remaining in the current window
X-RateLimit-ResetUnix timestamp when the current window resets
Implement exponential backoff when you receive a 429 response. Wait for the time indicated by X-RateLimit-Reset before retrying, and avoid tight retry loops that can amplify traffic spikes.

​
Pagination

List endpoints use cursor-based pagination rather than page numbers. This approach is more reliable for real-time data where new items can be inserted between requests. To paginate through results, pass the cursor query parameter with the value of next_cursor from the previous response. When has_more is false, you have reached the end of the result set.
​
limit
integer
Maximum number of items to return per page. Defaults to 20. Maximum is 100.
​
cursor
string
Cursor string returned by the previous response’s pagination.next_cursor. Omit this parameter to start from the beginning.
Example — first page: 
curl https://api.hitorino.tv/v1/streams?limit=25 \
  -H "Authorization: Bearer YOUR_API_KEY"
Example — subsequent page: 
curl "https://api.hitorino.tv/v1/streams?limit=25&cursor=cur_01HABC" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Error Responses

When a request fails, Hitorino returns an appropriate HTTP status code and a JSON body with a structured error object. This makes it straightforward to programmatically distinguish between different failure types. 
{
  "error": {
    "code": "resource_not_found",
    "message": "No stream exists with the provided ID."
  }
}
​
error
object
Top-level error container present on all failed responses.

​
HTTP Status Codes

StatusMeaning
200 OKRequest succeeded.
201 CreatedResource was successfully created.
400 Bad RequestThe request body or parameters are invalid.
401 UnauthorizedAPI key is missing or invalid.
403 ForbiddenAPI key lacks the required scope for this action.
404 Not FoundThe requested resource does not exist.
409 ConflictThe request conflicts with existing state (e.g., duplicate webhook URL).
429 Too Many RequestsRate limit exceeded.
500 Internal Server ErrorAn unexpected error occurred on Hitorino’s side.
Never expose your API key in client-side code. All API calls that include your key should be made from a secure server-side environment. If a key is compromised, revoke it immediately from Settings → API Keys in the dashboard.