Skip to content

Lives list

GET /api/v1/lives returns the publicly visible livestreams on the platform — scheduled, on air, interrupted, and ended streams (with their replays).

Item Value
Method and path GET /api/v1/lives
Full URL https://ohmy.xin/api/v1/lives
Authentication Bearer key required
Request body None
Response data is an array of live objects, meta.pagination carries the page info
Pagination Cursor based, 20 items per page by default, 100 maximum
Visibility Only directory-listed streams in public circles are returned
GET /api/v1/lives HTTP/1.1
Host: ohmy.xin
Authorization: Bearer omx_live_xxxxxxxx_yyyyyyyy...
Accept: application/json

Authentication, rate limiting, and the error envelope follow the shared API conventions; this page covers only what is specific to the endpoint.

Every parameter is optional. Calling the endpoint with no parameters returns the first page in the default sort order.

Parameter Type Default Description
limit integer 20 Items per page, between 1 and 100. Out-of-range values return 400.
cursor string — The meta.pagination.next_cursor from the previous page. An opaque string — send it back verbatim.
sort string created_at:desc Sort order: created_at:desc (newest first by creation time) or updated_at:desc (newest first by update time).
circle_number string — Filter by circle, using the circle’s number (up to 32 characters).
state string scheduled,live,interrupted Filter by state, comma-separated. Allowed values: scheduled, live, interrupted, ended.
scheduled_after ISO 8601 timestamp — Lower bound on scheduled_at (inclusive).
scheduled_before ISO 8601 timestamp — Upper bound on scheduled_at (inclusive).
updated_after ISO 8601 timestamp — Lower bound on updated_at (inclusive).
终端窗口
curl -s "https://ohmy.xin/api/v1/lives?limit=2&state=scheduled,live&circle_number=7000101526" \
-H "Authorization: Bearer omx_live_xxxxxxxx_yyyyyyyy..."

data is an array; each element describes one livestream.

Field Type Nullable Description
number string No The stream’s public number. The internal id is never returned.
title string No Stream title.
description string Yes Stream description; null when there is none.
kind string No Stream kind — always video today.
state string No State: scheduled, live, interrupted, or ended.
url string No The room URL — share it directly with users.
cover_url string Yes Cover image URL; null when there is none.
viewer_count integer Yes Current viewers. Only populated while the stream is on air (live / interrupted); null in every other state.
scheduled_at ISO 8601 timestamp Yes Scheduled start time.
started_at ISO 8601 timestamp Yes Actual start time.
ended_at ISO 8601 timestamp Yes End time.
duration_seconds integer No Stream duration in seconds; 0 before it starts or before it ends.
replay_available boolean No Whether a replay is available: true once the stream has ended, the replay is visible, and a recording is ready.
comments_count integer No Number of comments.
reminders_count integer No Number of reminders.
updated_at ISO 8601 timestamp No Last update time.
circle object No The circle that owns the stream.
host object Yes The host; null when unavailable.
Field Type Nullable Description
number string No Circle number — feed it straight into the circle_number filter.
name string No Circle name.
url string No Circle home page, in the live channel view.
avatar_url string Yes Circle avatar URL.
Field Type Nullable Description
name string No Host display name.
avatar_url string Yes Host avatar URL.
Field Type Nullable Description
limit integer No The page size actually applied.
has_more boolean No Whether another page exists.
next_cursor string Yes Cursor for the next page; null when has_more is false.
{
"data": [
{
"number": "9100004",
"title": "On air now",
"description": "Weekly market outlook",
"kind": "video",
"state": "live",
"url": "https://ohmy.xin/circles/7000101526/lives/9100004",
"cover_url": "https://ohmy.xin/circles/7000101526/lives/9100004/card_cover.png?v=1a2b3c4d",
"viewer_count": 42,
"scheduled_at": null,
"started_at": "2024-01-16T10:00:00+08:00",
"ended_at": null,
"duration_seconds": 0,
"replay_available": false,
"comments_count": 12,
"reminders_count": 7,
"updated_at": "2024-01-16T10:30:00+08:00",
"circle": {
"number": "7000101526",
"name": "Crypto Lab",
"url": "https://ohmy.xin/circles/7000101526?channel=live",
"avatar_url": "https://cdn.ohmy.xin/circles/7000101526/avatar.webp"
},
"host": {
"name": "Alice",
"avatar_url": "https://cdn.ohmy.xin/users/a1b2c3/avatar.webp"
}
}
],
"meta": {
"pagination": {
"limit": 20,
"has_more": false,
"next_cursor": null
},
"request_id": "9f4f2d1e-7c3b-4c68-9f9f-0a1b2c3d4e5f"
}
}

Pagination is cursor based: fetch the first page, take meta.pagination.next_cursor, pass it back as the cursor parameter on the next call, and stop when has_more is false.

终端窗口
# First page
curl -s "https://ohmy.xin/api/v1/lives?limit=2" \
-H "Authorization: Bearer omx_live_xxxxxxxx_yyyyyyyy..."
# Next page — pass the previous next_cursor back verbatim
curl -s "https://ohmy.xin/api/v1/lives?limit=2&cursor=eyJzIjoidHJlYXRlZF9hdDpkZXNjIiwiYyI6WyIyMDI0LTAxLTE2VDAyOjAwOjAwWiIsOTEwMDAwNF19" \
-H "Authorization: Bearer omx_live_xxxxxxxx_yyyyyyyy..."

A livestream appears in the list only when all of these hold:

  1. The host has listed it in the circle’s livestream directory (directory_listed is true);
  2. Its state is scheduled, live, interrupted, or ended;
  3. Its circle is bound to Mixin, not dormant, and set to public.

Beyond the shared envelope, this endpoint adds one case:

HTTP status error.code When it happens
400 invalid_parameter A query parameter is invalid: limit out of range, an illegal sort/state value, a malformed timestamp, an inverted time window, or an invalid cursor.

The 400 response lists each offending parameter in error.details:

{
"error": {
"code": "invalid_parameter",
"message": "Invalid query parameter: state must contain only: scheduled, live, interrupted, ended.",
"details": [
{ "param": "state", "reason": "must contain only: scheduled, live, interrupted, ended" }
]
},
"meta": {
"request_id": "9f4f2d1e-7c3b-4c68-9f9f-0a1b2c3d4e5f"
}
}

For the other status codes (401, 429, 503, 500), see the API conventions.

  • API reference — authentication, rate limits, response envelope, and error codes
  • Quickstart — create an account, generate a key, make your first call
  • Strategies list — the other list endpoint
  • OpenAPI spec — the machine-readable description of this endpoint (OpenAPI 3.1)