> ## Documentation Index
> Fetch the complete documentation index at: https://start.hitorino.tv/llms.txt
> Use this file to discover all available pages before exploring further.
# Hitorino REST API — Overview and Core Concepts Guide
> Learn the base URL, versioning strategy, JSON request/response format, rate limits, cursor-based pagination, and error handling for the Hitorino REST API.
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:
```bash theme={null}
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](https://hitorino.tv/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`.
```bash theme={null}
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.
```json theme={null}
{
"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.
Maximum number of items to return per page. Defaults to `20`. Maximum is `100`.
Cursor string returned by the previous response's `pagination.next_cursor`. Omit this parameter to start from the beginning.
**Example — first page:**
```bash theme={null}
curl https://api.hitorino.tv/v1/streams?limit=25 \
-H "Authorization: Bearer YOUR_API_KEY"
```
**Example — subsequent page:**
```bash theme={null}
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.
```json theme={null}
{
"error": {
"code": "resource_not_found",
"message": "No stream exists with the provided ID."
}
}
```
Top-level error container present on all failed responses.
A machine-readable error code string. Use this field for programmatic error handling rather than parsing the human-readable `message`.
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.