Hitorino REST API — Overview and Core Concepts Guide

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.

Authentication	Limit
Authenticated (API key)	1,000 requests per minute
Unauthenticated	60 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:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the current window
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix 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.

integer

Maximum number of items to return per page. Defaults to 20. Maximum is 100.

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

object

Top-level error container present on all failed responses.

Show error fields

string

A machine-readable error code string. Use this field for programmatic error handling rather than parsing the human-readable message.

string

A human-readable description of what went wrong. Suitable for logging, but not guaranteed to remain stable across API versions.

HTTP Status Codes

Status	Meaning
`200 OK`	Request succeeded.
`201 Created`	Resource was successfully created.
`400 Bad Request`	The request body or parameters are invalid.
`401 Unauthorized`	API key is missing or invalid.
`403 Forbidden`	API key lacks the required scope for this action.
`404 Not Found`	The requested resource does not exist.
`409 Conflict`	The request conflicts with existing state (e.g., duplicate webhook URL).
`429 Too Many Requests`	Rate limit exceeded.
`500 Internal Server Error`	An 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.

​Base URL

​Versioning

​Request Format

​Response Format

​Rate Limits

​Pagination

​Error Responses

​HTTP Status Codes

Base URL

Versioning

Request Format

Response Format

Rate Limits

Pagination

Error Responses

HTTP Status Codes